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];
    "Partner chose inline, or no subagent tool?" [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?" -> "Partner chose inline, or no subagent tool?" [label="yes"];
    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
    "Partner chose inline, or no subagent tool?" -> "executing-plans" [label="yes"];
    "Partner chose inline, or no subagent tool?" -> "subagent-driven-development" [label="no"];
}

对比执行计划(内联方式):

• 每个任务使用全新的子 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, mark todo complete" [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: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, mark todo complete" [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, mark todo complete" [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, mark todo complete";
    "Append completion to ledger, mark todo complete" -> "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:finishing-a-development-branch";
}

设置

确保工作在隔离的工作区中进行：使用 superpowers:using-git-worktrees 创建一个工作区，或确认已有工作区。 未经您的人类搭档明确同意，切勿在 main/master 分支上开始实施。

对话记忆在上下文压缩后不会保留。在实际会话中，丢失进度的控制者曾重新派发整个已完成的任务序列，这是观察到的代价最高的故障。请将进度记录在台账文件中，而不仅仅是待办事项中。

• 每个计划拥有一个工作区：技能启动时，运行本技能的 bash scripts/sdd-workspace PLAN_FILE。该命令会输出计划的 git 忽略目录（位于 <repo-root>/.superpowers/sdd/ 下），此目录存放本计划的所有产物：台账、简报、报告和评审包。其他计划的目录不归您读写。
• 检查本计划的台账 <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 恢复。

阅读一次计划，记录其背景和全局约束，并为每个任务创建一个待办事项。如果计划指明了规格说明（Spec），也要阅读它：规格说明是计划所依据的权威，计划内部的冲突以规格说明为准。若无法获取规格说明，则需在台账中注明此情况；在没有规格说明的情况下作出的裁定只是暂行的。

在派发任务 1 之前，扫描计划一次，并在检查时记录所检查的内容：

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

扫描的输出是一张表格，而不是结论。对于每一对共享文件或接口的任务，各占一行：两个任务的名称、其中一个任务产出的内容与另一个任务所消费的内容，以及您发现的问题。对于每个任务，各占一行：其自身文本是否前后一致，即其所指定的测试与其所指定的代码是否一致，其所创建的文件与其后续所修改的文件是否一致。仅说“扫描无问题”而没有这些行，不能算作您已完成的扫描。

将该表格写入台账。在执行开始前，对发现的每一个问题作出裁定，每项裁定都要对照要求该内容的计划文本，并将每项裁定记录在台账中。如果扫描无问题，则直接继续，无需额外说明。对扫描发现的每一个冲突作出裁定：规格说明是具有约束力的权威，计划则是其论证过程。将裁定记录在对应行旁边，然后派发任务 1。评审循环仍是对仅在实施过程中才显现的冲突的最后一道防线。

模型选择

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

机械性实现任务（独立函数、规格清晰、涉及 1-2 个文件）：使用快速且廉价的模型。当计划描述充分时，大多数实现任务都属于机械性任务。

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

架构与设计任务：使用当前可用的最强模型。 整个分支的最终审查属于此类，应派发给当前可用的最强模型，而不是会话默认模型。

审查任务：根据 diff 的规模、复杂度和风险，选择判断能力与之匹配的模型。小型机械性 diff 不需要最强模型；涉及微妙并发改动的 diff 则需要。对小型修复 diff 的范围化重新审查，使用廉价到中档的模型即可。

修复循环升级（第 4-5 轮）：使用比卡住的实现者高至少一个档位的模型。

派发子 Agent 时务必显式指定模型。 若省略模型，子 Agent 会继承会话模型，而该模型通常是能力最强、成本最高的，这会使本节的规定形同虚设。

轮次数比 token 单价更重要。 实际耗时和上下文成本与子 Agent 的轮次数成正比，而最廉价的模型在多步骤工作中往往需要 2-3 倍的轮次，总成本反而更高。对于审查者，以及依据文字描述工作的实现者，应以中档模型为底线。当任务计划文本中已包含需要编写的完整代码时，实现工作即为转录加测试，此时实现者使用最廉价的档位即可。单文件机械性修复同样使用最廉价的档位。

实现任务的复杂度信号：

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

任务循环

合并同类小型工作。 当计划中列出多个任务，且每个任务都是同一类型的小型独立改动（例如在多个文件中重复相同的单行修复、常量修改或字段新增）时，不要为每个任务单独派发一个子 Agent。应撰写一份派发说明，列出每个文件及其改动，将整批工作交给一个子 Agent，并将其 diff 作为一个整体进行审查。只有需要独立判断、独立测试或独立审查面的工作，才适合一任务一派发。

