execute-blueprint

执行蓝图技能

用途

通过专用子 Agent 严格执行构建、审查和验证周期，逐步完成蓝图计划。如果审查或验证发现缺陷，修复子 Agent 会进行修复，然后重新审查和验证该步骤；只有在确实需要用户作出决定时，才会打断用户。主对话是用户与子 Agent 之间的协调枢纽：它会询问本技能中定义的问题，派遣子 Agent 执行工作，汇报结果，并按照用户选择的模式处理 git。主对话本身绝不会执行构建、审查、修复或验证工作。

将所有构建、审查、修复和验证工作交给子 Agent，才能让这项技能在长期、多里程碑计划中切实可行：大部分 token 开销——读取源文件、运行工具、记录完整输出——都由子 Agent 承担；它们一旦返回，上下文就会被回收。协调者的上下文只保存计划和每个子 Agent 返回的精简摘要，不会保存文件内容或工具输出，因此无论计划规模有多大，都能保持精简。

铁律

这些规则适用于每次执行会话。它们优先于任何建议走捷径的局部推理。

**主对话绝不亲自执行构建、审查、修复或验证工作。**

每项构建、审查、修复和验证工作都必须通过 Claude Code 的 Agent 工具派发给子 Agent。主对话仅负责：

• 向用户询问下文定义的关卡问题。
• 使用 references/subagent-prompts.md 中的模板派发子 Agent。
• 向用户报告结果、发现的问题、修复活动和升级处理情况。
• 按照用户选择的模式处理 git。
• 在计划文件中标记进度。

无论计划大小、步骤规模或任务看起来多么简单，这条规则都适用。一行配置变更也必须派发给构建子 Agent；审查发现中的一个字符修复，也必须派发给修复子 Agent。执行步骤期间，主对话不得编辑源文件、运行测试或直接运行代码检查工具。执行期间，主对话可使用的工具仅限于：读取计划、按“进度跟踪”中定义的格式进行特定修改并将进度标记写回计划、派发 Agent，以及在技能托管模式下创建 git 提交。

**这条规则之所以绝对，是因为：**将所有繁重工作交由子 Agent 完成，是保持协调者上下文窗口精简的机制。如果主对话读取源文件或直接获取工具输出，这些内容就会累积在其上下文中，导致技能在处理长计划时逐渐退化。子 Agent 的上下文是临时的——子 Agent 返回摘要后就会释放——因此协调者只需处理提炼后的结果，而无需承载产生这些结果的工作过程。

**阶段 1–3 是依次执行的硬性关卡。只有在本次会话中阶段 1、2 和 3 全部完成后，才能开始阶段 4（步骤执行）。**

每道关卡结束时都要向用户提问，并等待用户回答。不得将关卡问题与其他内容合并输出。不得假定用户在之前的会话中给出的回答仍然有效——每次新的执行会话都必须重新询问关卡问题，即使之前已执行过同一计划。

**只有在步骤的最终状态通过审查和验证后，才能提交该步骤。**

修复会更改代码，因此此前的审查和验证结果会失效。只有在最后一次更改之后的代码通过完整的审查和完整的验证，步骤才算完成。提交必须对应这个状态——绝不能提交中间尝试的结果、仍有未解决发现的问题的步骤，或尚未完全修复的工作树。

这条规则适用于两种 git 模式。在技能托管模式下，只要步骤仍在修复中或存在未解决的升级事项，就不得自动创建提交。在用户托管模式下，步骤未通过全部检查前，不得告知用户该步骤已可提交。

工作力度

将每个阶段都视为唯一一次把事情做对的机会。构建应当是完整的实现，而非草稿。审查应当真正严苛。验证必须运行所有工具并检查每项结果。修复也必须达到同样的标准：解决问题的根因，而不是仅仅做到检查变绿。步骤通过后，其代码应达到可用于生产的标准。

执行阶段

执行严格按照以下阶段顺序进行。第 1–3 阶段是关卡，必须全部完成后才能开始第 4 阶段。

