execute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Execute

执行

Purpose

用途

Execute blueprint plans by driving each step through a strict build, review, and verify cycle using dedicated subagents. Keep the main conversation lean and focused on orchestration and user decisions while subagents handle the heavy implementation, review, and verification work. Ensure every step meets its acceptance criteria before marking it complete and moving on.

通过专用subagent，遵循严格的构建、审核、验证周期推进每个步骤，以此执行蓝图计划。主对话保持精简，聚焦于流程编排和用户决策，繁重的实现、审核、验证工作则交由subagent处理。在标记步骤完成并进入下一个步骤前，需确保每个步骤都满足其验收标准。

Effort Level

工作量等级

Treat each phase as the only chance to get it right. Builds should be complete implementations, not drafts. Reviews should be genuinely adversarial. Verifications must run every tool and inspect every result. After all three phases pass, the step's code should be production-ready.

将每个阶段都视为一次性做对的唯一机会。构建应当是完整的实现，而非草稿。审核应当是真正的对抗性审核。验证必须运行所有工具并检查每一项结果。三个阶段全部通过后，该步骤的代码应当达到生产就绪标准。

Workflow

工作流程

Locate the Plan

定位计划

Scan

docs/plans/

for plan files. If a single plan file exists, use it. If multiple plan files or milestone folders exist, present the list to the user and ask which to execute. For milestone folders containing numbered step files, start from the first step that is not marked with a checkmark. If the plan file is specified directly in the user's request (e.g., "execute 01_milestone_name.md"), use that file without asking.

Read the entire plan file into context before beginning execution. Identify all step headings, their phase instructions (Phase 1 build, Phase 2 review, Phase 3 verification), and any dependencies between steps. Count the total number of steps and report to the user how many steps the plan contains and how many are already marked complete before asking to proceed.

If the user requests executing only specific steps (e.g., "execute steps 3-5" or "skip step 2"), honor the request — execute only the specified steps in order, skipping others. Warn if skipped steps contain dependencies required by the requested steps.

扫描

docs/plans/

目录下的计划文件。如果只有一个计划文件，直接使用该文件。如果存在多个计划文件或里程碑文件夹，向用户展示列表并询问要执行哪一个。对于包含编号步骤文件的里程碑文件夹，从第一个没有标记对勾的步骤开始执行。如果用户请求中直接指定了计划文件（例如“执行01_里程碑名称.md”），无需询问直接使用该文件。

开始执行前将完整的计划文件读入上下文。识别所有步骤标题、对应的阶段说明（第一阶段构建、第二阶段审核、第三阶段验证），以及步骤之间的所有依赖关系。统计总步骤数，在询问用户是否继续前，告知用户计划包含的总步骤数以及已标记完成的步骤数。

如果用户要求仅执行特定步骤（例如“执行步骤3-5”或“跳过步骤2”），遵循该要求——按顺序仅执行指定步骤，跳过其他步骤。如果被跳过的步骤包含指定步骤所需的依赖项，需发出警告。

Git Handling

Git处理

Before executing the first step, ask the user which git mode to use. Present exactly two options:

User-managed mode:

Pause after each individual step completes all three phases (build, review, verify).
The user inspects changes, stages files, and commits at their discretion.
Do not create any commits automatically.
Do not resume execution until the user explicitly says to continue.
Even when steps are batched, pause after each individual step within the batch. The batch boundary serves as a cumulative progress checkpoint — present a batch summary after the final step in the batch, but the user has already had the opportunity to review after each step.

Skill-managed mode:

After each individual step passes all three phases, create a commit automatically.
Include the plan file's progress updates (✅ heading prefix and ticked checkboxes) in the same commit as the step's implementation changes — do not create a separate commit for plan progress.
Use a clear, descriptive commit message in conventional commits format referencing the step.
Never include Claude Code or AI attribution in commit messages. No co-authored-by lines, no bot signatures, no AI references of any kind.
After committing, proceed to the next step without pausing (unless the batch boundary is reached).

Store the user's choice and apply it consistently for the remainder of the execution session. If the user wants to switch modes mid-session, they must say so explicitly. Default to asking every time — never assume a mode from a previous session.

