subagent-driven-development

子 Agent 驱动开发

通过为每项任务分派一个全新的子 Agent 来执行计划，并在每项任务后进行两阶段审查：先审查规范符合性，再审查代码质量。

为什么使用子 Agent： 你可以将任务委派给拥有独立上下文的专用 Agent。通过精心编写指令和提供上下文，确保它们专注于任务并顺利完成。它们绝不应继承你当前会话的上下文或历史记录——你要准确构建它们所需的信息。这也能保留你自己的上下文，用于协调工作。

核心原则： 每项任务使用全新的子 Agent + 两阶段审查（先审查规范，再审查质量）= 高质量、快速迭代

持续执行： 不要在任务之间停下来向人类伙伴确认。按照计划不间断地执行所有任务。只有以下列出的四种情况，或所有任务均已完成时，才可以停止。“要继续吗？”之类的提示和进度总结会浪费他们的时间——他们让你执行计划，那就执行。

做出裁定，不要停滞。 正在执行的计划不应等待人类回应。遇到冲突、歧义、计划缺陷，或你原本想征求同意后才会超出限制的情况，都由你做决定。规范具有约束力，计划是对规范的解释，而规范和计划都未能解答的问题则由你判断。将每项决定记录在台账中，格式为 Ruling: <what you decided> — <why> — <what it costs if wrong>，然后继续执行。错误的裁定会导致返工，人类伙伴可以看到并撤销；但暂停会话等待答复会耗费他们一整天，毫无益处。

只有以下四种情况需要停止：不可逆或破坏性操作；涉及安全的操作；规范要求事先征求同意的工作区之外的副作用（如合并、推送到共享分支、发布）；以及计划存在严重缺陷，导致所有可行路径都只能靠猜测。遇到这些情况时，停止并询问。

适用场景

digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];
    "executing-plans" [shape=box];
    "Manual execution or brainstorm first" [shape=box];

    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
}

与执行计划（并行会话）的区别：

• 同一会话（无需切换上下文）
• 每项任务使用全新的子 Agent（避免上下文污染）
• 每项任务后进行两阶段审查：先审查规范符合性，再审查代码质量
• 迭代更快（任务之间不需要人工介入）

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
        "Implementer asks questions?" [shape=diamond];
        "Answer questions, provide context" [shape=box];
        "Implementer implements, tests, commits, self-reviews" [shape=box];
        "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" [shape=box];
        "Spec ✅ and quality approved?" [shape=diamond];
        "Finding conflicts with plan text?" [shape=diamond];
        "Rule on the conflict, ledger the ruling" [shape=box];
        "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [shape=box];
        "Dispatch scoped re-review (./re-review-prompt.md)" [shape=box];
        "All findings addressed?" [shape=diamond];
        "R = 5?" [shape=diamond];
        "Adjudicate each open finding" [shape=box];
        "Any load-bearing finding?" [shape=diamond];
        "Rule and continue; stop only if every path forward is a guess" [shape=box];
        "Park findings in ledger with rulings" [shape=box];
        "Append completion to ledger, TaskUpdate: mark task completed" [shape=box];
    }

    "Setup: worktree, ledger check, read plan, pre-flight review" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [shape=box];
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" [shape=box];
    "Final review clean: delete this plan's workspace" [shape=box];
    "Use superpowers-extended-cc:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];

    "Setup: worktree, ledger check, read plan, pre-flight review" -> "Dispatch implementer subagent (./implementer-prompt.md)";
    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer asks questions?";
    "Implementer asks questions?" -> "Answer questions, provide context" [label="yes"];
    "Answer questions, provide context" -> "Implementer implements, tests, commits, self-reviews";
    "Implementer asks questions?" -> "Implementer implements, tests, commits, self-reviews" [label="no"];
    "Implementer implements, tests, commits, self-reviews" -> "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)";
    "Generate review package, dispatch task reviewer (./task-reviewer-prompt.md)" -> "Spec ✅ and quality approved?";
    "Spec ✅ and quality approved?" -> "Append completion to ledger, TaskUpdate: mark task completed" [label="yes"];
    "Spec ✅ and quality approved?" -> "Finding conflicts with plan text?" [label="no"];
    "Finding conflicts with plan text?" -> "Rule on the conflict, ledger the ruling" [label="yes"];
    "Rule on the conflict, ledger the ruling" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model";
    "Finding conflicts with plan text?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no"];
    "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" -> "Dispatch scoped re-review (./re-review-prompt.md)";
    "Dispatch scoped re-review (./re-review-prompt.md)" -> "All findings addressed?";
    "All findings addressed?" -> "Append completion to ledger, TaskUpdate: mark task completed" [label="yes"];
    "All findings addressed?" -> "R = 5?" [label="no"];
    "R = 5?" -> "Fix round R of 5: R≤3 resume implementer; R≥4 fresh implementer, more capable model" [label="no - next round"];
    "R = 5?" -> "Adjudicate each open finding" [label="yes - breaker trips"];
    "Adjudicate each open finding" -> "Any load-bearing finding?";
    "Any load-bearing finding?" -> "Rule and continue; stop only if every path forward is a guess" [label="yes"];
    "Any load-bearing finding?" -> "Park findings in ledger with rulings" [label="no"];
    "Park findings in ledger with rulings" -> "Append completion to ledger, TaskUpdate: mark task completed";
    "Append completion to ledger, TaskUpdate: mark task completed" -> "More tasks remain?";
    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
    "More tasks remain?" -> "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" [label="no"];
    "Dispatch final code reviewer (../requesting-code-review/code-reviewer.md)" -> "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals";
    "Final findings? ONE fix dispatch, one scoped re-review, adjudicate residuals" -> "Final review clean: delete this plan's workspace";
    "Final review clean: delete this plan's workspace" -> "Use superpowers-extended-cc:finishing-a-development-branch";
}

