step-running

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Step Running

步骤执行

You execute a single step of a DAG plan as an atomic background sub-agent. You work autonomously to completion and report results — you do NOT interact with the user.

This is the DAG sibling of

phase-running

. The execution model and atomicity contract are identical; the differences are:

You receive a step file path (
```
step-<n>.md
```
), not a plan path + phase number.
You claim the step atomically via the step's frontmatter
```
status
```
field before doing work, and release it on completion / failure. This makes the same plan dir safe to drive from multiple orchestrator instances.

你作为原子性后台子Agent执行DAG计划的单个步骤。自主完成任务并报告结果——请勿与用户交互。

这是

phase-running

在DAG体系中的同类组件。执行模型和原子性契约完全相同，差异点在于：

你接收的是步骤文件路径（
```
step-<n>.md
```
），而非计划路径+阶段编号。
你在开始工作前，通过步骤文件的frontmatter
```
status
```
字段以原子方式认领步骤，并在完成/失败时释放认领。这使得同一计划目录可安全地由多个编排器实例驱动。

Execution Model

执行模型

This skill runs inside a background

Agent

(sub-agent). v-implementing (or a user invoking

/run-step

) spawns it via the Agent tool with

run_in_background: true

The step agent receives:

Step path: full path to
```
step-<n>.md
```
Plan dir: full path to the parent plan directory (read
```
root.md
```
from here for plan-level context)
Agent ID: unique identifier for this sub-agent (e.g. orchestrator session ID + step ID + timestamp). Used for atomic claim + stale-claim detection.
Relevant context: any extra context from the caller

该技能运行在后台

Agent

（子Agent）中。v-implementing（或用户调用

/run-step

）会通过Agent工具以

run_in_background: true

的方式启动它。

步骤Agent会接收：

步骤路径：
```
step-<n>.md
```
的完整路径
计划目录：父计划目录的完整路径（从此处读取
```
root.md
```
获取计划级上下文）
Agent ID：该子Agent的唯一标识符（例如编排器会话ID + 步骤ID + 时间戳），用于原子性认领和过期认领检测。
相关上下文：调用方提供的任何额外上下文

Concurrency: Atomic Claim

并发处理：原子性认领

Before doing any work, claim the step:

Read the step file's frontmatter.
If
status: done
— report
```
Status: skipped
```
and exit. The step is already finished.
If
status: claimed
and
```
assignee
```
differs from your agent ID:
- Fresh claim (
```
claimed_at
```
  within last hour): report
```
Status: blocked
```
  (reason:
```
claimed by <other-id>
```
  ) and exit.
- Stale claim (>1h): proceed and overwrite — the previous worker likely died.
Otherwise (
```
status: ready
```
, or stale
```
claimed
```
): rewrite the frontmatter block in a single
```
Edit
```
so the write is atomic-enough for filesystem-based coordination. Set:
- ```
status: claimed
```
- ```
assignee: <your-agent-id>
```
- ```
claimed_at: <ISO timestamp UTC>
```
Re-read the file. If
```
assignee
```
is not yours, another worker raced you — report
```
Status: blocked
```
(reason:
```
lost claim race
```
) and exit.

On terminal transitions, set frontmatter:

Completed:
```
status: done
```
, clear
```
assignee
```
and
```
claimed_at
```
.
Blocked or failed (retry-able):
```
status: ready
```
, clear
```
assignee
```
and
```
claimed_at
```
. The orchestrator (or another worker) can retry.
Failed (non-retry-able): leave
```
status: claimed
```
so the orchestrator can investigate; include the reason in the report.

For true cross-machine atomicity (NFS, etc.), the caller is responsible for rendezvous (e.g. a shared lock service). The single-Edit pattern is good-enough for local filesystem and well-behaved network filesystems.

在开始任何工作前，先认领步骤：

读取步骤文件的frontmatter。
若
status: done
——报告
```
Status: skipped
```
并退出，该步骤已完成。
若
status: claimed
且
assignee
与你的Agent ID不同：
- 新鲜认领（
```
claimed_at
```
  在过去1小时内）：报告
```
Status: blocked
```
  （原因：
```
claimed by <other-id>
```
  ）并退出。
- 过期认领（超过1小时）：继续执行并覆盖认领——之前的工作进程可能已终止。
其他情况（
```
status: ready
```
，或过期的
```
claimed
```
）：通过单次
```
Edit
```
重写frontmatter块，确保写入操作对基于文件系统的协调具备足够原子性。设置：
- ```
status: claimed
```
- ```
assignee: <your-agent-id>
```
- ```
claimed_at: <ISO timestamp UTC>
```
重新读取文件。若
```
assignee
```
不是你的ID，说明其他工作进程抢先认领——报告
```
Status: blocked
```
（原因：
```
lost claim race
```
）并退出。

在最终状态转换时，设置frontmatter：

已完成：
```
status: done
```
，清除
```
assignee
```
和
```
claimed_at
```
。
阻塞或可重试失败：
```
status: ready
```
，清除
```
assignee
```
和
```
claimed_at
```
，编排器（或其他工作进程）可重试。
不可重试失败：保留
```
status: claimed
```
以便编排器排查，在报告中注明原因。

对于跨机器的真正原子性（如NFS等），调用方需负责同步（例如共享锁服务）。单次Edit模式对于本地文件系统和行为良好的网络文件系统已足够。

Autonomy

自主性

Step agents always run as Autopilot within the sub-agent. The calling context controls outer autonomy and human checkpoints.

CRITICAL: Step agents do NOT use AskUserQuestion. If something is ambiguous, report

Status: blocked

with details. The caller handles all user interaction.

步骤Agent始终在子Agent内部以Autopilot模式运行。调用上下文控制外部自主性和人工检查点。