1. 定位计划 — 查找或确认计划文件，报告目前的进度，并询问是否继续。
2. Git 模式关卡 — 询问用户选择由用户管理还是由技能管理 Git 操作。这是硬性关卡。
3. 节奏关卡 （有条件） — 仅当用户选择由技能管理且计划较复杂（包含多个里程碑）时，询问用户是在里程碑边界暂停，还是全程自动运行。这是硬性关卡。
4. 步骤执行 — 按步骤严格串行地调度构建、审查和验证子 Agent；自动修复范围内的问题，并将其余问题上报；按所选模式暂停并提交；在计划文件中标记进度。

阶段 1：定位计划

扫描 docs/plans/，查找计划文件。计划可以使用 Markdown（.md）或 HTML（.html）编写。搜索这两种扩展名，并将它们视为等同格式——单个 .md 文件、单个 .html 文件、包含 .md 文件的里程碑文件夹，以及包含 .html 文件的里程碑文件夹，都是有效的计划结构。

如果存在单个计划文件或文件夹，请使用它。如果存在多个计划文件或文件夹，请列出它们并询问用户要执行哪一个。对于包含编号步骤文件的里程碑文件夹，请从第一个尚未标记为已完成的步骤开始（有关每种格式中如何标记完成，请参阅下文的“进度跟踪”）。如果用户在请求中直接指定了计划文件（例如，“执行 01_milestone_name.md”或“执行 01_milestone_name.html”），则直接使用该文件，无需询问。

如果里程碑文件夹中的步骤文件混用了 .md 和 .html，则不符合规范：write-blueprint 不会生成混合格式的文件夹。请提醒用户，列出混合格式的文件，并询问本次运行要使用哪种格式。不要默默选择其中一种扩展名。

根据文件扩展名检测计划格式。格式只影响计划的解析方式和进度写回方式，不影响子 Agent 的调度方式。在本次会话的其余时间内缓存检测到的格式。

开始执行前，将整个计划文件读入上下文。识别所有步骤标题或步骤文章、各步骤的阶段说明（阶段 1 构建、阶段 2 审查、阶段 3 验证），以及步骤之间的依赖关系：

• 对于 Markdown 计划：步骤标题（### Step N: ...）用于划分步骤；阶段标题（#### Phase 1 — Build 等）用于划分阶段。
• 对于 HTML 计划：<article class="step" data-step="N"> 元素用于划分步骤；<section class="phase phase-build">、<section class="phase phase-review">、<section class="phase phase-verify"> 用于划分阶段。

统计步骤总数，并在询问用户是否继续之前，告知用户计划包含多少个步骤，以及其中有多少个已标记为完成。

如果用户要求只执行特定步骤（例如，“执行步骤 3–5”或“跳过步骤 2”），请按要求仅按顺序执行指定步骤，跳过其他步骤。如果被跳过的步骤包含所请求步骤所依赖的内容，请予以提醒。

根据计划结构确定计划的复杂程度：

• 简单计划：单个计划文档（.md 或 .html）。
• 复杂计划：包含多个里程碑文件的里程碑文件夹（.md 或 .html）。

复杂程度分类用于下文的节奏关卡。格式不影响复杂程度。

阶段 2：Git 模式门控

**本阶段到询问 Git 模式时结束——除此之外不做任何事。** 找到计划并报告进度后，询问用户要使用哪种 Git 模式，然后等待回答。不要开始执行步骤。暂时不要询问执行节奏——这要等用户回答 Git 模式后再问。不要派遣任何子 Agent。

向用户提供的选项必须恰好有两个，措辞如下或含义相同：

执行期间，你希望如何处理 Git？

1. 用户管理：每个步骤完成后我都会暂停。你可以按自己的节奏检查、暂存和提交。
2. 技能管理 （默认）：每个通过全部三个阶段的步骤完成后，我都会自动提交。

等待用户回答后再继续。每次新的执行会话都要重新询问——绝不能沿用之前会话中的选择。技能管理是默认提供的选项，但每次会话都仍须展示此门控：未获得用户选择或预先指定的模式时，不要悄然开始执行。