设置

确保工作在隔离的工作区中进行：使用 superpowers-extended-cc:using-git-worktrees 创建工作区，或验证现有工作区。 未经人类伙伴明确同意，绝不要在 main/master 分支上开始实现。

会话压缩后，对话记忆不会保留。在真实会话中，忘记进度的控制器曾重新分派整组已完成的任务——这是观察到的代价最高的失败。请将进度记录在台账文件中，而不只是任务列表中。

• 每个计划都有自己的工作区：技能启动时，运行此技能的 scripts/sdd-workspace PLAN_FILE——它会打印该计划被 git 忽略的 目录（<repo-root>/.superpowers/sdd/<plan-basename>/），其中存放 此计划的所有产物：台账、简报、报告、评审包。 你不得读取或写入其他计划的目录。
• 检查此计划的台账 <workspace>/progress.md。如果其首行写明了你的计划文件，则带有 Task <N>: complete 行的任务已完成——不要再次分派；从第一个尚无此行的任务继续。最后一行是修复轮次的任务仍处于循环中：从下一轮继续。如果台账首行写明的是其他计划文件，或者旧的扁平路径 .superpowers/sdd/progress.md 下有遗留台账，那就是其他计划的进度：保留原样，并为你自己的计划从头开始。
• 创建台账，并将其身份标记作为首行： # SDD ledger — plan: <plan file path>。
• 台账是你的恢复地图：其中记录的提交都存在于 git 中，即使你已不记得创建它们。压缩后，相信台账和 git log，不要依赖自己的回忆。
• git clean -fdx 会销毁工作区（它是被 git 忽略的临时目录）；如果发生这种情况，请从 git log 恢复。
• 台账记录的是状态，而非推理。条目应采用此技能规定的单行格式（分派、修复轮次、完成、次要、搁置、BLOCKED）——一项事件一行；只有搁置裁定可以占三行。不要记录方法论叙述、评审者的赞许、自我纠正长文，也不要重述先前条目中的事实——之后每一轮都会重新读取每一条多余内容。关于你自身流程的经验不属于状态：请放进给人类伙伴的最终报告，因为 Finish 时会删除工作区（包括此文件），写在这里的内容也会随之消失。
• 使用 shell 追加方式（cat >> progress.md <<'EOF'）添加条目，不要用 Edit 工具——随着文件增长，Edit 会重新发送锚定文本，而且每添加一条都会触发权限提示。

