Issue workflow skill guide

Issue 作成から PR 作成後の確認まで、どの skill を入口にするか選びたい利用者向けのガイドである。

対象読者と使いどころ

まず何が起きるか

1. 入口の選び方 で、調査、Issue 作成、実装、review、E2E、PR 作成のどこから始めるか選ぶ。
2. よく使う組み合わせ から、近い呼び出し例を選ぶ。
3. PR、reviewer、E2E の指定が必要なら、対応する option section で意味を確認する。
4. 実行後は各 workflow の stdout JSON と artifact を見て、次の action または完了を判断する。

停止条件

• 選んだ mode で消費できない option、相互に矛盾する reviewer 指定、実行可能な review path がない組み合わせは開始前に止まる。
• readiness、validation、review、CI、E2E の required action が残る場合は、指示された解消手順を行い、downstream phase や完了報告へ進まない。
• 外部 AI や reviewer が利用できない場合は、coverage を黙って下げず degraded mode の続行手順を使う。

詳細 contract

詳細 contract は各 skill と review-orchestrator の stdout JSON / artifact を source of truth とし、この文書は「どの入口にどの引数を渡すか」を判断するための利用者向けガイドとする。

Loop Engineering の Skill 入口と profile policy は loop-engineering reference を正本とする。 外部 scheduler からの定期実行入口は loop-automation-run reference、loop-state.v1 から許可された次 skill invocation を実行する controller contract は loop-controller-run reference を正本とする。 この guide は既存 workflow entrypoint の使い分けを扱い、Loop controller の state schema や profile 境界は所有しない。 外部 AI や reviewer が unavailable / rate limit / approval blocked で止まった時の続行手順は degraded mode を入口にする。 進行中 family の横断確認には review-orchestrator issue workflow-family-list を使い、単一 family の完了判定には workflow-family-status を使う。

Loop Engineering の要点:

• report: 状況整理。次に何をするかは人間が選ぶ。
• handoff: 次に呼ぶ skill command を生成する。ただし自動実行はしない。
• loop-state.v1: その判断と再開情報を残すための artifact。人間向けには resume_command、controller 向けには next_invocation を見る。

旧 profile 名の org-l1 / org-l2 / personal-l3 は、それぞれ report / handoff / auto-merge の互換 alias として扱う。 新しく生成する state と result は短い profile 名を使う。

Loop controller が handoff profile で既存 workflow へ handoff する場合、loop-state.v1 の child workflow は profile: "handoff"、allowed_terminal_scope: ["draft_pr", "review", "e2e", "pr_body_update"]、forbidden_mutations に merge / auto_merge / required_check_bypass、controller 向けの next_invocation、risk_level、requires_user_confirmation を残す。 これらの child workflow field は既存 consumer が実行上限と確認要否を判定するために維持する。 resume_command は /fix-github-issue、/implement-from-plan、/agent-team-run など、次に呼ぶ skill invocation に限定し、merge mutation を要求しない。 next_invocation は skill 名、args、実行 mode、対象 Issue / PR / doc、default の PR / review / E2E intent を構造化し、controller が resume_command を parse せず実行判断できるようにする。 handoff の既定 publication boundary は draft PR であり、通常 PR 作成や merge は downstream workflow の evidence / effect policy ではなく profile 上限で別に判断する。 Review、E2E、PR body update は許可できるが、その evidence / obligation / recovery は各 durable workflow family の state を正本にする。

loop-engineering は resume_command と next_invocation を出力するだけで、その skill を自動実行しない。 ユーザーが skill だけを使う場合、report は report の candidate work items と loop-state.v1 の work_items / next_action を見て次の skill を選ぶ入口である。handoff は run の後に出力された resume_command を次の skill invocation として実行し、controller は next_invocation を読む。 loop-controller-run はこの controller 側の実行 adapter で、既定は dry-run、yes がある場合だけ allowlist と profile boundary を満たす next_invocation を既存 skill に渡す。 どの skill を呼ぶかは next_invocation.skill が正本であり、controller が fix-github-issue / implement-from-plan を入力から推測しない。 複数候補がある場合は target=<workflow-id>、target=<1-based index>、または target=all を明示し、agents= / reviewers= は downstream skill へ渡す reviewer handoff intent として扱う。