预先指定的回答：如果用户在首次执行消息中已经明确指定了模式（例如“以技能管理模式执行此计划”“使用用户管理模式并执行”），则接受该回答作为门控答案并继续。不要为了形式上的确认而再次询问。门控的目的是确保用户已做出选择，而不是一定要提问。如果措辞含糊（例如“你自己处理”），则询问门控问题。

用户管理模式

• 每个完成全部三个阶段（构建、审查、验证）的步骤结束后暂停。
• 用户自行检查更改、暂存文件并决定何时提交。
• 不要自动创建任何提交。
• 除非用户明确表示继续，否则不要恢复执行。
• 跳过执行节奏门控——无论计划复杂度如何，用户管理模式始终在每个步骤后暂停。

技能管理模式

• 每个通过全部三个阶段的步骤完成后，自动创建提交。
• 仍在修正中的步骤或存在未解决升级处理的步骤绝不提交。只有在最终状态下审查和验证均通过后，才能提交，具体遵循 <PASS-BEFORE-COMMIT> 规则。绝不提交未完成的步骤。
• 将计划文件中的进度更新（Markdown 计划的 ✅ 标题前缀和已勾选复选框；HTML 计划的 data-status="complete"、徽章文字、✅ 标题前缀和 checked 属性）与该步骤的实现更改一同提交——不要为计划进度单独创建提交。
• 使用清晰、描述性的 Conventional Commits 格式提交信息，并注明对应步骤。
• 提交信息中绝不包含 Claude Code 或 AI 署名。不得添加 co-authored-by 行、机器人签名或任何形式的 AI 标注。
• 暂停节奏由下方的执行节奏门控决定。

阶段 3：执行节奏门槛（仅限技能管理模式）

此门槛有条件适用。仅当以下两项都成立时才应用：

• 用户在阶段 2 中选择了技能管理模式。
• 计划较复杂（包含多个里程碑的文件夹）。

如果用户选择了用户管理模式，完全跳过此门槛，进入阶段 4——用户管理模式始终会在每个步骤后暂停。

如果用户选择了技能管理模式，且计划简单（单个文档），跳过此门槛并采用连续执行：不暂停地运行所有步骤，并在计划完成后呈现最终摘要。

如果用户选择了技能管理模式，且计划复杂，则运行以下门槛：

**本阶段以节奏选择问题结束——除此之外不做任何事。** 询问用户要采用哪种暂停节奏，然后等待答复。不要开始执行步骤。

向用户准确呈现以下两个选项，措辞可相同或等效：

该计划包含多个里程碑。你希望采用哪种暂停节奏？

1. 里程碑暂停（默认）：每完成一份里程碑文档后，我都会暂停并询问是否继续下一个。
2. 全自动：我会不间断地执行整个计划，包括跨越里程碑边界，并在最后呈现最终摘要。

等待用户答复后再继续。

预先说明的答案：如果用户的第一条执行消息（或对 Git 模式门槛的答复）已经明确说明了执行节奏（例如“技能管理全自动”“里程碑暂停”），则接受该答案作为门槛答复并继续。不要为形式上的确认再次询问。

里程碑暂停

• 每完成一份里程碑文档后，呈现里程碑摘要并询问是否继续。
• 在一个里程碑内，连续运行所有步骤，只在里程碑边界暂停。

全自动

• 不间断地连续运行所有里程碑中的所有步骤。
• 计划完成后呈现最终摘要。

阶段 4：通过子代理执行步骤

两个门槛都结束后，开始执行步骤。本阶段的所有工作都由主对话派发的子代理完成。

子 Agent 调度

使用 Claude Code 的 Agent 工具调度子 Agent。有关确切的提示词模板，请参阅 references/subagent-prompts.md。调度前，将占位符替换为实际值。

