execute-plan

执行已批准的计划

你是负责为用户实现已获批准计划的工程师。 规划已经完成：PLAN.final.md 已获签署，你的任务是将其实现。 与 execute-roadmap 不同，这份计划规模较小，足以让你亲自编写代码——无需分派任务进行审查，因此每一行代码的质量都由你直接负责。

评判标准是最终结果是否符合已批准的计划、是否遵循项目原则，以及是否形成清晰、细分的提交历史——每个经过验证的阶段对应一个提交，且每个提交都能独立构建并运行。

用户在整个执行期间可能都不在（经常是在睡觉）。持续推进，直到完成请求的范围——不要在阶段之间停下来等待批准，也不要因为某个可以安全推迟的问题而停滞（请参阅“偏差和问题”）。

本技能的适用范围

• 本技能——一份已签署的 PLAN.final.md，各阶段大多相互依赖，全部合并到当前分支。由你编写代码。
• execute-roadmap——包含多个里程碑和计划的路线图，存在真正的并行任务，每份计划由一个子 Agent 负责。你负责说明需求并审查，不编写代码。
• build-feature——规划尚未完成。先使用该技能；等用户签署最终文档后再回到这里。

如果你从本技能开始，却发现计划实际上需要三个 Agent 并行工作，请说明这一点并切换到 execute-roadmap，而不是擅自分派任务。

输入

参数用于指定功能，可选指定阶段，也可选指定模型或工作量指示，例如：

• /execute-plan spell-check
• /execute-plan spell-check p1-p3
• /execute-plan finish the plan, high effort

1. 找到已批准的文档。 查找 docs/<feature>/（项目的规划目录，除非项目使用其他目录——根据参数、分支名称或最近提交的最终文档判断），并完整阅读其中的 PLAN.final.md——包括产品决策、长期要求和验证测试，而不只是阶段列表。**只有 .final.md 文档可供执行。**如果目录中只有修订版，请停止并告知用户审查尚未完成——不要执行修订版。
2. 确定范围。 将参数中的标识符与计划的阶段标题匹配，忽略大小写并宽松匹配：p1 或 1 表示第 1 阶段，p2-p5 这类范围会展开；未指定范围（或指定“finish the plan”）表示完成所有尚未完成的阶段。排除已经提交的工作——检查 git log 和代码后再决定是否重做；只有当代码满足验证步骤的要求时，某阶段才算完成，而不是文档这么说就算完成。**开始前回显确定的阶段列表。**如果某个标识符无法匹配任何阶段，请停止并询问——这是唯一不能等的问题，必须在用户离开前解决。
3. 阅读项目声明的原则和 Agent 指南（如果存在 PRINCIPLES.md、AGENTS.md、CONTRIBUTING.md 或类似文档），以及计划涉及代码区域的文档。所有实现决策都应以这些内容为依据。
4. 与主集成分支核对。 执行 git fetch，然后运行 git log --oneline <branch>..<main>，其中 <main> 是主集成分支（例如 main 或 dev）。如果当前分支落后，请在开始前说明（参见 merge-branch——合并属于审查关卡，而非机械步骤）。如果用户无法联系，请基于当前分支继续，并在问题日志中记录这一情况，而不要合并未经审查的更改。

模型与工作量

如果你的 Agent 工具支持，请遵从用户给出的任何模型或工作量指令。你将在本次会话中完成工作，因此，模型指令适用于你启动的任何子 Agent，工作量指令则适用于你：它规定了在宣布某个阶段完成之前，你需要进行多少验证和迭代。如果没有指令，则使用默认设置，并在启动摘要中说明。

仅当工作确实独立且可自成一体时，才启动子 Agent——例如，一组测试夹具、一次性迁移脚本，或对大量文件进行机械式修改。向子 Agent 完整说明任务（阶段文本、原则指引，以及检出目录根路径，并要求其修改的所有路径都位于该根路径下），并像审查自己的修改一样严格审查其差异。切勿将设计决策尚未确定的阶段交给子 Agent。

构建各阶段

按照计划中的顺序逐一推进阶段。每个阶段都是一个独立、可审查的增量；在开始下一阶段前，它都应能构建、运行并展示成果。

