---
name: start-feature
description: >
  当用户要求开始开发新功能、新模块或启动一项开发任务时使用。
  优先走 agent pool（claim 一个预热好的 slot），池不存在或不适用时回落到
  setup-worktree.sh 创建命名 worktree。完成分支创建/检出、环境配置、
  数据库隔离、依赖安装的全自动编排。
  触发短语：开始开发、新功能、启动任务、start feature、
  new feature、开新分支开发、我要开发、开始做。
  不触发：仅创建分支（用 git-main）、仅修改代码（直接做）。
---

# 启动功能开发技能

## 目标

接收功能需求描述，**优先 claim agent pool 的 slot 作为执行环境**；
池缺失 / 不适用时回落到 `setup-worktree.sh` 命名 worktree。
完成后让用户立即可以编码。

## 入口决策（关键）

**永远先尝试 agent-claim**——这条路径秒级完成，比创建新 worktree 快 ~140×。
**根据 exit code 决策**，不要把命令抛回给用户（执行者是 AI）。

```
                          ┌────────────────────────────┐
   开新任务 ──→ agent-claim│ exit │ 含义/动作              │
                          ├──────┼────────────────────────┤
                          │  0   │ 已 claim，eval 后开干 │
                          │  2   │ 同分支冲突 → ask 用户  │
                          │  3   │ 池满 → ask 扩/等/旧路 │
                          │  4   │ 池未初始化 → ask init │
                          │  5   │ 显式禁用 → 走旧路     │
                          └──────┴────────────────────────┘
```

### 第 1 步：claim 一个 slot

```bash
bash scripts/dev/agent-pool/agent-claim.sh <task-branch> [<base-branch>]
```

**分支命名规范**（之后会传给 git-main / commit-* skills）：
- `feature/<kebab-case>` — 新功能
- `bugfix/<kebab-case>` — bug 修复
- `hotfix/<kebab-case>` — 紧急生产修复
- `chore/<kebab-case>` — 杂项 / 配置 / 文档

### 第 2 步：根据 exit code 处理

#### `exit 0` — 成功

```bash
eval "$(bash scripts/dev/agent-pool/agent-claim.sh feature/<name>)"
# 自动 export：FFOA_AGENT_SLOT, FFOA_AGENT_DIR, FRONTEND_PORT, BACKEND_PORT, ...
```

进入 slot 目录开干：

```bash
cd "${FFOA_AGENT_DIR}"
```

**告知用户的 IDE 入口**（如果用户在用 VSCode multi-root workspace）：claim 时会
自动刷新 `<repo-parent>/<repo>.code-workspace` 文件，slot name 立即标上新分支。
如果 IDE 已打开此文件，会弹"workspace 已修改，重新加载？"——点一下即可看到新
slot 状态。详见 `scripts/dev/agent-pool/README.md` §「VSCode multi-root +
Remote-SSH 入口」。

跳到第 3 步。

#### `exit 2` — 同分支已被占用

stderr 含 `EXISTING_SLOT=N` 和 `EXISTING_DIR=...`。

用 `AskUserQuestion` 询问：
- 选项 A：换分支名（建议在用户原意上加后缀，如 `-v2` / `-followup`）
- 选项 B：直接 cd 到 `EXISTING_DIR` 接手已占的 slot（不再 claim）

#### `exit 3` — 池满

stderr 含 `EXIT_REASON=pool_full` 和当前池状态。

用 `AskUserQuestion` 询问：
- 选项 A：等待某个 slot 释放（用户自己决定哪个先释放）
- 选项 B：`pool-resize --size <N+1>` 扩容（约 80 秒/slot）
- 选项 C：走旧路 `setup-worktree.sh` 创建命名 worktree（适合长期 feature）

#### `exit 4` — 池未初始化

最常见的协作者首次场景。stderr 含 `EXIT_REASON=not_initialized`。