执行第一个步骤前，询问用户使用哪种git模式。仅提供以下两个选项：

用户管理模式：

每个单独步骤完成全部三个阶段（构建、审核、验证）后暂停。
用户自行检查变更、暂存文件、按需提交。
不自动创建任何提交。
用户明确要求继续前，不要恢复执行。
即使步骤被分批处理，批次内的每个单独步骤完成后都要暂停。批次边界作为累计进度检查点——批次内最后一个步骤完成后展示批次总结，但用户已经有机会在每个步骤完成后进行检查。

技能管理模式：

每个单独步骤通过全部三个阶段后，自动创建一个提交。
将计划文件的进度更新（✅标题前缀和已勾选的复选框）与该步骤的实现变更放在同一个提交中——不要为计划进度单独创建提交。
使用清晰、描述性的conventional commits格式提交信息，关联对应的步骤。
提交信息中绝对不要包含Claude Code或AI归属信息，不要有co-authored-by行、机器人签名、任何形式的AI相关引用。
提交完成后，无需暂停直接进入下一个步骤（除非到达批次边界）。

存储用户的选择，在本次执行会话的剩余流程中统一应用该模式。如果用户想要在会话中途切换模式，必须明确提出。默认每次都要询问——永远不要假设沿用之前会话的模式。

Step Execution

步骤执行

Group steps into batches of up to 3 steps maximum. Execute steps strictly serially within a batch: Step A must complete its full build, review, and verify cycle and pass all three phases before Step B begins its build phase. The execution order within a batch is always:

Step A: Build → Review → Verify (all must pass)
Step B: Build → Review → Verify (all must pass)
Step C: Build → Review → Verify (all must pass)

Never batch builds together. Never batch reviews together. Never batch verifications together. Never start Step B's build while Step A's review or verification is pending. Each phase gates the next phase. Each step gates the next step.

After a batch completes (all steps in the batch passed all phases), handle git according to the chosen mode, then present a batch summary to the user showing which steps completed. Ask whether to proceed with the next batch.

将步骤分组为批次，每个批次最多包含3个步骤。批次内的步骤严格串行执行：步骤A必须完成完整的构建、审核、验证周期且三个阶段全部通过后，步骤B才能开始构建阶段。批次内的执行顺序始终为：

步骤A：构建 → 审核 → 验证（必须全部通过）
步骤B：构建 → 审核 → 验证（必须全部通过）
步骤C：构建 → 审核 → 验证（必须全部通过）

永远不要将多个构建放在一起批处理，永远不要将多个审核放在一起批处理，永远不要将多个验证放在一起批处理。永远不要在步骤A的审核或验证还未完成时就开始步骤B的构建。每个阶段都是下一个阶段的闸门，每个步骤都是下一个步骤的闸门。

批次完成后（批次内所有步骤都通过全部三个阶段），根据选择的模式处理git，然后向用户展示批次总结，说明已完成的步骤。询问是否继续执行下一个批次。

Subagent Dispatch

Subagent调度

Use Claude Code's Agent tool to dispatch subagents. Reference

references/subagent-prompts.md

for the exact prompt templates. Substitute placeholders with actual values before dispatching.

Build subagent dispatch:

Pass the step's objective text verbatim from the plan into
```
{{STEP_OBJECTIVE}}
```
.
Pass the step's acceptance criteria list verbatim from the plan into
```
{{ACCEPTANCE_CRITERIA}}
```
.
Pass the step's Phase 1 instructions verbatim from the plan into
```
{{PHASE_1_INSTRUCTIONS}}
```
.
The build subagent has full filesystem access to read and write files.
Capture the structured build summary from the subagent's response.

Review subagent dispatch:

Pass the step's acceptance criteria list verbatim from the plan into
```
{{ACCEPTANCE_CRITERIA}}
```
.
Pass the captured build summary into
```
{{BUILD_SUMMARY}}
```
.
Pass the step's Phase 2 instructions verbatim from the plan into
```
{{PHASE_2_INSTRUCTIONS}}
```
.
The review subagent reads files independently from disk — the build summary is provided for orientation and focus, not as a trusted source of truth.
Parse the review response to identify any blocking findings.