派发提示词中粘贴的所有内容，以及子 Agent 输出的所有内容，都会保留在你的上下文中，并在本次会话后续每一轮被重新读取。应通过文件交接产物。

等待已派发的子 Agent： 不要以过短的超时轮询等待接口，也不要进行无限期的静默等待。 当你有本地工作要做时（如更新台账、打包下一次审查、阅读报告），继续推进即可，子 Agent 的结果会自行送达。 当确实无事可做时，应分段等待（在平台允许的情况下，每段五到十分钟）。每段等待之间，发送一行状态信息，并核对仍在运行的子 Agent：列出它们，并追查那些已结束但未汇报结果的子 Agent。分段等待几乎能保留长时间等待的全部效率，同时确保卡住或丢失的子 Agent 能在几分钟内被发现，而不是等到会话结束。

1. 派发实现者

派发前记录 BASE(git rev-parse HEAD),审查包和修复轮次的 diff 都需要它。

• 任务说明: 派发实现者之前,运行本 skill 的 bash scripts/task-brief PLAN_FILE N。它会把任务的完整文本提取到一个唯一命名的文件中,并打印该路径。派发内容应使任务说明保持为唯一的需求来源。派发内容应包含:(1) 一句话说明该任务在项目中的位置;(2) 任务说明路径,并注明"请先阅读此文件,它是你的需求说明,其中的精确值须原样使用";(3) 任务说明无法得知的、早前任务中确定的接口与决策;(4) 你对在任务说明中发现的歧义所作的解决方案;(5) 报告文件路径及报告约定。精确值(数字、魔术字符串、签名、测试用例)只出现在任务说明中。切勿让子 Agent 通读整个计划文件。
• 报告文件: 报告文件以任务说明命名(任务说明 …/task-N-brief.md → 报告 …/task-N-report.md),并写入派发提示中。实现者将完整报告写入该文件,只返回状态、提交记录、一行测试摘要和疑虑。
• 派发提示只描述一个任务,不描述会话历史。不要在后续派发中粘贴累积的前序任务摘要(例如"任务 1-3 完成后的状态")。曾有一次真实会话的派发达到 42k 字符,其中 99% 是粘贴的历史。新的子 Agent 只需要它的任务、它涉及的接口以及全局约束,别无其他。
• 派发内容须包含无子 Agent 约定(位于实现者模板中):实现者绝不派发子 Agent,包括辅助 Agent,也绝不派发审查者。审查由你在报告提交之后发起。在真实会话中,工作 Agent 派生的每个审查者都与你派发的任务审查重复,等于每个任务多出一个完整的审查席位。
• 如果早前任务在本任务涉及的区域中记录了一项发现,应在派发内容中附上该台账条目的指针。
• 从派发结果中记录实现者的 Agent 身份。修复循环第 1-3 轮会恢复该 Agent。
• 切勿并行派发多个实现子 Agent(会产生冲突)。

模板: implementer-prompt.md

2. 处理报告

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

DONE: 生成审查包(bash scripts/review-package PLAN_FILE BASE HEAD,在本 skill 目录下运行。它会打印所写入的唯一文件路径。BASE 是派发实现者之前记录的提交。绝不使用 HEAD~1,否则会静默丢弃多提交任务中除最后一个提交以外的所有改动),然后使用打印出的路径派发任务审查者。

DONE_WITH_CONCERNS: 实现者已完成工作,但提出了疑虑。继续之前请先阅读这些疑虑。如果疑虑涉及正确性或范围,请在审查前处理。如果只是观察性意见(例如"这个文件越来越大"),请记录下来并继续进入审查。

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

BLOCKED: 实现者无法完成任务。请评估阻塞原因:

1. 如果是上下文问题,补充更多上下文,使用同一模型重新派发
2. 如果任务需要更强的推理能力,使用更强的模型重新派发
3. 如果任务过大,将其拆分为更小的部分
4. 如果计划本身有误,对修正作出裁决,记入台账,并在派发内容中附上该裁决后重新派发

切勿忽略升级请求,也切勿在没有任何改变的情况下强制同一模型重试。如果实现者表示卡住了,就必须做出改变。

如果实现者在开始前或任务过程中提出问题,请清楚、完整地作答,必要时补充上下文,不要急于进入实现。

3. 审查任务