Codex Automation や同等の外部 scheduler から定期実行する場合は、loop-automation-run reference を入口にする。 scheduler は loop-automation-run を呼ぶだけで、repo logic、workflow 選択、validation、PR 作成可否は loop-state.v1、controller result JSON、downstream skill artifact を source of truth にする。 eligible な next_invocation が無い場合、validation が失敗した場合、Issue が曖昧な場合は PR を作らず、required action と artifact path を報告する。 GitHub Actions billing、runner、service infrastructure だけの失敗は code failure と分けて報告し、required checks の bypass や scheduler 設定の変更は行わない。

入口の選び方

github-issue-breakdown は Issue 作成が主責務で、fix / continue-to-fix / implement が明示されない限り実装へ進まない。 /github-issue-breakdown agent=copilot は Copilot CLI を起票前 validation agent として使い、Issue 作成だけを求めた場合は validation、post-create、必要な sub-issue link、親 Issue 本文更新までで止まる。 agent=copilot は validation agent selector であり、実装後の local reviewer を選ぶ agents=copilot や GitHub 上の reviewer / trigger を選ぶ reviewers=copilot とは別物である。 Copilot validation が strict mode で proceed 以外になった場合、proceed でも採用すべき指摘が残る場合、または timeout、invalid_output、subagent_unavailable、cleanup_failure で validation 未完了になった場合は Issue 作成へ進まない。 実装まで続ける場合だけ /github-issue-breakdown agent=copilot continue-to-fix のように fix / continue-to-fix / implement を明示し、first fix target が 1 件に決まった時だけ fix-github-issue へ渡す。 loop-engineering は Loop Engineering の Skill 入口で、profile=report の read-only report 生成と profile=handoff の次 skill invocation 生成を実行する。加えて、profile=auto-merge の auto-merge policy gate も評価する。report は次の skill を自動選択せず、handoff は resume_command と next_invocation を出すが自動実行しない。auto-merge は policy gate の stdout JSON と artifact を残すが、merge は実行しない。agents= / reviewers= は Skill レベルの review intent として検証・表示するが、report / handoff では review dispatch せず、review-orchestrator loop run へも渡さない。 loop-automation-run は Codex Automation や cron などの外部 scheduler から呼ぶ薄い wrapper である。scheduler 向けの固定 prompt、clean tree preflight、duplicate PR / Issue check、no-op 報告を持ち、実行可否判定は loop-controller-run と downstream skill の artifact に委ねる。 loop-controller-run は loop-state.v1 の child_workflows[].next_invocation を読み、既定では dry-run として実行予定と停止理由を artifact に残す。yes がある場合だけ、reference の allowlist と profile boundary に従って既存 skill に渡す。 agent-team-run は明示的な親 Issue queue 実行の入口であり、通常の Issue 作成や github-issue-breakdown 後に自動起動しない。通常の dependency-mode=stacked は pr=draft|create の直列依存だけを PR chain として進める。publication-mode=serial-stack を付けた場合だけ sibling implementation の fan-out を許可し、required の publication gate と closing Issue gate を通して PR 公開を coordinator の凍結順へ接続する。fan-in、pr=none、auto-merge との組み合わせには使わない。 issue worker は fix-github-issue flow を継承し、PR 前 simplify 後、review、push、PR 作成の前に fix-code-comments を実行する。 cross-repo の sub-issue は worker へ dispatch せず、queue に blocker を残す。独立した same-repo entry は続行できるが、cross-repo entry に依存する entry は blocked のままとする。 fix-github-issue は選択済み Issue 1 件だけを扱い、親 Issue や複数候補を再分解しない。 Issue を作らない実装は implement-from-plan を使い、dummy Issue や hidden Issue で代替しない。 実装系入口の作業場所は未指定時 worktree=on で、readiness gate 通過後に current cwd の git worktree 種別を判定する。git worktree list --porcelain の先頭 worktree path と current cwd の repo root が一致すれば primary checkout、一致しなければ linked git worktree と扱う。primary checkout では専用 git worktree を作成し、既存 linked git worktree では追加 worktree を作らず再利用する。worktree=off は明示された場合だけ current cwd で作業する escape hatch として扱う。

