executing-plans

执行计划

通过分阶段编排执行书面实施计划：计划审查 → 任务创建 → 按批次协调器调度并验证 → Git 提交 → 完成。每个批次都会在一个全新的子 Agent（Agent 工具）中运行，因此主 Agent 的上下文不会累积批次执行记录。执行会跨多个轮次运行多个批次——推荐的运行方式是通过 Claude Code 内置的 /goal 包装执行（见下文）。

推荐：通过 /goal 包装执行

通过 Claude Code 内置的 /goal 启动（v2.1.139+），这样运行就会持续到完成，而不是在一个批次后停止：

/goal "Claude has emitted the Phase 6 completion message 'Plan execution complete. All N tasks verified and committed' AND has reported the final commit hash from Phase 5 in the transcript" /superpowers:executing-plans <plan>

/goal 是由用户输入的外层包装器——它必须为调用添加前缀；技能无法在运行过程中为自身启用它。评估器只判断 Claude 在转录记录中叙述的内容（不会读取文件或运行命令）——条件必须针对叙述的输出来表述，不能针对文件系统状态。注意：executing-plans 只会在所有批次完成后的 Phase 5 提交一次——不要围绕“每批次提交哈希”表述条件，否则永远无法匹配；每批次的评估器判定是进度信号，不是完成信号。完整语义和条件表述方式：../../skills/references/goal-wrapper.md。技能主体本身由单轮驱动，并在每一轮开始时通过 bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" 获取当前状态（见下方步骤 1）。

每轮迭代的步骤 1——通过 batch-progress.sh 获取当前状态

在执行任何其他操作之前，运行：

bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path>

该脚本会读取计划目录，统计 sprint-contract-batch-*.md 和 handoff-summary-*.md 文件，并输出明确的下一步操作指令（“Batch 3 active — Agent next” / “Batch 2 closed — TaskList then commit-or-next-batch” / “Batch 4 not yet started — Phase 3 steps 0-1-2”）。将输出视为权威的“我当前处于哪一步”信号，并按指令操作。这取代了旧循环中每轮迭代的文件系统扫描和注入——数据相同，但范围限定于此技能。

首次调用时跳过此步骤（尚未解析计划路径）——转到下方的“首次操作”。

关键：提前退出检查（仅在首次调用时先运行一次）

读取 _index.md。如果“Execution Plan” YAML 在单个批次中列出的任务少于 5 个，则提前退出：跳过协调器和冲刺契约；直接内联执行任务并提交。$ARGUMENTS 中的 --force 标记可跳过此检查。响应模板见 ./references/bail-out.md。如果这项内联工作需要一个简单的“持续执行，直到条件 X 成立”为止的循环，请直接使用 /goal。

首次操作——解析计划路径

解析计划路径，然后获取当前状态。

