executing-plans

执行计划

在本会话中由你自己逐项执行计划：不为每个任务分派实现者 subagent，也不为每个任务配备审查者。在结束时对整个分支进行一次全新上下文的审查。

为何内联执行： subagent 驱动的开发会为每个任务各配一个全新的实现者和一个全新的审查者，且每个人都要从零重新阅读代码库。内联执行只需要一个上下文（即你的）加上结束时的一个审查者。它放弃的是每个任务的全新上下文，以及每个任务的第二双眼睛。本技能通过其他方式保留了这两者的价值：任务简报即规格说明，台账即你的记忆，TDD 即每个任务的关卡，最终审查者即第二双眼睛。

核心原则： 计划已经完成了思考工作。严格按计划执行，用你亲眼见过失败再变为通过的测试来证明每一步，并留下一份不会因你自己遗忘而丢失的记录。

叙述： 在工具调用之间，最多叙述一行简短的话。台账和工具结果承载记录本身。

持续执行： 不要在任务之间停下来向你的人类搭档确认。他们选择内联执行是为了节省开销，而不是为了在每个任务之后回答"要不要继续？"。请不间断地执行计划中的全部任务。

裁决，而非停滞。 冲突、歧义、计划缺陷，都由你自己决定。规格说明是具有约束力的权威，计划是其论证，而规格和计划都没有回答的问题，由你的判断来定夺。每一项决定都要以 Ruling: <what you decided> — <why> — <what it costs if wrong> 的格式记入台账，然后继续推进。未在台账中记录裁决而偏离计划，就是暗中做出的决定。

只有四种情况会让你停下来，且仅限于此：不可逆或具破坏性的操作；涉及安全的敏感操作；超出本工作树、按惯例应先征询意见的副作用（例如合并、推送到共享分支、发布）；以及计划严重破损，以至于每条前进路径都只能靠猜测。遇到这些情况，请停下来询问。

何时使用

• 你已有一份来自 superpowers:writing-plans 的计划，并且人类搭档在交接时选择了内联执行。
• 你的运行环境没有 subagent 工具（参见 ../using-superpowers/references/ 中的各平台参考文档）。切勿伪造分派，直接在此处执行计划。
• 任务大多相互独立，这与 superpowers:subagent-driven-development 的前提条件相同。

一份完全明确的计划使内联执行变成了单纯的转录加测试，它在中端会话模型上也能良好运行。唯一值得动用最强模型的环节是最终审查，本技能会单独派发它。选择内联执行时，请把这一点告知你的人类搭档。

如果人类搭档希望每个任务都设有审查关卡，或者计划长到后面的任务会运行在被压缩的上下文中，请优先选择 superpowers:subagent-driven-development。对长计划进行内联执行仍然可行，台账正是使其可恢复的关键，但最后几个任务得到的关注最少。

流程