github-issue-breakdown は draft 前に intent-policy inventory を行い、Agent が補う UX 可視挙動、データ形式、公開 API、設定形式、scope / repo 境界、Issue 分割、non-goal、fallback、validation 範囲を棚卸しする。 design doc を公開した flow は repo-scoped binding record を Issue 作成へ渡し、published family の completion で Issue identity との紐付け evidence を確認する。Issue 本文の構造検査は長い段落や項目に加えて、3 段落以上の連続散文と section 内の散文合計も report-only で観測する。 同一 repository の child Issue は、親本文の Mermaid 以外の各 surface で GitHub autolink が有効な bare #N として記載する。same-owner cross-repo の child は canonical Issue URL 付きの owner/repo#N link を使う。 一次情報で解消できる fact-check は先に潰す。high-impact 未確定が 1 件でも残る場合は、draft 前に intent-policy inventory の最小 interview で確認する。各質問には Issue 構成への影響を添え、high-impact 質問には grouped questions の最大 3 個制限を適用しない。high-impact ではない質問だけを必要に応じて最大 3 個へ束ねる。 AskUserQuestion が使えない runtime は質問一覧を報告して draft 前に停止する。 ユーザー回答済み前提や一次情報で凍結した判断は validation input に残し、後段 validation の Open Questions は local fact-check、凍結済み、根本変更に分類して扱う。

task-research は Issue 作成、既存 Issue 実装、Issue なし local plan 実装の前に read-only 調査を行う入口である。 research-plan.json、research-packet.json、research-brief.md を作り、handoff=github-issue-breakdown|fix-github-issue|implement-from-plan が指定された場合だけ handoff.json と resume command を残す。 未指定の artifact set は repo identity scoped user state root 配下に保存し、artifact-manifest.json / artifact-index.json に state-root-relative ref、packet digest、target、created_at、validation status を残す。既存 tmp/task-research/<id> は legacy fallback 候補であり、自動移動や削除はしない。 task-research 自体は Issue 作成、コード編集、commit、push、PR 作成、review 対応を行わない。 research=auto|off|light|standard|deep|spike は調査深度であり、validation の agent= や review の agents= とは別である。 research-mode=single|parallel は実行方式であり、未指定 default は single である。parallel は read-only worker の report と worker 数の解決理由を research-workers.json に分け、集約結果だけを research-packet.json に投影する。 parallel の worker 数は固定値ではなく、明示指定がなければ resolved_depth から解決する。 明示 research-mode=parallel で worker が unavailable / timeout になった場合、single mode へ silent fallback して成功扱いにしない。timeout は 30 分程度を既定目安にする。 task-research handoff=github-issue-breakdown agent=claude の agent= は、github-issue-breakdown の起票前 validation agent selector として resume command に残す。task-research の調査深度や reviewer selector にはしない。 research packet は downstream の validation、readiness、capability preflight、checkpoint、PR 前 simplify、multi-review の代替にならない。

よく使う組み合わせ

agents=none は local reviewer skip intent であり、PR target では Copilot bot review だけを使う。 fix-github-issue / implement-from-plan では pr=create / pr=draft と組み合わせた時だけ有効な review path になる。 github-issue-breakdown は実装移行が明示されている場合だけ agents=none を handoff に保持し、Issue 作成だけで止める場合は review を起動しない。 same-owner cross-repo の child は canonical Issue URL で親 Issue に紐づけられる。ただし cross-repo child や repository を一意に解決できない同番号 child は first fix target に自動選択せず、child repository で fix-github-issue --issue <canonical Issue URL> を直接開始する。