1. 解析计划路径：
   • 如果 $ARGUMENTS 提供了路径（例如 docs/plans/YYYY-MM-DD-topic-plan/），则使用该路径
   • 否则，选择 YYYY-MM-DD-*-plan/ 下按名称排序最后的 *-plan/ 文件夹——也就是名称中日期前缀最高的文件夹，而不是文件系统修改时间最新的文件夹。使用 ls -1d docs/plans/*-plan/ 2>/dev/null | sort | tail -1（不要使用 ls -t / ls -1dt——编辑较旧文件夹中的文件时，其目录修改时间会更新，导致它的排序高于新创建的文件夹）。直接使用结果（无需确认）。
   • 如果没有找到计划文件夹，则中止并显示清晰的错误消息，其中注明预期的路径模式
2. 运行 bash "${CLAUDE_PLUGIN_ROOT}/skills/executing-plans/scripts/batch-progress.sh" <plan-path> 以打印当前批次状态。裸路径 scripts/batch-progress.sh 无法解析——技能运行在计划所在的仓库工作目录中，而非插件目录中，因此必须通过绝对插件路径指定脚本。如果批次已存在，直接遵循脚本的指令（跳过 Phase 1/2——这些阶段已在之前的轮次运行）。否则，继续执行初始化。

初始化（仅第一轮）

1. 计划检查：确认文件夹中包含 _index.md，且其中有“Execution Plan”部分。启动任何批次前，先查阅文档索引：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" show <plan-path>。如果该行的状态为 expired:，则拒绝执行——该计划已被复盘作废，不再具有权威性；告知用户是哪次复盘使其失效，然后停止。如果状态为 implemented:<old-sha>（发布后返工），则在启动批次 1 之前运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "wip"，以便索引反映该计划正在重新执行。然后查阅记忆：运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" list --kind memory --status active，并在第一阶段“计划审查”之前阅读主题最相关的前几项结果。
2. 上下文：完整阅读 _index.md。这是执行的权威信息来源。

背景知识

核心原则：先审查再执行、批次验证、明确阻塞项、以证据为依据。

强制技能：无论采用何种执行模式，都必须加载 superpowers:behavior-driven-development。

关键——两个内部关卡技能是执行所必需的，不可省略。 每个实现子 Agent 的提示都必须要求其在报告任务完成之前加载 superpowers:verification-before-completion（不得声称完成，除非在返回内容中贴出最新验证证据）；批次协调器在对评估者的 REWORK 判定采取行动之前，必须加载 superpowers:receiving-code-review（针对代码库核实每项返工内容；不得盲目实现）。未在协调器提示中包含其中任一要求，均属违反协议。详见：./references/batch-execution-playbook.md（Agent 提示模板 + 返工循环）。

完成定义

参见 ./references/definition-of-done.md（不可协商；优先于所有其他指导）。

阶段 1：计划审查与理解

1. 阅读计划：阅读 _index.md，了解范围、架构决策，并从“Execution Plan”部分提取内嵌的 YAML 任务元数据。
2. 了解项目：探索代码库结构、关键文件，以及与计划相关的模式。
3. 检查阻塞项：参见 ./references/blocker-and-escalation.md。
4. 执行前冲突扫描（一次，在阶段 2 之前）：逐项核对每个任务的明确指令与已确定的 code-v{N}.md 检查清单，找出矛盾（例如，任务要求使用检查清单禁止的存根或重复逻辑）。如果没有发现冲突，则无需操作。参见 ./references/preflight-conflict-scan.md。

阶段 2：任务创建（强制）

参见 ./references/phase-2-task-creation.md。

阶段 3：批次执行循环（上下文重置架构）

参见 ./references/phase-3-orchestration.md 和 ./references/batch-execution-playbook.md。

关键——每次派发子 Agent 都必须声明模型。 使用 Agent 工具启动批次协调器或任何审查者时，务必显式传入 model（常规实现／验证使用 sonnet，仅在需要深入推理或最终全面审查分支时使用 opus，机械式全面检查使用 haiku）。未指定 model 时会静默继承会话中成本最高的模型层级——如果任其默认，派发就会偏向最高层级，耗尽预算。选择能胜任工作的最低成本层级；切勿让其默认。

关键——原生 Workflow 工具仅可选择性使用。 除非用户明确选择多 Agent 编排（表示“使用工作流”或类似意思，或已启用 ultracode），否则绝不可调用 Workflow。通过 /goal 运行时，绝不可在用户不知情的情况下静默分派后台 Agent。未经用户选择时，使用默认的、受限的 Agent 工具启动轮次，并用一句话说明该选项。选择规则和任务映射：../../skills/references/workflow-orchestration.md。

阶段 4：验证与反馈

参见 ./references/phase-4-verification.md。

第 5 阶段：Git 提交

使用 git-agent 提交实现更改（失败时回退到 git）。

操作：

1. 运行：git-agent commit --intent "<feature description>" --co-author "Claude <Model> <Version> <[email protected]>"
2. 如果出现身份验证错误，使用 --free 标志重试
3. 回退方案：如果 git-agent 不可用或执行失败，则通过 Skill 工具调用 /git:commit 技能；完整的回退流程见 ../../skills/references/git-commit.md

重要——提交后立即更新计划的 docs-index 行（不得延后）。 实现提交完成后，将计划的索引行状态更新为 implemented：bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" set-status <plan-path> "implemented:$(git rev-parse --short HEAD)"。然后将索引更新作为单独的小型提交：git-agent commit --no-stage --intent "mark <plan> implemented in docs index"。切勿使用 --amend——这会改写历史，并干扰 Stop hook 对 completion_commit 的检测（该 hook 会检查计划的修改文件集合中位于提交顶端的提交；若执行 amend，顶端提交会被悄然重指向）。

重要——有条件的记忆写入步骤，与上述后续提交合并（不得延后）。 是否执行取决于现有的计划内学习多样性差距信号（references/intra-plan-learning.md:54——某个批次的所有检查项均为 PASS，但该批次在达到 PASS 前需要经过 2 轮或更多返工）。如果本次运行中的任一批次触发了该信号，还要编写 docs/memory/pitfall_<slug>.md，记录反复出现的返工原因，然后运行 bash "${CLAUDE_PLUGIN_ROOT}/lib/docs-index.sh" upsert memory docs/memory/<path> --status active --summary "<one-line>" --category pitfall，并将其暂存到上述专用后续提交中——不要为此单独创建提交。此多样性差距触发条件与 batch-execution-playbook.md:165 中单独的硬中止上限明确不同（最多 2 轮返工后升级）；该上限不是记忆写入触发条件，而是用于控制返工循环的硬性停止点，不用于记录记忆。如果没有任何批次触发多样性差距信号，此步骤不执行。

有关模式、模板和要求，请参阅 ../../skills/references/git-commit.md。仅在所有任务完成后提交；使用有意义的功能范围。

第 6 阶段：完成

确认所有任务均已完成，然后输出完成摘要。

1. 最终任务审查：使用 TaskList 确认每项任务的状态均为 completed。如果有任何任务处于 in_progress 或 pending 状态，则不要继续——返回第 3 阶段完成剩余任务。
2. 摘要消息：“计划执行完成。所有 [N] 项任务均已验证并提交。”（面向用户；不是机器触发条件——见下方说明）。

完成日志会自动生成。 不要自行编写 docs/retros/plans-completed.jsonl。插件唯一的 Stop hook（hooks/stop-state-sync.sh）会根据磁盘上的持久状态检测计划是否完成——每个批次都已移交（handoff-summary-* 的数量 ≥ 批次数量），且有一个 Git 提交涉及 handoff-state.md 的修改文件集合——并以机械方式追加 plan_completed 事件，且只记录首次完成。检测基于状态，而非取决于你输出的任何句子，因此即使改写措辞或跳过摘要也能正常工作。/superpowers:retrospective 第 5a 阶段会从该日志读取 completion_commit。有关行格式，请参阅 ../retrospective/references/evolution-protocol.md §计划完成日志架构。

退出条件

所有任务均已执行并验证，证据已记录，没有阻碍，最终验证通过，Git 提交已完成。此技能全程自主运行——不需要用户批准。如需无人值守地跨多轮继续执行，请使用 /goal 包装（见文件顶部）。

参考资料

• ./references/blocker-and-escalation.md - 识别和处理阻塞项的指南
• ./references/preflight-conflict-scan.md - 在第 2 阶段之前，扫描任务与检查清单之间矛盾的第 1 阶段流程
• ./references/batch-execution-playbook.md - 批量执行模式
• ./references/definition-of-done.md - 不可妥协的完成规则
• ./references/phase-2-task-creation.md - TaskCreate / 依赖层级工作流
• ./references/phase-3-orchestration.md - 主 Agent 批次循环与协调器启动
• ./references/phase-4-verification.md - 证据、交接和计划内学习
• ../../skills/references/git-commit.md - Git 提交模式与要求（跨技能共享资源）
• ../../skills/references/goal-wrapper.md - /goal 包装器语义与条件措辞（跨技能共享资源）
• ../../skills/references/workflow-orchestration.md - 大型并行批次的原生 Workflow 升级机制（选择加入规则 + 任务映射）
• ./references/evaluation-file-formats.md - 评估文件格式定义（冲刺约定、评估报告、交接摘要）
• ./references/sprint-contract-template.md - 冲刺约定模板与协商协议
• ./references/handoff-template.md - 长期计划的交接摘要模板
• ./references/intra-plan-learning.md - 模式扫描、批次交接和检查清单演进格式
• ./scripts/batch-progress.sh - 根据文件系统生成的批次进度概览（每次迭代的第 1 步都运行）
• ../../lib/task-brief.sh - 将单个任务的文本提取到文件中，供实现者从磁盘读取（diff/task-text-as-files）
• ../../lib/review-package.sh - 生成净差异审查包文件，供评估者从磁盘读取
• ../../lib/task-ledger.sh - 持久化的逐任务完成记录；派发前检查，PASS 后追加