通读计划一次，记下其上下文和全局约束。如果计划指定了 Spec，也要阅读：Spec 是计划论述所依据的权威，计划内部的冲突应以 Spec 为准。若计划没有可访问的 Spec，则在台账中注明——没有 Spec 时作出的裁定均为暂定。

分派 Task 1 前，通读计划一次，边检查边记录检查内容，查找冲突：

• 相互矛盾的任务，或与计划的全局约束矛盾的内容
• 计划明确要求、但评审标准视为缺陷的内容（例如不验证任何内容的测试、逐字重复的逻辑代码块）

检查结果应以表格呈现，而非直接下结论。每对共享文件或接口的任务各占一行：列出两个任务、一方产出的内容与另一方消费的内容，以及检查结果。每个任务也各占一行：说明任务自身内容是否一致——其指定的测试是否与指定的代码相符、创建的文件是否与之后触及的文件相符。没有这些行就声称“检查无误”，不算真正执行了检查。

将表格写入台账。在执行开始前，对发现的所有问题作出裁定——每项都要对照计划中要求该内容的文本——并将每项裁定记录到台账。如果检查无误，则无需评论。对检查发现的每项冲突作出裁定——Spec 是约束性权威，计划是对 Spec 的论述——将裁定记录在对应行旁边，并针对计划中的每个任务调用 TaskCreate，附上完整任务文本。

使用元数据进行派发

派发实现子代理时：

1. 通过 TaskGet 读取任务描述——元数据嵌入在末尾的 json:metadata 代码围栏中
2. 解析元数据 JSON，并将字段（files、acceptanceCriteria、verifyCommand）映射到实现者提示词的对应部分
3. 实现者应收到所有结构化数据——不要让他们从散文描述中自行解析
4. 对于用户关卡任务，不要重新决定计划已确定的内容：按原样派发已确定的验证，除非自规划以来出现了实质性条件变化（不同的 fixture/分支、新的阻塞因素、计划假设失效）——条件没有变化却重新询问已确定的做法，就是绕过关卡。

模型选择

为每个角色选择能够胜任的最低能力模型，以节省成本并提高速度。

机械式实现任务（独立函数、明确规格、1-2 个文件）：使用快速、低成本的模型。计划明确的情况下，大多数实现任务都是机械式的。

集成与判断类任务（多文件协调、模式匹配、调试）：使用标准模型。

架构、设计和审查任务：使用能力最强的可用模型。

审查任务：根据差异的大小、复杂度和风险，选择判断能力相当的模型。小型机械式差异不需要最强模型；微妙的并发变更则需要。对小型修复差异进行范围明确的复审，可使用低到中档模型。

修复循环升级（第 4-5 轮）：使用至少比陷入困境的实现者高一个档次的模型。

派发子代理时始终明确指定模型。 如果省略模型，就会继承会话所用模型——通常是能力最强、成本也最高的模型，从而在不知不觉中违背本节的要求。

轮次数比 Token 价格更重要。 墙钟时间和上下文成本会随着子代理轮次数增加；最便宜的模型在多步骤任务中通常需要多出 2-3 倍的轮次——总体成本反而更高。审查者以及根据散文描述工作的实现者，至少使用中档模型。当任务计划文本包含要编写的完整代码时，实现只是转录加测试：这类实现者可使用最低档模型。单文件机械式修复也可使用最低档模型。

任务复杂度信号（实现任务）：

• 涉及 1-2 个文件且规格完整 → 低成本模型
• 涉及多个文件且有集成问题 → 标准模型
• 需要设计判断或广泛理解代码库 → 能力最强的模型

任务循环

批量处理同类小任务。 如果计划列出多个彼此独立、编辑类型相同的小任务——例如在多个文件中重复进行同一种单行修复、常量变更或字段添加——不要为每个任务派发一个子代理。整理成一份派发说明，列出所有文件及其变更，然后一次性派发给同一个子代理，并将其差异作为一个整体审查。只有当任务需要独立判断、独立测试或独立审查范围时，才逐个派发。