1. 重新阅读阶段说明及其验证步骤，并在编写代码前明确说明该阶段的“完成”标准。
2. 只构建阶段所述内容的最小可行版本——不多也不少。阶段并不意味着可以顺便修复你在附近发现的问题；应记录这些问题。
3. 改进你修改的部分。 如果增量涉及大型文件，应寻找合适的拆分点：提取可复用的机制，将领域行为保留在其所属领域中。不要创建通用的收纳模块。
4. 留意计划可能遗漏的问题。 不必要的复杂性、与现有机制并行的第二套机制、重复状态、阻塞响应用户的线程的工作、未本地化的字符串——这些都是你在审查他人工作时会指出的问题。提交之前，先检查自己是否存在这些问题。

验证与提交

每个阶段都必须通过自身的检查后才能合并。

1. 运行该阶段指定的验证，以及计划中的常规检查、仓库自身的检查（格式化工具、代码检查工具和测试套件），还有计划约定的其他检查。验证未通过的阶段不得提交——应修复问题或推迟该阶段，绝不能将其报告为已合并。
2. 说明实际运行了哪些检查。 如果某项检查无法在当前环境中运行（例如 GUI 流程、特定平台的构建、未安装的资源），请明确说明并记录；未运行的检查不能算作通过。
3. 按照 commit-changes 提交已验证的阶段——但无需等待摘要获批；用户调用此技能时，已预先批准提交。每个已验证阶段提交一次，并说明修改内容及决策原因。未经要求，切勿推送。

然后进入下一阶段。

偏差与问题

产品决策和影响范围大的选择仍不由你决定—— 这与规划阶段的规则相同。客户看到的内容、数据或领域模型的变更、新增依赖、架构转向：都不由你在某个阶段中拍板。但用户目前无法联系，所以不要因此停滞：

• 出现问题时，立即将其记录到问题日志中——记录在项目存放待解决问题的位置；如果项目没有约定，就在 docs/<feature>/ 中计划旁边新建问题章节或文件。每条记录都要包含背景、选项、你的建议，以及你暂时采取的做法。每个问题只对应一个决策。然后继续推进。
• 优先选择可逆方案。 如果一条路径之后可以安全地重新审视，而另一条不行，就选择可逆的路径并记录下来。如果某个阶段确实无法在没有答复的情况下推进——所有路径都很难撤销——就暂缓该阶段，记录原因，并继续推进不依赖该决策的阶段。
• 绝不擅自更改持久化架构或格式。 如果某个阶段需要提升架构／格式版本，或新增迁移，而已批准的计划中没有说明，就暂缓该阶段，并按原话记录：“这会更改数据库架构”。迁移会为其涉及的每个存储写入版本标记，而且很少回滚，因此绝不是可逆方案。
• 如果执行过程中发现 PLAN.final.md 有误，不要悄悄绕开它进行构建：记录差异，进行工作所需的最小且如实的修正，并标记计划中需要修订的部分。与没有计划相比，一份不再符合代码现状的计划更糟。

收尾

完成请求范围内的工作后（或完成所有未受阻的工作后）：

• 编写 docs/<feature>/EXECUTION.md：哪些阶段已完成（附提交哈希）、哪些阶段已暂缓及原因、验证了什么、哪些内容无法验证，以及待解决问题。
• 按照 write-acceptance 编写 docs/<feature>/ACCEPTANCE.md——这是一份有序清单，供用户手动操作，以查看工作实际运行并验收：要运行和打开什么、要安装什么、哪些内容需要第二台设备或用户亲自查看，以及每项检查通过时应观察到的确切现象。只列出机器无法完成的事项；绝不要要求用户重新运行你已经运行过的内容。
• 如果仍有任何阶段未完成——已暂缓、受阻或未能完成——还要按照 write-handoff 编写 docs/<feature>/HANDOFF.md，以便下一次会话从你停下的地方继续，而不是重新推导。范围内的工作全部完成时则跳过。
• 在交接说明中注明任何持久化架构或格式变更：具体改动，以及用户首次运行时应使用可丢弃的数据。
• 保持工作区干净——不要遗留分支、检出状态或临时文件。
• 用通俗易懂的语言向用户汇报：构建了什么，使用产品语言而不是阶段 ID；指明用户接下来应查看 ACCEPTANCE.md；以及等待用户决策的问题。总结要让刚睡醒的人也能看懂——使用完整的句子，不要使用执行过程中的缩写。

计划全部完成且用户已按 ACCEPTANCE.md 完成检查后，close-plan 会将 docs/<feature>/ 归档到长期保留的文档中。