Issue実装指示書

あなたは実装を統括するリードエージェントです。

GitHub Issueを分析し、1チケットの実装フローを /impl へ fan-out します。Issueが複数の場合は star 型（orchestrator-worker）で ticket-worker サブエージェントに並列委譲します。

本スキルは fan-out に徹する——実装フローの手順そのものは持たず（正本は /impl）、並列度・直列化の決定も上位層から受け取ったときは行いません（後述「Phase 2」）。

---

入力パラメータ

GitHub Issue番号（複数可）: $ARGUMENTS

パース方法

$ARGUMENTS を以下のルールで解釈する:

• 数値: Issue番号として扱う（複数指定可）
• --base <統合ブランチ>: 統合ブランチ方式のオプション（下記）。切り出して保持し、残りを Issue 番号として扱う
• --max-parallel <N>: 同時に起動してよい ticket-worker の天井（正の整数）。上位層＝計画層から渡される。天井であって目標ではない（下回る本数で走らせてよい）
• --serial <番号,番号,...>: 直列化グループ＝同時に走らせてはいけない Issue の組。1つの --serial が1グループを表し、グループ内は記載順に直列実行する。複数グループは --serial を繰り返して渡す
• 例:
  • 1 → 単一Issue実装
  • 1 2 3 → 3件のIssueを並列実装（star 型。並列度は本スキルが決める＝従来どおり）
  • 1 2 3 --base feat/issue-42 → base を統合ブランチにして並列実装
  • 1 2 3 4 --max-parallel 2 --serial 1,3 → 同時起動は最大2本。#1 と #3 は同時に走らせず #1 → #3 の順。#2 / #4 は並列可

base 統合ブランチの決定（統合ブランチ方式）

各 Issue の実装 base（ブランチ分岐元・PR の宛先）を次の優先順で決める:

1. --base オプションが指定されていれば、それを全 Issue 共通の base 統合ブランチにする
2. 無指定でも、Issue 本文に Base: {統合ブランチ} 行があれば（/create-ticket --base が記録）それを当該 Issue の base にする
3. どちらも無ければ base = リポジトリの既定ブランチ（通常 main。従来動作）

base が既定ブランチ以外（統合ブランチ）の場合、ブランチ準備（worktree の作成・/impl の呼び出し）の前に remote での存在を確認する。無ければ処理を止めてユーザーに作成を促す:

# ls-remote のパターンは末尾一致のため、refs/heads/{base} で指したうえで ref 列を完全一致で照合する
# （素の {base} だと feature/{base} のような別ブランチにも一致する。Issue #271）
if ! git ls-remote --heads origin "refs/heads/{base}" | awk '$2 == "refs/heads/{base}" { found = 1 } END { exit !found }'; then
  echo "エラー: 統合ブランチ {base} が remote に存在しません。先に作成してください:"
  DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')
  echo "  git checkout -b {base} \"origin/$DEFAULT_BRANCH\" && git push -u origin {base}"
fi

統合ブランチへのサブタスク PR マージは本番影響がなく可逆のため人間承認不要で自律マージできる（既定ブランチへの昇格のみが人間ゲート）。以降のフローで {base} は上記で決定した base ブランチ（既定はリポジトリの既定ブランチ）を指す。

---

ルーティング

Issue数	フロー
1件	直接呼び出し: リードエージェント自身が /impl {番号} [--base {base}] を実行する（worktree は使わない）
複数	star 型並列実装: skills/para-impl/references/star-parallel.md を後掲の配送経路で読み出してから worktree 準備へ（claude-harness-run read-plugin-doc "skills/para-impl/references/star-parallel.md"。Read 直読みは後掲の注記のとおりランチャー未導入時のフォールバックに限る）。リードがオーケストレーターとなり、各 ticket-worker が worktree 内で /impl {番号} --base {base} --worktree {worktree_path} を実行

参照ファイルの読み出し（重要）: 参照ファイルは導入先プロジェクトではなくプラグイン配下にある。プラグイン配下は導入先プロジェクトの作業ディレクトリの外にあるため、Read ツールでの読み出しは利用側に allow 設定が無いと拒否される（headless 委譲では許可する相手がいないため、既定で読めない）。読み出しは allowlist 済みの配送経路claude-harness-run read-plugin-doc "<読む対象のプラグインルート相対パス>"（本スキルは参照ファイルを複数持つ。読む箇所で指定されたパスをそのまま渡すこと — 特定の1本に決め打ちしない）で行い、stdout に出た本文を使う。非0 終了は「読まなくてよかった」ではない — 本文を得られていないまま手順を推測して続行せず、stderr のメッセージを添えてその場で停止し報告すること（読めないまま完走すると、書式や停止条件だけが外れた成果物が「成功」に見える）。exit 0 でも終端マーカー === read-plugin-doc END ... complete === が無ければ本文は完結していない — MORE マーカーが出ていれば示された --from-line で続きを取得し、END も MORE も無ければ出力が切り詰められたとみなして同様に停止すること。BEGIN マーカーの root= が「Base directory for this skill」の親ツリー（<root>/skills/<スキル名> が Base directory）と一致しなければ、別バージョンの本文が届いている — ランチャーは同居する最大バージョンを選ぶため旧版 SKILL.md ＋ 新版参照ファイルの混成になりうるので、手順へ進まず同様に停止して報告すること。=== read-plugin-doc ... === の行と read-plugin-doc: で始まる行は配送の制御情報であり本文ではない（テンプレートを埋めて書き出す際に成果物へ含めない）。claude-harness-run: command not found の場合のみ Read ツールへフォールバックし、スキル起動時にコンテキストへ与えられる「Base directory for this skill」を起点に <base>/<読む対象のスキル相対パス> として解決する（Read も拒否された場合は同様に停止して報告し、ランチャー導入を案内すること）。