按任务进行的审查是任务级的检查点。全面审查只在最终的整分支审查中进行一次。切勿跳过任务审查，也不能接受缺少任一结论的报告。规范符合性与任务质量两项结论均必须具备。实现者的自我审查不能替代任务审查，两者都需要。

• 将审查所需的 diff 以文件形式交给审查者：运行本技能的 bash scripts/review-package PLAN_FILE BASE HEAD，并将其输出的文件路径交给审查者（若无 bash，则执行 git log --oneline、git diff --stat 和 git diff -U10 处理该范围，并重定向到一个唯一命名的文件）。该输出不会进入你自己的上下文，而审查者可以通过一次 Read 调用同时看到提交列表、统计摘要和带上下文的完整 diff。使用你在派发实现者之前记录的 BASE。绝不要使用 HEAD~1，它会悄悄截断多提交任务。绝不要在没有 diff 文件的情况下派发任务审查者。
• 审查者输入： 任务审查者会获得三个路径（同一份 brief 文件、报告文件和审查包），以及约束该任务的全局约束。
• 你交给审查者的全局约束块是它的注意力焦点。请从计划的 Global Constraints 部分或规范中逐字复制具有约束力的要求：精确的值、精确的格式，以及组件之间明确声明的关系（"与 X 布局相同"、"与 Y 一致"）。审查者的模板已包含流程规则（YAGNI、测试规范、审查方法），约束块只用于本项目规范的要求。
• 不要添加没有具体、针对该任务理由的开放式指令，例如"检查所有用法"或"如有用可运行竞态测试"。
• 不要要求审查者重新运行实现者已在同一代码上运行过的测试。实现者的报告已包含测试证据。
• 不要预先裁定审查结果。切勿指示审查者忽略或不标记某个特定问题。若你认为某项发现是误报，应让审查者提出，并在审查循环中裁定。如果你正在编写的提示词包含"不要标记"、"不要将 X 视为缺陷"、"至多为 Minor"或"计划已选择"，请停下：你正在预先裁定，通常是为了避免一轮审查循环。

任务审查者可能会报告"⚠️ 无法从 diff 验证"条目。这些要求存在于未变更的代码中，或跨越多个任务。它们不会阻塞审查的其余部分，但你必须在将任务标记为完成前自行解决每一项，因为你掌握审查者所缺乏的计划与跨任务上下文。若你确认某项确系真实缺口，则将其视为未通过的规范审查，并与其他发现一起进入修复循环。

模板：task-reviewer-prompt.md

4. 修复循环

当审查报告规范 ❌、任何严重或重要发现，或你确认属实缺口的 ⚠️ 条目时，循环触发。

循环开始前，有两条路径可直接离开循环：

• 在工作过程中将 Minor 发现记录到进度台账中（Task <N>: minor (deferred): <one-liner>），并让最终的整分支审查参考该列表，以判断哪些必须在合并前修复。无人阅读的汇总等同于静默丢弃。Minor 发现永不进入循环。
• 标注为 plan-mandated 的发现，或任何与计划文本要求相冲突的发现，由你负责裁定：根据计划文本权衡该发现，以规范作为具有约束力的依据做出决定，并在据此行动前将裁定记入台账。不要因为计划要求了某事就驳回该发现，也不要在没有已记录裁定的情况下派发与计划相矛盾的修复。

其他所有发现都进入循环。一轮修复包括一次修复派发加一次限定范围的复审。每个任务最多五轮： 第 1–3 轮：恢复原实现者。 将未解决的发现原文发送给它。它的上下文仍然完整，知道任务、代码以及自己的选择。如果你的运行框架无法向正在运行的子 Agent 发送消息，则派发一个新的实现者，并附上 brief 路径、报告文件路径和发现项。无论哪种方式，报告文件都是持久记忆。

第 4–5 轮：按模型选择规则，派发一个能力更强的新实现者。 附上 brief 路径、报告文件路径、未解决的发现项，并使用以下说明：“先前的实现者已尝试此任务 [N] 次，现在由你负责。请阅读报告文件，了解已尝试的内容。” 经过三次恢复后仍然循环，通常说明实现者看不清自己的问题。新视角加上能力提升，可以一并解决。

每一轮都需如此： 实现者修复问题，重新运行覆盖已修改代码的测试，将修复报告追加到同一份报告文件，并返回简短的约定结果。重新派发审查者之前，先确认修复报告包含覆盖测试、所运行的命令以及输出，三者齐全后再派发复审。在修复消息中写明覆盖测试文件的名称。单行修复无需运行整个测试套件。

