agent-team-run reference

agent-team-run は、親 Issue に紐づく sub-issue 群を worker へ分配し、必要なら統合作業まで進める入口である。

まず何が起きるか

/agent-team-run 724 のように親 Issue を指定する。
sub-issue 群と依存関係から実行計画を作り、dispatch 前に確認する。
実行可能な sub-issue を worker へ渡し、結果を queue に取り込む。
integration=on なら、issue worker の完了後に統合作業も行う。
完了、停止、利用者判断待ちを Issue ごとに報告する。

各 worker の research packet が current でない、validation を通らない、または必要な質問に回答されていない場合は dispatch しない。worker が追加判断を必要とした場合は失敗扱いにせず、質問を保存して利用者へ返す。

issue worker は fix-github-issue flow を継承し、PR 前 simplify とそこで生じた変更の commit の後、review、push、PR 作成の前に fix-code-comments skill を実行する。dispatch prompt の自己点検指示にはこの実行が含まれる。

cross-repo の sub-issue は worker へ dispatch しない。queue に structured blocker を残し、独立した same-repo entry だけを続ける。cross-repo entry に依存する entry は blocked のままにする。

runtime=codex は、候補ファイル、code block を含む実装例、検証 command がそろった具体的な research packet を必要とする。不足時は packet を具体化するか、計画を作成した runtime と同じ tier で実装する。runtime=claude では、この追加条件を要求しない。

design-doc=auto|off で design doc を省略しても、Codex worker の packet 条件は変わらない。粒度不足だけを理由に design doc を追加せず、packet の具体化か同じ tier での実装を選ぶ。

この Skill は自動起動しない。通常の Issue 作成や github-issue-breakdown の完了後に使う場合も、利用者が /agent-team-run を明示する。

対象

sub-issue を持つ親 Issue 1 件を指定する。各 sub-issue は、worker が単独で PR、または branch、commit、pushまで進められる粒度に分けておく。

Options

引数	既定	意味
`<親Issue番号/URL>`	必須	実行する sub-issue 群を持つ親 Issue
`pr=draft`	`draft`	worker が Draft PR を作る
`pr=create`	`draft`	worker が通常 PR を作る
`pr=none`	`draft`	worker は branch、commit、pushまで行い、PR は作らない
`runtime=auto`	`auto`	実行中の runtime に対応する worker を使う
`runtime=codex` / `runtime=claude`	`auto`	worker runtime を固定する
`dependency-mode=stacked`	`wait-on-merge`	`pr=draft` / `pr=create` で依存先の PR chain に後続 PR を積み、merge 前でも次の worker を進める
`dependency-mode=wait-on-merge`	`wait-on-merge`	依存先の PR が merge されてから次の worker を進める
`publication-mode=serial-stack`	未指定	sibling の実装を並列化し、PR 公開を coordinator の凍結順へ接続する
`max-workers=auto`	`auto`	queue の状態から同時実行数を決める
`max-workers=N`	`auto`	1 回に dispatch する worker 数を指定する
`worker-timeout=45m`	`45m`	worker response の締切
`integration=on` / `integration=off`	`on`	issue worker 後の統合作業を行うか選ぶ
`integration-validation-command=<cmd>`	なし	integration worker に渡す検証 command。複数指定可
`auto-merge`	off	条件を満たした worker PR の auto-merge を明示的に許可する
`dry-run`	off	計画と checkpoint だけを表示し、dispatch しない
`yes`	off	dispatch 前の確認を省略する

integration=off と integration-validation-command=...、または pr=none と auto-merge は同時に使えない。

dependency-mode を省略すると wait-on-merge になる。選んだ mode は queue init と dispatch の両方へ渡し、再開時も queue に保存された値を使う。

pr=none は mode に関係なく従来の local branch merge を使う。通常の pr=draft|create の stacked は fan-in / fan-out を受け付けない。publication-mode=serial-stack を付けた場合だけ sibling implementation の fan-out を許可する。fan-in と auto-merge は許可しない。

publication-mode=serial-stack は queue init と dispatch の両方へ同じ literal flag を渡す write-once 設定である。publication gate と closing Issue gate は required で実行する。

required へ昇格すると、implementation 完了後も worktree を保持し、coordinator が publication intent を heartbeat する。凍結順が来た時だけ同じ worktree へ finalization worker を再 dispatch し、restack 後の validation、review、E2E、push、PR 作成を行う。既に open PR がある場合は、same-parent stack の verified member だけを再実装せず完了扱いにする。

false stop、unsafe pass、duplicate publication、順序違反、closing Issue の誤停止または見逃しがあれば、両 gate を report-only に rollback する。残存 publication intent は計測 artifact に記録して abort し、required registry へ持ち越さない。

auto-merge は repo、branch、label の allowlist と validation、review、conflict、close readiness の条件を満たす PR だけを対象にする。条件を満たさない PR は merge しない。

停止と再開

次の場合は該当 worker を起動せず、queue の状態と必要な対応を報告する。

research packet が current ではない、または実装に必要な情報が足りない。
worker が needs_user_decision を返した。
runtime、worker 数、timeout を解決できない。
worker が timeout、parse failure、cleanup failure になった。
auto-merge や integration の条件を満たしていない。

質問へ回答した後は、案内された queue resume --answers <path> で同じ sub-issue を再開できる。run 全体を閉じる必要がある場合は、報告された queue path を使って queue abort し、新しい run を始める。

完了時に確認できること

各 sub-issue が完了、blocked、利用者判断待ちのどれかに確定している。
応答が不明な worker が残っていない。
integration=on では、issue worker が完了した後に integration 結果と指定した検証結果を確認できる。
integration=off では integration 結果を要求しない。
timeout や blocked entry がある場合は successful completion とせず、対象 Issue と再開方法を報告する。

自然言語の worker summary だけでは完了にしない。queue が取り込んだ結果と状態を正本にする。

Examples

入力	動作
`/agent-team-run 724`	Draft PR、runtime auto、integration on で checkpoint 後に実行する
`/agent-team-run 724 pr=create runtime=codex max-workers=2`	Codex worker を最大2件ずつ実行し、通常 PR を作る
`/agent-team-run 724 dependency-mode=stacked`	依存先の PR chain に後続 PR を積み、merge 待ちをせず次の worker を進める
`/agent-team-run 724 dependency-mode=stacked publication-mode=serial-stack`	sibling implementation を並列に進め、publication coordinator の shadow 観測を残す
`/agent-team-run 724 pr=none integration=off yes`	PR と integration なしで実行し、checkpoint の確認を省略する
`/agent-team-run 724 auto-merge integration-validation-command="go test ./..." yes`	auto-merge を opt-in し、integration の検証 command を指定する
`/agent-team-run 724 dry-run`	dispatch せず計画と checkpoint を表示する