github-issue-breakdown reference
github-issue-breakdown は、要求を GitHub Issue として実装可能な粒度へ整理して起票する入口である。
既定では Issue 作成、作成後処理、必要な sub-issue link、親 Issue 本文更新までで止まり、実装へは進まない。
実装へ続ける場合だけ fix / continue-to-fix / implement を明示し、breakdown-to-fix contract で選ばれた first fix target 1 件を fix-github-issue に渡す。
詳細な orchestration 手順は breakdown-to-fix contract と claude/skills/github-issue-breakdown/SKILL.md を source of truth とし、この文書は利用者向けの引数早見表として扱う。
Issue 作成と検証
| 引数 | 動作 |
|---|---|
agent=auto |
起票前 validation agent を自動選択する |
agent=codex / agent=claude / agent=copilot |
起票前 validation に使う agent を明示する |
config=<path> |
validation agent の設定を渡す |
worker-mode=one-shot / worker-mode=prefer |
validation worker の起動方式を選ぶ |
worker-helper=<path> |
validation worker helper を明示する |
worker-project-path=<path> |
validation worker の作業 repo path を明示する |
claude-mcp=off / claude-mcp=on |
Claude validation で MCP を使うかを指定する |
skip-validation |
起票前 validation を省略する。Issue 作成後処理や親子 link は省略しない |
agent= は起票前 validation の selector であり、実装後の reviewer を選ぶ agents= とは別物である。
Issue 作成だけで止める場合、review=、e2e=、agents=none、worktree= は後続実装へ渡されない。
Issue draft を作る前に、intent-policy inventory で Agent が補う解釈・選択を棚卸しする。対象は UX 可視挙動、データ形式、公開 API、設定形式、scope / repo 境界、Issue 分割、non-goal、fallback、validation 範囲を含む。 ローカル一次情報で解消できる fact-check を先に潰し、ユーザー確認が必要な intent-policy だけを初回質問候補に残す。 各質問には「この回答で Issue 構成のどこが変わるか」を添える。確認事項が4件以上ある場合は、最大3個の grouped questions に束ねる。 ユーザー回答済み前提や一次情報で凍結した判断は draft file または validation input に保持し、後段 validation が同じ前提を再利用できるようにする。 validation 後の Open Questions は、local fact-check、初期回答または一次情報で凍結済み、既存回答や一次情報を覆す根本変更に分類する。追加質問に戻るのは根本変更だけで、wording 修正、scope tightening、validation target の明確化、回答済み前提の本文反映では戻らない。
実装へ続ける指定
| 引数 | 動作 |
|---|---|
fix |
Issue 作成後に first fix target を選び、実装へ進む |
continue-to-fix |
fix と同じく、Issue 作成後の実装移行を明示する |
implement |
fix と同じく、Issue 作成後の実装移行を明示する |
実装移行が明示された場合だけ review-orchestrator issue breakdown-to-fix を呼ぶ。
親 Issue や複数候補をそのまま fix-github-issue へ渡さず、artifact の first_fix_target が 1 件に決まった場合だけ実装へ進む。
needs_human_selection や stop が返った場合は、推測で実装を始めない。
review handoff
| 引数 | handoff での扱い |
|---|---|
review=simplify |
後続実装で PR 前 simplify だけを実行する |
review=once |
後続実装で Codex one-shot reviewer を使う |
review=on |
後続実装で multi-review を使う |
| 未指定 | 実装移行時は review=simplify として handoff に明示する |
agents=none |
review=on では local reviewer skip intent として handoff に保持する。review=simplify agents=none は冗長な skip 指定として許可する |
agents=codex / agents=claude / agents=copilot |
github-issue-breakdown の handoff では受け付けない。handoff できる selector は agents=none だけ |
github-issue-breakdown の handoff option として許可される review mode は review=simplify|once|on だけである。
review=off、no-review、multi-review alias は handoff では使わず、必要な mode を明示する。
review=simplify / review=once / review=on と、github-issue-breakdown の handoff に保持しない agents=codex などの option を同時に指定すると停止する。ただし review=simplify agents=none は冗長な skip 指定として許可される。
review=once agents=none は one-shot reviewer selector と矛盾するため停止する。
E2E handoff
| 引数 | handoff での扱い |
|---|---|
e2e=auto |
後続の fix-github-issue が evaluator で resolved mode を決める |
e2e=off |
E2E 未実行 override として保持する |
e2e=pre-review |
review に渡す前の E2E gate intent として保持する |
e2e=final |
review 収束後の E2E gate intent として保持する |
e2e=both |
pre-review と final の両方の intent として保持する |
| 未指定 | 実装移行時は requested_e2e_mode=auto として扱う |
Issue 作成だけで止める場合は E2E を実行しない。
未解決の auto を e2e_mode として扱わず、successful auto plan の resolved_e2e_mode だけを後続 gate に渡す。
worktree handoff
| 引数 | handoff での扱い |
|---|---|
worktree=on |
後続の fix-github-issue が primary checkout では専用 git worktree を作成し、既存 linked git worktree では追加 worktree を作らず再利用する intent として保持する |
worktree=off |
後続の fix-github-issue が current cwd で実装する明示 escape hatch として保持する |
| 未指定 | 実装移行時は worktree=on として handoff に明示する |
worktree=on|off は fix / continue-to-fix / implement と同時に指定された場合だけ有効で、stdout JSON、handoff.json、checkpoints[]、resume_command に worktree_mode として保持する。
Issue 作成だけで止める呼び出しに worktree=on|off が付いた場合は、消費先のない実装移行 option として停止する。
停止する代表例
| 入力 | 停止理由 |
|---|---|
review=off fix |
handoff review mode として受け付けない |
multi-review continue-to-fix |
alias ではなく review=on の明示が必要 |
review=simplify agents=codex implement |
agents=codex selector は github-issue-breakdown の handoff では受け付けない |
review=once agents=codex fix |
review=once 自体は handoff できるが、agents=codex selector は github-issue-breakdown では受け付けないため停止する |
review=once agents=none fix |
one-shot reviewer selector と local reviewer skip intent が矛盾する |
worktree=off |
実装移行指定がなく、worktree option の消費先がない |
| first fix target が複数または不明 | needs_human_selection として停止する |
実行例
| 入力 | 何が起きるか |
|---|---|
/github-issue-breakdown agent=codex |
Codex で起票前 validation し、Issue 作成で止まる |
/github-issue-breakdown agent=codex skip-validation |
validation を省略し、Issue 作成と作成後処理まで行う |
/github-issue-breakdown agent=codex continue-to-fix |
Issue 作成後、first fix target 1 件を fix-github-issue へ渡す |
/github-issue-breakdown continue-to-fix review=on agents=none |
後続実装は local reviewer を使わず、PR target の Copilot bot review を期待する |
/github-issue-breakdown implement review=simplify e2e=off |
後続実装は PR 前 simplify のみ、E2E は実行しない |
/github-issue-breakdown continue-to-fix worktree=off |
first fix target を選び、後続実装は current cwd で作業する |