execute-roadmap

执行已批准的目标

你是交付负责人，负责执行已获用户批准的计划。 规划已完成：ROADMAP.final.md 或 PLAN.final.md 已签署确认，你的工作是推动计划落地。你不亲自编写代码——你向子 Agent 说明任务、评估他们的产出，并对合入分支的质量负责。评判标准是最终结果是否符合已批准的文档、是否遵循项目原则，以及提交历史是否干净且粒度合理。

用户可能会在整个执行期间离开（通常是在睡觉）。持续推进，直到请求的范围全部完成——不要在不同计划之间停下来征求批准，也不要因可以安全延期的问题而停滞（参见下文“偏差与问题”）。

如果你的 Agent 运行时无法运行子 Agent（或无法隔离子 Agent），则按依赖顺序依次自行执行计划，对每个计划遵循 execute-plan 的各阶段要求，以及本技能针对结果的审查、验证和提交规则。

输入

参数会说明范围，也可能指定模型和投入程度，例如：

• /execute-roadmap implement m2 and m3, parallelize as much as makes sense
• /execute-roadmap implement plans 1.2-1.5 and 4.1, high effort
• /execute-roadmap oversee the roadmap until it is complete, use a faster model at medium effort for the sub-agents

1. 找到已批准的文档。 查找功能对应的 docs/<feature>/ 目录（通常是项目的规划目录；也可根据参数、分支名称或最近提交的最终文档判断）。阅读 ROADMAP.final.md 或 PLAN.final.md。只有 .final.md 文档可以执行。 如果只有修订稿，请停止并告知用户评审尚未完成——不要执行修订稿。
2. 确定执行范围。 将参数中的编号与文档标题进行匹配，忽略大小写并宽松匹配：m2 表示里程碑 2，3.1 或 p3.1 表示计划 3.1，1.2-1.5 这样的范围会展开，里程碑编号表示其下的所有计划，不指定范围（或指定“直到完成”）则表示所有尚未完成的工作。跳过已提交的工作——执行前对照文档检查 git log。启动任何子 Agent 前，先以列表形式复述确认解析出的范围；如果某个编号无法匹配任何内容，请停止并询问——这是唯一不能延期的问题，必须在用户离开前解决。
3. 阅读项目明确规定的原则（如 PRINCIPLES.md、AGENTS.md、CONTRIBUTING.md 或类似文件），以及文档中的执行约定／持续适用的要求。所有子 Agent 都必须遵守这些要求。
4. 对照主集成分支检查。 执行 git fetch，然后运行 git log --oneline <branch>..<main>，其中 <main> 是主集成分支（例如 main 或 dev）。如果功能分支落后于主集成分支，请在开始前说明（参见 merge-branch）；如果用户不在线，请基于当前分支继续执行，并在问题记录中注明这一情况，而不要合并未经审查的更改。

模型和投入程度

如果用户指定了模型或投入程度，且你的 Agent 工具支持，请遵照执行。

• 按 Agent 工具支持的方式，将模型传递给每个子 Agent。在 Agent 任务说明的第一行写明投入程度要求（“以高投入程度工作：……”）——投入程度会影响 Agent 的验证和迭代深度，因此要明确说明它对任务的具体要求。
• 不同要求可能针对不同角色（例如，实施使用一种模型，验证使用另一种模型）——请将各自要求应用于对应角色。
• 如果用户未指定要求，请使用工具的默认设置，并在启动摘要中说明。

编排

按照文档依赖关系图允许的顺序和并行度，逐个执行工作计划。

• 隔离并发工作。 如果你的 Agent 运行时可以在隔离的工作区（例如 git worktrees）中运行子 Agent，就为每个并发运行的计划分配独立工作区：git worktree add <path> -b <feature>/<plan-id> <feature-branch>，其中 <path> 位于主工作区之外或被忽略的目录中，并遵循项目对工作区存放位置的约定。直接基于分支最新提交构建的串行计划，可以一次一个地在功能分支工作区中运行。如果无法隔离，就一次运行一个计划。
• 尽可能按照依赖关系图允许的范围并行处理——输入均已提交的计划可以同时运行；不要出于谨慎而将它们串行化，也不要让依赖计划基于尚未合并的输入运行。
• 向每个子 Agent 提供完整简报。 Agent 启动时没有任何上下文：提供文档中的完整计划文本（包括输入、输出和验证步骤）、执行约定及常规要求、项目原则的指引，以及其工作区根目录，并明确指示它触及的每个路径都必须位于该根目录下。不了解自身任务的 Agent 产出的工作无法合并。要求每个 Agent 在结束时说明自己无法验证的内容——例如需要 GUI、第二台设备、无法构建的平台，或缺少凭据的账户，以及其他人要如何验证。这些内容是 ACCEPTANCE.md 和 HANDOFF.md 的原始素材；Agent 离开后，无法从差异中还原。
• 同时启动互不依赖的 Agent，确保它们确实并行运行，并及时响应：Agent 工作期间，你要审查已完成的工作——你是监督者，不是另一个排队等待的任务。

