| name | flow |
| description | Post-planmode implementation workflow with quality gates. Use immediately after exiting planmode to execute an approved plan. |
Flow（严谨计划执行流）
退出 planmode 后立即执行本 skill。本 skill 包含从 worktree 隔离到合并分支的完整流程。
Step 0：隔离工作区（GATE 3）
⛔ 必须先建 worktree，再做任何其他操作。
调用 superpowers:using-git-worktrees 创建隔离分支（.worktrees/ 目录），切换到 worktree 目录。
Step 1：建立完整 TodoList
通过 plan-reader subagent 获取 plan 结构（见下方），然后用 TaskCreate 建立整个实施阶段的 todo list。List 不怕长，怕的是遗漏。
注：规划阶段（planmode 内）的 [research]、[plan-review]、[collie-review]、[exit] 此时应已全部标记为 completed（由 auto ExitPlanMode 步骤清理）。本步骤用 TaskCreate 在同一 TaskList 中追加实施阶段任务，不会也无需替换已完成的规划任务。
Plan-Reader Subagent（替代主 session 直接 Read）
从 session context 中提取 plan-source metadata → $PLAN_SOURCE。然后 dispatch 一个 haiku subagent（不在主 session 读 plan 文件）：
输入：$PLAN_SOURCE 文件绝对路径
任务：Read plan 文件全文，提取：
- Task Execution DAG 表（若存在）→ 直接用作 batch 分组和依赖基础
- 若 DAG 表缺失 → 从 task 描述中推断依赖，在 warnings 中标记
- 每个 task 的行号范围（
start/end line numbers）
- 文件冲突检查：同 batch 内各 task 的 Key files，若有重叠 → 加入 conflicts
输出格式（JSON）：
{
"plan_source": "/path/to/plan.md",
"plan_topic": "my-feature",
"tasks": [
{ "id": "task1", "subject": "...", "batch": 1, "depends_on": [], "key_files": ["src/foo.js"], "plan_lines": { "start": 45, "end": 103 } }
],
"conflicts": [
{ "batch": 1, "tasks": ["task1", "task3"], "shared_files": ["src/foo.js"] }
],
"warnings": []
}
主 session 拿到 JSON 后：
- 用
tasks 数组创建 TaskCreate（含 batch 和 blocked-by 信息）
- 若
conflicts 非空 → 评估：人工确认分 batch 或确认 task 不改同一区域
- 若
warnings 非空 → 记录，继续
TodoList 结构模板
每个有代码改动的 task 拆成两条，批次编号直接写入描述：
[task0] 归档计划文档- 对计划中每个有代码改动的 task：
[task N] <任务描述> [batch-X]（有外部依赖时追加 [blocked-by: task M]）[task N-CR] code review for task N [batch-Y, blocked-by: task N]
[e2e-setup] 建立 e2e 基建（条件：仅当 plan E2E Assessment 标注"需新建 e2e 基建"时创建）[e2e-verify] 运行 e2e / 集成测试，验证 critical path（条件：仅当 plan E2E Assessment 结论为 e2e_feasible: true 时创建）[test-verify] 运行单元测试，确保 0 失败[doc-refresh] 对照实现结果核对 README / CLAUDE.md / spec，补更新遗漏[collie-final-review] 最终 rubric 审查（worktree 清理前的 pre-merge gate，调用 collie:review Mode=code）[finish] finishing-a-development-branch
示例（3 个互相独立的 task）：
[task0] 归档计划文档
[task1] 实现功能 A [batch-1]
[task2] 实现功能 B [batch-1]
[task3] 实现功能 C [batch-1]
[task1-CR] code review task1 [batch-2, blocked-by: task1]
[task2-CR] code review task2 [batch-2, blocked-by: task2]
[task3-CR] code review task3 [batch-2, blocked-by: task3]
[e2e-setup] 建立 e2e 基建（条件性）
[e2e-verify] 运行 e2e / 集成测试（条件性）
[test-verify] 运行单元测试
[doc-refresh] 对照实现结果核对 README / CLAUDE.md / spec，补更新遗漏
[collie-final-review] 最终 rubric 审查（collie:review Mode=code）
[finish] finishing-a-development-branch
每完成一条立即标记，不得批量滞后更新。TodoList 是实施阶段的唯一进度看板。
Plan-Todo 交叉核对（建 list 后立即执行）
⛔ TodoList 建完后必须执行交叉核对，不得跳过。
Dispatch 一个 haiku subagent，prompt 自包含：
Plan archive: <$ARCHIVE_PATH>
TodoList snapshot: <当前所有 TaskCreate 条目的 subject 列表>
请逐条对比 plan 中的每个 task 与 TodoList 条目，输出差异报告：
- 匹配：plan task X → [task Y]
- 遗漏：plan task X → 无对应 TodoList 条目
- 多余：[task Z] → plan 中无对应 task（可接受，如 [task0]、[test-verify] 等流程性任务）
只报差异，无差异则输出"全部匹配"。
主 session 收到差异报告后：
- 遗漏 → 立即用 TaskCreate 补上
- 有意合并 → 必须给出具体解释（"plan task X 的工作已包含在 [task Y] 中，因为 …"），模糊解释不接受
- 无差异 → 继续
Step 2：归档计划文档（task0）
执行阶段 session context 里带有 plan 内容，但 planmode 原始文件路径不会自动传递。plan 文件的前三行嵌有元数据（由 /collie:auto Step 2 写入，hook 在 ExitPlanMode 前已验证存在）：
<!-- plan-source: /absolute/path/to/plan/file.md -->
<!-- plan-topic: my-feature-slug -->
<!-- plan-executor: collie:flow -->
归档流程：
- 从 session context 的 plan 内容中提取前三行，读出
$PLAN_SOURCE（原始文件路径）和 $PLAN_TOPIC（feature slug）（$PLAN_EXECUTOR 由 hook 验证，本 skill 无需读取）
- 构造目标路径：
docs/plans/YYYY-MM-DD-$PLAN_TOPIC-plan.md（记为 $ARCHIVE_PATH）
- ⛔ 必须用 Bash
cp 归档，禁止 Write/Edit（避免 LLM 改写内容）：
mkdir -p docs/plans
cp "$PLAN_SOURCE" "$ARCHIVE_PATH"
Fallback（元数据缺失或源文件不存在，理论上 hook 已拦截，但防御性处理）：
主 session 用 Write 工具把 plan 内容原样写入 $ARCHIVE_PATH，task0 备注原因。⛔ 禁止 dispatch subagent。
完成后立即将 task0 标记为 completed。
⚠️ $ARCHIVE_PATH 在 Step 3 有两个用途：
- 主 session dispatch 实现 subagent 时，连同 Step 1 记录的该 task 行号范围一起传入；subagent 用
Read(path, offset, limit) 精确读取对应段落，作为 VBC 的 acceptance criteria 来源（主 session 不提取内容，零 context 膨胀）
- CR subagent 需要全局视角，直接传入路径，按需读取
Step 3：执行计划（GATE 4）
⛔ 所有实现工作必须卸载给 subagent，主 session 只做协调和审查，不在主 session 里写代码。
按批次逐批执行：
- 找出当前 batch 中所有 pending 且
[blocked-by] 已全部完成的 task
- 调用
superpowers:dispatching-parallel-agents，一次性 dispatch 整批
- 等本批全部完成后，进入下一批
⚠️ 强制注入到每个实现 subagent prompt 的三项参数（缺一不可）：
- Worktree 路径：subagent 必须在该目录下工作，否则破坏 worktree 隔离
$ARCHIVE_PATH（plan 归档绝对路径）：subagent 从该文件读取 plan 段落- Task 行号范围（Step 1 记录的
lines X-Y）：subagent 用此范围精确定位，无需 grep
Dispatch prompt 模板（每个实现 subagent）
Worktree: <绝对路径>
Plan archive: <$ARCHIVE_PATH 绝对路径>
Plan lines for this task: <lines X-Y>
Your task: [task N] <一句话概要>
在 worktree 目录下执行本 task。调用 superpowers:verification-before-completion 时，
"Re-read plan" 步骤必须先执行：
Read(file=Plan archive, offset=X-1, limit=Y-X+1)
读取本 task 对应的 plan 原文段落，以其中的 acceptance criteria 逐条生成 checklist 并验证。
不得只验 prompt 里的任务概要描述。
所有 git commit 的 message body 必须包含：
Refs: <$ARCHIVE_PATH 的相对路径，如 docs/plans/2026-04-16-my-feature-plan.md>
CR subagent 的 prompt 模板
Worktree: <绝对路径>
Plan archive: <$ARCHIVE_PATH 绝对路径>
Review target: [task N] 的实现
请 Read Plan archive 中与 task N 相关的段落，对照实现做完整性和质量审查。
调用 superpowers:requesting-code-review。
CR subagent 需要全局视角（跨 task 一致性），直接传路径让它按需读取比 inline 更合适。
Step 4：每条 Todo 的执行要求
[task N]（实现 task）
subagent 内部按 TDD 流程执行，缺一不可：
- 调用
superpowers:test-driven-development — 先写失败测试，再写最小实现使测试通过
- 调用
superpowers:verification-before-completion — 提供新鲜的验证证据后才能声明完成
- VBC 的 "Re-read plan" 步骤：用 prompt 里的
Plan archive 路径和 Plan lines 行号，执行 Read(offset=X-1, limit=Y-X+1) 读取本 task 对应 plan 段落，以其中 acceptance criteria 逐条生成 checklist 并验证
- ⛔ 只验 prompt 里的任务概要描述 = 退化为 task-level 自证 = VBC 失效
[task N-CR]（CR task）
⛔ 必须另起独立 subagent 执行。
⛔ 禁止在实现该 task 的 subagent 内自我 review（自审盲区），禁止在主 session 执行。
subagent 调用 superpowers:requesting-code-review。
收到 CR 反馈后，主 session 遵循 superpowers:receiving-code-review — 技术验证，不盲目同意。
CR 发现需修复的问题时（receiving-code-review 确认修复有效后）：
⛔ 禁止主 session 直接写代码修复。 即使只改一行——了解"如何改"本身需要读取源码文件，会污染主 session 上下文。
必须 dispatch 新的修复 subagent，传入：
- CR issue 清单（引用 CR 原文）
- worktree 绝对路径
$ARCHIVE_PATH（plan 归档路径，按需参考）- 受影响的文件路径（CR 报告中通常已含）
修复 subagent 完成后，dispatch 新的 CR subagent 验证修复结果。
修复→验证循环直到 CR 通过或主 session 判断需要升级处理。
Step 5：测试全通（GATE 5.9）
⛔ 进入收尾前的强制检查，不得跳过。
- 运行完整单元测试套件，确保 0 失败
- 集成测试／E2E：按 plan E2E Assessment 的结论执行。plan 确认
e2e_feasible: true 的，必须运行且通过；plan 标注 e2e_feasible: false 且理由充分的，可跳过
- 有失败用例 → 必须修复，不得注释掉或跳过
Step 5.5：文档对齐（GATE 5.95）
⛔ 收尾前必须完成的文档核对，不得跳过。
按以下顺序逐项核对：
- README.md — 如果本次改动影响了 README 中描述的命令 / 工作流 / 配置 / 架构，必须同步更新
- CLAUDE.md — 如果本次改动影响了 CLAUDE.md 中描述的约束 / hook / state 文件 / 红线，必须同步更新
- docs/*-spec.md — 如果实现过程中发现的新认知与 spec 有偏差，或学到了新 pitfall，必须回写到对应 spec
- docs/plans/ — 本次计划文档已在 Step 2 归档，无需重复
.claude/skills/*/SKILL.md — 如果本次改动新增或更新了项目级 skill，必须同步更新对应 SKILL.md- Deferred cleanup — 检查 plan 文件（
$ARCHIVE_PATH）中是否包含 <!-- consumed-deferred: ... --> metadata。若有，删除对应的 deferred 文件（rm docs/plans/<topic>-deferred.md）。这些 scope 已在本次 plan 中交付，deferred 文件完成使命。
新增或更新项目级 skill 时的硬约束：必须调用 Skill('skill-creator')（由 superpowers plugin 提供）生成或更新 .claude/skills/<slug>/SKILL.md。禁止 free-form prose 写入——这保证产出的 skill 遵守 frontmatter / Concise is Key / references 规范，能被其他 Claude session 正确发现和加载。
判断"是否需要新增/更新 skill"的启发见 skills/review/references/rubric-red-lines.md Red line #12 补充说明。
如果 plan 阶段已规划好对应的 doc 更新任务（通过 plan-doc-reviewer 和 collie:review 的审查），这一步通常只是快速确认。
如果没有规划，说明 plan 阶段双 reviewer 漏检，这一步就是安全网——必须补上再进入 Step 6。
豁免情况：本次改动仅限于内部逻辑（无 user-facing 命令 / workflow / 配置 / 约束变更），且未新增 agent / skill / hook，可在 TodoList 里把 [doc-refresh] 直接标记为 N/A 并注明理由。
Step 5.7：最终 rubric 审查（GATE 5.7）
⛔ worktree 清理前最后一道 rubric gate，不得跳过。
调用方式
Skill("collie:review")
Mode=code
Target=<当前 worktree 绝对路径 或 "worktree diff">
Context="Plan: $ARCHIVE_PATH（from task0）"
Gate 语义
- PASS → 进入 Step 6
- WARN → 必须修复 WARN 项后重跑，不得跳过
- BLOCK → 必须修复 BLOCK 项后重跑，不得跳过
WARN / BLOCK 处理
⛔ 禁止主 session 直接写代码修复，理由与 [task N-CR] 的 CR 处理一致（读源码会污染主 session 上下文）。
修复流程：
- 从 rubric review 输出中提取所有 FAIL 问题（Red line 违规 + 逐条 question FAIL）
- Dispatch 修复 subagent，传入：
- FAIL 问题清单（引用 review 原文）
- worktree 绝对路径
$ARCHIVE_PATH（plan 归档路径）
- 修复 subagent 完成后，dispatch 新的
Skill("collie:review") with 同样 Mode/Target/Context
- 修复 → 重审循环直到 PASS
- 连续 3 轮仍 BLOCK → 升级（通过
scripts/escalate.sh 上报，等用户介入）
⛔ 禁止退出 flow 返回 auto.md 层修复——TodoList 状态会丢失，CR 历史链断裂。
与 [task N-CR] 的区别
[task N-CR]：per-task 粒度，使用 superpowers:requesting-code-review，关注单个 task 的实现质量[collie-final-review]：整体 rubric 粒度，使用 collie:review Mode=code，关注所有改动聚合后的 13 红线 + 6 问题 + ELEPHANT
两者互补，不重复。
Step 6：收尾（GATE 6）
⛔ 仅在 Step 5.7（GATE 5.7）[collie-final-review] 返回 PASS 后进入。
调用 superpowers:finishing-a-development-branch（合并 / PR / 清理 worktree）。
