v-implementing

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

v-implementing

You are implementing an approved DAG-structured plan produced by

v-planning

. The plan is a directory with

root.md

+ one

step-<n>.md

per node. Your job is to act as a topological scheduler: at each tick, find steps whose dependencies are all done, fan them out as parallel sub-agents (one per ready step), wait, repeat — until the DAG is drained. Then run Global Verification.

This is the parallel sibling of

implementing

. The orchestration model is the same (sub-agents do the work, main session coordinates), only the scheduler is different.

你正在实现由

v-planning

生成的已获批DAG结构计划。该计划是一个包含

root.md

和每个节点对应一个

step-<n>.md

文件的目录。你的职责是作为拓扑调度器：在每个周期，找出所有依赖项已完成的步骤，将它们作为并行子Agent（每个就绪步骤对应一个）分发出去，等待执行完成，重复此过程直到DAG中的所有步骤都执行完毕。之后运行全局验证。

这是

implementing

技能的并行版本。编排模型一致（子Agent负责执行工作，主会话负责协调），仅调度器逻辑不同。

Working Agreement

工作约定

All user-facing questions go through
AskUserQuestion
— see

desplega:ask-user

for conventions. Never ask in chat as plain bullets.

All read/research/validation work goes through sub-agents — keep raw tool output out of the main session. Default to

run_in_background: true

. The fan-out scheduler below is built on this.

The autonomy mode (below) controls how often you check in. AskUserQuestion is always the mechanism.

File-review is on by default — when significant changes land in a step (or wave), invoke

/file-review:file-review <path>

for inline feedback (skip only if Autopilot).

所有面向用户的问题都需通过
AskUserQuestion
提交——遵循

desplega:ask-user

的约定。切勿在聊天中直接以普通项目符号形式提问。

所有读取/调研/验证工作都需通过子Agent完成——不要在主会话中展示原始工具输出。默认设置

run_in_background: true

。下方的分发调度器基于此规则构建。

自治模式（如下）控制你向用户汇报的频率。AskUserQuestion始终是提问的标准机制。

文件审核默认开启——当步骤（或某一轮并行步骤）中出现重大变更时，调用

/file-review:file-review <path>

获取内联反馈（仅在自动驾驶模式下可跳过）。

Autonomy Mode

自治模式

Mode	Behavior
Autopilot	Drain the DAG without pausing. Only stop on blocker / failed step.
Critical (Default)	Pause when each wave of parallel steps completes; wait for manual verification before unlocking the next wave.
Verbose	Pause after each individual step (even within a wave).

模式	行为
自动驾驶（Autopilot）	无需暂停，持续执行完DAG中的所有步骤。仅在遇到阻塞或步骤执行失败时停止。
关键节点（Critical）（默认）	每一轮并行步骤完成后暂停；等待人工验证通过后再解锁下一轮并行步骤。
详细模式（Verbose）	每个步骤执行完成后均暂停（即使是同一轮并行步骤中的步骤）。

Initial Setup Questions

初始设置问题

After understanding the plan and before the scheduler loop starts, gather implementation-specific details (skip in Autopilot):

在理解计划并启动调度器循环前，收集实现相关的具体细节（自动驾驶模式下可跳过）：

1. Branch / Worktree Setup

1. 分支/工作树设置

Check the current branch:

git branch --show-current

. Then check if the

wts

plugin is installed (look for

wts:wts

in available skills).

If wts is installed, use AskUserQuestion:

Question	Options
"You're on `<current-branch>` . Where would you like to implement?"	1. Continue on current branch, 2. Create a new branch, 3. Create a wts worktree

If wts is not installed, drop the worktree option.

检查当前分支：

git branch --show-current

。然后检查是否安装了

wts

插件（在可用技能中查找

wts:wts

）。

若已安装wts，使用AskUserQuestion提问：

问题	选项
"当前分支为 `<current-branch>` 。你希望在何处进行实现？"	1. 在当前分支继续，2. 创建新分支，3. 创建wts工作树

若未安装wts，则移除工作树选项。

2. Commit Strategy

2. 提交策略

Use AskUserQuestion:

Question	Options
"How would you like to handle commits during parallel implementation?"	1. Commit after each step completes (Recommended), 2. Commit at the end (single commit), 3. Let me decide as I go

If "Commit after each step" is selected, after a step's manual verification passes, create a commit:

[step-N] <step name>

使用AskUserQuestion提问：

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

若选择“每个步骤完成后提交”，则在步骤人工验证通过后，创建提交：

[step-N] <step name>

。

Getting Started

开始执行

Given a plan directory path:

Read
root.md
fully (no
```
limit
```
/
```
offset
```
). Capture: Overview, Current State, Desired End State, Implementation Approach, Global Verification.
Read every
step-<n>.md
's frontmatter to build the dependency graph (
```
id
```
,
```
depends_on
```
). You don't need to read step bodies up front — the sub-agents will do that.
Validate the DAG:
- No cycles
- Every
```
depends_on
```
  ID exists as a step file