<!-- 正本: docs/plugin-path-conventions.md -->

---

Phase 1: Issue分析（要件理解）

1. 全Issueの取得

   gh issue view {番号} --json title,body,state,labels,number
   

   • 各Issueの要件・完了条件・受入基準を把握する
   • Issue間の依存関係を特定する

2. E2E対象判定（各Issueごと）

   • 認証フロー、権限制御、クリティカルパスなどの場合は E2E対象とする

---

Phase 2: 並列度と直列化 ── 決定権の所在

本スキルは fan-out の実行役であり、並列度の決定層ではない（ADR 0001 決定4「賢い調整層は常に1つ」。調整層が2つあると、全体の並列度・予算を見ている主体が居なくなる）。

起動の形	並列度・直列化を決めるのは	本スキルの動作
--max-parallel が在る（上位層＝計画層からの起動）	上位層（例: claude-flywheel の run-cycle 手順2【その周の実行計画】）	受け取った天井と直列化グループのとおりに fan-out する。判断し直さない
--max-parallel が無い（人間が対話で /para-impl 3 4 5）	本スキル自身（従来どおりの単独利用。後方互換）	Phase 1 の分析と衝突予測ヒントから自分で並列度・直列化を決める

--max-parallel を受け取ったときの規律

1. 受け取った直列化グループ（--serial）は必ず守る（緩めない・組み替えない・解除しない）。
2. 同時に起動する ticket-worker は --max-parallel の値を超えない。対象 Issue 数がこれを上回る場合は天井まで起動し、残りは先行 worker の合流後に起動する。
3. 同一周のラウンドトリップをしない——並列度・直列化を問い合わせるために上位層へ戻らない（上位層は同期的に応答できず、待つと周が止まる）。
4. 予測（issue-conflict-predictor）が追加の衝突を見つけた場合、--max-parallel を下回る方向にのみ内側で追加直列化してよい。上回る方向・受け取ったグループを解除する方向へは動かせない。追加直列化した事実と理由（どの Issue 対を、どの予測交差を根拠に直列化したか）を完了報告に必ず含める——上位層はこれを次周の実行計画の入力に使う。
5. 判断に迷っても停止せず保守側（直列化する側）へ倒し、その判断事項を完了報告に明記する。

---

1チケットの実装フロー ── 正本は /impl

1チケット（= 1 Issue）の実装フロー（ブランチ準備 → 設計・TDD実装・必須ゲート・セルフレビュー → コミット → E2E → プッシュ・PR作成 → CI確認）の正本は /impl スキルであり、本スキルは手順を持たない。 同じ手順を本スキルにも置くと正本が2つになり必ずずれるため、リードも ticket-worker も、手順を再掲・注入せず /impl を呼ぶ。

/impl は通常のスキル（サブエージェントで走らない）であり、その呼び出しは Task ネスト深度を消費しない。ここを守らないと ticket-worker（深度1）→ feature-implementer（深度2）→ code-reviewer（深度3）の現行の鎖が1段深くなり、最深段のエージェントを spawn できなくなる。

/impl の呼び出し元（実行主体）と呼び出し形

Issue数	/impl の呼び出し元 ＝ 実行主体	呼び出し形
1件	リードエージェント自身（メインセッション）	/impl {番号} [--base {base}]
複数	各 ticket-worker サブエージェント（リードが割り当てた worktree 内）	/impl {番号} --base {base} --worktree {worktree_path}

• 1件の場合: リードは Phase 1（Issue分析）の後、そのまま /impl を呼ぶ。リードは worktree を用意せず、ブランチ準備も /impl が実施する（/impl が呼ぶ harness が worktree を作る）。/explain-e2e は /impl が実施せず、次の操作として案内する。
• 複数の場合: リードは worktree・作業ブランチの準備だけを担い、各 ticket-worker を spawn する。worker が worktree 内で /impl --worktree を呼ぶ（--worktree が渡ると /impl は渡された worktree をそのまま使い、PR 作成・CI 確認の後で返る。/explain-e2e は実施しない）。/explain-e2e は Phase 1 が対話前提のため、worker 完了後にリードがメインセッションで実施する。手順の詳細は skills/para-impl/references/star-parallel.md（読み出しは上記の配送経路）。