digraph process {
    rankdir=TB;

    subgraph cluster_per_task {
        label="Per Task";
        "task-start: brief + BASE; read the brief" [shape=box];
        "Work the steps in order: TDD, run every verification, read every output" [shape=box];
        "Step output matches plan's Expected?" [shape=diamond];
        "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [shape=box];
        "Commit as the plan's commit steps say" [shape=box];
        "Completion contract met?" [shape=diamond];
        "task-done: run tests, ledger the result; mark todo complete" [shape=box];
    }

    "Setup: worktree, workspace + ledger, read plan + spec, pre-flight scan" [shape=box];
    "More tasks remain?" [shape=diamond];
    "Final whole-branch review (fresh reviewer if you have one)" [shape=box];
    "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" [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, workspace + ledger, read plan + spec, pre-flight scan" -> "task-start: brief + BASE; read the brief";
    "task-start: brief + BASE; read the brief" -> "Work the steps in order: TDD, run every verification, read every output";
    "Work the steps in order: TDD, run every verification, read every output" -> "Step output matches plan's Expected?";
    "Step output matches plan's Expected?" -> "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" [label="no"];
    "Plan wrong? Rule and ledger. Code wrong? systematic-debugging" -> "Work the steps in order: TDD, run every verification, read every output";
    "Step output matches plan's Expected?" -> "Commit as the plan's commit steps say" [label="yes, last step"];
    "Commit as the plan's commit steps say" -> "Completion contract met?";
    "Completion contract met?" -> "Work the steps in order: TDD, run every verification, read every output" [label="no - finish the task"];
    "Completion contract met?" -> "task-done: run tests, ledger the result; mark todo complete" [label="yes"];
    "task-done: run tests, ledger the result; mark todo complete" -> "More tasks remain?";
    "More tasks remain?" -> "task-start: brief + BASE; read the brief" [label="yes"];
    "More tasks remain?" -> "Final whole-branch review (fresh reviewer if you have one)" [label="no"];
    "Final whole-branch review (fresh reviewer if you have one)" -> "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger";
    "Re-grade, then: Critical/Important → ONE fix pass, each fix RED→GREEN + green suite; Minor → ledger" -> "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 分支上开始实现。

对话记忆在上下文压缩后不会保留。内联执行器如果丢失了进度，就会重新实现提交已经存在的任务。这与控制器重复派发任务的失败相同，代价则由你自己的上下文承担。应将进度记录在账本文件中，而不只记在待办项里。Harness 待办项只是实时视图，账本才是正式记录。

工作区和账本与 superpowers:subagent-driven-development 共享，使用相同的目录和格式。因此计划可以在执行过程中更换执行器，新的执行器会从同一份账本恢复进度。

• 每个计划拥有一个工作区。skill 启动时，运行 ../subagent-driven-development/scripts/sdd-workspace PLAN_FILE。它会输出该计划的 git 忽略目录 （<repo-root>/.superpowers/sdd/<plan-basename>/），此计划的所有产物都存放在这里，包括账本、任务简报和评审材料包。其他计划的目录不得由你读取或写入。
• 检查此计划的账本 <workspace>/progress.md 是否存在。如果其第一行写明了你的计划文件，则带有 Task <N>: complete 行的任务均已完成，不要重做。从第一个没有该行的任务继续。这些任务的提交即使在你的上下文中已不记得，仍然存在于 git 中。上下文压缩之后，应以账本和 git log 为准，而不是你自己的记忆。如果账本第一行写的是另一个计划文件，那它属于另一个计划的进度：不要动它，请新建你自己的账本。
• 创建账本时，将其身份信息作为第一行： # SDD ledger — plan: <plan file path>。
• git clean -fdx 会销毁工作区（它是 git 忽略的临时目录）。若发生这种情况，请从 git log 恢复。

阅读一次计划，记下其上下文和全局约束，并为每个任务创建一个待办项。如果计划指明了 Spec，也要阅读它。Spec 是计划所依据的权威文件，计划内部的冲突以 Spec 为准。如果计划指向的 Spec 无法访问，应在账本中记录该情况。没有 Spec 时做出的裁定都只是暂定的。

必需子技能： 在 Task 1 之前加载 superpowers:test-driven-development。它管辖下面每个任务的每个步骤。即使计划的步骤已经写明“先编写失败的测试”，也不能免除你阅读该 skill 的义务。

在 Task 1 之前，检查计划中各任务之间的冲突。计划中的 Interfaces 代码块会告诉你应查看哪里。对于每个消费更早任务产出的任务，在账本中记录一行，写明这两个任务、一方的产出与另一方的消费要求，以及你发现的问题。彼此不共享任何内容的任务不需要记录。如果计划中的任务彼此不共享任何内容，则只写一行：Pre-flight: no shared interfaces。对于这些行所揭示的每个冲突，以 Spec 作为约束性依据进行裁定，将裁定记录在对应行旁，然后开始 Task 1。每个任务自身的文本会在阅读其简报时再检查，不在此处检查。

任务循环

你打印的所有内容以及每个工具结果，都会在整个会话期间保留在你的上下文中。将较长的测试输出重定向到工作区中的文件，然后读取其末尾部分。只阅读任务简报，不要通读整个计划。

1. 领取任务

• 运行此 skill 的 scripts/task-start PLAN_FILE N。它会在一次调用中输出简报路径和 BASE（该任务的提交范围所基于的提交）。
• 即使是设置阶段已经记住的任务，也要阅读其简报。你的记忆只是摘要，简报中才有确切的值、签名和测试用例。
• 将该任务的待办项标记为 in_progress。

每次工具调用都会让你的整个上下文重新读取一遍。记账工作应附带在实际工作中完成：账本追加应与提交放在同一次调用中，而不要单独占用一次调用。

2. 执行步骤

计划中的步骤已按 RED-GREEN 顺序排列；请在环境搭建时加载的 superpowers:test-driven-development 下按此顺序执行。测试步骤的代码需先编写、先运行。观察其失败是步骤的一部分，而非形式上的要求。如果测试在实现代码存在之前就通过，这说明测试本身有问题。

每个运行命令的步骤都带有 Expected: 行。运行命令，阅读输出，并与之比对。结果分为三种情况：

• 一致。 进入下一步。
• 代码有误。 使用 superpowers:systematic-debugging。找出原因；切勿为了让步骤输出符合预期而修补表象。
• 计划有误：步骤与规格相矛盾、前序任务的接口与本任务所用的不一致，或命令无法执行。请以满足规格的最小改动做出裁定，在台账中记录为 Task <N>: Ruling: <finding> — <what you decided and why>，然后继续。裁定以台账为准，而非依靠记忆：之后涉及同一接口的任务应从台账中读取该裁定。

按计划中的提交步骤进行提交。一个任务跨越多次提交是可以的；BASE 是审查范围的起点，绝不是 HEAD~1。

3. 完成约定

在写入任务的台账行之前，以下各项须全部成立，并附有本次会话中的证据，而不是根据 diff 看起来正确而推断：

• 任务简报中提到的每个测试都已存在，并在本任务中运行过，且你已阅读其输出。
• 任务的最终测试运行通过。task-done 即该次运行，它会将命令和结果写入台账行。
• 简报中的每个 Expected: 行都已与真实输出进行比对。
• 与简报的每处偏差都在台账中有对应的 Ruling: 行。

必需子技能： superpowers:verification-before-completion 约束此项声明。若缺少任一项，则任务未完成，请补全它。

4. 完成任务

使用该技能的 scripts/task-done PLAN_FILE N BASE -- <test command> 运行，其中 <test command> 为简报为整个任务指定的测试命令。它会运行测试，将完整输出保存在工作区中，打印末尾部分，并且仅在测试通过时，才将完成行追加到台账中：

Task <N>: complete (commits <base7>..<head7>, tests: <command> → <result>)

运行失败则不记录任何内容，该任务视为未完成。记录成功后，将待办事项标记为完成，然后进行下一个任务。

最终审查

运行 ../subagent-driven-development/scripts/review-package PLAN_FILE MERGE_BASE HEAD （MERGE_BASE 为分支起始所基于的提交，例如 git merge-base main HEAD），并根据它输出的文件进行审查。

若有子 Agent 工具： 使用可用的最强模型派发审查者，因为整分支审查属于判断型任务。使用 superpowers:requesting-code-review 提供的 code-reviewer.md，并提供审查包路径、计划和规格路径，以及计划中的 Review Focus 章节原文（如果有）。该章节列出计划中的测试未覆盖的输入类别和故障模式，审查者会逐一检查。同时指向账本中的 Ruling: 行，以便审查者权衡你做出的决定。请明确指定模型；如果省略，子 Agent 会继承会话的模型，而该模型未必是最强的。这是整个运行过程中唯一的全新上下文。不要跳过此步骤，也不要用你自己对 diff 的阅读来替代。

若没有子 Agent 工具： 阅读 code-reviewer.md，并在最后一个任务的账本行之后，作为一次单独的过程，依据审查包自行完成该审查。在账本中写入 Final review: self-review (no subagent tool)，并在你的最终消息中说明此事：作者自审的效力弱于全新的审查者，是否足以合并由你的人类搭档决定。

在据此采取任何行动之前，先对审查发现进行分类。审查者给出的严重性标签只是建议，最终裁定权在你。其中的“Declined to judge”列表同样由你决定：列表中的每一行都是你需要做出并记入账本的裁定，与计划冲突的处理方式相同，格式为 Final: Ruling: <审查者搁置的行为> — <一个合理的软件使用者会得到什么，以及为何该结果成立或为何它现在应被视为一项发现> — <若判断错误的代价>。先按影响重新评级：规格是一份愿景文档，发现项的等级取决于它上线后一个合理的使用者会遇到什么，而不取决于规格是否点名了触发该问题的输入。如果审查者因为规格未提及而将某发现定为 Minor，那么他评判的是规格，而不是影响。随后：

• Critical 和 Important 进入修复阶段。
• Minor 以 Final: minor (deferred): <一句话概述> 的形式记入账本，并在你的最终消息中列于“Deferred minors”下。Minor 不进入修复阶段，也不会成为裁定。裁定是针对冲突所做的决定，而不是对你未采纳某条润色建议的记录。

由你亲自修复 Critical 和 Important 发现，因为你是这里的实现者，并且只进行一次修复。每项修复都通过 TDD 验证，而不是通过第二位审查者验证：先编写能复现该发现的测试，看它失败，再使其通过，然后运行完整的测试套件。在账本中按 Final: fixed <发现> — <测试名称> RED→GREEN, suite <N>/<N> 的格式记录每项修复。没有先失败过的测试所支撑的修复不算已验证；修复阶段结束后，如果测试套件不是全部通过，则修复阶段尚未完成。不要再次派发复审：它会重新阅读一份 diff，而这份 diff 的覆盖测试已经能回答“是否已解决”，套件运行也已经能回答“是否没有破坏其他内容”。

你决定不修复的发现即为裁定，格式为 Final: Ruling: <发现> — <代码为何保持现状> — <若判断错误的代价>，并会被列入提交给你人类搭档的裁定清单。修复阶段只有一次，不存在第二轮。

收尾

在删除任何内容之前，先将账本中所有包含 Ruling: 的行按你做出的顺序收集到最终消息的“Rulings I made”下，每项注明判断错误时的代价；并将所有 minor (deferred) 行收集到“Deferred minors”下。两份清单都必须完整。你的最终消息是你代表人类搭档做出的决定，以及你选择不处理的发现，传达给他们的唯一途径。

当最终审查通过且其修复已提交后，删除本计划的工作区目录，因为 git 历史现在就是记录。同级目录属于其他计划，请不要改动。

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

常见借口

借口	现实
"我记得任务 N 的内容"	你记得的是摘要。任务书里有准确的数值，去读它。
"计划里的代码是对的，跳过看测试失败这一步"	一个你从未见过它失败的测试什么也证明不了。这只是一步，去运行它。
"我最后再跑完整套件，不逐步运行"	逐步运行才能知道是哪一步出了问题。任务结束时的运行是约定要求，不能替代逐步运行。
"计划在这里有误，我直接做正确的事就行"	做正确的事，并把裁定记入台账。未入账的偏差就是一个暗中做出的决定。
"我等做完几个任务再写台账条目"	上下文压缩不会等待方便的时机。每个任务写一行，与提交放在同一条消息中。
"让我在下一个任务前先确认一下"	他们选择内联执行是为了节省开销。进度提示则会耗费他们的时间。只有那四个停止点才能让你停下。
"我仔细看过自己的 diff，最终审阅者是多余的"	作者相同，盲点也相同。审阅者是这次运行能换来的唯一全新视角。
"测试应该能通过，改动很简单"	"应该"不是证据。约定要求提供命令及其输出。
"子 Agent 又慢又贵，最终审阅我也跳过"	内联执行已经去掉了逐任务的审阅者。对整个分支做一次审阅是底线，而不是上限。
"审阅者说是 Minor，那就是 Minor"	这个标签评定的是规格说明的沉默。应当评估使用者实际得到的结果。重新评级，然后再设门禁。
"修复很明显，不需要先写一个失败的测试"	失败的测试是证明问题确实存在、如今已消除的唯一证据。没有它，你手里只有一个 diff 和一点希望。
"顺手把那些 Minor 问题也修了"	你修的每一个 Minor 问题，都意味着一次搭档没有要求的测试、修复和套件运行。把它们记入台账，由你的搭档决定。

示例工作流

You: I'm using the executing-plans skill to implement this plan inline.

[Setup: worktree verified]
[Read plan once: docs/superpowers/plans/feature-plan.md; spec read]
[Resolve workspace: sdd-workspace docs/superpowers/plans/feature-plan.md — no ledger inside, fresh start]
[Pre-flight scan: 2 shared-interface rows, 4 self-consistency rows, clean; written to ledger]
[Create todos for all tasks]

Task 1: Hook installation script

[task-start plan 1 → brief read; BASE a1b2c3d]
[Step 1: write failing test — written]
[Step 2: run it — FAIL: install_hook not defined. Matches Expected.]
[Step 3: implement — written]
[Step 4: run it — PASS 1/1. Matches Expected.]
[Step 5: commit — d4e5f6a]
[Contract: tests ran, output read, no deviations]
[task-done plan 1 a1b2c3d -- npm test -- hooks → ledger: Task 1: complete (commits a1b2c3d..d4e5f6a, tests: npm test -- hooks → 1/1 pass)]

Task 2: Recovery modes

[task-start plan 2 → brief read; BASE d4e5f6a]
[Step 2: run failing test — FAIL, but on an import error: Task 1 exported
 installHook, brief consumes install_hook]
[Ruling: brief's consumer name is a typo against Task 1's Produces block;
 use installHook — Ledger: Task 2: Ruling: install_hook → installHook — matches Task 1 Produces — cost if wrong: one rename]
[Steps 2-5 as planned; commit b7c8d9e]
[task-done plan 2 d4e5f6a -- npm test -- recovery → ledger: Task 2: complete (commits d4e5f6a..b7c8d9e, tests: npm test -- recovery → 8/8 pass)]

...

[After all tasks: review-package plan MERGE_BASE HEAD; dispatch code-reviewer, most capable model]
Reviewer: One Important finding — progress reporting interval hardcoded. Two Minor.
[Re-grade: Important stands; minors → ledger as deferred]
[Fix pass: test_progress_interval_configurable RED → extract PROGRESS_INTERVAL → GREEN; suite 12/12; commit]
[Ledger: Final: fixed hardcoded interval — test_progress_interval_configurable RED→GREEN, suite 12/12]

Rulings I made:
- Task 2: install_hook → installHook (brief typo; cost if wrong: one rename)

Deferred minors:
- README lacks a usage example
- recovery.js could split verify/repair into two files

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

Using superpowers:finishing-a-development-branch.