PR mode

PR 作成時は必ず create-pr を使う。 gh pr create --fill は使わず、diff だけでは分からない背景、判断、期待状態を PR 本文に書く。 同じ turn で CI / review / E2E / 追加検証の結果が確定した場合は、完了報告前に update-pr を使うか、既存 PR 本文が最新結果を反映していることを確認する。

review mode

review=auto は review-orchestrator issue review-profile-plan または plan 側の同等 evaluator が出す schema_version: "issue-review-profile-plan.v1" artifact を source of truth とする。 minimal は review=simplify、full は review=on agents=codex,claude に解決する。standard / high は実装 runtime の反対側を既定 reviewer にし、Claude Code では codex、Codex では claude、Copilot と runtime 不明時は codex を選ぶ。Codex で claude headless の preflight が失敗した場合は codex へ縮退し、理由を profile plan と review report に残す。local reviewer を使う resolved mode では、明示された fixed agents= があれば profile default agents を上書きする。 判定不能時は low ではなく standard に倒し、実装後 diff で risk が上がった場合は observed artifact で再評価して escalation する。 user override の review=simplify|once|on|off は auto result より優先する。

review option がなく、agents= / reviewers= / pause= / per-agent-timeout= / quiescence= / force-copilot-request / no-copilot-bot もない場合は review=auto として扱う。 agents= だけが指定された場合は review=auto + fixed agents intent として扱い、auto profile が local reviewer を使う resolved mode を返した場合だけ profile default agents を上書きする。reviewers= / pause= / per-agent-timeout= / quiescence= / force-copilot-request / no-copilot-bot など multi-review 用 option が指定された場合は review=on 相当になる。 github-issue-breakdown から実装へ handoff する場合は review=auto|simplify|once|on だけを受け付ける。review=off / no-review / multi-review alias は handoff option として使わず、必要な mode を明示する。 github-issue-breakdown review=once は後続 skill の既定 Codex one-shot reviewer として扱う。review=once agents=codex のような selector は github-issue-breakdown では暗黙に落とさず、handoff 前に停止する。fixed one-shot agent を指定する場合は後続の fix-github-issue / implement-from-plan で指定する。

review=simplify と agents=codex の同時指定、github-issue-breakdown review=once agents=codex、review=once agents=none、review=once agents=claude,copilot のように、選んだ mode で消費できない option は実装前に停止する。 review=simplify agents=none と review=off agents=none は local reviewer を起動しない mode への冗長な skip 指定として許可する。 fix-github-issue / implement-from-plan では review=once no-copilot-bot を PR 後 Copilot bot gate の明示 opt-out として許可する。 github-issue-breakdown の handoff では review=on の時だけ reviewers= と review loop budget を保持する。no-copilot-bot は legacy opt-out として保持できるが、明示された reviewers= を上書きしない。 ask-user は review finding の採否確認 marker であり、単独では multi-review を有効化しない。

実装 workflow から local reviewer を起動する場合は、通常検証、PR 前 simplify、必要な pre-review E2E gate が収束した後の pre-review commit を reviewer 対象 HEAD とする。 pre-review commit 後は git diff --exit-code と git status --porcelain で working tree が clean であることを確認し、dirty / 未追跡が残る場合は local reviewer へ進まない。 fix-github-issue / implement-from-plan はこの clean な pre-review commit に対して fix-code-comments を実行し、review 指摘の対応で HEAD が変わった場合も push 前に再実行する。completion-check は最新 HEAD の run record を report-only の comment-check-observation.v1 として照合する。 agent-simplify は commit 前の uncommitted diff を扱う mutating simplify/fixer phase として残し、直接の /multi-review local / /review-only local は明示 local diff review として uncommitted diff を扱える。