Verification subagent dispatch:

Pass the step's Phase 3 checklist verbatim from the plan into
```
{{PHASE_3_CHECKLIST}}
```
.
Pass the project's tool chain configuration (test runner, linter, type checker commands) into
```
{{TOOL_CHAIN_CONFIG}}
```
. Extract the tool chain from the plan's Tool Chain table — it was confirmed by the user during planning and is the authoritative source. If the plan has no Tool Chain table, detect from the project's config files (pyproject.toml, package.json, Makefile, etc.) as a fallback. Cache the resolved configuration and reuse it for subsequent verification dispatches unless the plan explicitly changes tool chain requirements.
The verification subagent runs actual tools and reports pass/fail per checklist item.
Parse the verification response to identify any failures. A single failed check means the entire verification phase fails.

使用Claude Code的Agent工具调度subagent。参考

references/subagent-prompts.md

获取准确的提示词模板，调度前将占位符替换为实际值。

构建subagent调度：

将计划中步骤的目标文本原样传入
```
{{STEP_OBJECTIVE}}
```
。
将计划中步骤的验收标准列表原样传入
```
{{ACCEPTANCE_CRITERIA}}
```
。
将计划中步骤的第一阶段说明原样传入
```
{{PHASE_1_INSTRUCTIONS}}
```
。
构建subagent拥有完整的文件系统读写权限。
从subagent的响应中提取结构化的构建总结。

审核subagent调度：

将计划中步骤的验收标准列表原样传入
```
{{ACCEPTANCE_CRITERIA}}
```
。
将提取到的构建总结传入
```
{{BUILD_SUMMARY}}
```
。
将计划中步骤的第二阶段说明原样传入
```
{{PHASE_2_INSTRUCTIONS}}
```
。
审核subagent独立从磁盘读取文件——提供构建总结仅用于定位和聚焦方向，不作为可信的事实来源。
解析审核响应，识别所有阻塞性问题。

验证subagent调度：

将计划中步骤的第三阶段检查清单原样传入
```
{{PHASE_3_CHECKLIST}}
```
。
将项目的工具链配置（测试运行器、linter、类型检查器命令）传入
```
{{TOOL_CHAIN_CONFIG}}
```
。从计划的工具链表中提取工具链——该配置已在规划阶段得到用户确认，是权威来源。如果计划中没有工具链表，作为 fallback 从项目的配置文件（pyproject.toml、package.json、Makefile等）中检测。缓存解析后的配置，后续调度验证subagent时复用，除非计划明确变更了工具链要求。
验证subagent运行实际的工具，按检查清单项报告通过/失败状态。
解析验证响应，识别所有失败项。只要有一个检查项失败，整个验证阶段即失败。

Failure Handling

失败处理

If the review subagent returns any blocking finding, stop immediately. Do not proceed to verification. Do not attempt to auto-fix. Do not retry the build. Present the full blocking findings to the user with file:line references and explanations. Wait for the user to provide guidance on how to proceed. The user may choose to:

Fix the issues manually and ask to re-run the review.
Ask the skill to re-run the build with additional instructions.
Skip the step (mark it as skipped, not as complete).
Abort execution entirely.

If the verification subagent returns any failed check, stop immediately. Do not proceed to the next step. Do not attempt to auto-fix. Present the full failure details to the user including complete error output. Wait for the user to provide guidance. The same options apply as with blocking review findings.

Advisory review findings do not block execution. Present them to the user as informational notes after the step passes all phases. The user may choose to address them later or ignore them.

Steps that have already passed all three phases and been marked complete retain their checkmarks regardless of subsequent failures in other steps. A failure in Step B does not roll back Step A.

如果审核subagent返回任何阻塞性问题，立即停止。不要进入验证阶段，不要尝试自动修复，不要重试构建。向用户展示完整的阻塞性问题，包含文件:行号引用和说明。等待用户提供下一步指引。用户可以选择：

手动修复问题，要求重新运行审核。
要求技能携带额外说明重新运行构建。
跳过该步骤（标记为已跳过，而非已完成）。
完全终止执行。