- At least one step has
```
depends_on: []
```
  (otherwise nothing can start)
Set
root.md
frontmatter
status: in-progress
.
Build a TodoWrite list with one entry per step, marked
```
pending
```
.
Resume support: if any step's body has
```
- [x]
```
boxes already (or its frontmatter says
```
status: completed
```
if the user added it), trust them and treat that step as
```
done
```
.

If no path given, ask via AskUserQuestion.

给定计划目录路径后：

完整读取
root.md
（不要使用
```
limit
```
/
```
offset
```
参数）。记录：概述、当前状态、期望最终状态、实现方案、全局验证内容。
读取每个
step-<n>.md
的前置元数据以构建依赖图（包含
```
id
```
、
```
depends_on
```
字段）。无需预先读取步骤主体内容——子Agent会负责处理。
验证DAG：
- 无循环依赖
- 每个
```
depends_on
```
  中指定的ID都存在对应的步骤文件
- 至少有一个步骤的
```
depends_on: []
```
  （否则无法启动任何步骤）
将
root.md
的前置元数据
status
设置为
in-progress
。
创建TodoWrite列表，每个步骤对应一个条目，标记为
```
pending
```
。
恢复支持：若任何步骤的主体中已有
```
- [x]
```
已勾选框（或用户已将其前置元数据的
```
status
```
设为
```
completed
```
），则信任这些标记，将该步骤视为
```
done
```
。

若未提供路径，则通过AskUserQuestion询问用户。

The Scheduler Loop

调度器循环

The scheduler reads each step's frontmatter

status

(

ready

claimed

done

) and

depends_on

. The frontmatter

status

field is the single source of truth — multiple orchestrator instances on the same plan dir coordinate through it (each

desplega:step-running

sub-agent atomically claims its step before doing work).

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

调度器读取每个步骤前置元数据中的

status

（

ready

claimed

done

）和

depends_on

字段。前置元数据中的

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已执行完毕，或所有未完成的步骤已被其他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

Spawning a Step Sub-agent

生成步骤子Agent

Use the

Agent

tool with

run_in_background: true

, invoking

desplega:step-running

. Pass:

Step path: full path to
```
step-<n>.md
```
Plan dir: full path to the parent plan directory
Agent ID: unique ID for this sub-agent (e.g. orchestrator session ID + step ID + timestamp). step-running uses this for atomic claim + stale-claim detection.
Plan-level context (optional): a quick brief from
```
root.md
```
. step-running re-reads
```
root.md
```
itself, so this is just to reduce round-trips.

step-running

owns:

Atomic claim (rewrite frontmatter

status: ready

→

status: claimed, assignee: <agent-id>, claimed_at: <ts>

)

Three-bucket verification (Automated Verification, Automated QA, QA Doc identification)
Terminal status transition (
```
status: done
```
on success,
```
status: ready
```
on retry-able failure)
Reporting back

The orchestrator does NOT do step work itself — it delegates. See

desplega:step-running

for the full sub-agent contract.

Executor routing: if the

desplega:delegate-work

skill is available, pick each step's executor per its routing matrix instead of defaulting to a

step-running

sub-agent — a step may route to a Codex variant (one worktree per parallel slice) or a specific Claude model tier. Only the executor choice changes; the scheduler, frontmatter claim protocol, and all other semantics here stay unchanged. When a step routes to Codex, the orchestrator owns the frontmatter bookkeeping that

step-running

would normally do (Codex must not edit plan files).

使用

Agent

工具并设置

run_in_background: true

，调用

desplega:step-running

。传入以下参数：

步骤路径：
```
step-<n>.md
```
的完整路径
计划目录：父计划目录的完整路径
Agent ID：该子Agent的唯一ID（例如编排器会话ID + 步骤ID + 时间戳）。step-running使用该ID进行原子认领和过期认领检测。
计划级上下文（可选）：来自
```
root.md
```
的简要概述。step-running会自行重新读取
```
root.md
```
，此处传入仅为减少往返次数。

step-running

负责：

原子认领（将前置元数据中的

status: ready

改写为

status: claimed, assignee: <agent-id>, claimed_at: <ts>

）

三阶段验证（自动验证、自动QA、QA文档识别）
最终状态转换（成功时设为
```
status: done
```
，可重试失败时设为
```
status: ready
```
）
执行结果汇报

编排器自身不执行步骤工作——仅负责委托。请查看

desplega:step-running

了解子Agent的完整协议。

执行器路由：若

desplega:delegate-work

技能可用，则根据路由矩阵为每个步骤选择对应的执行器，而非默认使用

step-running

子Agent——步骤可能会路由到Codex变体（每个并行分片对应一个工作树）或特定的Claude模型层级。仅执行器选择会改变；调度器、前置元数据认领协议及所有其他语义保持不变。当步骤路由到Codex时，编排器需负责原本由

step-running

处理的前置元数据记录工作（Codex不得编辑计划文件）。

Wave Completion