你粘贴到派发提示中的所有内容——以及子代理返回的所有内容——都会在整个会话期间留在上下文中，并在之后的每一轮重新读取。通过文件移交交付物。

等待已派发的子代理： 不要使用很短的超时轮询等待接口，也不要一直默默等待而不设时限。当你还有本地工作时——更新台账、准备下一轮审查、阅读报告——继续工作；子代理结果会自行到达。确实无事可做时，以有界时段等待（平台允许时，每次五到十分钟），并在各时段之间发送一行状态信息、核对正在运行的子代理：列出它们，并跟进那些已完成却未报告的子代理。有界等待几乎能保留长时间等待的全部效率，同时确保在几分钟内发现卡住或丢失的子代理，而不是等到会话结束才发现。

1. 指派实现人员

在指派前记录 BASE（git rev-parse HEAD）——审查材料包和修复轮次的差异都需要它。

• 任务简报： 指派实现人员前，运行此技能的 scripts/task-brief PLAN_FILE N——它会将任务完整文本提取到一个唯一命名的文件中，并打印文件路径。撰写指派内容时，应让简报成为唯一的需求来源。指派内容应包含：（1）一行说明此任务在项目中的位置；（2）简报路径，前面加上“先阅读此文件——它是需求来源，具体值必须逐字照用”；（3）简报无法获知的早期任务接口和决策；（4）你对简报中所发现歧义的处理方式；（5）报告文件路径和报告要求。具体值（数字、魔法字符串、签名、测试用例）只能出现在简报中。绝不要让子代理阅读整个计划文件。
• 报告文件： 根据简报命名实现人员的报告文件（简报 …/task-N-brief.md → 报告 …/task-N-report.md），并将其写入指派提示词。实现人员需在该文件中撰写完整报告，并且只返回状态、提交记录、一行测试摘要和关注事项。
• 指派提示词只描述一个任务，不描述本次会话的历史。不要在后续指派中粘贴累积的前序任务摘要（例如“任务 1-3 完成后的状态”）——一次实际会话的指派内容曾达到 42k 个字符，其中 99% 都是粘贴的历史记录。新子代理只需要了解它的任务、涉及的接口和全局约束，不需要其他内容。
• 指派内容必须包含不得使用子代理的约定（该约定也写在实现人员模板中）：实现人员绝不指派子代理——既不能指派助手，也不能指派审查人员。审查由你在收到报告后进行。实际会话中，工作者指派的每位审查人员都会重复控制者已经安排的任务审查——每个任务都多占用一个完整的审查席位。
• 如果早期任务在本任务涉及的区域留下了待处理发现，需在指派内容中指向相应的记录条目。
• 记录指派结果中实现人员的 Agent 身份——修复循环第 1-3 轮都要恢复使用该 Agent。
• 绝不要并行指派多个实现子代理（会产生冲突）。

模板：implementer-prompt.md

2. 处理报告

实现子代理会报告以下四种状态之一。请分别妥善处理：

DONE： 生成评审包（在此技能目录中运行 scripts/review-package PLAN_FILE BASE HEAD；该命令会打印写入文件的唯一路径；BASE 是你在派发实现子代理前记录的提交，绝不能使用 HEAD~1，否则多提交任务中除最后一次提交外的所有提交都会被悄然遗漏），然后将打印出的路径提供给任务评审子代理。只有在收到实现子代理的报告后才能生成评审包，绝不能在其仍在工作时生成——差异内容可能变化，提前生成的包会过时。

DONE_WITH_CONCERNS： 实现子代理已完成工作，但提出了疑虑。继续之前请阅读这些疑虑。如果疑虑涉及正确性或范围，请在评审前处理。如果只是观察（例如“这个文件越来越大”），请记录下来并继续评审。

NEEDS_CONTEXT： 实现子代理需要未提供的信息。请补充缺失的上下文并重新派发。

BLOCKED： 实现子代理无法完成任务。请评估阻碍：