如果验证subagent返回任何失败的检查项，立即停止。不要进入下一个步骤，不要尝试自动修复。向用户展示完整的失败详情，包括完整的错误输出。等待用户提供指引，可选操作与审核阻塞性问题的处理选项一致。

建议性的审核发现不会阻塞执行。在步骤通过所有阶段后，作为信息提示告知用户。用户可以选择后续处理或忽略这些问题。

已经通过全部三个阶段并标记为完成的步骤，无论后续其他步骤是否失败，都保留已完成的标记。步骤B的失败不会回滚步骤A的进度。

Progress Tracking

进度追踪

Immediately after a step passes all three phases (build, review, verify), mark it complete in the plan file with two updates:

Prepend a checkmark to the step heading. For example, transform
```
### Step 1: Auth middleware
```
into
```
### ✅ Step 1: Auth middleware
```
.
Tick all markdown checkboxes within the completed step by changing
```
- [ ]
```
to
```
- [x]
```
for every checkbox in that step's Phase 3 verification checklist (and any other checkboxes within the step).

Write both changes to the plan file on disk so progress persists across sessions. On resume, scan the plan file for the first step heading that does not have a ✅ prefix and begin execution from that step.

If the user previously paused execution (user-managed git mode), re-read the entire plan file before resuming. The user may have edited the plan during the pause — added steps, removed steps, reordered steps, or modified instructions. Honor whatever the plan file contains at resume time.

步骤通过全部三个阶段（构建、审核、验证）后，立即在计划文件中标记为完成，包含两处更新：

在步骤标题前添加对勾。例如，将

### 步骤1：认证中间件

改为

### ✅ 步骤1：认证中间件

。

勾选完成步骤内的所有markdown复选框，将该步骤第三阶段验证清单中的所有
```
- [ ]
```
改为
```
- [x]
```
（以及该步骤内的其他所有复选框）。

将两处变更写入磁盘上的计划文件，确保进度跨会话持久化。恢复执行时，扫描计划文件找到第一个没有✅前缀的步骤标题，从该步骤开始执行。

如果用户之前暂停了执行（用户管理git模式），恢复执行前重新读取完整的计划文件。用户可能在暂停期间编辑了计划——添加步骤、删除步骤、重排步骤顺序或修改说明。恢复执行时完全遵循计划文件的当前内容。

Plan Modifications on Resume

恢复执行时的计划变更处理

Always re-read the plan file from disk when resuming execution. Never rely on a cached version of the plan from a previous session or earlier in the conversation. The user may have:

Edited step instructions based on review findings.
Added new steps between existing steps.
Removed steps that are no longer needed.
Reordered steps for dependency reasons.
Modified acceptance criteria or verification checklists.

Accept the plan as-is at resume time. Do not warn about or question changes unless a step's dependencies appear to be broken (e.g., a step references artifacts from a removed step).

恢复执行时始终从磁盘重新读取计划文件，永远不要依赖之前会话或对话早期缓存的计划版本。用户可能已经：

根据审核发现编辑了步骤说明。
在现有步骤之间添加了新步骤。
删除了不再需要的步骤。
因依赖关系重排了步骤顺序。
修改了验收标准或验证检查清单。

恢复执行时直接接受计划的当前内容。除非步骤的依赖关系看起来被破坏（例如某个步骤引用了已删除步骤的产出物），否则不要对变更发出警告或提出质疑。

Subagent Architecture

Subagent架构

Phase	Receives	Does
Build	Phase 1 instructions (verbatim from plan); full filesystem access	Read context, implement changes, write tests, return structured summary listing files changed with intent, key decisions, and any deviations
Review	Acceptance criteria (verbatim from plan) + build summary (structured, for orientation) + Phase 2 instructions (verbatim from plan)	Read all changed files fresh from disk, verify each acceptance criterion is met, perform adversarial review, return findings categorized as blocking or advisory with file:line references
Verification	Phase 3 checklist (verbatim from plan, includes acceptance criteria) + tool chain configuration	Execute each check using actual tools, return pass/fail per checklist item with full error output on failure

