| name | subagent-driven-development |
| description | Use when executing implementation plans with independent tasks. Dispatches a fresh subagent per task with TDD + quality gate + code review. Required after writing-plans skill. Terminal state: invokes finishing-a-development-branch skill. |
Subagent 驱动开发
标准开发流程的执行引擎。非降级场景默认使用。
持续执行原则
任务间不停下来询问"是否继续"。完成一个任务后立即进入下一个。
允许停下的三种情况：
- BLOCKED：遇到无法独立解决的阻塞，需用户介入
- 真正的歧义：任务意图不明确，继续会导致方向性错误
- 全部任务完成：计划中所有任务均已通过门控
其他情况一律持续执行。
Phase 0a：工作区隔离（建议）
调用 using-git-worktrees skill，确保实现工作发生在隔离工作区：
- 已在 linked worktree → skill 自动检测并跳过创建
- 在主仓库 → skill 询问用户是否建 worktree（路径
.claude/worktrees/<branch>/）
- 用户拒绝 → 在原地继续
这不是 IRON LAW，是工程建议。 用户可拒绝。但默认应建议建。
skill 同时负责 baseline 测试验证；baseline 失败时由 skill 阻塞，控制权交回用户。
完成后进入 Phase 0。
Phase 0：环境就绪检查
从 docs/changes/<feature>/tasks.md 的「环境前置（Environment Prerequisites）」段读取依赖清单，逐项验证：
- 执行每项的 Verify 命令，收集结果
- 全部通过 → 进入 Phase 1
- 有失败 → 列出失败项 + 错误输出 + 计划中的 Suggested Fix → 阻塞等待用户手动处理 → 用户确认后重验 → 全部通过才继续
不自动执行 Fix 命令。环境准备是用户的责任。
Phase 1：加载与校验
- 读取
docs/changes/<feature>/tasks.md（由 writing-plans skill 产出）
- 提取所有任务文本
- 检查粒度：每任务 1-3 文件，有独立 TDD 步骤和审查门控
- 如果任务涉及 UI，实现前确认计划已引用：
DESIGN.md（如存在）docs/designs/<feature>/review-verdict.mddocs/designs/<feature>/tokens/docs/designs/<feature>/components/*.md- 已记录的 design identity gap 及其用户决策
- 不合格 → 报告用户，建议重新拆分
Controller 传递契约
SDD 精确约束了 implementer 能做什么（见 implementer-prompt），但 controller 把任务交出去时同样受契约约束。controller 违约不会被 implementer-prompt 自动拦截——这是 controller 自身纪律。
不变量：传规格，不传实现
调度 implementer（Phase 2 Step 1）时，{{TASK_TEXT}} 替换内容及任何附加上下文：
| 可传 | 不可传 |
|---|
| 任务规格、验收标准、GREEN 条件 | 可直接誊抄的完整函数体 / 实现源码 |
| 接口签名、数据结构契约、类型定义 | 逐行实现指令（"把这段代码写进去"） |
| 测试场景、必测边界、依赖说明 | 任何绕过 RED→GREEN 的现成答案 |
理由：implementer 必须靠 RED→GREEN 自行设计。controller 把实现喂进 prompt → implementer 退化为誊写工 → TDD 设计发现价值归零 → code-review 也查不出设计问题（设计未经独立检验，是 controller 单方拍定）。
判据：接口签名/数据契约是"做什么"的边界，可传；函数体是"怎么做"的答案，不可传。
不变量：派发集合不随序列漂移
per-task code-review 的 reviewer 派发集合由 diff 特征决定，不因任务序号、不为"提速 / 避免 cold-start"在长任务序列中段简并或合并。每个任务独立按规则推导派发集合，前一任务的派发方式不构成本任务的依据。执行机制见 code-review skill「派发自检」段。
不变量：带上已审定决策
调用 per-task code-review 时，传入 plan「已审定决策」段原文作为 ratified_decisions。来源唯一：该清单只能从 plan 文件读取原样传入，controller 不得运行时构造、改写或追加——否则它退化为"想绕过的审查塞进清单即免责"的后门。无该段则传空。reviewer 据此只降级"如实落实已审定决策的实现"，偏离清单或清单外的问题照常按 severity 判定。
Phase 2：逐任务执行循环
对每个任务顺序执行以下步骤：
记录起点： base_SHA = $(git rev-parse HEAD)，用于后续 diff 计算和审查范围。
Step 1：调度 implementer subagent
读取 implementer-prompt.md 模板，将 {{TASK_TEXT}} 替换为当前任务完整文本后，通过 Task(subagent_type="general-purpose") 调度。替换内容与任何附加上下文必须遵守 Controller 传递契约（传规格不传实现）。
模型选择（在 Task 的 model 参数中指定）：
| 判断条件 | 模型 |
|---|
| 1-2 个文件 + 完整规格（无歧义） | haiku |
| 多文件集成 / 需要跨模块协调 | sonnet |
| 架构判断 / 复杂设计决策 | opus |
上下文隔离： 不让 subagent 读计划文件，所有信息通过 prompt 传递。
提问处理：
如果 implementer 在开始工作前提问（通过 NEEDS_CONTEXT 或显式提问）→ Controller 回答问题 → 重新调度（fresh subagent，携带原始任务文本 + 回答）。
不要忽略提问。提问说明信息不足，强行执行会导致方向性错误。
状态处理：
| 状态 | 处理 |
|---|
| DONE | → Step 2 |
| DONE_WITH_CONCERNS | 记录关注点 → Step 2 |
| BLOCKED | 报告用户，拆分任务或补充上下文 |
| NEEDS_CONTEXT | 补充信息，重新调度（fresh subagent） |
Step 2：质量门控
调用 /code-quality-gate skill：格式化 → lint → 类型检查 → debug 产物检测。
通过 → Step 3。
失败处理：
- 将「质量门控错误输出 + 当前任务文本」构造为新 prompt
- 重新调度 新的 implementer subagent（同样 general-purpose + implementer-prompt.md） 修复（使用与 Step 1 相同的模型）
- 修复完成后重跑 Step 2
- 主代理不自己读完整错误输出后改代码
Step 3：代码审查
调用 /code-review (per-task)：
task_text = 当前任务完整文本diff = git diff <base_SHA>（包含未提交的工作区变更）base_SHA / head_SHA = Phase 2 起点记录的 base_SHA + 当前 HEADimplementer_report = Step 1 的 implementer 状态报告
APPROVE → Step 4。
BLOCK → 调用 /review-handling 处理反馈 → 构造修复 prompt → 重新调度 implementer subagent 修复 → 修复完成后回到 Step 2。
修复者是 implementer subagent，不是主代理。主代理不读审查反馈后自己改代码。
Step 4：门控判定 + 提交
审查通过：
- 将工作区变更 commit（Conventional Commits 格式，scope + description 从任务描述提取）
- 记录新的
head_SHA
- 标记任务完成 → 下一任务
未通过： 反馈已在 Step 3 转回 implementer subagent；待修复完成后重新从 Step 2 开始。
Phase 3：全局审查
所有任务通过 Phase 2 后，调用 /code-review (global)：
plan_text = tasks.md 全文（所有任务）task_summaries = 每个任务的 implementer 状态报告摘要（DONE / DONE_WITH_CONCERNS + 关键决策）full_diff = git diff <first_base_SHA>..HEADbase_SHA = 第一个任务的 base_SHAhead_SHA = HEAD
APPROVE → Phase 4。
BLOCK → 调用 /review-handling 处理反馈 → 构造修复 prompt → 重新调度 implementer subagent 修复 → 修复完成后重新 Phase 3。
修复者是 implementer subagent，不是主代理。
Phase 4：收尾
Phase 3 通过后，调用 /finishing-a-development-branch skill：验证测试 → 文档与产物清理 → commit 整理 → 环境检测 → 呈现集成选项 → 执行并清理工作区。
反逃避机制
NEVER： 跳过任务 TDD 循环 / 跳过质量门控 / 合并多任务审查 / 审查未通过就下一任务 / 让子代理读计划文件 / 自行判定"太简单不需要 TDD" / 批量写测试或批量实现 / 在 implementer prompt 中放入可直接誊抄的完整实现（违反传递契约：传规格不传实现）
修复者是 implementer subagent，不是主代理。 主代理不得在收到审查反馈后自己修改代码。
Red Flags： 跳过审查的理由是"改动小" / 多任务合并审查 / 子代理状态不明确 / 先实现后补测试 / 问题标记为"后续处理"
→ 出现任何 Red Flag → 停止，当前任务重新开始。
模型选择
| 步骤 | 模型 | 备注 |
|---|
| Step 1 implementer（简单） | haiku | 1-2 文件 + 完整规格（general-purpose） |
| Step 1 implementer（标准） | sonnet | 多文件集成（general-purpose） |
| Step 1 implementer（架构） | opus | 需要架构判断（general-purpose） |
| Step 3 代码审查 | 见 code-review skill | 派发规则和模型选择由 code-review skill 管理 |
| Phase 3 全局审查 | 见 code-review skill | 同上 |
无子代理时的回退
主会话顺序执行每任务 TDD 循环（参考 implementer-prompt.md 的 TDD 执行链）：写测试 → RED → 实现 → GREEN → 重构 → 质量门控 → 调用 /code-review (per-task) → 审查通过后 commit。逐任务串行，不跳跃。
关键原则
- 隔离：每任务独立上下文（fresh subagent）
- 串行：任务间严格顺序
- 审查委托：代码审查通过
/code-review skill 统一调度，不在 SDD 内管理 reviewer 派发
- 门控：每任务必须通过 TDD + 质量门控 + 代码审查
- 当场修复：审查问题不拖延，修复闭环始终通过 implementer subagent
- 持续执行：任务间不询问"是否继续"
Integration
前置 skill（建议触发）：
using-git-worktrees —— Phase 0a 调用，确保隔离工作区（已在 worktree 则跳过）
后继 skill（必触发）：
code-review —— Phase 2 Step 3 / Phase 3 调度review-handling —— code-review BLOCK 时finishing-a-development-branch —— Phase 4 收尾，凭路径溯源清理 .claude/worktrees/ 下的 worktree