1. 如果是上下文问题，请补充更多上下文，并使用相同模型重新派发
2. 如果任务需要更强的推理能力，请使用能力更强的模型重新派发
3. 如果任务规模过大，请拆分为更小的部分
4. 如果计划本身有误，请裁定修正方案，将其记入记录，并在重新派发时附上该裁定

绝不能忽视升级请求或在不作任何调整的情况下让同一个模型重试。如果实现子代理表示遇到了困难，就必须有所改变。

如果实现子代理在开始前或执行过程中提出问题，请清晰、完整地回答；如有需要，请补充上下文，切勿催促其开始实现。

向人工协作伙伴升级问题

对于任何执行期间的 AskUserQuestion——无论是计划脚本提出的，还是由实现子代理转交的——都必须先：

1. 重新阅读计划头部的“用户决策（已作出）”。如果已有记录的决策能回答该问题，请直接采用该答案，而不是提问。
2. 如果确实需要提问，请根据计划中的事实说明相关产物及其作用或状态（不能只说名称），并在每个选项的描述中说明哪些内容会改变、哪些内容保持不变。人工协作伙伴并不了解计划的全部内容；缺少上下文的建议会让人误以为你在提出新方案。

3. 审查任务

每项任务的审查都是针对该任务的关卡。全面审查只在最终的整个分支审查中进行。绝不要跳过任务审查，也绝不要接受缺少任一结论的报告——必须同时满足规范合规性和任务质量要求。实现者的自我审查不能替代任务审查；两者都不可少。

• 将差异文件交给审查者：运行此技能的 scripts/review-package PLAN_FILE BASE HEAD，并将其输出的文件路径 提供给审查者（或者，不使用 bash 时：将该范围的 git log --oneline、git diff --stat 和 git diff -U10 重定向到一个唯一命名的 文件）。输出不会进入你自己的上下文，审查者可以通过一次 Read 调用看到提交列表、统计摘要，以及包含上下文的完整差异。使用你在派发实现者之前记录的 BASE——绝不要用 HEAD~1，否则多次提交的任务会被悄悄截断。没有差异文件，绝不要派发任务审查者。
• **审查者输入：**任务审查者会收到三个路径——同一份简述文件、报告文件和审查包——以及对该任务有约束力的全局约束。
• 提供给审查者的全局约束区块是其关注重点。请从计划的「全局约束」部分或规范中原样复制具有约束力的要求，包括精确值、精确格式，以及组件之间明确规定的关系（“布局与 X 相同”、“与 Y 匹配”）。审查者的模板已包含流程规则（YAGNI、测试卫生、审查方法）——约束区块应写明本项目规范的具体要求。
• 除非有具体的任务相关理由，否则不要添加“检查所有用法”或“如果有用就运行竞态测试”之类的开放式指令。
• 不要要求审查者重新运行实现者已针对同一代码运行过的测试——实现者的报告已包含测试证据。
• 不要预先替审查者判断问题——绝不要指示审查者忽略或不要报告某个具体问题。如果你认为某项发现是假阳性，应让审查者提出，再在审查循环中裁定。如果你写的提示中出现“不要报告”、“不要把 X 视为缺陷”、“最多 Minor”或“计划选择了”，就停下来：你这是在预先判断，通常是为了省掉审查循环。 任务审查者可能会报告“⚠️ 无法从差异中验证”的事项——这些要求可能涉及未更改的代码或跨任务内容。这些事项不会阻碍其余审查，但在将任务标记为完成之前，你必须自行解决每一项：你掌握审查者所没有的计划和跨任务上下文。如果你确认某项确实存在缺口，应将其视为规范审查未通过——与其他发现一同进入修复循环。

模板：task-reviewer-prompt.md

4. 修复循环

出现以下情况时启动循环：审查报告规范 ❌、存在任何 Critical 或 Important 级别的发现，或有一项经你确认属于真实缺口的 ⚠️ 事项。

循环开始前，有两种情况可直接结束处理：