按项目铁律「任何需求都必须在 slot/worktree 里做」（[`docs/standards/10-agent-pool.md` § 不变量](../../../docs/standards/10-agent-pool.md#不变量) 第 7 条），**必须先 init 池再 claim**——不接受"在主仓库直接干"或"走旧路"作为快捷方式。

用 `AskUserQuestion` 询问：

```
未检测到 agent 池。本项目要求所有需求改动在 slot/worktree 里做，
需要现在初始化池吗？

选项：
  A. 现在初始化（默认 3 slot，约 5 分钟，占 ~9 GB 磁盘 + 200 MB 内存）—— 推荐
  B. 这次本任务用命名 worktree（仅当任务持续多周、属于长期 feature 时合理）
  C. 取消任务
```

- 选 A：跑 `bash scripts/dev/agent-pool/pool-init.sh`，完成后回到第 1 步重 claim
- 选 B：跳到"路径 B：命名 worktree"——**只**在长期 feature 场景合理（参考已有命名 worktree 如 `asset-management` / `recruitment`）
- 选 C：终止

**反例**：用户说"反正改动小，我就在主仓库直接干"——AI **不应**接受。回应："按项目规则任何改动都要在 slot 里，claim 一个 slot 只要 0.5 秒（池已存在的话）。请允许我先 init 池或选 B 走命名 worktree。"

#### `exit 5` — 池被显式禁用

`FFOA_AGENT_POOL_ENABLED=false`（CI 环境 / 资源紧张机器）。
**不询问用户**，自动走"路径 B"。

### 第 3 步：在 slot 内干活

```bash
cd "${FFOA_AGENT_DIR}"
# slot 已经有：
#   - 分支已切到 task-branch（基于最新 develop）
#   - .env 已配（独立端口 + 独立 DB + Caddy 域名）
#   - PG/Redis 容器已运行
#   - node_modules 已装好（pool-init 时预热）
#   - prisma client 已生成
```

启动开发服务器：

```bash
npm run dev
```

继续走对应开发 skill：
- 后端 → backend-main
- 前端 → frontend-main
- DB schema → database-main
- 需要先写文档 → docs-main

### 第 4 步：任务完成时释放 slot

```bash
bash scripts/dev/agent-pool/agent-release.sh
```

未提交改动会自动 stash 到 `wip/slot-N-<timestamp>` 分支保命。

## 路径 B：命名 worktree（fallback / 长期 feature）

适用场景：
- 池被禁用（exit 5）或用户在 exit 4 时选了 B
- **长期 feature**（持续多周），用户要语义命名（如 `asset-management`）
- 用户明确要求隔离的、长期保留的目录

```bash
bash scripts/dev/setup-worktree.sh \
  ~/Code/ffworkspace-wt/<short-name> \
  feature/<branch-name>
```

`setup-worktree.sh` 自动：分配端口 → 起 PG/Redis 容器 → 复制并改写 `.env`
→ 装 deps → `prisma db push` → 灌种子 → 注入 Caddy 域名 → 生成 TASK.md。

约 80-90 秒一次。

## 文档审查闸门（条件）

**触发**：本次涉及"新模块 / ≥ 3 份文档变更 / 触碰契约面（API、schema、状态机、权限、UI 规格）"——前一步调用 `docs-main` 后**必须**接 `doc-review`：

```
... → docs-main → doc-review → database-main / backend-main / frontend-main
```

**通过标准**：doc-review 报告 🔴 数量 ≤ 1 且 🟡 ≤ 2，才允许实现；否则停下由用户决策。

**跳过**：单文档小改 / 不触碰契约面 / 仅运维操作 — 直接跳过。

## 不要做的事

- ❌ 不要把"请运行 `bash xxx`"这种提示抛给用户——AI 是执行者，要么自己跑要么用 AskUserQuestion 问决策
- ❌ 不要默认假设要 setup-worktree.sh，先试 agent-claim
- ❌ 不要在 exit 5（禁用）时还硬上 agent-claim，自动走旧路
- ❌ 不要忘了 exit 0 时 `eval` 输出（不 eval 就拿不到 `$FFOA_AGENT_DIR`）

## 资源参考

- agent-pool README：[scripts/dev/agent-pool/README.md](../../../scripts/dev/agent-pool/README.md)
- 工作流主文档：[docs/standards/05-development-workflow.md](../../../docs/standards/05-development-workflow.md)
- setup-worktree.sh 端口分配规则、隔离架构：见上述 README

## 注意事项

- **钉钉 API 有 IP 白名单**：新环境首次调用钉钉接口可能报 errcode=88，要到钉钉开放平台加服务器出口 IP
- **合并到 develop 前先 `git fetch origin develop && git merge origin/develop`** 避免大量冲突
- **提交前跑 `/simplify` 和构建检查**
- **远端服务器 .env 可能是软链**：UAT/正式环境的 `backend/.env` / `frontend/.env` 软链到同一文件，改前先 `ls -la`