v-implementing

v-implementing

你正在实现由 v-planning 生成并已获批准的 DAG 结构计划。该计划是一个目录，包含 root.md 和每个节点对应的一个 step-<n>.md。你的工作是充当拓扑调度器：每一轮，找出所有依赖项均已完成的步骤，将它们作为并行子 Agent 分派（每个就绪步骤一个），等待完成后重复此过程，直到 DAG 中的所有步骤都已完成。然后运行全局验证。

这是 implementing 的并行版本。编排模型相同（子 Agent 负责执行，主会话负责协调），只有调度器不同。

工作约定

所有面向用户的问题都必须通过 AskUserQuestion 提出——约定请参见 desplega:ask-user。切勿在聊天中用普通项目符号提问。

所有读取、研究和验证工作都必须交由子 Agent 执行——不要将原始工具输出放在主会话中。默认使用 run_in_background: true。下方的扇出调度器基于此运行。

自主模式（下文所述）控制你多久确认一次进度。始终使用 AskUserQuestion 提问。

默认启用文件审查——某个步骤（或波次）有重大更改时，调用 /file-review:file-review <path> 获取内联反馈（仅 Autopilot 模式下跳过）。

自主模式

模式	行为
Autopilot	不暂停，直到 DAG 中所有步骤都已完成。仅在遇到阻塞或步骤失败时停止。
Critical（默认）	每个并行步骤波次完成后暂停；等待人工验证后再解锁下一波。
Verbose	每个步骤完成后暂停（即使该步骤属于某个波次）。

初始设置问题

了解计划后、调度器循环开始前，收集与实现相关的详细信息（Autopilot 模式下跳过）：

1. 分支 / Worktree 设置

检查当前分支：git branch --show-current。然后检查是否已安装 wts 插件（查看可用技能中是否有 wts:wts）。

如果已安装 wts，使用 AskUserQuestion：

问题	选项
"当前位于 <current-branch>。你希望在哪里进行实现？"	1. 在当前分支继续，2. 创建新分支，3. 创建 wts worktree

如果未安装 wts，移除 worktree 选项。

2. 提交策略

使用 AskUserQuestion：

问题	选项
"并行实现期间，你希望如何处理提交？"	1. 每个步骤完成后提交（推荐），2. 最后统一提交（单次提交），3. 过程中由我决定

如果选择“每个步骤完成后提交”，则在某个步骤通过人工验证后，创建提交：[step-N] <step name>。

3. 编排模式（仅当 Workflow 工具可用时）

问题	选项
"是否将 DAG 波次作为 Workflow 脚本运行？（确定性调度，将并行步骤作为 agent() 调用）"	1. 是 — 使用 Workflow 波次，2. 否 — 使用 Agent 扇出（默认）

选择“是”即表示明确选择启用 Workflow 工具所要求的功能。若选择启用，下面调度器循环中的每个波次都会作为一个 Workflow 脚本运行——通过 parallel() 并行调用 agent()，每个就绪步骤对应一个调用，并按照 desplega:delegate-work 为每个调用指定 model/effort。其他内容均不变：步骤 Agent 仍须遵循 step-running 约定（原子化 frontmatter 声明、三类验证），自主模式的暂停点仍位于 Workflow 调用之间，绝不会位于某次调用内部。在 Autopilot 模式下会跳过这些问题，因此不会启用 Workflow；除非用户预先授权，否则使用 Agent 扇出。

4. 代码审查模式

问题	选项
"是否在每个波次后自动进行代码审查？"	1. 每个波次自动进行双轴审查（推荐），2. 仅在最后进行一次审查（DAG 完成后），3. 关闭 — 我会自行审查

在 Autopilot 模式下，跳过此问题，并默认每个波次后自动审查。

开始使用

给定计划目录路径：

1. 完整读取 root.md（不使用 limit/offset）。提取：概述、当前状态、期望的最终状态、实施方案、全局验证。
2. 读取每个 step-<n>.md 的 frontmatter，构建依赖关系图（id、depends_on）。无需预先读取步骤正文，子 Agent 会负责读取。
3. 验证 DAG：
   • 不存在循环
   • 每个 depends_on ID 都对应一个步骤文件
   • 至少有一个步骤的 depends_on: []（否则无法启动任何步骤）
4. 将 root.md frontmatter 中的 status 设为 in-progress。
5. 构建 TodoWrite 列表，每个步骤对应一项，状态标为 pending。
6. **支持恢复：**如果某个步骤正文中已有 - [x] 复选框（或者用户添加的 frontmatter 中标明 status: completed），则信任这些标记，并将该步骤视为 done。

如果未提供路径，请通过 AskUserQuestion 询问。

调度器循环

调度器会读取每个步骤 frontmatter 中的 status（ready | claimed | done）和 depends_on。frontmatter 中的 status 字段是唯一真实来源——同一计划目录中的多个编排器实例通过它进行协调（每个 desplega:step-running 子 Agent 在执行工作前都会以原子方式认领其步骤）。