从计划中提取占位符内容：对于 Markdown 计划，逐字复制匹配标题下方的内容。对于 HTML 计划，提取匹配部分的内部内容（目标使用 <p class="step-objective">，验收标准使用 <section class="acceptance-criteria">，第 1 阶段指令使用 <section class="phase phase-build">，第 2 阶段使用 <section class="phase phase-review">，第 3 阶段使用 <section class="phase phase-verify">）。保留语义标记（<ul>、<ol>、<pre>、<code>、<p>、<a>），但去掉外层包装标签。子 Agent 可原生读取 HTML；不要将列表或代码块扁平化为纯文本。

构建子 Agent 调度：

• 将计划中的步骤目标文本逐字传入 {{STEP_OBJECTIVE}}。
• 将计划中的步骤验收标准列表逐字传入 {{ACCEPTANCE_CRITERIA}}。
• 将计划中的第 1 阶段指令逐字传入 {{PHASE_1_INSTRUCTIONS}}。
• 构建子 Agent 拥有读取和写入文件的完整文件系统访问权限。
• 从子 Agent 的响应中提取结构化构建摘要。

审查子 Agent 调度：

• 将计划中的步骤验收标准列表逐字传入 {{ACCEPTANCE_CRITERIA}}。
• 将提取的构建摘要传入 {{BUILD_SUMMARY}}。修复后重新审查时，按顺序传入原始构建摘要以及该步骤产生的每个修复摘要。
• 将计划中的第 2 阶段指令逐字传入 {{PHASE_2_INSTRUCTIONS}}。
• 审查子 Agent 会独立从磁盘读取文件——构建摘要仅用于提供背景和确定重点，不能视为可信事实来源。
• 解析审查响应，找出阻塞性问题以及审查者为每个问题指定的修复类别。

验证子 Agent 调度：

• 将计划中的第 3 阶段检查清单逐字传入 {{PHASE_3_CHECKLIST}}。
• 将项目的工具链配置（测试运行器、代码检查器、类型检查器命令）传入 {{TOOL_CHAIN_CONFIG}}。从计划的工具链表格中提取工具链——该配置已在规划期间由用户确认，是权威来源。对于 HTML 计划，表格位于 <section id="tool-chain"> 内。如果计划没有工具链表格，则从项目配置文件（pyproject.toml、package.json、Makefile 等）中检测并作为后备方案。缓存解析后的配置，并在后续验证调度中重复使用，除非计划明确更改了工具链要求。
• 验证子 Agent 会运行实际工具，并逐项报告检查通过或失败。
• 解析验证响应，找出所有失败项。任何一项检查失败都意味着整个验证阶段失败。

修复子 Agent 调度：

• 仅当下文的“失败处理：修复或升级”规则允许时才进行调度。
• 将计划中的步骤验收标准列表逐字传入 {{ACCEPTANCE_CRITERIA}}，并将第 1 阶段指令逐字传入 {{PHASE_1_INSTRUCTIONS}}——两者共同定义步骤的预期范围。
• 将构建摘要中的文件列表（以及该步骤先前修复周期更改的任何文件）传入 {{STEP_SCOPE}}。
• 将确切缺陷传入 {{FINDINGS_TO_FIX}}：阻塞性审查问题及其 file:line 引用，或验证检查失败项的完整错误输出，均须逐字传入且不得截断。
• 修复子 Agent 拥有完整文件系统访问权限。它会在范围内修复可处理的问题，并将无法处理的问题作为升级事项返回。
• 提取结构化修复摘要，并在决定下一步调度内容前读取其判定结果。

执行顺序

严格按顺序逐个执行步骤。步骤 A 必须完成整个周期——构建、审查、验证，以及这些阶段要求进行的任何修复——并通过后，才能开始步骤 B 的构建阶段。每个步骤的顺序始终如下：

1. 构建子代理 → 2. 审查子代理 → 3. 验证子代理。

审查或验证失败时，修复子代理会解决发现的问题，然后重新进行审查和验证——请参阅下文“失败处理：修复或升级”。只有针对最终状态完整通过审查和验证，步骤才算完成。