• 随进度记录 Minor 级别的发现（Task <N>: minor (deferred): <one-liner>），并在最终的整个分支审查中提供这份清单，让审查者判断哪些必须在合并前修复。无人查阅的汇总等于悄悄丢弃。Minor 级别的发现绝不进入循环。
• 如果发现被标记为计划要求，或与计划文本中的要求冲突，则由你作出裁定：依据计划文本权衡该发现，以规范为最终依据，并在采取行动前记录裁定。不要因为计划有此要求就驳回发现，也不要在没有记录裁定的情况下派发与计划相矛盾的修复。 其他所有情况都进入循环。一个修复轮次包括一次修复派发和一次范围明确的重新审查。每项任务最多五轮： 第 1–3 轮——让原实施者继续处理。 将尚未解决的问题原文发给它。它的上下文是完整的：它了解任务、代码以及自己的选择。如果你的执行框架无法向仍在运行的子 Agent 发送另一条消息，就派遣一位新的实施者，并提供任务简述路径、报告文件路径和未解决的问题——无论采用哪种方式，报告文件都是持久化记忆。

第 4–5 轮——派遣一位使用更强大模型的新实施者（参见模型选择），并提供任务简述路径、报告文件路径、未解决的问题，以及以下说明：“此前的实施者已尝试此任务 [N] 次；现在由你负责。请阅读报告文件，了解已经尝试过的方案。” 一个问题在三次继续处理后仍未解决，通常意味着实施者无法看清自己的问题——一次性换新视角并提升能力。

无论哪一轮，都要： 让实施者修复问题、重新运行覆盖已修改代码的测试、将修复报告追加到同一报告文件，并返回简短的约定内容。在重新派遣审查者之前，先确认修复报告包含覆盖该问题的测试、运行的命令和输出；这三项齐全后，再派遣重新审查。请在修复消息中列出覆盖测试的文件名——如果只改了一行，无需运行完整测试套件。

重新审查的范围有限。 运行 scripts/review-package PLAN_FILE FIX_BASE HEAD，其中 FIX_BASE 是上一次审查所看到的提交，并将问题列表、任务简述、报告文件和打印出的差异路径一并发送给 re-review-prompt.md。重新审查者会逐项判定问题为 ADDRESSED 或 NOT ADDRESSED，并且只标记修复差异中新增的回归问题。修复差异中新增的 Critical/Important 问题会加入未解决问题列表。范围外的观察记入台账，作为延后处理的次要问题——它们绝不能延长循环。

每轮结束后， 将以下内容追加到台账： Task <N>: fix round <R>/5 (<X> addressed, <Y> open — <finding one-liners>; commits <a7>..<b7>)

绝不要在控制器会话中自行修复问题——让上下文保持清晰，以便协调；控制器自行修复会跳过审查。

打破循环。 第 5 轮重新审查后若仍有未解决问题，停止派遣。自行裁定每个未解决问题——你掌握计划和审查者所缺乏的跨任务上下文：

• 审查者判断有误，或该问题存在争议： 暂缓处理，记录为 Task <N>: parked — <finding> — Ruling: <why the code stands>。最终审查会看到双方的意见。
• 问题确实存在，但下游没有任何内容依赖它： 同样暂缓处理，并在裁定中说明问题确实存在，只是延期处理。
• 问题确实存在且会影响后续工作——后续任务会基于它构建，或它揭示了计划缺陷：就能解除依赖任务阻塞的最小改动作出裁定，记入台账：Task <N>: Ruling: <finding> — <what you decided and why>，并在派遣下一项任务时一并提供。悄无声息地搁置结构性故障，会让每个依赖任务都建立在故障之上。只有缺陷不再让所有后续路径都变成猜测时，才可停止。

仅在达到轮次上限时进行裁定。为结束循环而提前裁定，就是换个名目先入为主。每项裁定都必须记入台账——严禁悄无声息地丢弃问题。

5. 完成任务

当审查结果干净时，或者所有未解决的问题都已在触及上限时附上裁定并暂缓处理，请在同一条消息中将完成行追加到台账，并记录其他事项：

• Task <N>: complete (commits <base7>..<head7>, review clean)
• Task <N>: complete (commits <base7>..<head7>, <K> parked) 在触发熔断机制后

