agent-team-run reference

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

まず何が起きるか

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

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

issue worker は fix-github-issue flow を継承する。dispatch prompt は、PR 前 simplify commit 後に非 test・非 generated Go の追加 hunk を確認し、理由 (reason)、制約 (constraint)、外部契約 (external_contract) に該当するコメントを書くよう指示する。コメントを書いた場合は validation と commit を行い、commit 後の diff で行範囲を更新して comment intent record を保存する。HEAD が変わった場合は最終 push 前に再記録する。

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

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

integration=on を明示して integration-validation-command を省略すると、queue plan が拒否する。

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

worker option は queue init にだけ渡し、dispatch には渡さない。再開時も queue に保存された値を使う。

Claude runtime の worker-effort は、effort 別の worker 定義 agent-team-worker-<effort> を選んで反映する。worker-model は Agent tool の model 引数へ渡し、定義側では model を固定しない。

Codex runtime の worker-model / worker-effort は subagent 起動 param へ渡す。渡せない場合は queue dispatch を呼ばず、request と worktree を作る前に止める。

worker prompt に e2e-apply=confirmed が載っている場合だけ、worker の fix-github-issue は local apply の事前承認として扱う。

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 は、依存を持つ sub-issue が 1 件以上ある場合だけ使える。依存のない sub-issue だけの親 Issue は queue init と dispatch が拒否するため、publication-mode を外して実行する。

直列 chain の先頭にある依存なしの sub-issue は、親 Issue の table に載っていれば自身を chain root として publication を登録する。先頭 Issue は親 PR なしで default branch へ公開され、後続の sub-issue は predecessor 経由で同じ stack identity へ合流する。

先頭 Issue の PR は GitHub の stack に所属しない。2 件目の stack-prepare は root intent の公開記録と一致する単独 PR を tail として受理し、2 件目の PR 作成時に 2 つの PR を stack として link する。

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 だけを再実装せず完了扱いにする。

finalization worker が blocked を返した場合、queue ingest は publication intent を aborted にして entry を blocked に収束させる。stack-prepare が lease 取得前に止まった場合は push も PR 作成も起きていないため、remote の effect を照合せずに intent を閉じる。

finalization worker が blocked または timeout でも、publication intent が既に公開済みなら queue ingest は abort せずに entry を blocked で閉じる。deadline 後に親が stack-complete を補った場合も、成功 result を後から補完しないため done にはしない。

finalization worker は PR 作成後に自分で stack-complete を呼ぶ。queue ingest は同じ PR と head で完了済みの intent を冪等な成功として扱い、entry を done にする。PR か head が異なる場合は拒否する。

coordinator の heartbeat は lease 中と公開済みの publication intent を変更せず、entry を blocked にもしない。

lease 取得前に aborted になった intent は、新しい run が別の branch と owner で同じ sub-issue を dispatch すると再登録される。lease 取得後に aborted になった intent と公開済みの intent は、branch が違えば branch_conflict のまま拒否する。report-only で閉じた intent も lease を経ずに公開されうるため同じ扱いにする。

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

Related Docs

• agent-team pump loop runbook
• agent-team live E2E fixture
• agent-team issue workflow contract
• Issue workflow skill guide
• claude/skills/agent-team-run/SKILL.md