并行步骤轮次完成

When a wave finishes:

Review each agent's report. Mark steps
```
done
```
only if
```
completed
```
was reported.
Handle
QA Doc: <path>
— for each step that reported a QA doc, invoke
```
desplega:qa
```
against that path. The Automated QA bucket inside the step is already handled by the sub-agent; only the linked doc needs separate orchestration here. (
```
QA: n/a
```
→ proceed normally.)
Manual verification (if not Autopilot) — present manual verification items from each completed step's body. Wait for user confirmation. Don't tick manual boxes until confirmed.
Commits (if commit-per-step was selected) — after a step's manual verification passes, create a commit:
```
[step-N] <step name>
```
.
Loop — recompute
```
ready
```
and start the next wave.

当一轮并行步骤完成时：

审核每个Agent的报告。仅当报告显示
```
completed
```
时，才将步骤标记为
```
done
```
。
处理
QA Doc: <path>
——对于每个报告了QA文档的步骤，针对该路径调用
```
desplega:qa
```
。步骤内部的自动QA阶段已由子Agent完成；仅需单独编排处理关联的文档。（若为
```
QA: n/a
```
则正常继续。）
人工验证（非自动驾驶模式下）——展示每个已完成步骤主体中的人工验证项。等待用户确认。在用户确认前不要勾选人工验证框。
提交（若选择按步骤提交）——步骤人工验证通过后，创建提交：
```
[step-N] <step name>
```
。
循环——重新计算
```
ready
```
步骤并启动下一轮并行执行。

Handling Failures and Mismatches

处理失败与不匹配

If a sub-agent reports

failed

blocked

, or you spot a mismatch between plan and reality:

Question	Options
"[step-N] [issue]. How should I proceed?"	1. Adapt step (edit step-N.md and retry), 2. Retry as-is, 3. Skip and continue (mark step blocked), 4. Stop the run

In Autopilot mode, use best judgment, document the decision in the step file, and continue if non-fatal.

若子Agent报告

failed

或

blocked

，或你发现计划与实际情况不匹配：

问题	选项
"[step-N] [问题描述]。我应如何处理？"	1. 调整步骤（编辑step-N.md并重试），2. 按原步骤重试，3. 跳过并继续（标记步骤为阻塞），4. 停止执行

在自动驾驶模式下，自行做出合理判断，将决策记录在步骤文件中，若为非致命问题则继续执行。

After the DAG Drains

DAG执行完毕后

When every step is

done

Run Global Verification from
```
root.md
```
. Tick automated checks; surface manual checks to the user.
Set
```
root.md
```
frontmatter
```
status: completed
```
.
Offer post-implementation auditing: "Would you like me to run
```
/verify-plan
```
and
```
/review
```
on the plan directory?"
If commit-per-step was off, offer to create a single bundled commit now.

当所有步骤均标记为

done

时：

执行
```
root.md
```
中的全局验证。勾选自动检查项；将人工检查项展示给用户。
将
```
root.md
```
的前置元数据
```
status
```
设置为
```
completed
```
。
提供实现后审计选项：“是否需要我对计划目录运行
```
/verify-plan
```
和
```
/review
```
？”
若未选择按步骤提交，则提供创建单次合并提交的选项。

Important Guidelines

重要指南

One step = one sub-agent. Don't bundle steps into a single agent even if they're in the same wave — fan-out is the whole point.
Plan-level context goes to every sub-agent. Sibling step bodies do not.
The DAG is canonical via step frontmatter — if
```
root.md
```
's table is out of sync, trust the frontmatter.
Resume works step-granular. If the user re-runs
```
/v-implement
```
mid-DAG, completed steps stay completed; only undone ones rerun.
Don't tick manual checkboxes until the user confirms — automated boxes can be ticked by the sub-agent or the orchestrator.

一个步骤对应一个子Agent。即使步骤属于同一轮并行执行，也不要将多个步骤捆绑到单个Agent中——分发执行是本技能的核心。
计划级上下文需传递给所有子Agent。但无需传递兄弟步骤的主体内容。
DAG的权威来源是步骤前置元数据——若
```
root.md
```
中的表格与前置元数据不一致，以前置元数据为准。
恢复执行以步骤为粒度。若用户在DAG执行过程中重新调用
```
/v-implement
```
，已完成的步骤保持完成状态；仅重新执行未完成的步骤。
不要勾选人工验证框——需等待用户确认后再勾选；自动验证框可由子Agent或编排器勾选。

Review Integration

审核集成

file-review

is available and the user opted in:

After each step's significant code changes, invoke
```
/file-review:file-review <changed-file>
```
.
Process feedback with
```
file-review:process-review
```
before treating the step as done.
Skip in Autopilot.

若

file-review

技能可用且用户已启用：

每个步骤出现重大代码变更后，调用
```
/file-review:file-review <changed-file>
```
。
在将步骤标记为完成前，使用
```
file-review:process-review
```
处理审核反馈。
自动驾驶模式下跳过此步骤。