agent-team-run reference

agent-team-run は、親 Issue に紐づく sub-issue 群を review-orchestrator agent-team queue の parent-assisted queue runner で実行する入口である。 plan 生成、queue 初期化、dispatch 前 checkpoint、runtime 別 worker dispatch、response / ingest / status loop、optional integration、artifact ベース完了報告までを扱う。

queue 状態、worker gate、artifact 検証、entry の next action は review-orchestrator agent-team queue subcommand 群の stdout JSON と artifact を source of truth とする。 worker の自然言語 summary だけで成功扱いにしない。

Target

親 Issue 1 件を対象にする。親 Issue には sub-issue が紐づいており、worker Issue が単独で worker PR または branch / commit / push まで進められる粒度で分割されている必要がある。

通常の Issue 作成、github-issue-breakdown 後の handoff、fix-github-issue の内部処理から自動起動しない。ユーザーが明示的に /agent-team-run を指定した場合だけ使う。 fix-github-issue / implement-from-plan の worktree=on|off は単一実装 flow の作業場所 option であり、agent team queue の --worktree-root とは別物である。

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 を使う。Codex runtime では `codex`、Claude Code runtime では `claude` として扱う
`runtime=codex`	`auto`	Codex subagent で worker request を処理する
`runtime=claude`	`auto`	Claude Code Agent tool で worker request を処理する
`auto-merge`	off	成功した issue worker PR を coordinator が自動 merge する
`max-workers=3`	`3`	1 回の dispatch で発行する ready worker の上限
`worker-timeout=45m`	`45m`	worker response deadline
`integration=on`	`on`	`queue plan --integration` を付け、issue worker 完了後に integration worker を実行する
`integration=off`	`on`	integration entry を plan に含めず、issue worker の done / blocked だけで run を閉じる
`integration-validation-command=<cmd>`	なし	`integration=on` の時だけ `queue plan --integration-validation-command` として渡す。複数指定可
`dry-run`	off	plan、init、status、checkpoint 提示までで dispatch しない
`yes`	off	dispatch 前のユーザー確認 checkpoint を skip する

integration=on|off は plan に integration entry を含めるかどうかの写像である。 integration=off では integration phase を実行せず、完了報告にも integration 結果を含めない。 integration-validation-command は指定された値だけ渡し、未指定時に検証 command を推測で補完しない。 worker-timeout は skill 側の default として 45m に解決し、未指定でも dispatch 時に --worker-timeout 45m を渡す。 pr、runtime、max-workers、worker-timeout、default branch は dispatch 前 checkpoint までに解決し、queue command には解決済みの PR_MODE、RUNTIME、MAX_WORKERS、WORKER_TIMEOUT、DEFAULT_BRANCH を渡す。 RUN_ID は queue init 前に agent-team-$(date -u +%Y%m%dT%H%M%SZ)-$(git rev-parse --short HEAD) のように一意に決め、dispatch stdout JSON は tmp/agent-team/RUN_ID/dispatch.json に保存して pending_requests[] の source にする。 dispatch stdout が返す absolute queue_path / request_path / worktree_path は、以降の respond / ingest でもそのまま使う。 relative --queue と absolute request/worktree path を混在させると path validation が失敗する場合がある。 dry-run は queue status に基づく dispatch 前 checkpoint と同じ項目を提示し、ユーザー確認を挟まず dispatch せずに終了する。

Stopping Combinations

組み合わせ	停止理由
`pr=none auto-merge`	PR を作成しないため merge 対象が存在しない
`integration=off integration-validation-command=...`	integration worker を作らないため validation command の消費先がない
`runtime=auto` が解決不能	worker dispatch 手段を決定できない
`max-workers` が 1 未満	ready worker を発行できない
`worker-timeout` が解釈不能	response deadline を決定できない

Completion Conditions

完了報告は queue artifact と ingest 結果に基づく。最低限、次を確認する。

team-queue.json の run status が hard stop ではない。
worker request / response / cleanup evidence が request ごとに揃っている。ただし --cleanup-status skipped で ingest した timeout / parse failure / unavailable response は cleanup evidence を要求しない。
worker result は response status が result を生成する場合だけ必須とし、claim gate blocked の unavailable や result 未生成の timeout / parse failure では手書き補完しない。
claim gate blocked の unavailable response は cleanup evidence なしで queue ingest し、queue artifact 上の blocked state を証跡にする。
timeout / parse failure も queue respond --status timeout|parse_failure --cleanup-status skipped で response artifact を作り、cleanup evidence なしで ingest する。
queue ingest の --cleanup-evidence は cleanup 証跡の出力先を明示したい時だけ渡す。省略時は queue dir 配下の cleanup/<request_id>.json に保存される。
worker の自然言語 summary ではなく、queue ingest 後の status と artifact path で完了を判断している。
blocked entry がある場合、Issue 番号、claim gate または worker blocked reason、queue 上の状態を報告できる。
integration=on かつ issue worker がすべて done の場合は integration worker の result と、validation command を指定した場合はその結果が artifact に残っている。blocked entry がある場合は integration artifact を要求せず、abort 扱いにする。
integration worker result の validation_commands[] は command、state: "success"、exit_code: 0 を含める。state: "passed" など別表記は schema validation で失敗する。
integration=off の場合は integration entry と integration 結果を報告対象に含めていない。
hard stop / timeout / parse failure / cleanup failure がある場合は successful completion として扱わず、queue abort と新 run の案内を含める。 abort が必要な場合は review-orchestrator --repo OWNER/REPO agent-team queue abort --queue tmp/agent-team/RUN_ID/team-queue.json --reason 'REASON' を使う。

Live E2E Notes

pr=none の依存 branch merge を確認する fixture は、worker 同士が同じ行や同じ小さなテキスト塊を編集しないように分ける。依存 branch merge は dispatch 時に実行されるため、同一箇所への追記は request 発行前に conflict blocked になり得る。
auto-merge 検証では、worker worktree が PR branch を checkout したままだと gh pr merge --delete-branch の local branch delete が失敗する場合がある。merge attempt と branch delete failure は queue artifact の merge_status / merge_error に残るが、next_action: done と run completed は達成され得るため、merge side effect と run completion を分けて報告する。
integration worker の成功は自然言語報告ではなく、team-integration-result.json が queue ingest に通り、queue status が completed になることで判断する。

Examples

入力	動作
`/agent-team-run 724`	default の draft PR、runtime auto、integration on、max-workers 3 で checkpoint 後に実行する
`/agent-team-run 724 pr=create runtime=codex max-workers=2`	Codex subagent で最大 2 worker ずつ通常 PR 作成 mode で実行する
`/agent-team-run 724 pr=none integration=off yes`	PR なしで worker branch を push し、integration なし、checkpoint 確認を skip して実行する
`/agent-team-run 724 auto-merge integration-validation-command="go test ./..." yes`	issue worker PR の自動 merge を opt-in し、integration validation command を plan に渡す
`/agent-team-run 724 dry-run`	plan / init / status / checkpoint 表示までで dispatch しない