build-train

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

build-train

Batch-execute multiple issues into a single build branch. Stage 01 plans the dependency order; stage 02 launches parallel build subagents in waves — concurrent where builds are independent, sequential where one build depends on another's output. Stage 03 merges all PRs into the build branch, stage 04 opens one final PR to the default branch (which runs the review pipeline once).

将多个issues批量执行到单个构建分支中。第01阶段规划依赖顺序；第02阶段分批次启动并行构建子代理——相互独立的构建会并发执行，存在依赖关系的构建则按顺序执行（一个构建依赖另一个构建的输出）。第03阶段将所有PR合并到构建分支，第04阶段向默认分支提交一个最终PR（仅运行一次审查流水线）。

Purpose

目的

Convert the monolithic

build-train

skill into an ICM procedure. The monolith dispatched workers in a single long-lived session; by the merge phase its context carried every worker prompt and log, degrading conflict-resolution judgement. This proc isolates each phase into a focused subagent and — critically — replaces the serial "spawn one worker, wait, spawn next" loop with a dependency-graph wave scheduler: builds with no unmet dependency run as concurrent Task subagents; dependent builds wait for their prerequisite's handoff.

将单体式

build-train

技能转换为ICM流程。原单体架构在单个长会话中调度工作进程；到合并阶段时，其上下文包含了每个工作进程的提示和日志，导致冲突解决判断能力下降。本流程将每个阶段隔离为专注的子代理，并且关键的是——用依赖图批次调度器替代了串行的“启动一个工作进程，等待，再启动下一个”循环：无未满足依赖的构建会作为并发Task子代理运行；有依赖的构建会等待其前置构建的交接。

Arguments

参数

Param	Required	Default	Notes
`repo`	yes	—	`org/repo` , first positional arg
`--issues`	yes	—	Comma-separated issue numbers, e.g. `10,14,15,16`
`--branch`	no	`build/YYYY-MM-DD`	Build branch name; `-2` suffix appended if it exists

Parse from

$ARGUMENTS

参数	是否必填	默认值	说明
`repo`	是	—	`org/repo` ，第一个位置参数
`--issues`	是	—	逗号分隔的issue编号，例如 `10,14,15,16`
`--branch`	否	`build/YYYY-MM-DD`	构建分支名称；如果已存在则追加 `-2` 后缀

从

$ARGUMENTS

中解析。

What it does

功能说明

6-stage ICM procedure:

Stage	Mode	Description
00-setup	inline	Default branch, create build branch + label, read all issues
01-plan-order	subagent	Read issue bodies, derive dependency graph, emit build waves
02-build-fanout	subagent (PARALLEL)	Fan out builds wave-by-wave: parallel within a wave, sequential across edges. Each build = one Task worker producing a PR; verify + fix base/label
03-merge-chain	subagent	Merge each build-train PR into the build branch, resolve conflicts
04-final-pr	subagent	Open one final PR build branch → default branch (no build-train label)
05-report	inline	Write report, emit outcome marker

6阶段ICM流程：

阶段	模式	描述
00-setup	内联	获取默认分支，创建构建分支并添加标签，读取所有issues
01-plan-order	子代理	读取issue内容，生成依赖图，输出构建批次
02-build-fanout	子代理（并行）	分批次启动构建：同一批次内并行执行，跨依赖边时按顺序执行。每个构建对应一个生成PR的Task工作进程；验证并修复基准分支/标签
03-merge-chain	子代理	将每个build-train PR合并到构建分支，解决冲突
04-final-pr	子代理	提交一个从构建分支到默认分支的最终PR（无build-train标签）
05-report	内联	生成报告，输出结果标记

Handoff locations

交接文件位置

.procedure-output/build-train/{stage}/handoff.md

Stage 02 additionally writes one sub-handoff per build:

.procedure-output/build-train/02-build-fanout/builds/{issue}.md

Stage 00 writes the root context (repo, default branch, build branch, issue manifest). All subagent stages receive only the handoffs they need — never the full orchestrator context.

.procedure-output/build-train/{stage}/handoff.md

