build-train

build-train

複数の Issue をまとめて 1 つのビルドブランチに一括実行します。ステージ 01 では依存関係の順序を計画します。 ステージ 02 ではビルドサブエージェントをウェーブ単位で並列起動します。ビルドが独立している場合は並列に、 あるビルドの出力に別のビルドが依存する場合は順番に実行します。ステージ 03 ではすべての PR をビルド ブランチにマージし、ステージ 04 ではデフォルトブランチに最終 PR を 1 件作成します（レビュー パイプラインは 1 回だけ実行されます）。

目的

モノリシックな build-train スキルを ICM 手順に変換します。モノリスでは 1 つの長時間セッションでワーカーを 起動していましたが、マージの段階では、すべてのワーカーのプロンプトとログがコンテキストに蓄積され、 競合解決の判断が鈍っていました。この手順では各フェーズを専用のサブエージェントに分離し、さらに重要な点として、 「ワーカーを 1 つ起動して待ち、次を起動する」という直列ループを、依存関係グラフに基づくウェーブスケジューラーに置き換えます。未解決の依存関係がないビルドは並列の Task サブエージェントとして実行され、依存するビルドは前提となるビルドの引き継ぎを待機します。

引数

Param	必須	デフォルト	備考
repo	はい	—	org/repo。最初の位置引数
--issues	はい	—	Issue 番号をカンマ区切りで指定します。例：10,14,15,16
--branch	いいえ	build/YYYY-MM-DD	ビルドブランチ名。すでに存在する場合は末尾に -2 を追加します

$ARGUMENTS から解析します。

実行内容

6 ステージの ICM 手順：

Stage	Mode	Description
00-setup	インライン	デフォルトブランチの確認、ビルドブランチとラベルの作成、すべての Issue の読み込み
01-plan-order	サブエージェント	Issue の本文を読み、依存関係グラフを導出し、ビルドウェーブを出力
02-build-fanout	サブエージェント（並列）	ウェーブごとにビルドを分散実行：ウェーブ内は並列、依存関係の辺をまたぐ場合は順次実行。各ビルドは PR を作成する 1 つの Task ワーカーで実行されます。ベースとラベルを検証して修正
03-merge-chain	サブエージェント	各 build-train PR をビルドブランチにマージし、競合を解決
04-final-pr	サブエージェント	ビルドブランチからデフォルトブランチへの最終 PR を 1 件作成（build-train ラベルなし）
05-report	インライン	レポートを作成し、結果マーカーを出力

引き継ぎ先

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

ステージ 02 では、ビルドごとに個別のサブ引き継ぎファイルも書き込みます：

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

ステージ 00 ではルートコンテキスト（リポジトリ、デフォルトブランチ、ビルドブランチ、Issue マニフェスト）を書き込みます。すべての サブエージェントステージには、必要な引き継ぎ情報のみを渡し、オーケストレーターのコンテキスト全体を渡すことはありません。

実行方法

ステージ 00（インライン）

自分で実行します。CONTEXT.md を読み込みます：

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

.procedure-output/build-train/00-setup/handoff.md に引き継ぎファイルを書き込みます。

ステージ 01（サブエージェント）

Task を 1 つ起動します。00-setup の引き継ぎファイルのパスと、ステージの CONTEXT.md のパスのみを渡します。

ステージ 02（サブエージェント — 内部で並列、ウェーブスケジューラー）

ファンアウトステージ用に Task を 1 つ起動します。このステージの CONTEXT.md に沿ってウェーブループを実行します。ステージ 01 の ビルド順序を読み込んだ後、各ウェーブについて、そのウェーブに含まれるすべてのビルドを 1 回の応答で並列の 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.

ステージ 03 → 04（順次実行するサブエージェント）

各ステージで Task を 1 つ起動します。そのステージの CONTEXT.md に入力として記載されている引き継ぎ情報のみを渡します。 現在のステージが完了するまで次のステージを開始しないでください。ステージが失敗した場合は、失敗マーカーを出力し、回復不能な場合に限り停止します（「終了パス」を参照）。

ステージ 05（インライン）

自分で実行します。CONTEXT.md を読み込み、オーケストレーターから [pylot] outcome=... マーカーを出力します （サブエージェントからは出力しません）。

ステージ間の引き継ぎチェーン

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] ...

終了パス

• 成功：ステージ 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 内のビルド単位の失敗では、トレインは失敗しません。失敗したイシューはスキップされ、トレインは続行します（中断せずにスキップ）。トレインが失敗するのは、ビルドが 1 件も成功しなかった場合のみです。

厳守事項

1. ステージ 02 では、同じウェーブ内のビルドを並列で起動する必要があります — 1 回の応答で、ウェーブ内のすべての Task 呼び出しを行い、呼び出しの間に待機しないでください。
2. 逐次エッジを遵守してください — 依存関係が満たされていないビルドは後続のウェーブまで保留し、前提となるサブハンドオフが存在する前に起動しないでください。
3. ワーカープロンプトでは --base $BUILD_BRANCH を指定する必要があります — 主な指示として、プロンプト内で 2 回繰り返してください。
4. ビルドワーカーの完了後、すべての PR を検証して修正してください — ワーカーが誤った場合は、ベースブランチを変更し、build-train ラベルを追加してください。
5. 最終 PR には build-train ラベルを付けないでください — 通常のレビュー工程に進みます。
6. ビルドブランチへの強制プッシュは禁止です。
7. 中断せずにスキップしてください — ビルドの失敗やマージ不能な PR はスキップして記録し、トレインは続行します。
8. リポジトリごとに実行できる build-train は一度に 1 つだけです — 開始前に、ステージ 00 で既存の build/* ブランチを確認してください。
9. スコープを厳守してください — 各ワーカーは割り当てられたイシューのみを処理し、それ以外には手を出さないでください。
10. ステージ 00 と 05 はインラインで実行します — [pylot] outcome=... マーカーは、オーケストレーターが出力する必要があります。
11. オーケストレーターのコンテキスト全体をサブエージェントの Task プロンプトに渡さないでください — 入力のみを渡してください。
12. 各ステージは、次のステージが読み込む前に handoff.md を書き出す必要があります。 ステージを省略しないでください（実行内容が「何もしない」であっても実行します）。

参照ファイル

• CONTEXT.md — アーキテクチャの概要
• stages/NN-name/CONTEXT.md — ステージごとの入力、タスク、出力仕様