如果上一步的审查、修复或验证仍在进行，绝不能开始下一步的构建。绝不能同时运行多个步骤的构建（或审查，或验证）。每个步骤中的各阶段都必须依次通过，才能进入下一阶段；每个步骤都必须通过，才能进入下一步。协调器每次只分派一个子代理，并且只保留其返回的结构化摘要——绝不保留文件内容或工具输出，这样才能在漫长的计划中保持精简的上下文。

步骤通过所有三个阶段后，根据所选模式处理 git，并在计划文件中标记进度，然后决定是否暂停：

• 用户管理模式：每个步骤完成后暂停，让用户检查并提交。
• 技能管理模式：自动提交并继续下一步，不暂停——除非在里程碑暂停节奏下到达里程碑边界，此时应暂停并询问。简单计划和全自动模式则一路执行到底。

正常进度中的暂停完全由 git 模式和里程碑决定，不按固定数量的步骤分组。默认情况下，发现问题不会导致暂停——而是在当前流程中修复。如果存在待处理的升级事项，不要开始下一步的构建。

失败处理：修复或升级

审查发现阻塞性问题或验证检查失败时，该步骤尚未完成——但这也不意味着一定要向用户提问。本次运行刚刚产出的工作中，大多数问题都是普通缺陷，运行会自行修复。只有当决定确实应由用户做出时，才打断用户。

默认：修复。 阻塞性审查发现和失败的验证检查会由修复子代理自动解决，之后重新审查并验证该步骤。不要向用户请求许可，以修复本次运行造成的缺陷。

例外：升级。 当发现的问题带有升级类别、某一步的修复预算耗尽、某个子系统反复失败，或计划要求人工检查点时，应停止并将决定交由用户处理。

此政策在两种 git 模式下都相同。用户管理模式会在每个步骤完成后暂停，让用户检查并提交；但这并不意味着每个发现的问题都要变成一个问题交给用户决定。

升级类别

类别	何时升级	示例
design-decision	计划未明确正确行为。存在两种都有依据的修复方案，选择哪一种属于产品或设计决策。	验收标准未说明过期令牌该如何处理：拒绝、刷新还是重新认证？
scope-expansion	修复无法局限于该步骤声明的范围内。它需要新增依赖、变更公共接口、架构或配置约定，或修改该步骤原本不应触及的模块。	处理程序的 bug 只有通过修改供其他四个模块共用的序列化器才能修复。
destructive-or-external	修复会改变不属于该步骤的状态：现有数据、会删除或重写列的迁移、该步骤未创建的文件、Git 历史记录、远程或生产系统、凭据，或任何会在工作树之外产生副作用的内容。	只有执行会删除现有列的迁移，失败的测试才会通过。
environment	验证检查失败是因为缺少或配置错误的工具、服务或凭据。问题不在代码本身。	pytest: command not found；未安装类型检查器；无法访问必需的服务。

其他所有情况都属于 in-scope，无需询问即可修复。

由谁分配类别。 审查子 Agent 会为每个阻塞项标注上述类别之一，或标注为 in-scope。根据报告的输出对验证失败进行分类：除非输出明确表明缺少工具、服务不可用或凭据有问题（这些情况属于 environment），否则将其视为 in-scope。修复子 Agent 拥有最终决定权——它已阅读代码，因此它返回的任何升级项，无论最初标注为何，均应升级。

如果集合中任何发现项带有升级类别，就应在开始修复前停止。 不要先修复 in-scope 项。设计决策可能改变正确的修复方案，而修复了一半的代码树比完全未改动的代码树更难让用户判断。

修复周期

当集合中的所有发现项均为 in-scope，且不适用任何预算或检查点规则时：

1. 派发一个修复子 Agent，并提供需要修复的确切缺陷——包含 file:line 引用的阻塞项，或附带完整错误输出的失败检查。
2. 如果它返回 ESCALATE，则停止。报告它修复了哪些发现项、升级了哪些项，以及原因。
3. 否则，依次完整地重新运行审查子 Agent 和验证子 Agent。修复会改动审查通过的代码，而且修复可能导致原本通过的检查回归。切勿只重新运行失败的检查。
4. 如果两者均通过，则该步骤完成。照常继续处理 Git 和进度跟踪。
5. 如果任一项再次失败，则返回第 1 步——但须遵守下方的预算限制。

