{"id":48745220,"url":"https://github.com/jfk/gh-issue-driven","last_synced_at":"2026-06-05T06:01:00.562Z","repository":{"id":350051178,"uuid":"1204778207","full_name":"JFK/gh-issue-driven","owner":"JFK","description":"Claude Code orchestration harness for GitHub-issue-driven development: propose → start → ship → tag, with design gates, pluggable post-PR review, and HITL at every phase boundary.","archived":false,"fork":false,"pushed_at":"2026-05-29T06:04:03.000Z","size":486,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T06:17:54.294Z","etag":null,"topics":["ai-agents","claude-code","claude-code-plugin","code-review","developer-tools","github-copilot","github-issues","orchestration","workflow-automation"],"latest_commit_sha":null,"homepage":"https://qiita.com/kiyotaman/items/302c8b7dc2cbcec555ff","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JFK.png","metadata":{"files":{"readme":"README.ja.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T10:20:49.000Z","updated_at":"2026-05-29T05:00:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JFK/gh-issue-driven","commit_stats":null,"previous_names":["jfk/gh-issue-driven"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/JFK/gh-issue-driven","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JFK%2Fgh-issue-driven","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JFK%2Fgh-issue-driven/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JFK%2Fgh-issue-driven/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JFK%2Fgh-issue-driven/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JFK","download_url":"https://codeload.github.com/JFK/gh-issue-driven/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JFK%2Fgh-issue-driven/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33932040,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","claude-code-plugin","code-review","developer-tools","github-copilot","github-issues","orchestration","workflow-automation"],"created_at":"2026-04-12T10:13:52.298Z","updated_at":"2026-06-05T06:01:00.547Z","avatar_url":"https://github.com/JFK.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gh-issue-driven\n\n[![GitHub release](https://img.shields.io/github/v/release/JFK/gh-issue-driven)](https://github.com/JFK/gh-issue-driven/releases)\n[![CI](https://github.com/JFK/gh-issue-driven/actions/workflows/lint.yml/badge.svg)](https://github.com/JFK/gh-issue-driven/actions/workflows/lint.yml)\n[![License: MIT](https://img.shields.io/github/license/JFK/gh-issue-driven)](LICENSE)\n\n[English](README.md) | **日本語**\n\n\u003e **GitHub issue 駆動開発のフルライフサイクルワークフロー: セッションコンテキストからの `propose` → 設計ゲート付き `start` → advisor ゲート付き `ship`（事後レビューは opt-in、全フェーズ境界に HITL 確認）→ リリース儀式自動化 `tag`。マルチ issue バッチ、プラガブル事後レビュア、per-repo Kagura Memory 自動検出付き。**\n\n`gh-issue-driven` は [Claude Code](https://claude.com/claude-code) のプラグインですが、本質は**オーケストレーション・ハーネス**です。Claude Code 自身のスキルやエージェント（設計レビュア、記憶リコール、`/code-review`、Copilot）を、各フェーズ境界で人間が確認できる 1 本の「Issue → Release」パイプラインに束ねる薄いメタ層です。コードジェネレータでも単発コマンドでもなく、それらのスキルをガバナンスゲートと記憶とともに*編成する*層です。\n\n「issue #142 の作業を始める」を 1 本の再現可能な 3 フェーズワークフローに変えます:\n\n```mermaid\ngraph LR\n    P[\"/propose\"] -.-\u003e I[Issue #N]\n    I --\u003e S[\"/start\u003cbr/\u003eGate1 設計\"]\n    S --\u003e IMP[\"実装 + /code-review\"]\n    IMP --\u003e SH[\"/ship\u003cbr/\u003eGate2 + PR\"]\n    SH --\u003e T[\"/tag\u003cbr/\u003eリリース儀式\"]\n    T --\u003e R[GitHub Release]\n\n    P -.HITL.-\u003e H0((立ち止まり))\n    S -.HITL.-\u003e H1((立ち止まり))\n    SH -.HITL.-\u003e H2((立ち止まり))\n\n    style H0 fill:#ffe4b5\n    style H1 fill:#ffe4b5\n    style H2 fill:#ffe4b5\n    style I fill:#e6f3ff\n    style R fill:#d4edda\n```\n\n1. **`/gh-issue-driven:start \u003cissue...\u003e`** — issue を取得、Kagura Memory から関連する過去ナレッジを recall、**gate 1**(設計レビュー、`/claude-c-suite:ask` → 必要なら `/ceo` にエスカレーション)を実行、型付きフィーチャーブランチを作成し、実装フェーズへハンドオフ。複数 ID を渡すとバッチブランチを作成。\n2. _(あなたがコードを書き、`/code-review` で作業ツリーの diff をレビュー — `/ship` で PR を作る前の事前レビュー)_\n3. **`/gh-issue-driven:ship`** — **gate 2**(デフォルトは `cso` + `qa-lead` + `cto` advisor 並列実行。`gate2.binary_gate` で optional なバイナリゲート追加可能)を回し、PR を作成。**事後レビューは opt-in**: `review.provider` のデフォルトは `none` なので、`/ship` は PR を作って **停止** します（プロバイダ未設定の場合）。プロバイダ(Copilot / `/code-review` / both)を設定すると、`/ship` はレビューループを **`/gh-issue-driven:review`**（その正規の置き場所）へ **委譲** します。あるいは `/goal` がレビューを代行します。プロバイダ設定時はレビューループ開始直前で **HITL 確認ゲート** が立ち止まり、このPRでループを起動するかを聞きます。\n4. **`/gh-issue-driven:tag \u003cversion\u003e`** — リリース儀式: milestone の closed issues をラベルごとにグルーピングしてリリースノート生成、`plugin.json` + `marketplace.json` の version bump、`CHANGELOG.md` 更新、コミット、annotated tag、`--follow-tags` で push、GitHub Release 作成。`dry-run` ですべてを事前プレビュー可能(ファイル・git・GitHub を一切触らない)。\n\nワークフロー全体は `kagura-memory` の `session-start` / `session-summary` で挟まれ、初回実行時は **context 自動検出**で設定不要。issue ごとの学びが永続化されます。\n\n\u003e 📖 **設計思想を読む**: [Qiita 記事 — Issue→Release を自動化したら、逆に人間が重要になった話](https://qiita.com/kiyotaman/items/302c8b7dc2cbcec555ff) · [スライド資料](https://docs.google.com/presentation/d/1eVUJLepOofN5bJUC7GBK7grPgTqRdfge5Ft9izaK8k4/edit)\n\n---\n\n## 60秒クイックスタート\n\n```text\n# ステップ0 — リポジトリの GitHub Settings ページで一度だけ:\n#   Settings → Code review → ☑ Automatic Copilot code review\n#   URL: https://github.com/\u003cowner\u003e/\u003crepo\u003e/settings/code-review\n#   これを有効にすると、Copilot レビューループが gh CLI のバージョンに依存せず動く。\n#   有効化しない場合は gh CLI \u003e= 2.88.0 が必要 (下記「必要なバージョン」参照)。\n\n# Claude Code セッション内 — プラグイン install:\n/plugin marketplace add JFK/gh-issue-driven\n/plugin install gh-issue-driven\n\n# 推奨 companion プラグイン (無くても degrade して動作)\n# 注: install target の `@\u003cmarketplace\u003e` は marketplace.json の name フィールド (GitHub repo slug ではない)\n\n/plugin marketplace add JFK/claude-c-suite-plugin    # gate1 + gate2 レビュア\n/plugin install claude-c-suite@claude-c-suite\n\n/plugin marketplace add kagura-ai/memory-cloud       # session-start/summary + recall\n/plugin install kagura-memory@kagura-memory-cloud\n\n# Optional (v0.2 の深掘りレビュー用):\n/plugin marketplace add JFK/claude-phd-panel-plugin\n/plugin install claude-phd-panel@claude-phd-panel\n\n# 任意のリポジトリで:\n/gh-issue-driven:doctor          # 初回環境チェック (ステップ0 の確認 prompt も走る)\n/gh-issue-driven:start 142       # フェーズ1（単一 issue）\n/gh-issue-driven:start 4 12 20   # 複数 issue を1ブランチにまとめることも可能\n# ... 実装、その後 /code-review で diff レビュー ...\n/gh-issue-driven:ship            # フェーズ2 (gate2 + PR 作成。事後レビューは opt-in)\n# ... PR が main にマージされ、milestone が release ready になったら ...\n/gh-issue-driven:tag 0.3.0 dry-run   # フェーズ3 プレビュー\n/gh-issue-driven:tag 0.3.0           # フェーズ3 実行 (リリース儀式)\n```\n\n\u003e **ステップ0 が必要な理由**: GitHub の \"Automatic Copilot code review\" リポジトリ設定を有効にすると、PR 作成時と push のたびに Copilot レビューが自動で要求されるため、gh CLI のバージョンに関係なくループが自走します。有効化していない場合、プラグインは `gh pr edit --add-reviewer @copilot` にフォールバックしますが、これは `gh \u003c 2.88.0` で **silent に no-op します** ([#15](https://github.com/JFK/gh-issue-driven/issues/15) 参照)。`/gh-issue-driven:doctor` は repo ごとに7日間隔でステップ0 の確認 prompt を出し、どちらのモードも使えない場合は hard fail します。\n\n---\n\n## コマンド一覧\n\n| コマンド | フェーズ | 動作 |\n|---|---|---|\n| `/gh-issue-driven:start \u003cissue...\u003e [flags]` | 1 | issue 取得、gate 1、ブランチ作成。複数 ID でバッチ対応。フラグ: `dry-run`, `force`, `no-memory`, `--branch=\u003cname\u003e`, `--autonomous[=\u003clevel\u003e]`（無停止実行のため green/yellow HITL を抑制。主に `/goal` が使用） |\n| `/gh-issue-driven:ship [flags]` | 2 | gate 2、PR 作成、session 保存。事後レビューは opt-in (`review.provider`、デフォルト `none`)、設定時は `/ship` がレビューループを `/gh-issue-driven:review` へ **委譲**。フラグ: `dry-run`, `force`, `no-copilot`, `draft`, `auto-skip`, `--review=code-reviewer`, `--autonomous[=\u003clevel\u003e]`（無停止実行のため green/yellow + レビュー起動 HITL を抑制。主に `/goal` が使用） |\n| `/gh-issue-driven:review [flags]` | 2 | **事後レビューループの正規の置き場所** — open 済み PR に対してレビューを実行(または再実行) (Copilot / `/code-review` / both、`review.provider` に従う)。re-entrant 設計。フラグ: `dry-run`, `force`, `--autonomous[=\u003clevel\u003e]` |\n| `/gh-issue-driven:tag \u003cversion\u003e [flags]` | 3 | リリース儀式: リリースノート生成、manifest bump、`CHANGELOG.md` 更新、commit、annotated tag、push、GitHub Release 作成。フラグ: `dry-run`, `force`, `--notes-file=\u003cpath\u003e` |\n| `/gh-issue-driven:propose \u003cdescription\u003e [flags]` | 0 | issue の下書きと作成: dedup チェック、品質レビュー、PM エンリッチメント、HITL 確認。フラグ: `dry-run`, `force` |\n| `/gh-issue-driven:goal \u003cmilestone\u003e [flags]` | G | **マイルストーンを PR まで駆動**: 各 open issue について `start` → 実装（TDD + 差分に対する軽量 inner-review パス、既定は Haiku ティア）→ `ship`（gate2 + PR + session-summary; PR後レビューは opt-in）を回し、issue 間で resumable state に checkpoint。**red** verdict で HITL 停止、green/yellow は継続。委譲先 start/ship に `--autonomous=\u003cgoal.autonomy\u003e` を渡すので、`red-only`/`unattended` では green/yellow + レビュー起動 prompt が抑制され、green/yellow パスは完全無停止で動きます (#74)。マージも default branch への push もしません。コスト制御: 事後レビューは `review.provider`（デフォルト `none`）または毎回指定の `no-copilot` フラグで opt-in、修正適用モデルは `review.model`（デフォルト `auto`）で right-size、inner-review のモデルは `goal.inner_review.model`（デフォルト `auto`）または `review-model=\u003ctier\u003e` で選択可能。フラグ: `dry-run`, `force`, `resume`, `no-copilot`, `review-model=\u003ctier\u003e` |\n| `/gh-issue-driven:doctor [verbose\\|fix]` | — | read-only な環境健康診断 |\n| `/gh-issue-driven:config [show\\|init\\|path\\|\u003ckey\u003e]` | — | 実効設定の表示、テンプレート初期化 |\n| `/gh-issue-driven:status [\u003cbranch\u003e\\|all\\|proposals]` | — | カレントブランチ(または全ブランチ/提案一覧)の state 表示 |\n\n---\n\n## 3 フェーズの仕組み\n\n### Phase 1 — `/gh-issue-driven:start`(Gate 1: 設計レビュー)\n\nissue 取得と recall の **後**、ブランチ作成の **前** に走ります。戦略：\n\n1. まず `/claude-c-suite:ask`（単一視点ルータ）を呼ぶ。軽量・高速で、専門1分野で済む issue に最適。\n2. `/ask` 応答内で最後に出現した `## Verdict:` 行のトークンが `decline` の場合、`/claude-c-suite:ceo` に昇格して3視点 synthesis を実行。（`decline` は同じ `## Verdict:` 行で使われる gate1 専用トークンであり、別チャネルではない。応答本文に \"decline\" や \"escalate\" という単語が出てきても、それはレビュアの推論の一部であり routing シグナルではない — 構造化された verdict 行のみがカウントされる。）\n3. レビュアの応答末尾の `## Verdict: green|yellow|red` 行から verdict を解析する。構造化行が canonical で last-wins、case は正規化、末尾の句読点は許容。キーワードヒューリスティックは構造化行が無い場合の **fallback のみ** で、warn ログを emit して soft-deprecation の追跡が可能。\n4. **green** → HITL 確認ゲート（ブランチ作成前にユーザー確認。`gate1.green_continue_requires_confirm` で設定可、デフォルト `true`） / **yellow** → ユーザー確認 / **red** → abort（`force` で override 可）\n\nブランチ作成後、`/start` は **suggested workflow** を表示し、ワンタップの continue を提示します。実装は **直交する2層** で構成されます：\n\n- **オーケストレーション** — 変更の規模/リスクで選ぶ: 直接編集（trivial / docs / rename / config）・`/feature-dev:feature-dev`（moderate）・`superpowers:writing-plans → subagent-driven-development`（large / plan-driven）。**overkill を避け**、選ぶのは最大1つ。\n- **テストファースト規律** — `superpowers:test-driven-development` は、テスト面がある変更（実ロジックを含むもの）では **デフォルト** で適用される規律。選んだオーケストレーションの **内側** で red→green→refactor を回すものであり、独立したルートでは **ない**。opt-out は純粋な docs / formatting / rename / config のみ。スキル未インストールでもデフォルトは維持（手動で test-first）。これは `/goal` step 5b と対称 — TDD は **両コマンド** でデフォルトの実装規律。ワンタップの *continue* が自動起動するのはオーケストレーション（`/feature-dev` か plan 起案）のみで、テストファースト規律はその内側で適用されます。\n\n### Phase 2 — `/gh-issue-driven:ship`(Gate 2: PR 作成直前のレビューバッテリー + PR 作成)\n\n実装の **後**、PR 作成の **前** に走ります。デフォルトでは **3つの advisor reviewer** が 1ターン内で並列発火 (advisor-only mode)：\n\n| レビュア | 役割 | verdict 型 |\n|---|---|---|\n| `/claude-c-suite:cso` | セキュリティ | Advisory（`green`/`yellow`/`red`） |\n| `/claude-c-suite:qa-lead` | テスト網羅 | Advisory |\n| `/claude-c-suite:cto` | 技術負債 | Advisory |\n\n3つの advisor verdict が集約される：いずれか red → red、yellow → yellow、それ以外 green。verdict handling は gate1 と同じ (green → HITL 確認ゲートで PR 作成前にユーザー確認、`gate2.green_continue_requires_confirm` で設定可、デフォルト `true` / yellow → 確認 / red → abort、`force` で override)。\n\n#### Optional binary gate (default off)\n\n「fail なら `force` でも block されるハードバイナリゲート」が欲しいプラグインメンテナは、`~/.claude/gh-issue-driven-config.json` の `gate2.binary_gate` に skill 名を設定できます：\n\n```json\n{\n  \"gate2\": {\n    \"binary_gate\": \"/claude-c-suite:audit\"\n  }\n}\n```\n\n設定すると、その skill が advisor 3つに加えて 4つ目のレビュアとして並列発火し、その verdict (`pass`/`fail`) がハードリリースゲートとして読まれる。\n\nデフォルトは `null` (binary gate なし)。以前のバージョンは `/claude-c-suite:audit` がデフォルトだったが、これは `claude-c-suite-plugin` 自身の規約遵守チェッカーであり、他のプラグイン (gh-issue-driven 含む) では script が存在せずエラーで終わる → 全 `/ship` invocation を block していた。v0.1.1 (#26) で修正。\n\n### Phase 3 — `/gh-issue-driven:tag`(リリース儀式)\n\nPR が default branch にマージされ、milestone の準備が整った後に実行します。儀式は「**すべてのチェックをファイル変更の前に寄せる**」構造になっているため、どこかで失敗しても作業ツリーはクリーンなままです:\n\n1. **Pre-flight**: default branch にいるか? 作業ツリーはクリーンか? remote と同期しているか?\n2. **Milestone readiness**: 指定バージョンに対応する milestone に open issues が残っていないか(残っている場合は `force` で警告付き続行)。\n3. **Lint + tests**: `check-frontmatter.py` と `tests/*.sh` がファイル変更前に走る。\n4. **リリースノート生成**: milestone の closed issues をラベルでグルーピング(`bug` → \"Bug Fixes\"、`enhancement` → \"Enhancements\" など `tag.label_group_map` で設定可)、\"Full Changelog\" 比較リンク付き。\n5. **Manifest bump**: `.claude-plugin/plugin.json` と `.claude-plugin/marketplace.json` を Edit tool で更新(traceability のため sed は使わない)。2 ファイルが bump 前から非同期な場合は abort。\n6. **CHANGELOG.md 更新**: 先頭に日付付きエントリを prepend、GitHub Release ページへリンク。\n7. **Commit**: `chore: release v\u003cversion\u003e`(リリース3ファイルのみ stage)。\n8. **Annotated tag**: `git tag -a v\u003cversion\u003e`(annotated が必須 ― `--follow-tags` は lightweight tag を拾わない)。\n9. **Push**: `git push --follow-tags origin \u003cdefault_branch\u003e` で commit と tag を一緒に送信、partial-failure window を閉じる。\n10. **GitHub Release 作成**: `gh release create v\u003cversion\u003e --notes-file ...` で生成したノートを使用。\n\n`dry-run` フラグで各ステップの効果(リリースノート完全版、manifest diff、CHANGELOG 追加行、git コマンド列)を事前プレビューできます ― ファイル・git・GitHub を一切触りません。このコマンドは **default branch に push する唯一のコマンド** です(他のコマンドは全て default branch への push を禁止しています)。\n\n`git push` が branch protection で拒否された場合、コマンドはループや再試行をしません。代わりに、ローカルに作成済みの commit と tag を保持したまま、**リカバリワークフロー** (短命ブランチ経由の PR で version bump をマージする手順)を表示します ― 作業を失わず、destructive ステップを再実行しません。\n\n### Verdict 行の規約\n\nレビュアの skill は、応答末尾に最終的な `## Verdict:` 行を出力すること。トークンは次のいずれか：\n\n- `## Verdict: green`\n- `## Verdict: yellow`\n- `## Verdict: red`\n- `## Verdict: decline`  \u0026nbsp;\u0026nbsp;— gate1 (`/ask`) のみ、routing 昇格シグナル\n- `## Verdict: pass`  \u0026nbsp;\u0026nbsp;— `/audit` のみ\n- `## Verdict: fail`  \u0026nbsp;\u0026nbsp;— `/audit` のみ\n\n（応答中に複数の `## Verdict:` 行が現れた場合は last-wins が適用される — 下記ルール参照。）\n\nルール：\n\n- **構造化行が canonical**。`gh-issue-driven` はこの行を最優先で解釈する。\n- **last-wins**: 応答中に複数行ある場合、最後の出現が勝つ（\"最初は red と思ったが結局 green\" のような自然な記述に対応）。\n- **case insensitive**: `Green` / `green` / `GREEN` はすべて `green` に正規化される。\n- **末尾の句読点 OK**: `## Verdict: green.` のような形式も `\\b\u003ctoken\u003e\\b` で許容される。\n- **キーワードヒューリスティックは fallback のみ**: 構造化行が無い場合だけ走る。fallback したときは `verdict_parser=heuristic` という warn ログを emit するので、ヒューリスティック完全廃止 (v0.4) の判断材料として追跡可能。\n- **`decline` は gate1 routing 専用トークン**: 別チャネルではない。本文中に \"decline\" の単語が出ても、それは routing シグナルではなくレビュアの推論。\n\n`claude-c-suite` / `claude-phd-panel` などの reviewer skill を保守している場合、この行を出力するように改修すれば統合がよりクリーンになる。\n\n---\n\n## 並行開発 (`--worktree`)\n\n`/gh-issue-driven:start \u003cissue\u003e --worktree` は、in-place で checkout する代わりに、新しい feature branch を別の [git worktree](https://git-scm.com/docs/git-worktree) の中に作成します。これによりメインの作業ディレクトリを `main`(または別の feature branch)のままにしつつ、新しい branch での実装を別ディレクトリで並行して進められます。(`start` は issue identifier を先に解釈し、続くトークンを flag として解釈するので、`--worktree` は必ず issue の *後* に置きます。)\n\n### 1 つのフラグに 2 系統のパス\n\n- **`superpowers` プラグインが入っている場合**: `superpowers:using-git-worktrees` に委譲されます。smart directory selection によって、通常はリポジトリ外の sibling path に worktree が配置されます。\n- **入っていない場合**: フォールバックとしてリポジトリ内の `.worktrees/\u003cbranch\u003e` に作成します。このディレクトリは `/.worktrees/` エントリで gitignore しておく想定で、`/gh-issue-driven:doctor fix` を実行すると `/.worktrees/` 追記用の `try:` コマンドが表示されます(doctor 自身は read-only でファイル編集は一切しないため、オペレータが手動で実行します)。`--branch=\u003coverride\u003e` と併用すると `.worktrees/\u003coverride\u003e` に配置されます。\n\nどちらのパスでも、`start` の recap に `cd \u003cworktree-path\u003e` のヒントが表示されるので、次のシェルプロンプトで正しい作業ディレクトリに移動できます。\n\n### ライフサイクル ― merge 後の後片付け\n\nPR が merge されても worktree は自動削除されません。merge して `main` を pull したあと、以下を実行してください:\n\n```bash\ngit worktree remove \u003cworktree-path\u003e\ngit worktree prune   # 古い登録情報の掃除\n```\n\n先にディレクトリを `rm -rf` してしまった場合(推奨しません)は、`git worktree prune` だけで dangling 登録を解消できます。\n\n### `--worktree` を使うか、superpowers を直接呼ぶか\n\n- **`start --worktree` を使う**: このプラグインの 3 フェーズフロー (`start → ship → tag`) に worktree を紐付けたいとき。branch 名・state file・gate1 サマリが全て新 branch 用に揃います。\n- **`superpowers:using-git-worktrees` を直接呼ぶ**: このプラグインとは無関係に worktree が欲しいとき (任意 branch のレビュー、実験など) — state file も gate1 review も走りません。\n\n---\n\n## Token 効率化フラグ (`auto-size`, `auto-skip`, `--with-plan`, `--parallel`)\n\n`/start` と `/ship` には、作業の実態に応じて cascade を軽量化する opt-in フラグがあります。フラグ未指定時の挙動は v0.8.0 と byte-identical です。\n\n### `auto-size` — small issue で gate1 を完全スキップ (`/start`)\n\n`/gh-issue-driven:start \u003cissue\u003e auto-size` で **issue-size heuristic** を起動。primary issue のラベルが `gate1.size_heuristic.small_labels` (デフォルト: `good first issue`, `documentation`, `docs`, `tests`, `i18n`) に一致するか、本文が `small_body_max_chars` (デフォルト 500 字) 未満なら、gate1 は **完全にスキップ** されます。`/claude-c-suite:ask` も `/ceo` 昇格も走りません。state file には `gate1.reviewer=\"size-heuristic\"` と synthetic verdict markdown が記録されます。\n\nHITL 確認ゲートは引き続き発火するので、「I have feedback」でスキップを上書き可能。batch invocation (`/start 4 5 6`) は決して small 扱いされません — bundling 自体が coherence signal だからです。\n\n毎回 `/start` でデフォルト ON にしたい場合は `~/.claude/gh-issue-driven-config.json` の `gate1.size_heuristic.enabled: true` に設定。\n\n### `auto-skip` — 関係ない gate2 advisor をスキップ (`/ship`)\n\n`/gh-issue-driven:ship auto-skip` は diff を調べ、変更ファイル**すべて**が `gate2.diff_scope_skip.docs_only_patterns` (デフォルト `README*` / `CHANGELOG*` / `CONTRIBUTING*` / `docs/` / `.github/`) に一致したら、`docs_only_skip_advisors` (デフォルト `cso` と `qa-lead`) をスキップします。残りの advisor (例: `cto`) は走り、binary gate (`gate2.binary_gate`) は影響を受けません。\n\n1ファイルでも非doc 変更があれば docs-only 判定は不成立 — partial skip はありません。このリポジトリの `commands/*.md` は markdown-as-code (実行 spec) なので、意図的にデフォルトパターンから除外されています。\n\n永続化設定は `gate2.diff_scope_skip.enabled: true`。\n\n### `--review=code-reviewer` — gate2 cascade を code-reviewer agent に差し替え (`/ship`)\n\n`/gh-issue-driven:ship --review=code-reviewer` は gate2 advisor cascade (`cso` + `qa-lead` + `cto`) を **`feature-dev:code-reviewer` agent の単一呼び出しに置き換え**ます。この agent は独自のコンテキストウィンドウを持ち (prompt 埋め込みの diff だけでなく自前のツールで変更ファイルを読む)、confidence ベースのフィルタリングで bug/security/quality/conventions を1パスでカバー — ガバナンス視点の cascade に対する、より高速で code-quality 重視の代替です。\n\n- **Verdict**: agent 出力に high-priority マーカー (`must fix` / `blocker` / `critical` / `high-priority`) を含めば `fail`、なければ `pass`。`pass` → green (HITL ゲートは維持)、`fail` → red (`force` なしでは PR 作成を中止)。\n- **`auto-skip` と直交**: 両方指定かつ diff が docs-only なら `auto-skip` 優先 (docs-only は重いレビュー不要、というより厳しい省略)。\n- **graceful degradation**: agent を提供する `feature-dev` プラグイン未インストール時は warning を出して通常の gate2 cascade にフォールバック — silent skip しません。可用性は `/gh-issue-driven:doctor` で確認。\n- `--review=` 構文は将来の reviewer ターゲット用に予約。\n\n### `--with-plan` — gate1 後に実装プランを生成 (`/start`)\n\n`/gh-issue-driven:start \u003cissue\u003e --with-plan` で、gate1 verdict 後・branch 作成前に `superpowers:writing-plans` を起動。plan markdown は会話から取得され、`~/.claude/cache/gh-issue-driven/\u003cbranch-flat\u003e.plan.md` に永続化、state file の `plan.path` が pointer になります。\n\n`superpowers` プラグインが必要。未インストール時は warning を出して plan なしで継続 (abort しません)。\n\nplan は `/start` 会話の **in-line で生成** されます — `/claude-c-suite:ask` や `/kagura-memory:session-start` と同じ実行モデルで、autonomous な sub-process は存在しません。\n\n### `--parallel` — subagent dispatch で実装 (`/start`)\n\n`/gh-issue-driven:start \u003cissue\u003e --with-plan --parallel` で plan 生成後に `superpowers:subagent-driven-development` をチェーン: step 18 の continue target が「plan を入力として subagent dispatch を起動」になります (`/feature-dev:feature-dev` 起動や conversation 内 plan 起案の代わり)。\n\n`--parallel` は `--with-plan` を要求します (subagent skill は plan を input として消費する仕様)。`--parallel` 単独は明示エラーで弾きます。\n\n### こんなときは使わない\n\n- **`auto-size` + 複雑 issue**: グローバルに `auto-size` を ON にして heuristic が複雑 issue を small と誤判定した場合、gate1 はそのままスキップされます。HITL gate が safety net なので、override して再実行可能。\n- **`auto-skip` + security-sensitive docs**: `docs/` に脅威モデルなど security review 必須の文書がある場合は default `false` のまま、必要 PR で `cso` を手動で追加。\n- **`--parallel` + 些細な変更**: subagent dispatch には setup コストがあります。1ファイルの fix なら conversation 内 continue target (「plan を起案」) の方が安価。\n- **`--review=code-reviewer` + ガバナンス重要変更**: code-reviewer agent は code-quality 重視でガバナンス視点ではありません。security/QA/architecture の*ガバナンス*観点 (`cso`/`qa-lead`/`cto`) が要る変更ではデフォルトの cascade を使ってください。\n\n---\n\n## Copilot レビューループ\n\nレビューループは **`/gh-issue-driven:review`** の正規の仕事です(`review.provider` が `none` でないとき `/ship` がここへ委譲)。レビュアの add を発火し、polling loop に入る前に **HITL 確認ゲート** で立ち止まります(v0.3.0 以降):\n\n```text\nCopilot review on PR #\u003cnum\u003e\nhttps://github.com/\u003cowner\u003e/\u003crepo\u003e/pull/\u003cnum\u003e\n\nIs Copilot review running on this PR?\n  1) Yes, it's running (or I triggered it another way)\n  2) No, skip the review loop for this run\n  3) Retry — let me trigger it now (I'll press Yes when ready)\n```\n\nCopilot が `--add-reviewer` の呼び出しを実際に受理したかどうか、プラグイン側からは検証できません ― org 権限、Copilot の課金/ポリシー、Mode A トグル、手動のコメントメンション経由の trigger、draft PR の不安定さなど、API で問い合わせ不能な要因が多いためです。検出マトリクスを肥大化させる代わりに、プラグインはあなたに聞きます。PR が draft の場合、draft PR の不安定性についての注意書きも prompt で表示され、事前に No を選んで promote してから再実行できます。\n\n**Yes** を選ぶと、polling loop に入ります(デフォルト **最大 5 回**、設定可):\n\n1. Copilot の新しい activity を待つ(`gh pr view --json reviews,comments,reviewDecision` を 60秒ごとに poll、最大 15 分)。\n2. 最新レビューと新しい bot コメントをパース。\n3. **終了条件**: `approved` / `no_actionable_feedback` / `max_loops` / `tests_failed` / `silent_no_op` (「confirmed されたが反応が無い」という真の anomaly を意味し、catch-all ではない)。\n4. actionable なコメントを `Edit` / `Bash` で適用。nit は skip。\n5. `copilot.run_tests_after_edits` が true ならローカルテスト実行。\n6. `fix: address Copilot review (loop N)` で commit、push。\n7. **各 Copilot レビュースレッドへ返信**（`copilot.reply_to_threads`、デフォルト ON）: actionable なスレッドには `✅ Fixed in \u003csha\u003e: …` を返信して **resolve**（`copilot.resolve_threads`、デフォルト ON、GraphQL `resolveReviewThread` mutation 経由）、non-actionable なスレッドには理由を返信して open のまま残す。返信/resolve は best-effort（失敗しても warning のみで loop は止めない）で、dry-run では skip。\n8. レビュー再依頼。\n\n**No** を選ぶと、state ファイルに `exit_reason=\"hitl_declined\"` を書き、PR を draft のままにして loop を clean に skip します。準備ができたら(例: Web UI で Copilot を trigger した後、draft から promote した後)、`/gh-issue-driven:review` で loop を再実行できます ― decline は「今回は skip」の意味であり「二度と聞くな」ではないため、ゲートは再度 prompt します。\n\n**Retry** を選ぶと、同じ prompt が即座に再表示されます。プラグインは poll も wait もしません ― あなた自身のペースで Copilot を trigger し、準備ができたら Yes を押してください。\n\nループは **never-blocking**: 5 周使い切っても PR は開いたまま、残りは手動で対応します。\n\n### HITL ゲートの無効化\n\n`~/.claude/gh-issue-driven-config.json` で `copilot.hitl_confirm_invocation: false` を設定すると、v0.3.0 以前の動作(prompt なしで `--add-reviewer` 発火後そのまま loop 開始)に戻せます。CI や非対話環境で operator が prompt に応答できない場合に有用です。\n\n### 必要なバージョン (どちらか一方)\n\nCopilot ループには **2つの動作モード**があり、**どちらか一方**が成立していればループが end-to-end で動きます:\n\n- **Mode A (推奨)** — リポジトリ設定で `Settings → Code review → ☑ Automatic Copilot code review` を有効化。**任意の `gh` CLI バージョンで動く**。Copilot が PR 作成時と push のたびに自動で要求される。\n- **Mode B** — `gh` CLI **v2.88.0 以降** ([2026年3月の Changelog](https://github.blog/changelog/2026-03-11-request-copilot-code-review-from-github-cli/) で追加された本物の `--add-reviewer @copilot` サポート)。それ以前の `gh` バージョンでは手動 reviewer add が silent に no-op する ([#15](https://github.com/JFK/gh-issue-driven/issues/15) 参照)。\n\n両モード共通: リポジトリのプランで GitHub Copilot code review 機能が利用可能であること。\n\n### Web UI による手動フォールバック\n\nMode A を有効化できず、`gh` も 2.88.0+ にアップグレードできない場合:\n\n1. プラグインが PR を作成した後、HITL ゲートが prompt を出します。\n2. GitHub Web UI で PR を開く → Reviewers → \"Copilot\" をクリック。\n3. HITL prompt が再表示されたら **Yes** を押す(または先に **Retry** を選んで Copilot を trigger してから Yes を押す)。\n\n---\n\n## クロスプラグイン Skill 呼び出しの契約\n\nこのプラグインは他プラグインのスラッシュコマンドを **Skill ツール経由で skill として呼び出します**。各ゲートのコマンド本文に明示的に書かれています：\n\n\u003e Invoke `/claude-c-suite:ask` via the Skill tool, passing the prompt block built in step N as input.\n\n並列レビュアの場合 (gate2 で invoke する skill 数は `gate2.binary_gate` の設定で変わる):\n\n\u003e In a single tool-call batch, invoke gate2 reviewer skills in parallel via the Skill tool. **デフォルト (advisor-only mode、`gate2.binary_gate: null`)**: 3 advisor skill — `/claude-c-suite:cso`, `/claude-c-suite:qa-lead`, `/claude-c-suite:cto`。**`gate2.binary_gate` が skill 名 (例: `/claude-c-suite:audit` for plugin maintainers) に設定されている場合**: 4 skill — configured binary gate skill + 3 advisor。\n\nskill が見つからない場合の degrade：\n- advisor reviewer missing → そのゲートスロットは `unknown`、警告を出して継続\n- binary gate skill missing (`gate2.binary_gate` 設定時のみ該当) → `unknown` 扱い、`force` で続行可\n- `gate2.binary_gate` が `null` (デフォルト) → binary gate なし、advisor-only mode、`force` 不要\n- `kagura-memory` missing → recall と session-start/summary をスキップ (`memory.context_id` resolution 失敗時は warning 1行を出す)\n\n`/gh-issue-driven:doctor` で何が入っているか確認できます。\n\n---\n\n## 設定\n\nデフォルトはバンドル済み。`~/.claude/gh-issue-driven-config.json` で上書き可能：\n\n```bash\n/gh-issue-driven:config init      # テンプレート書き出し（既存があれば上書きしない）\n/gh-issue-driven:config show      # 実効設定表示\n/gh-issue-driven:config path      # ファイルパス表示\n/gh-issue-driven:config copilot.max_loops   # 単一値表示\n```\n\n主な設定：\n\n| キー | デフォルト | 備考 |\n|---|---|---|\n| `default_branch` | `main` | base ブランチ |\n| `memory.context_id` | `null` (auto-detect) | Kagura Memory の recall 用コンテキスト。`null` (repo ごとに auto-detect)、`owner/repo` をキーとした **dict** (例: `{\"JFK/gh-issue-driven\": \"\u003cuuid\u003e\", \"*\": \"\u003cuuid\u003e\"}` — `\"*\"` は wildcard fallback)、または legacy scalar (UUID / name) を受け付ける。初回 `/start` 時にそのリポジトリ用のコンテキストを選択/作成するプロンプトが出て、dict のそのリポジトリのキーに永続化される。詳細は `/gh-issue-driven:config show`。 |\n| `gate1.primary` | `/claude-c-suite:ask` | gate1 の最初のレビュア |\n| `gate1.fallback` | `/claude-c-suite:ceo` | decline 時のエスカレーション先 |\n| `gate1.green_continue_requires_confirm` | `true` | green verdict 時にブランチ作成前で HITL 確認。`false` でスキップ |\n| `gate2.binary_gate` | `null` (off) | optional な override 不可バイナリゲート。skill 名 (例: `/claude-c-suite:audit`) を設定すると有効化 |\n| `gate2.green_continue_requires_confirm` | `true` | green verdict 時に PR 作成前で HITL 確認。`false` でスキップ |\n| `gate2.advisors` | `[cso, qa-lead, cto]` | 並列実行・集約 |\n| `review.provider` | `none` | 事後レビューのプロバイダ — `none`（opt-in: `/ship` は PR を作って停止）、`copilot`、`code-review`、`both`。設定時は `/ship` がループを `/gh-issue-driven:review` へ委譲 |\n| `review.model` | `auto` | **レビュー修正を適用する**モデルを right-size（`auto`\\|`haiku`\\|`sonnet`\\|`opus`）。`auto` はフィードバックの規模からティアを選択 |\n| `copilot.enabled` | _(deprecated)_ | もはや参照されません — 代わりに `review.provider` を使用 |\n| `copilot.max_loops` | `5` | 最大ループ数 |\n| `copilot.poll_interval_sec` | `60` | poll 間隔 |\n| `copilot.max_wait_sec` | `900` | 1ループあたりの最大待機時間 |\n| `copilot.run_tests_after_edits` | `true` | Copilot 修正後にローカルテスト実行 |\n| `copilot.reply_to_threads` | `true` | 各 Copilot レビュースレッドへ in-thread 返信（actionable は `✅ Fixed in \u003csha\u003e`、non-actionable は理由）|\n| `copilot.resolve_threads` | `true` | 返信後に actionable スレッドのみ resolve（GraphQL `resolveReviewThread`）。non-actionable は open のまま |\n\n### Copilot レビューループの最適化\n\nCopilot ループは設定なしで動作しますが、以下の2つのオプション設定でレビューの往復を約50%削減できます:\n\n1. **「Review new pushes」をオフにする** — リポの code-review 設定（`Settings → Code review → ☐ Review new pushes`）で無効化。プラグインは各修正コミット後に `gh pr edit --add-reviewer @copilot` で手動レビュー再依頼するため、push ごとの自動再レビューは重複ラウンドの原因になります。\n\n2. **`.github/copilot-instructions.md` を追加** — プロジェクト固有の指示で Copilot のレビュー品質を向上:\n\n   ```md\n   ## For pull request reviews\n\n   ### Priority\n   - Report only high-signal issues: correctness bugs, security vulnerabilities,\n     data loss risks, concurrency problems, performance regressions, broken tests.\n   - Skip pure style nits unless they mask a real bug.\n\n   ### Consolidation\n   - Group similar findings into one comment with all locations listed.\n   - If more than 5 issues found, report only the top 5 by severity.\n     Mention the count of lower-priority items in a summary line.\n\n   ### Project conventions\n   \u003c!-- プロジェクト固有の規約をここに追記してください。例:\n   - This project uses Tailwind CSS. Do not suggest CSS modules.\n   - All user-facing strings must use next-intl.\n   --\u003e\n   ```\n\n   Copilot は先頭 4,000 文字を読み取ります。詳細: [Copilot code review のカスタマイズ](https://docs.github.com/ja/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review)\n\n`/gh-issue-driven:doctor` はこのファイルが存在しない場合に informational として表示します。\n\n---\n\n## State ファイル\n\n`gh-issue-driven` が追跡している各ブランチには state ファイルがあります：\n\n```text\n~/.claude/cache/gh-issue-driven/\u003cbranch-flat\u003e.json\n~/.claude/cache/gh-issue-driven/\u003cbranch-flat\u003e.gate1.md\n~/.claude/cache/gh-issue-driven/\u003cbranch-flat\u003e.gate2.md\n```\n\n`/gh-issue-driven:status` でこれらを整形表示できます。\n\n---\n\n## 必要な依存\n\n| ツール | 必須 | 用途 |\n|---|---|---|\n| `gh` (任意のバージョン) | 必須 | issue/PR 操作。**Mode A**: 任意のバージョンで OK。**Mode B**: v2.88.0+ 必須 (本物の `--add-reviewer @copilot` サポートは2026年3月に追加 — Mode A vs Mode B の区別は上記「必要なバージョン」を参照)。 |\n| `git` | 必須 | ブランチ操作 |\n| `jq` | 必須 | JSON パース |\n| `python3` | 推奨 | 一部ヘルパー |\n| [`claude-c-suite`](https://github.com/JFK/claude-c-suite-plugin) | 推奨 | gate1/gate2 レビュア（無くても degrade して動く） |\n| [`claude-phd-panel`](https://github.com/JFK/claude-phd-panel-plugin) | optional | v0.2 の深掘りレビュー用 |\n| [`kagura-memory`](https://github.com/kagura-ai/memory-cloud) | optional | session-start/summary と recall |\n\n---\n\n## Limitations / 既知の制限事項\n\n`gh-issue-driven` は v0.1.0 以来 15 回以上のリリースで `JFK/gh-issue-driven` 自身の PR を ship してきました。v0.7.0 時点で以下の既知の sharp edge があります。データ損失や state corruption は無いものの、operator experience に影響します:\n\n- **遅い Mode A repo で `silent_no_op` の false-positive** ([#23](https://github.com/JFK/gh-issue-driven/issues/23)) — `/gh-issue-driven:review` ループの bounded wait は 30秒。GitHub の \"Automatic Copilot code review\" auto-review が 30秒以上かかる repo (`JFK/gh-issue-driven` で実測 ~4分) では wait が expire し、loop が誤って skip され `exit_reason=silent_no_op` が記録される。state file の診断は正しいので、Copilot review が landing したら `/gh-issue-driven:review` を再実行すれば復旧可能。アーキテクチャ的な修正は #23 で追跡 (検出を polling loop に統合)。\n- **`/gh-issue-driven:doctor` が context_id の解決を validate しない** — `memory.context_id` は `/start` 時に解決されるが、`/doctor` ではまだ解決チェックが行われない。follow-up として追跡。\n- **loop state machine のテスト無し** — verdict parser と Copilot detection function は fixture-driven test されているが、`/gh-issue-driven:review` polling loop の 5 つの terminal `exit_reason` state は自動テストで cover されていない ([#10](https://github.com/JFK/gh-issue-driven/issues/10) で追跡)。\n- **`claude-c-suite:audit` がこのプラグインを評価できない** — audit skill の `scripts/audit.py` がこのプラグインの layout に存在しない。de-facto baseline は `lint.yml` (frontmatter 検証、JSON syntax、version sync、fixture test、inline-jq sync を validate)。\n\n既知 issue の全リストは [v0.4.0 milestone](https://github.com/JFK/gh-issue-driven/milestone/6) を参照してください。\n\n---\n\n## ライセンス\n\n[MIT](LICENSE) © Fumikazu Kiyota\n\n---\n\n🤖 [Claude Code](https://claude.com/claude-code) で作りました。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfk%2Fgh-issue-driven","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjfk%2Fgh-issue-driven","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjfk%2Fgh-issue-driven/lists"}