第02阶段还会为每个构建生成一个子交接文件：

.procedure-output/build-train/02-build-fanout/builds/{issue}.md

第00阶段会写入根上下文（仓库、默认分支、构建分支、issue清单）。所有子代理阶段仅接收所需的交接文件——绝不会接收完整的编排器上下文。

Execution

执行步骤

Stage 00 (inline)

第00阶段（内联）

Run yourself. Read CONTEXT.md:

.claude/skills/build-train/stages/00-setup/CONTEXT.md

Write handoff to

.procedure-output/build-train/00-setup/handoff.md

自行运行。读取CONTEXT.md：

.claude/skills/build-train/stages/00-setup/CONTEXT.md

将交接文件写入

.procedure-output/build-train/00-setup/handoff.md

。

Stage 01 (subagent)

第01阶段（子代理）

Spawn one Task. Pass the 00-setup handoff path + stage CONTEXT.md path only.

启动一个Task。仅传递00-setup交接文件路径和阶段CONTEXT.md路径。

Stage 02 (subagent — internally PARALLEL, wave scheduler)

第02阶段（子代理——内部并行，批次调度器）

Spawn ONE Task for the fan-out stage. That stage's CONTEXT.md drives the wave loop: it reads the build order from stage 01, then for each wave launches all of that wave's builds as concurrent Task workers in a SINGLE response and does NOT wait between them within the wave; it waits for the whole wave before starting the next. Builds joined by a sequential edge land in later waves.

Task prompt template (used for every subagent stage):

You are running stage {NN}-{name} of the build-train procedure.

Read your stage instructions:
  .claude/skills/build-train/stages/{NN}-{name}/CONTEXT.md