关键注意事项：步骤Agent不得使用AskUserQuestion。若遇到模糊情况，报告

Status: blocked

并附上详情。所有用户交互由调用方处理。

Process Steps

流程步骤

Step 1: Load Context

步骤1：加载上下文

Claim the step (see "Concurrency: Atomic Claim"). Stop here on any non-claim outcome.
Read the full step file.
Read
```
root.md
```
from the plan dir for plan-level context: Overview, Current State, Desired End State, Implementation Approach, Global Verification.
Read all files mentioned in the step's "Changes Required" section.

认领步骤（参见“并发处理：原子性认领”）。若认领未成功，在此终止。
读取完整的步骤文件。
从计划目录读取
```
root.md
```
获取计划级上下文：概述、当前状态、期望最终状态、实现方案、全局验证规则。
读取步骤“所需变更”部分中提及的所有文件。

Step 2: Pre-flight Check

步骤2：预检查

Check	Action if failed
All `depends_on` steps have `status: done`	Scheduler bug — release claim, report `blocked`
No merge conflicts in target files	Release claim, report `blocked`
Files/dirs from depended-on steps exist	Release claim, report `blocked`

检查项	检查失败时的操作
所有 `depends_on` 步骤的状态均为 `status: done`	属于调度器错误——释放认领，报告 `blocked`
目标文件无合并冲突	释放认领，报告 `blocked`
依赖步骤生成的文件/目录已存在	释放认领，报告 `blocked`

Step 3: Execute Step

步骤3：执行步骤

Implement the changes described in the step's "Changes Required" section. Adapt to minor mismatches; report

blocked

for significant ones.

实现步骤“所需变更”部分描述的修改。可适配轻微不匹配情况；若遇到重大不匹配，报告

blocked

。

Step 4: Run Verification

步骤4：运行验证

Same three-bucket pattern as

phase-running

Automated Verification (runnable commands): run each, record pass/fail. On failure, attempt one fix-and-retry.
Automated QA (agent-driven scenarios — browser-use, screenshot diff, CLI walkthrough): execute, record pass/fail per item.
Manual Verification: leave unchecked. Caller handles with the user.
QA Spec (linked doc): if present, report
```
QA Doc: <path>
```
. Do not execute scenarios inline.

采用与

phase-running

相同的三类验证模式：

自动化验证（可运行命令）：执行每个命令，记录通过/失败情况。失败时尝试一次修复并重试。
自动化QA（Agent驱动场景——浏览器操作、截图对比、CLI流程）：执行场景，记录每个项的通过/失败情况。
人工验证：保持未勾选状态，由调用方与用户协同处理。
QA规格文档（关联文档）：若存在，报告
```
QA Doc: <path>
```
，请勿在线执行场景。

Step 5: Update Step File

步骤5：更新步骤文件

Check off (
```
- [x]
```
) Automated Verification + Automated QA items that passed.
Do NOT check off Manual Verification items.
Update frontmatter
```
status
```
per "Concurrency: Atomic Claim" terminal-transition rules.
Update
```
last_updated
```
/
```
last_updated_by
```
frontmatter fields if present.

勾选（
```
- [x]
```
）通过的自动化验证和自动化QA项。
请勿勾选人工验证项。
根据“并发处理：原子性认领”中的最终状态转换规则更新frontmatter
```
status
```
。
若存在
```
last_updated
```
/
```
last_updated_by
```
frontmatter字段，更新其内容。

Step 6: Report Results

步骤6：报告结果

Completed:

Status: completed
Step: step-N - <Name>
Final frontmatter status: done
Files changed: [list]
Automated Verification: N/M passed
- [x] [Check 1] — passed
Automated QA: N/M passed
- [x] [Scenario 1] — passed
QA Doc: <path> | n/a
Manual verification needed:
- [ ] [Manual check 1]

Blocked / failed: mirror

phase-running

's shape, plus a

Final frontmatter status:

line so the orchestrator knows whether the step is released for retry (

ready

) or held for investigation (

claimed

已完成：

Status: completed
Step: step-N - <Name>
Final frontmatter status: done
Files changed: [list]
Automated Verification: N/M passed
- [x] [Check 1] — passed
Automated QA: N/M passed
- [x] [Scenario 1] — passed
QA Doc: <path> | n/a
Manual verification needed:
- [ ] [Manual check 1]

阻塞/失败： 沿用

phase-running

的报告格式，增加

Final frontmatter status:

行，以便编排器知晓步骤是否已释放可重试（

ready

）或保留待排查（

claimed

）。

Atomicity Contract

原子性契约

No interactive questions.
No partial states left unexplained.
Frontmatter
```
status
```
always reflects the final state at exit.
Report includes enough detail for the caller to decide next steps.

不发起交互式提问。
不留下未说明的中间状态。
Frontmatter
```
status
```
始终反映退出时的最终状态。
报告包含足够细节，供调用方决定后续操作。

Context Handoff Pattern

上下文传递模式

Direction	Data
Caller → Step Agent	Step path + plan dir + agent ID + autonomy mode
Step Agent reads	Step file + root.md + files in Changes Required
Step Agent writes	Frontmatter status transitions + checkboxes + code changes
Step Agent → Caller	Status + changed files + verification results + final frontmatter status
Caller handles	Manual verification, cross-step coordination, QA doc execution, human checkpoints

方向	数据
调用方 → 步骤Agent	步骤路径 + 计划目录 + Agent ID + 自主模式
步骤Agent读取	步骤文件 + root.md + 所需变更中的文件
步骤Agent写入	Frontmatter状态转换 + 勾选框 + 代码变更
步骤Agent → 调用方	状态 + 变更文件 + 验证结果 + 最终frontmatter状态
调用方处理	人工验证、跨步骤协调、QA文档执行、人工检查点