local reviewer と GitHub reviewer

agents= は local reviewer runtime の選択であり、GitHub PR 上の Copilot bot review ではない。 agents=copilot は GitHub Copilot CLI reviewer を意味し、copilot-pull-request-reviewer とは別経路である。 reviewers= は GitHub 上の reviewer / trigger selector で、未指定 default は reviewers=copilot である。 reviewers=codex は PR comment @codex review と Codex connector の完了待ち、reviewers=none は GitHub reviewer / trigger 無効化を意味する。

agents=none は単独で指定する。agents=none,codex のように他の local reviewer と併記すると停止する。 pr=none review=on agents=none は PR も Copilot bot もなく実行可能な review path がないため停止する。 pr=create agents=none reviewers=none / pr=draft agents=none reviewers=none は local reviewer と GitHub reviewer / trigger の両方を無効化するため停止する。 pr=create agents=none no-copilot-bot / pr=draft agents=none no-copilot-bot も旧互換 opt-out により実行可能な review path がないため停止する。 no-copilot-bot は timeout、API error、local reviewer の成功、agents=copilot を理由に自動付与しない。 過去 run で Copilot bot を期待していた coverage を後から無効化する場合は、allow-disable-copilot-bot と disable-copilot-bot-reason=<text> が必要になることがある。 review-only はこの表の PR target phase とは別の read-only entrypoint であり、常に local reviewer だけを使う。 review-only では GitHub Copilot bot review request、PR コメント、thread reply / resolve / close、record-action、コード修正、review loop を実行しない。 review-only agents=copilot もローカル GitHub Copilot CLI reviewer だけを意味し、GitHub Copilot bot への依頼ではない。

multi-review target

multi-review は PR target と local target を混ぜない。

--local-phase pre-pr では --validation-command または明示的な --validation-profile が必要である。 PR なしの standalone local target では GitHub Actions CI、Copilot bot、PR thread reply / resolve を要求しない。

E2E option

E2E は default off の opt-in gate として扱う。 fix-github-issue と implement-from-plan では未指定 default を requested_e2e_mode=auto として evaluator に渡し、成功した resolved_e2e_mode だけを実行 gate に渡す。

E2E が local server、host-wide config、installed skill、固定 port、外部サービスに影響する場合は feasibility を先に確認する。 方法が一意に決まらない場合や host-wide state に未確認の差分がある場合は needs_user_decision とし、ユーザー確認なしに実装、commit、push、PR 作成、完了報告へ進まない。 PR 本文へ書く場合は e2e=final や final gate ではなく、「手元で実行した検証」「最終確認」のような公開向け表現へ翻訳する。

PR 作成と PR 本文更新

create-pr は PR 作成専用の入口である。 PR タイトルと本文は .github/pull_request_template.md に沿い、変更羅列ではなく背景、判断、期待状態、review focus を伝える。 pr-writing-review=auto|codex|claude|copilot|off は PR 本文 reviewer gate 用の指定であり、Issue validation の agent= や multi-review の agents= と混同しない。

stacked PR の publication coordinator は、親 Issue の表が更新されると未公開 intent の row と相対順を再確認する。相対順が同じ場合は snapshot と Phase を更新し、並び替えまたは row 消失がある場合は publication_order_stale で lease と branch の変更前に停止する。復旧時は元の順序を表へ戻して resolver と intent 登録をやり直すか、既存 intent を resume または abort してから新しい順序で登録する。

update-pr は既存 PR のタイトルと本文を現在の実装内容へ合わせる。 PR 作成後に CI / review / E2E / 追加検証の結果が確定した場合、CI 未確認、review pending、これから確認します のような stale な表現を残さない。 内部 workflow option や skill 名は、対象そのものを変更している場合を除き、公開 PR 本文へそのまま出さない。

artifact と gate

自然言語の要約ではなく、stdout JSON と artifact を判定根拠にする。