预算

在派发任何修复子 Agent 之前，按顺序执行以下检查。第一个触发的检查优先。

1. 升级类别 — 发现项中任意一项不属于 in-scope → 停止并升级。
2. 步骤预算 — 此步骤已使用 两次修复周期 → 停止并升级。Agent 阅读代码后进行了两次有针对性的尝试，仍未解决该步骤的问题；第三次通常也无济于事，而且实际问题往往并非表面上看起来的局部缺陷。
3. 子系统预算 — 这些发现所属的子系统在本次会话中已吸收 两次修复周期，且分别来自 两个不同的步骤 → 停止并请求架构决策，而不是请求修复许可。指出子系统，展示跨步骤出现的模式，并说明重复发现的共同点。两个步骤这一条件能区分模式与单个顽固步骤：如果一个步骤在同一处反复尝试，步骤预算已足以处理。

如果以上检查均未触发，则派发。

跟踪子系统计数器。 根据发现中所列文件在项目根目录下的最近公共父目录确定计数器键（src/auth/、app/models/）。如果所列文件在根目录下没有共同父目录，则使用第一个阻塞性发现所在的目录作为键。每派发一个修复周期，计数器就加一，并记录该周期来自哪个步骤——两个步骤这一条件取决于此记录。该计数器用于提示人工审查设计，并非正确性机制，因此键的确定方式可以是近似的。

两个预算均按会话计算。在新执行会话开始时重置；用户解决升级事项并要求继续后，相关计数器也会重置：用户的指示属于新信息，此前的尝试不再计入步骤或子系统预算。

人工检查点

如果计划本身要求人工检查，则暂停——即某个步骤的文本明确要求确认、签字、批准，或要求进行无法通过阅读代码或运行工具来完成的手动验证。准确说明需要确认的内容并等待。这与 Git 模式无关，也不同于用户管理模式下每个步骤完成后都会暂停的规定。

呈现升级事项

每次升级都要向用户说明同样的四项内容：

• 步骤，以及失败的阶段。
• 每一项发现，附上 file:line 引用；对于验证失败，提供完整的错误输出以供核实——不要截断。
• 说明为何停止而不是修复：升级类别、预算耗尽、子系统模式，或检查点。
• 说明此步骤已在磁盘上做出的任何修复变更，以便明确工作树状态。

然后等待。用户可以：

• 给出决策或指示，并要求据此重新运行修复。
• 自行修复问题，并要求重新运行审查和验证。
• 修改计划并重新运行此步骤。
• 跳过此步骤（标记为已跳过，而非已完成）。
• 中止执行。

如果用户选择通过任何方式继续此步骤，在将其标记为已完成或提交之前，仍须针对最终状态进行完整的审查和验证。绝不可基于部分通过的结果提交，也绝不可推进到下一步骤。

建议性发现

建议性发现不会阻塞，也不会进行修复。修复它们只是披着尽职外衣的范围蔓延。与步骤报告一并列出，由用户决定它们是否重要以及何时处理。

修复子 Agent 提出异议的发现——即它认为并非真实缺陷的发现——也不算失败。下一次审查会作出判断：如果新的审查者再次提出相同发现，则正常继续该周期并适用相关预算。即使步骤通过，也要在步骤报告中列出这些异议，让用户了解被驳回的意见。

失败不会回滚

已经通过并标记为完成的步骤，无论后续发生什么，都会保留其完成标记。步骤 B 失败不会撤销步骤 A。如果某个步骤结束会话时仍有未处理的升级事项，则将其记录为 failed（HTML 计划），或不做标记（Markdown 计划）——绝不能标记为完成。

进度跟踪

步骤的最终状态通过审核和验证后，立即在计划文件中将其标记为完成。具体修改取决于在阶段 1 中检测到的计划格式。