然后通过 TaskUpdate 将任务标记为已完成，并继续下一项。在同一次 TaskUpdate 中，将描述缩减为 Goal: 行加上 Complete — see ledger.——在本次会话剩余时间里，系统会在定期提醒中重新注入每个任务的完整描述；已完成任务的详细信息会保留在计划、任务简介和 .tasks.json 中（状态同步不会修改其中的描述）。例外：元数据带有 userGate: true 或 user-gate 标签的任务保留完整描述——完成后重新验证钩子会读取该描述。

如果审查中仍有未修复、也未在触及上限时附上裁定并暂缓处理的 Critical/Important 问题，绝不要继续下一项任务。

最终审查

最终的全分支审查也需要一个审查包：运行 scripts/review-package PLAN_FILE MERGE_BASE HEAD（MERGE_BASE = 分支起点的提交，例如 git merge-base main HEAD），并在最终审查派发中附上输出的路径，这样最终审查者只需读取一个文件，而不必通过 git 命令重新推导分支差异。使用可用的最强模型进行派发（参见 Model Selection），并采用 superpowers-extended-cc:requesting-code-review 的 code-reviewer.md。指明台账中的 deferred-minor 和 parked 条目，让审查者判断哪些必须在合并前修复。

如果最终全分支审查发现问题，只派发一个修复子 Agent，并提供完整的问题列表——不要为每个问题分别派发修复者。逐问题派发修复者会让每个人都重新构建上下文并重新运行测试套件；在一个真实会话中，最终审查的修复阶段耗时比所有任务加起来还多。然后，对这轮修复执行且只执行一次范围限定的复审（针对修复范围运行 scripts/review-package PLAN_FILE FIX_BASE HEAD，re-review-prompt.md）。 按照任务循环中的熔断机制处理任何残留问题：附上裁定并暂缓处理，或者对关键问题作出裁定，并在台账中记录你的决定。只有上述四类问题会在此处阻止你继续。不会有第二轮修复——残留的关键问题会在 finishing-a-development-branch 提供选项时，呈现给与你协作的人类伙伴。

收尾

删除任何内容之前，收集台账中所有含有 Ruling: 的行——包括预检裁定、暂缓处理的问题、熔断机制的裁定等——按作出裁定的顺序列在最终消息的“我作出的裁定”下，并说明如果判断有误会造成什么代价。此列表必须完整：只要台账中有裁定，列表中就必须有。这个列表是你替人类伙伴作出的决定唯一能传达给他们的地方——他们会阅读并返工你判断错误的部分。随着工作区一同消失的裁定，就是秘密作出的决定。

当最终全分支审查干净且其修复已合并后，删除此计划的工作区（rm -rf <workspace>）——如今 git 历史就是记录。其他计划的同级目录不属于你；不要动它们。

使用 superpowers-extended-cc:finishing-a-development-branch。

常见借口

借口	现实
“规格合规度差不多就行”	审查者发现规格缺漏 = 尚未完成。修复问题，或达到上限后进行裁定——只有这两种出路。
“我自己修就行，派发任务是额外开销”	控制器修复会污染你的上下文，并跳过审查。恢复实施者的工作。
“再来一轮就能收敛”	超过上限后，轮次不会收敛——这是结构性问题。进行裁定并分流。
“审查者反正还会发现新问题”	有范围限制的复审用于验证修复，不会随意扩展范围。未触及代码中的新发现应记入台账，而不是加入循环。
“这个发现显然不对，我就忽略它”	只有达到上限后才能进行裁定，而且每项裁定都必须记入台账。禁止悄悄丢弃发现。
“修复很小，跳过复审吧”	未经审查的修复最容易引入回归。每轮都必须以一次有范围限制的复审结束。
“审查会拖慢循环”	没有审查的循环只是未经验证的反复折腾。审查是循环的刹车和方向盘。
“维护台账是额外开销”	台账是压缩后仍能保留下来的内容。没有台账的控制器曾重新派发整套已完成的任务序列。
“台账应该记录我的推理过程”	台账是恢复地图。状态用一句话记录；推理过程则是日记，会在之后的每轮中消耗上下文。
“我会把这条流程经验记在台账里”	工作区会在 Finish 时删除——经验也会随之消失。改为写进最终报告。
“实施者自己启动了审查者——额外多一层保障”	这是重复的角色，审查同一份差异；任务审查才是关卡。工作者自行启动审查者是应标记的缺陷，而不是严谨。