Your inputs:
  {only the input handoff paths this stage's CONTEXT.md lists}

Write your output to:
  .procedure-output/build-train/{NN}-{name}/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

为扇出阶段启动一个Task。该阶段的CONTEXT.md驱动批次循环：从第01阶段读取构建顺序，然后为每个批次启动该批次的所有构建作为并发Task工作进程，在单个响应中完成，批次内不等待；等待整个批次完成后再启动下一批次。存在顺序依赖的构建会被安排到后续批次。

Task提示模板（所有子代理阶段通用）：

You are running stage {NN}-{name} of the build-train procedure.

Read your stage instructions:
  .claude/skills/build-train/stages/{NN}-{name}/CONTEXT.md

Your inputs:
  {only the input handoff paths this stage's CONTEXT.md lists}

Write your output to:
  .procedure-output/build-train/{NN}-{name}/handoff.md

Execute all steps in CONTEXT.md. Write handoff.md before exiting.

Stages 03 → 04 (sequential subagents)

第03 → 04阶段（串行子代理）

For each, spawn one Task. Pass only the handoffs that stage's CONTEXT.md lists as inputs. Do not start the next stage until the current completes. On stage failure, emit the failure marker and stop only if the failure is unrecoverable (see Exit paths).

每个阶段启动一个Task。仅传递该阶段CONTEXT.md列出的交接文件作为输入。当前阶段完成后再启动下一阶段。如果阶段失败，输出失败标记，仅当失败不可恢复时才停止（参见退出路径）。

Stage 05 (inline)

第05阶段（内联）

Run yourself. Read CONTEXT.md and emit the

[pylot] outcome=...

marker from the orchestrator (never from a subagent).

自行运行。读取CONTEXT.md并从编排器输出

[pylot] outcome=...

标记（绝不能从子代理输出）。

Stage handoff chain

阶段交接链

00 ─► 01 ─► 02 ─► 03 ─► 04 ─► 05 (inline, reads all)

02 internal wave fan-out:
   wave 1: [build A] [build B] [build C]   ← concurrent Task subagents
              │         │         │
              └────── all join ───┘
   wave 2: [build D depends on A] [build E depends on B,C]   ← concurrent
              │                        │
              └──────── all join ──────┘
   wave 3: [build F depends on D] ...

00 ─► 01 ─► 02 ─► 03 ─► 04 ─► 05 (内联，读取所有内容)

02内部批次扇出：
   wave 1: [build A] [build B] [build C]   ← 并发Task子代理
              │         │         │
              └────── 全部完成 ───┘
   wave 2: [build D depends on A] [build E depends on B,C]   ← 并发
              │                        │
              └──────── 全部完成 ──────┘
   wave 3: [build F depends on D] ...

Exit paths

退出路径

Success: stage 05 emits

[pylot] outcome="build-train complete: final PR #N (M/N issues)" status=success

Failure: failing stage emits

[pylot] outcome="build-train failed at stage NN: {reason}" status=failed

Blocked: stage 00 finds an existing

build/*

train in progress →

[pylot] outcome="build-train blocked: existing build branch {name}" status=blocked

Per-build failures inside stage 02 do NOT fail the train — the failed issue is skipped and the train proceeds (skip-rather-than-break). The train only fails if zero builds succeed.

成功：第05阶段输出

[pylot] outcome="build-train complete: final PR #N (M/N issues)" status=success

失败：失败阶段输出

[pylot] outcome="build-train failed at stage NN: {reason}" status=failed

阻塞：第00阶段发现存在正在进行的

build/*

分支 →

[pylot] outcome="build-train blocked: existing build branch {name}" status=blocked

第02阶段内的单个构建失败不会导致整个流程失败——失败的issue会被跳过，流程继续执行（跳过而非中断）。仅当所有构建都失败时，流程才会失败。

Hard Rules

硬性规则

Stage 02 builds within a wave MUST launch in parallel — all of a wave's Task calls in one response, no waiting between them.
Respect sequential edges — a build whose dependency is unmet is held to a later wave; never launch it before its prerequisite's sub-handoff exists.
Worker prompts MUST specify
--base $BUILD_BRANCH
— primary instruction, repeated twice in the prompt.
Verify and fix every PR after its build worker completes — change base branch and add the
```
build-train
```
label if the worker got it wrong.
Final PR has NO
build-train
label — it enters the normal review pipeline.
Never force push the build branch.
Skip rather than break — a failed build or unmergeable PR is skipped and logged; the train continues.
One build-train per repo at a time — stage 00 checks for existing
```
build/*
```
branches before starting.
SCOPE LOCK — each worker works only its assigned issue, nothing else.
Stage 00 and 05 run inline — the
```
[pylot] outcome=...
```
marker MUST come from the orchestrator.
Never pass full orchestrator context into subagent Task prompts — inputs only.
Each stage writes handoff.md before the next reads it. No stage skipped (execute even if action is "nothing to do").

第02阶段同一批次内的构建必须并行启动——同一批次的所有Task调用在一个响应中完成，批次内不等待。
遵守顺序依赖——依赖未满足的构建会被安排到后续批次；绝不能在其前置构建的子交接文件生成前启动它。
工作进程提示必须指定
--base $BUILD_BRANCH
——核心指令，在提示中重复两次。
验证并修复每个构建工作进程完成后的PR——如果工作进程设置错误，修改基准分支并添加
```
build-train
```
标签。
最终PR无
build-train
标签——它会进入正常的审查流水线。
绝不能强制推送构建分支。
跳过而非中断——失败的构建或无法合并的PR会被跳过并记录；流程继续执行。
每个仓库同一时间只能运行一个build-train——第00阶段启动前会检查是否存在
```
build/*
```
分支。
范围锁定——每个工作进程仅处理分配给它的issue，不处理其他内容。
第00和05阶段内联运行——
```
[pylot] outcome=...
```
标记必须来自编排器。
绝不能将完整的编排器上下文传递给子代理Task提示——仅传递输入内容。
每个阶段必须在被下一个阶段读取前写入handoff.md。无阶段被跳过（即使动作是“无操作”也需执行）。

Reference files

参考文件

```
CONTEXT.md
```
— architecture overview
```
stages/NN-name/CONTEXT.md
```
— per-stage inputs, task, output contract

```
CONTEXT.md
```
— 架构概述
```
stages/NN-name/CONTEXT.md
```
— 各阶段的输入、任务、输出约定