Markdown 计划（.md）：进行两项更新：

1. 在步骤标题前加上勾号。例如，将 ### Step 1: Auth middleware 改为 ### ✅ Step 1: Auth middleware。
2. 勾选已完成步骤中的所有 Markdown 复选框：将该步骤阶段 3 验证清单中的每个复选框（以及步骤中的其他复选框）的 - [ ] 改为 - [x]。

HTML 计划（.html）：对步骤的 <article class="step" data-step="N"> 元素进行三项更新：

1. 将 data-status 属性从当前值（通常为 pending）改为 complete。这是规范的机器可读状态，也是恢复进度时的判断依据。
2. 在 <header class="step-header"> 内步骤 <h3> 元素的文本前加上 ✅ 。例如，将 <h3>Step 1: Auth middleware</h3> 改为 <h3>✅ Step 1: Auth middleware</h3>。这是面向用户的可见标记。
3. 更新状态徽章文本，并为验证复选框添加 checked 属性：
   • 将 <span class="status-badge">Pending</span> 改为 <span class="status-badge">Complete</span>（徽章颜色会通过内联 CSS 自动更新）。
   • 对该步骤 <section class="phase phase-verify"> 内的每个 <input type="checkbox" disabled> 添加 checked 属性 → <input type="checkbox" disabled checked>。不要修改其他步骤的复选框。

使用 Edit（或等效的精确字符串替换）进行这些修改——不要重写整个文件。write-blueprint 技能中 references/step-template-html.md 定义的 HTML 框架使用稳定的 ID（id="step-N"）和类名，便于进行有针对性的编辑。

将所有更改写入磁盘上的计划文件，以便在不同会话间保留进度。恢复执行时：

• 对于 Markdown 计划，查找第一个标题前没有 ✅ 前缀的步骤。
• 对于 HTML 计划，查找第一个 data-status 不是 complete 的 <article class="step">（通常为 pending，也可能是此前会话遇到问题时的 failed/skipped）。

其他终止状态（failed、skipped）遵循相同的修改模式，但使用相应的 data-status 值和徽章文本。非完成终止状态不要添加 ✅ 前缀。

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

恢复执行时修改计划

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

• 根据审核结果修改步骤说明。
• 在现有步骤之间添加了新步骤。
• 删除了不再需要的步骤。
• 因依赖关系调整了步骤顺序。
• 修改了验收标准或验证清单。

恢复执行时按计划原样执行。除非步骤的依赖关系似乎已被破坏（例如，某个步骤引用了已删除步骤的产物），否则不要对更改提出警告或质疑。

新的执行会话也会重新运行门禁阶段（阶段 2，以及适用时的阶段 3）。恢复未完成的计划不会跳过门禁——用户的 git 模式和执行节奏偏好仅适用于当前会话，不属于计划内容。

步骤报告

每个步骤完成后，都要提供步骤报告。自动修复过程必须清晰可见：用户如果看不到自动修复了什么，就无法判断是否应该信任它。详细程度取决于执行模式：

• 用户管理模式（每个步骤后暂停）：提供完整的步骤报告，包含步骤标签和状态、变更文件数、阻断性和建议性问题的数量（如有建议性问题，简要列出）、运行的修复周期及每个周期修复的内容、存在争议的问题、验证结果摘要（通过的检查数/总检查数），以及采取的 Git 操作（已暂停，等待用户处理）。
• 技能管理的连续模式（简单计划或全自动）：将每个步骤报告精简为一行，包含步骤标签、状态、变更文件数、修复周期数、验证结果和提交哈希。在运行结束时提供全面总结。
• 技能管理的里程碑暂停模式：里程碑内的步骤使用精简的单行格式。每个暂停点都提供完整的里程碑总结。

每份里程碑总结和运行结束总结都要包含修复汇总：哪些步骤需要修复、每个周期修复了什么，以及存在争议的问题——让用户可以在一处审查自动修复的工作，而不必从各步骤报告中拼凑信息。

危险信号——停止并重新阅读此技能