The review subagent reads files independently from disk. The build summary tells it where to look and what was intended, but the review subagent verifies everything by reading actual file contents. This prevents a build subagent from misrepresenting its own output.

The verification subagent runs real commands. It does not estimate whether tests pass. It does not guess linter output. It executes the tools and reports what happened.

阶段	接收输入	执行内容
构建	第一阶段说明（从计划原样获取）；完整文件系统访问权限	读取上下文、实现变更、编写测试、返回结构化总结，列出变更的文件及其用途、关键决策和所有偏离要求的内容
审核	验收标准（从计划原样获取） + 构建总结（结构化内容，用于定位方向） + 第二阶段说明（从计划原样获取）	从磁盘重新读取所有变更的文件，验证每个验收标准都已满足，执行对抗性审核，返回分类为阻塞性或建议性的问题，附带文件:行号引用
验证	第三阶段检查清单（从计划原样获取，包含验收标准） + 工具链配置	使用实际工具执行每个检查项，按清单项返回通过/失败状态，失败时附带完整错误输出

审核subagent独立从磁盘读取文件。构建总结仅告知它需要查看的位置和预期实现的内容，但审核subagent会通过读取实际文件内容验证所有信息，避免构建subagent谎报自身输出。

验证subagent运行真实的命令，不会预估测试是否通过，不会猜测linter输出，而是执行工具并报告实际运行结果。

Batching Rules

分批规则

Maximum batch size: 3 steps.
Execution within a batch: strictly serial. Step N must pass build, review, and verify before Step N+1 begins.
After a batch completes:
- User-managed git mode: pause and wait for the user. Present the batch summary. The user commits at their discretion.
- Skill-managed git mode: commits happen after each step within the batch. After the batch, present the batch summary and ask whether to continue.
If a step fails within a batch, the remaining steps in that batch do not execute. Present the failure and wait for guidance.
A batch never crosses milestone boundaries. If the current milestone has 2 remaining steps and the next milestone has steps, the current batch contains only those 2 steps.
If the plan has fewer remaining steps than the batch size, the batch contains only the remaining steps.

最大批次大小：3个步骤。
批次内执行：严格串行。步骤N必须通过构建、审核、验证后，步骤N+1才能开始。
批次完成后：
- 用户管理git模式：暂停并等待用户操作，展示批次总结，用户按需提交。
- 技能管理git模式：批次内每个步骤完成后都会自动提交。批次完成后，展示批次总结并询问是否继续。
如果批次内某个步骤失败，该批次剩余的步骤不再执行，展示失败信息并等待指引。
批次永远不会跨越里程碑边界。如果当前里程碑还剩2个步骤，下一个里程碑有其他步骤，则当前批次仅包含这2个步骤。
如果计划剩余步骤少于批次大小，批次仅包含剩余的步骤。

Step Reporting

步骤报告

After each step completes all three phases, present a concise step report to the user containing:

Step label and status (passed).
Count of files changed by the build subagent.
Count of blocking and advisory findings from the review (if any advisory findings exist, list them briefly).
Verification result summary (N/N checks passed).
Git action taken (committed with hash, or paused for user).

After a batch completes, present a batch summary listing all steps that completed in the batch and cumulative statistics.

每个步骤完成全部三个阶段后，向用户展示简洁的步骤报告，包含：

步骤标签和状态（已通过）。
构建subagent变更的文件数量。
审核发现的阻塞性和建议性问题数量（如果有建议性问题，简要列出）。
验证结果总结（N/N项检查通过）。
执行的Git操作（已提交，附带哈希值，或已暂停等待用户操作）。

批次完成后，展示批次总结，列出批次内完成的所有步骤和累计统计数据。

Additional Resources

额外资源

Refer to

references/subagent-prompts.md

for the complete prompt templates used when dispatching build, review, and verification subagents. These templates contain the exact system context, process instructions, constraints, and return format specifications for each subagent type. Substitute all placeholders with actual values before dispatching.

参考

references/subagent-prompts.md

获取调度构建、审核、验证subagent时使用的完整提示词模板。这些模板包含各类subagent的准确系统上下文、流程说明、约束和返回格式规范。调度前将所有占位符替换为实际值。