gates.review.required_actions、gates.validation.required_actions、gates.conflict.required_actions が残る場合は完了扱いにしない。 gates.follow_up_actions だけが残る場合、review loop は収束扱いにできるが、CI follow-up pending として報告し、完全完了とは書かない。

詳細仕様

このガイドは Issue workflow skill の入口と索引をまとめる利用者向け文書で、skill 別の実行手順は下記の skill entrypoint から確認する。 claude/skills/*/SKILL.md は実行手順と禁止事項、contract docs は review-orchestrator の JSON / artifact 境界を定義する source of truth として扱う。 下記の skill entrypoint link は GitHub 上の source doc 用の repo-local link である。docs-site へ取り込む場合は公開 HTML の href に ../claude/skills/ や /agent-dotfiles/claude/skills/ を残さず、公開済みの /agent-dotfiles/skills/<skill>/ へ変換するか、リンクではなく claude/skills/<skill>/SKILL.md の path 説明にする。

Skill entrypoint

• task-research: read-only research packet と downstream handoff artifact

• github-issue-breakdown: Issue breakdown と first fix target handoff

• loop-engineering: Loop Engineering の report-only run

• loop-automation-run: 外部 scheduler から呼ぶ Loop controller wrapper

• loop-controller-run: loop-state.v1 から許可された次 skill invocation を評価または実行

• agent-team-run: 親 Issue の sub-issue 群を agent team queue で実行

• fix-github-issue: 既存 Issue 1 件の実装

• implement-from-plan: Issue なし local plan からの実装

• multi-review: local / PR target の review 収束

• fix-code-comments: branch で変更した対応言語のコメントを全件確認して整形

• review-only: 修正や PR 書き込みなしの read-only review

• e2e-workflow-gate: E2E 実行可否と証跡の判断

• create-pr: PR 作成

• update-pr: PR タイトル・本文更新

• multi-review reference: PR / local / pre-pr target、reviewer、validation、Copilot bot、worker 互換 option

• fix-code-comments reference: changed comment hunk と変更コードのコメント不足を確認し、comment-only patch を検証する local workflow

• e2e-workflow-gate reference: E2E mode、requested / resolved の区別、needs_user_decision

• create-pr reference: PR 作成入口、pr-writing-review=、stack= / stack-base=、PR 本文生成方針

• update-pr reference: PR 作成後の本文更新、stale status 解消、gh pr edit --body-file -

• task-research reference: read-only research packet、depth、handoff artifact

• loop-engineering reference: report-only run、loop run 引数、review intent

• loop-automation-run reference: 外部 scheduler 向け wrapper、preflight、duplicate check、no-op reporting

• loop-controller-run reference: loop-state.v1 からの controller 実行、dry-run、yes

• review operations: review-orchestrator、multi-review、CI follow-up、ProjectV2 post-create

• durable workflow dogfood runbook: Issue 作成、実装、review、PR publication、agent-team で durable state / evidence / effect を使う運用手順

• github-issue-breakdown reference: Issue 作成、validation、stacked 依存の記述、実装 handoff の引数詳細

• agent-team-run reference: 親 Issue queue 実行、stacked dependency mode、serial-stack publication、runtime 別 worker dispatch、completion 条件

• fix-github-issue reference: 既存 Issue 実装、PR mode、review mode、Copilot bot、E2E の引数詳細

• implement-from-plan reference: Issue なし local plan 実装、plan validation、PR / review / E2E の引数詳細

• review-only reference: PR / local diff の read-only review、local reviewer、禁止操作、report 条件

• breakdown-to-fix contract: Issue 作成後に first fix target を選ぶ contract

• implementation readiness contract: GitHub Issue 実装前の readiness gate

• no-issue implementation flow contract: Issue なし local plan 実装 flow

• E2E auto policy contract: requested / resolved E2E mode、local apply、parallel safety

• claude/skills/*/SKILL.md: 各 skill の実行手順と禁止事項