while any step has status != done:
    ready = [step for step in steps
             if step.status == "ready"
             and all(dep.status == "done" for dep in step.depends_on)]
    if not ready:
        # DAG drained, OR every remaining undone step is claimed by another worker
        if any step has status == claimed: wait for in-flight claims to resolve
        else: report stuck (likely cycle or unrecoverable failure)
        continue
    fan out each step in `ready` as a parallel `desplega:step-running` sub-agent
    wait for the wave to complete
    review reports; step-running has already updated frontmatter
        (status: done on success, status: ready on retry-able failure, status: claimed if held for investigation)
    if Critical mode: pause for manual verification of newly-completed steps
    if any failed: stop and ask user how to proceed

启动步骤子 Agent

使用 Agent 工具并设置 run_in_background: true，调用 desplega:step-running。传入：

• 步骤路径：step-<n>.md 的完整路径
• 计划目录：父计划目录的完整路径
• Agent ID：此子 Agent 的唯一 ID（例如，编排器会话 ID + 步骤 ID + 时间戳）。step-running 使用它进行原子认领和过期认领检测。
• 计划级上下文（可选）：摘自 root.md 的简要说明。step-running 会自行重新读取 root.md，因此提供此说明只是为了减少往返次数。

step-running 负责：

• 原子认领（将 frontmatter 中的 status: ready 重写为 status: claimed, assignee: <agent-id>, claimed_at: <ts>）
• 三类验证（自动化验证、自动化 QA、QA 文档识别）
• 终态转换（成功时设置 status: done，可重试的失败时设置 status: ready）
• 汇报结果

编排器不会自行执行步骤工作，而是进行委派。完整的子 Agent 约定请参阅 desplega:step-running。

执行器路由：如果 desplega:delegate-work 技能可用，请根据其路由矩阵为每个步骤选择执行器，而不要默认使用 step-running 子 Agent——某个步骤可能会路由到 Codex 变体（每个并行切片使用一个 worktree），也可能路由到特定 Claude 模型等级。只有执行器选择会改变；调度器、frontmatter 认领协议以及此处的其他所有语义都保持不变。当步骤路由到 Codex 时，编排器负责执行通常由 step-running 负责的 frontmatter 记录工作（Codex 不得编辑计划文件）。

波次完成

波次结束时：

1. 审阅每个 Agent 的报告。 只有报告表明步骤已completed，才将其标记为 done。
2. 运行波次代码审查（除非审查模式为 Off）——针对波次的合并差异调用 desplega:code-reviewing：按照 desplega:delegate-work 的路由规则，将 Standards 和 Spec 维度作为并行后台子 Agent 执行；Spec 来源 = 已完成步骤的正文和成功标准。关键问题会阻止相应步骤提交——先修复并重新验证。如果选择了“Only at the end”，则在 DAG 完成后针对完整差异运行一次审查。
3. 处理 QA Doc: <path>——对于报告了 QA 文档的每个步骤，针对该路径调用 desplega:qa。步骤中的 Automated QA 项目已由子 Agent 处理；这里只需单独协调所链接的文档。（QA: n/a → 正常继续。）
4. 手动验证（非 Autopilot 模式）——展示每个已完成步骤正文中的手动验证项。等待用户确认。确认前不要勾选手动验证框。
5. 提交（如果选择了每步提交）——某个步骤的手动验证通过后，创建提交：[step-N] <step name>。
6. 循环——重新计算 ready，并启动下一波次。

处理失败和不匹配

如果子 Agent 报告 failed 或 blocked，或你发现计划与实际情况不符：

问题	选项
“[step-N] [issue]。我应该如何继续？”	1. 调整步骤（编辑 step-N.md 并重试），2. 按原样重试，3. 跳过并继续（将步骤标记为 blocked），4. 停止运行

在 Autopilot 模式下，自行判断，在步骤文件中记录决定，并在问题并非致命时继续。

DAG 完成后

所有步骤均为 done 时：

1. 运行 root.md 中的全局验证。勾选自动化检查项；向用户展示手动检查项。
2. 将 root.md 前置元数据中的 status: completed 设置为已完成状态。
3. 提供实施后的审计选项：“您希望我对计划目录运行 /verify-plan 和 /review 吗？”
4. 如果未启用每步提交，询问是否现在创建一个合并提交。
5. 如果工作内容将通过 GitHub PR 发布：审查评论出现后，使用 desplega:tackle-gh-comments 处理（获取讨论线程、核实每项意见、修复、回复、解决——最后推送）。

重要指南

1. 一个步骤 = 一个子 Agent。 即使步骤处于同一波次，也不要将多个步骤合并交给一个 Agent——并行分派才是关键。
2. 每个子 Agent 都要获得计划级上下文。 不要提供兄弟步骤的正文。
3. DAG 以步骤前置元数据为准——如果 root.md 中的表格不同步，以前置元数据为准。
4. 支持按步骤粒度恢复。 如果用户在 DAG 中途重新运行 /v-implement，已完成的步骤保持完成；仅重新运行未完成的步骤。
5. 用户确认前不要勾选手动检查框——自动化检查框可由子 Agent 或协调者勾选。

审查集成

如果 file-review 可用且用户选择启用：

• 每个步骤完成重要代码更改后，调用 /file-review:file-review <changed-file>。
• 将步骤视为完成前，先使用 file-review:process-review 处理反馈。
• Autopilot 模式下跳过。