工作流示例

You: I'm using Subagent-Driven Development to execute this plan.

[Setup: worktree verified]
[Read plan file once: docs/superpowers/plans/feature-plan.md]
[Resolve workspace: scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[TaskCreate for each task with full description]

Task 1: Hook installation script

[Get Task 1 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: "Before I begin - should the hook be installed at user or system level?"

You: "User level (~/.config/superpowers/hooks/)"

Implementer: [Later]
  - Implemented install-hook command
  - Added tests, 5/5 passing
  - Self-review: Found I missed --force flag, added it
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ✅ - all requirements met, nothing extra.
  Strengths: Good test coverage, clean. Issues: None. Task quality: Approved.

[Ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, review clean)]

Task 2: Recovery modes

[Get Task 2 text and context (already extracted)]
[Dispatch implementation subagent with full task text + context]

Implementer: [No questions]
  - Added verify/repair modes
  - 8/8 tests passing
  - Committed

[Run review-package PLAN_FILE BASE HEAD; dispatch task reviewer with the printed path]
Task reviewer: Spec ❌:
  - Missing: Progress reporting (spec says "report every 100 items")
  Issues (Important): Magic number (100)

[Fix round 1: resume the implementer with both findings]
Implementer: Added progress reporting, extracted PROGRESS_INTERVAL constant.
  Re-ran test/recovery.test.js — 10/10 passing. Fix report appended.

[Run review-package PLAN_FILE FIX_BASE HEAD; dispatch scoped re-review]
Re-reviewer: Missing progress reporting — ADDRESSED (src/recovery.js:41).
  Magic number — ADDRESSED (src/recovery.js:7). New breakage: none.
  Verdict: all findings addressed.

[Ledger: Task 2: fix round 1/5 (2 addressed, 0 open; commits d4e5f6a..b7c8d9e)]
[Ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, review clean)]

...

[After all tasks]
[Run review-package PLAN_FILE MERGE_BASE HEAD; dispatch final code-reviewer, most capable model]
Final reviewer: All requirements met. Deferred minors triaged: none block merge.

[Delete this plan's workspace — the record now lives in git]

Done! Using superpowers-extended-cc:finishing-a-development-branch.

有界并行派发

禁止的是写入范围重叠，而不是并行本身——上文“绝不要并行派发多个实现子 Agent（会产生冲突）”是顺序循环的默认做法。当每个运行中的 Agent 都通过不相交性测试时，可以并发派发：

• 只读 Agent 始终可以安全并行：审计、日志分析、验证关卡、长时间运行的测试套件（这些也非常适合在实现继续进行时交给免费的本地 Agent 类型）。
• 只有在以下条件都满足时，实现者才能并发运行：其任务的 files 列表没有共同路径，且任一任务都不在另一任务的 blockedBy 链中。files 元数据就是测试——没有重叠就没有冲突。
• 绝不要让两个写入者处理同一个文件，也绝不要用并行来跳过审查：每项任务仍须在完成时接受单独的任务审查。
• 在派发 Agent 之前，将每项并行任务标记为 in_progress——模型路由会根据所有进行中任务层级的并集解析每次派发；未标记的任务将因层级不匹配而被阻止派发。
• 当是否重叠不确定时，按顺序执行。上文的逐任务顺序循环仍是默认做法；并行是优化手段，而不是基准做法。

任务持久化同步

通过 TaskUpdate 将每项任务标记为已完成后，更新 .tasks.json 文件以保持同步：

1. 读取 <plan-path>.tasks.json
2. 将任务的 "status" 设为 "completed"
3. 将 "lastUpdated" 设为当前 ISO 时间戳
4. 写回文件

这可确保跨会话恢复正常工作。否则，新会话加载 .tasks.json 时会将已完成的任务显示为 "pending"。