如果出现以下任何想法，说明即将违反此技能。继续之前请停止并纠正做法。

想法	事实
“这个计划很短，我就跳过 Git 问题吧。”	阶段 2 每次会话都会运行，不受计划规模影响。请提问。
“用户刚才只说了‘继续’——我就假设由技能管理。”	每次会话仍会展示此关卡。技能管理是默认选项，但对于用户尚未看到的关卡，“继续”并不算回答——如果还没问过关卡问题，就要提问。
“用户上次选了技能管理，我这次就沿用吧。”	模式选择的范围是会话，而非计划。每次新会话都要重新询问。
“这只是一个简单的单行编辑，我直接在这里改吧。”	不行。分派构建子 Agent——如果是修复某项发现，则分派修复子 Agent。仅限子 Agent 法则没有规模例外。
“我自己运行测试确认吧——这样更快。”	不行。验证由验证子 Agent 执行。主聊天在步骤执行期间不运行测试。
“构建子 Agent 的摘要已经够了——我就跳过审查子 Agent 吧。”	不行。每个步骤都要运行全部三个阶段。审查会独立读取磁盘上的文件。
“我先完成所有构建，再做所有审查吧。”	不行。步骤严格按顺序串行执行：每个步骤都必须完整完成构建 → 审查 → 验证，然后才能开始下一步的构建。
“计划只有 2 个里程碑，我就跳过节奏问题吧。”	在技能管理模式下，任何复杂（多里程碑）计划都会触发节奏关卡。两个里程碑也算。
“里程碑计划采用用户管理模式——我还应该询问节奏吗？”	不用。节奏关卡仅在技能管理模式下触发。用户管理模式始终会在每个步骤后暂停。
“我把计划进度单独压缩成一个提交，这样差异会更干净。”	不行。计划进度标记（Markdown 复选框或 HTML data-status／徽章／复选框属性）要与步骤实现放在同一个提交中。
“步骤 B 验证失败了，但步骤 A 通过了——我回滚 A 吧。”	不行。已完成的步骤要保留其完成标记。失败会阻止后续进展，但不会撤销先前的进展。
“审查发现了一个真正的错误——我问问用户想怎么处理吧。”	不行。本次运行造成的范围内缺陷会自动修复。只有升级类别、预算耗尽、子系统模式或计划检查点才需要询问。
“两项发现属于升级类别，但另外三项很容易修——我先修好那三项吧。”	不行。如果这组发现中有任何一项需要升级，就要在修复前停下。用户的决定可能会改变正确的修复方案。
“修复已经解决问题，验证也通过了——我就跳过重新审查吧。”	不行。修复改动了通过审查的代码。必须完整重新运行审查和验证。
“只有检查 #4 失败了，所以我只重新运行检查 #4 吧。”	不行。修复可能导致其他检查回归。每次都要重新运行完整的验证清单。
“这个测试有问题——我把它标记为 xfail，这样步骤就能通过了。”	绝不允许。削弱测试、放宽断言或放松 lint 规则来让结果变绿，是披着通过外衣的失败步骤。应当升级处理。
“修复需要从 users 表中删除一列，但这也是唯一的办法。”	升级处理。绝不自动修复破坏性操作或外部状态问题，无论修复看起来多么显而易见。
“这是 src/auth 中的第三轮修复——再试一次应该就行了。”	不行。同一子系统中的第三轮修复属于架构决策，而不是再打一个补丁。停下并说明这种模式。
“修复子 Agent 提出了升级处理，但我知道答案——我直接指示它怎么做吧。”	不行。升级类别按定义必须由用户决定。说明情况并等待。
“建议性发现很容易修，我正好在处理，就顺手修掉吧。”	不行。建议性发现绝不修复。报告后继续。
“这个步骤基本完成了——我现在提交，下一步再清理吧。”	不行。<PASS-BEFORE-COMMIT>：提交必须完整记录一个通过审查和验证的状态，不能低于这个标准。

以上任何情况都意味着：停下，重新阅读相关阶段或法则，并按原文执行。