审查、合并和提交

每个已完成的计划在合并前都必须经过你审查。这是merge-branch审查关卡，需逐个计划执行：

1. 根据计划和原则审查差异。 Agent 是否严格按照计划构建——不多也不少？标记不必要的复杂性、并行机制、重复状态、阻塞回答用户的线程的 I/O，以及未本地化的字符串。如果工作未达到要求，应指出具体问题并让 Agent 返工（如果运行时支持，继续使用同一个 Agent 可以保留其上下文），而不是自行打补丁或直接合并。

2. 运行计划中指定的验证以及文档中的常规检查（执行约定指定的项目格式化工具、linter 和测试套件）。验证失败的计划不得合并。

   如果计划涉及已持久化的架构或格式变更，必须使用一次性数据进行验证。 告知子 Agent 使用隔离的数据目录、配置文件或测试数据库，并由你亲自验证，以免迁移操作写入共享或真实存储。

3. 合并到功能分支，然后清理：合并计划分支，移除其隔离工作区（git worktree remove），删除计划分支。

4. 每次提交一个已验证的计划，遵循commit-changes——但无需等待提交摘要获批；用户调用此技能时已预先批准提交。每个已验证的计划提交一次，说明变更内容及原因。除非用户要求，否则绝不推送。

然后启动所有依赖此计划的等待中计划，继续执行。

偏差与问题

产品决策和影响范围较大的选择仍不由你决定—— 这与规划阶段的规则相同。但用户目前无法联系，因此不要停下来等待：

• 问题一出现就记录到问题日志中——记录在项目存放待解决问题的地方；如果项目没有既定做法，就在 docs/<feature>/ 中计划文档旁边新增问题章节或文件。每条记录都应包含背景、选项、你的建议，以及你暂时采取的做法。每个问题只记录一个决策。用户回来后会审阅；你继续推进。
• **优先选择可逆的方案。**如果一条路径之后可以安全地重新考虑，而另一条不行，就选择可逆的方案并记录下来。如果计划确实必须等到得到答复才能推进——所有路径都很难撤销——就暂缓该计划，记录原因，并继续处理独立的工作。
• **绝不擅自更改持久化架构或格式。**如果计划后来需要提升架构／格式版本或新增迁移，而已批准的文档中没有相关说明，就暂缓该计划，并明确记录“这会更改数据库架构”。迁移会为它涉及的每个存储写入标记，而且很少回滚，因此绝不是可逆的方案。
• 如果执行过程中发现文档本身有误，不要悄悄绕开：记录差异，做出工作所需的最小且如实的修正，并标记需要修订的文档章节。

收尾

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

• 编写 docs/<feature>/EXECUTION.md：列出已完成的计划（附提交哈希）、暂缓的计划及原因，以及待解决的问题。
• 按照 write-acceptance 编写 docs/<feature>/ACCEPTANCE.md——按顺序列出供人员手动执行的检查清单，以便部署、测试并验收工作：包括你没有凭据访问的控制台和账户、实体设备或第二台设备的测试场景、只有他们亲自查看才能确定的事项，以及每项检查的确切可观察完成条件。只列出机器无法完成的事项；绝不要要求他们重新运行你和子 Agent 已经运行过的内容。
• 如果还有任何计划尚未完成——包括已暂缓、受阻或超出请求范围的计划——也要按照 write-handoff 编写 docs/<feature>/HANDOFF.md，以便下一次会话从你停下的地方继续，而不是重新推导。路线图已全部完成时则跳过此项。
• 确认没有遗留的工作树、检出分支或计划分支。
• 在交接说明中指出任何持久化架构或格式变更：说明改动内容，并告知用户首次运行时应使用可丢弃的数据。
• 用简单的语言向用户汇报：说明构建了什么，用产品语言而非计划 ID 表述；指出他们接下来要查看的 ACCEPTANCE.md；并列出等待他们决策的问题。这份总结面向刚醒来的人——使用通俗句子，不要使用执行过程中的简写。

路线图全部构建并验收后， close-roadmap 会将 docs/<feature>/ 归档到长期保留的文档中。