复审有范围限制。 运行 bash scripts/review-package PLAN_FILE FIX_BASE HEAD，其中 FIX_BASE 是上一次审查所见的 head。派发 re-review-prompt.md，并附上发现项列表、brief、报告文件和打印出的 diff 路径。复审者对每个发现项给出“已解决”或“未解决”的结论，并且只检查修复 diff 中引入的新问题。修复 diff 中新出现的严重或重要问题，将加入未解决发现项列表。范围之外的观察记入账本，作为延期的次要问题，不得延长循环。

每轮结束后， 向账本追加： 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)，适用于熔断机制触发后的情况。

然后将待办事项标记为完成，并进入下一个任务。只要审查中仍有未解决、也未挂起并附有上限裁定的严重或重要问题，就不得进入下一个任务。

Final Review

最终的整分支评审同样需要一个评审包：运行 bash scripts/review-package PLAN_FILE MERGE_BASE HEAD（MERGE_BASE 为分支起始时所基于的提交，例如 git merge-base main HEAD），并将输出的路径写入最终评审的派发中，使最终评审者只需读取一个文件，而无需用 git 命令重新推导分支差异。派发时使用可用的最强模型（参见 Model Selection），采用 superpowers:requesting-code-review 中的 code-reviewer.md。将台账中的 deferred-minor 和 parked 行指给它，使其能判断哪些问题必须在合并前修复。

如果最终整分支评审返回了问题，只派发一个修复子 Agent，并附上完整的问题清单，而不是为每个问题各派一个修复者。 逐个问题派发修复者会导致每个修复者都要重建上下文并重新运行测试套件；在一次实际会话中，最终评审的修复批次所花费的成本超过了所有任务的总和。 随后对修复批次运行且仅运行一次有范围限制的复审（bash scripts/review-package PLAN_FILE FIX_BASE HEAD，范围为修复区间，re-review-prompt.md）。 对于残留的问题，按任务循环熔断机制的做法处理：要么记为 parked 并附上裁决，要么对关键问题作出裁决，并将你的决定记入台账。只有上述四类情况会让你在此停下。这里没有第二轮修复批次。残留的关键问题应在 finishing-a-development-branch 提供选项时呈现给你的人类合作伙伴。

Finish

在删除任何内容之前，将台账中所有包含 Ruling: 的行收集到你的最终消息中，标题为"我做出的裁决"，按你做出的先后顺序排列，并注明每项若判断错误会造成的代价。该列表是穷尽的：只要台账中存在某项裁决，该列表就必须包含它。这份列表是把你代表人类合作伙伴所做的决定传达给对方的唯一途径，他们会阅读它，并重新处理你判断错误的部分。如果裁决随工作区一起消失，那它就是一个秘密做出的决定。

当最终整分支评审通过且其修复已合并后，删除本计划的工作区（rm -rf <workspace>）。此时 git 历史就是记录。同级目录属于其他计划，请勿触碰。

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

Common Rationalizations

借口	实际情况
"规范符合度差不多就行"	评审者发现了规范缺口，即表示任务未完成。要么修复，要么达到上限后作出裁决。这是仅有的两条出路。
"我自己修一下就行，派发太麻烦"	控制器自行修复会污染你的上下文，并跳过评审。应恢复实现者来修复。
"再来一轮应该就收敛了"	超过上限后，轮次不会收敛，问题是结构性的。应作出裁决并分流。
"评审者反正还会找出新问题"	有范围限制的复审用于验证修复，不能随意发散。针对未改动代码的新问题应记入台账，而不是纳入循环。
"这个问题明显是错的，我直接丢掉"	只有在达到上限时才能做出裁决，而且每项裁决都必须有台账记录。静默丢弃是禁止的。
"修复很小，跳过复审"	未经评审的修复是回归问题的主要来源。每一轮都必须以有范围限制的复审结束。
"评审会拖慢进度"	没有评审的循环只是未经验证的反复折腾。评审是循环的刹车与方向盘。
"记台账是额外负担"	台账是压缩上下文后得以保留的东西。没有台账的控制器，曾重新派发过整个已完成的任务序列。
"实现者自己派生了一个评审者，多一份保障"	这是对同一差异的重复评审席位，任务评审才是关口。由工作者派生的评审者是需要标记的缺陷，而不是严谨。

Example Workflow

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: bash scripts/sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Create todos for all tasks]

Task 1: Hook installation script

[Run task-brief for Task 1; dispatch implementer with brief + report paths + 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

[Run task-brief for Task 2; dispatch implementer with brief + report paths + 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:finishing-a-development-branch.