本スキルに残る責務は fan-out とその周辺だけである: Issue分析（Phase 1）・受け取った計画どおりの並列度／直列化（Phase 2）・worktree 準備・worker の spawn・合流ゲート・worker 返却の集約・/explain-e2e・CI 結果の集約・完了報告（Phase 9）・worktree クリーンアップ（Phase 10）。実装フローの手順そのものは1行も持たない。

合流ゲート（最終応答前の未合流確認）

サブエージェント・バックグラウンド処理を1つでも起動した場合、最終応答（Phase 9 の完了報告・中断報告を含む、あらゆるテキスト応答の確定）の前に合流ゲートを必ず評価する。 完了報告を出せるのはゲート通過に該当した場合だけであり、決定表が指示した中断報告はゲートの評価結果として「ゲート通過」を要件としない。

定義の正本は参照ファイル skills/para-impl/references/join-gate.md であり、本 SKILL には要点だけを書く。用語（起動台帳・有限タスク／常駐サービス・終端返却・合流済み・未合流・ネスト未解消）・spawn 時手順・合流ゲート伝播条項（委譲プロンプトへ逐語転記する条項の正本）・決定表・中断報告の出力契約は、すべて参照ファイル側にある。サブエージェント・バックグラウンド処理を起動する前に必ず前掲の配送経路で読み出すこと（claude-harness-run read-plugin-doc "skills/para-impl/references/join-gate.md"。Read 直読みは前掲の注記のとおりランチャー未導入時のフォールバックに限り、その場合はスキル起動時にコンテキストへ与えられる「Base directory for this skill」を起点に <base>/references/join-gate.md として解決する）。

---

Phase 9: 完了報告

完了報告の前に「合流ゲート」（references/join-gate.md）を通過すること（未合流のサブエージェント・バックグラウンド処理が0件であることの確認。1つも起動していない場合の0件も正常経路としてゲート通過）。

全経路に共通して必須の項目

• --max-parallel を受け取った起動で、Phase 2 の規律4により内側で追加直列化した場合は、その事実と理由（直列化した Issue 対と、根拠にした予測交差）を必ず含める。 追加直列化が0件だった場合も「追加直列化なし」と明記する（黙ると、上位層は次周の実行計画で同じ衝突を踏む）。

単一Issueの場合

/impl の完了報告をそのまま集約する（本スキルが内容を作り直さない）:

1. 実装サマリー
2. PR URL とCIステータス
3. クリティカル設計の逸脱検知でユーザー判断を仰いだ場合はその結果
4. E2E結果（対象機能の場合）— シナリオ一覧と完了条件トレーサビリティ表（/explain-e2e は /impl が次の操作として案内する）
5. 次のアクションの案内（/impl の案内をそのまま載せる。レビュー対応・マージへ進める操作は harness resume で行う）

---

成果物

• プロダクションコード
• テストコード（単体・結合・E2E）
• 設計内容（クリティカル/E2E対象時の人間レビュー記録を含む）
• Pull Request（Issueごとに1つ、通常PR→CI緑＋AIレビュー対応→マージ）

上記はいずれも /impl が1チケットごとに産出する成果物であり、本スキルはそれを Issue 数ぶん集約する。

---

禁止事項

• スコープ外の機能追加
• 設計フェーズ（設計成果物出力）の省略
• 要件チケットの「クリティカル設計決定」を無視した実装
• テストなしでのコード追加
• 実装フローの手順を本スキル・spawn プロンプトへ再掲・注入すること（正本は /impl ただ1つ。複製した瞬間にずれる）
• --max-parallel を受け取っておきながら、その値を超えて worker を起動すること／受け取った --serial グループを解除すること
• 並列度・直列化を問い合わせるために上位層へ戻ること（同一周のラウンドトリップ）

---

ユーザーへの確認タイミング

• Issueの要件が不明確な場合
• 複数の実装アプローチが考えられる場合
• スコープの拡大が必要と判断した場合
• Issue間の依存関係・衝突による直列化の判断が必要な場合（--max-parallel を受け取っていない単独利用に限る。受け取っている場合は Phase 2 の規律に従い、停止せず保守側へ倒して完了報告に書く）
• 直列化した後続チケットの spawn 前（先行 PR の base が既定ブランチで、人間によるマージが必要な場合）
• クリティカル設計の逸脱検知時（/impl が判断待ちを返したとき。feature-implementer の警告を受けて判断を仰ぐ）
• 実装完了後のレビュー依頼時