AI-Driven Plan (PlanGate / Codex 共用)

PlanGate ワークフローの plan フェーズ（WF-02〜WF-03） を Codex / Claude Code 両方で実行する skill。skill が担うのは読む順序と入出力規約であり、機械化された実行ロジックは上流リポジトリ（s977043/plangate）の scripts/ai-dev-workflow / bin/plangate CLI 側にある。

その CLI は導入先には配布されない（Human 決定 #1144: plugin が配るのは読み物層のみで、CLI と enforcement 層〔scripts/hooks/〕は含めない）。plan フェーズ自体は CLI 非依存で完結する（本 skill の手順どおり plan.md / todo.md / test-cases.md を手で作る）。CLI が必須なのは plan_hash の機械検証など一部に限られ、その分離と代替手順は下記「CLI 呼び出し」節と「CLI 不在時のフォールバック」節を正本とする。

本スキルは bundled resources（references/）で自己完結する。

パス表記の規約（重要）: 本 SKILL.md 中の references/… は、すべて 本スキル ディレクトリからの相対パス（= <skill_dir>/…）であって、導入先リポジトリのルートからの 相対パスではない。実行時はまず <skill_dir>（このファイルが置かれているディレクトリ）を 解決してから使う:

環境	<skill_dir>
plugin 導入先（Claude marketplace）	<plugin_root>/skills/ai-dev-plan/
install.sh --claude 導入先	.claude/skills/ai-dev-plan/
Codex 導入先	.codex/skills/ai-dev-plan/
上流リポジトリ（正本側）	.agents/skills/ai-dev-plan/

導入先が独自の正本（上流リポジトリの docs/ 配下に相当するもの）を別途保持している 場合は、そちらを優先すること。

Read First

参照解決順（導入先で必ずこの順に探す）

本 Skill は 上流リポジトリ基準の docs/** パスを直接参照しない（#1232）。docs/** は install.sh --claude / plugin（Claude marketplace）/ Codex の 3 経路とも配布対象外であり、 書いた時点で導入先では必ず空振りするためである。参照の解決は次の順で行う:

1. <skill_dir> 配下の同梱物（references/）を第一に読む — 契約 doc・テンプレートは 本スキルに同梱されている（「同梱リファレンス」節の一覧）
2. 導入先リポジトリが独自の正本（上流の docs/ 配下に相当するもの）を保持していれば、 そちらを優先する
3. rules（rules/*.md）だけは配布経路によって着地が異なるため、次の順で探す:
   1. 導入先リポジトリの相対パス（例: .claude/rules/mode-classification.md）
   2. 無ければ plugin root 配下（例: ${CLAUDE_PLUGIN_ROOT}/rules/mode-classification.md）
      • 解決は Bash で ls "${CLAUDE_PLUGIN_ROOT}/rules/" を実行して確認する。 Read ツールは絶対パスを要求し環境変数を展開しないため、${CLAUDE_PLUGIN_ROOT}/... という文字列をそのまま Read しても必ず失敗する
      • 変数が空・未設定なら glob（~/.claude/plugins/cache/** 等）で推測せず次へ進む。 キャッシュには複数バージョンが並存しうるため、当て推量は版の取り違えを招く
4. いずれでも解決できなければ 「正本 <path> を参照できなかった」と明示し、本 Skill 内の 記述と同梱 references/ を代替正本として扱い、推測で内容を補わない

plugin root 直下に docs/ を探しに行かないこと: plugin が配布するのは agents / commands / skills / rules 等の定義ディレクトリのみで docs/ を配布対象として 認識せず、plugin root 配下に相当する配布物が存在しないため必ず空振りする（クラス A の rules 参照が plugin root 配下で解決できるのは rules/ が実際に配布されるからであり、この非対称を docs/** に持ち込まない）。

導入経路は 3 つあり、配置されるものが違う（「同じ 4 ディレクトリが配られる」わけではない）:

• install.sh --claude 経由: コピー対象は agents / skills / commands / rules の 4 ディレクトリのみ（一次ソース: install.sh の for dir in agents skills commands rules）
• plugin（Claude marketplace）経由: バンドルは agents / assets / commands / hooks / rules / scripts / skills + README.md / .claude-plugin/。ただし scripts/ の中身は install-plangate-skills.sh のみで、ai-dev-workflow も bin/plangate も含まれない
• Codex（install.sh --codex / marketplace）経由: 配置されるのは skills だけ。 install_codex() は install-plangate-skills.sh を呼ぶのみで、同スクリプトは rules を一切扱わない（.claude/rules/ は作られない）。${CLAUDE_PLUGIN_ROOT} も Claude Code の変数であり Codex には無い

例外（上流リポジトリ内のドッグフーディング経路 / #1249 MINOR-3）: 上表「Codex 経由」の 「同梱（解決可）」が成立するのは 配布物経由（plugin/plangate/scripts/install-plangate-skills.sh。 source は plugin/plangate/skills/）に限る。上流リポジトリ自身が .codex/skills/ を作る scripts/install-plangate-skills-to-codex.sh は source が .agents/skills/ であり、そこには 本 skill の references/ が 存在しない（references/ は scripts/sync-plugin-plangate.sh が plugin/plangate/skills/** にだけ生成する）。したがって上流 repo の .codex/skills/<skill>/references/ は 構造上つねに不在であり、この経路では契約 doc・ テンプレートは手順 4（解決できなかったと明示）に落ちる。上流では docs/** の正本を直接 読めるため実害は無いが、上表の「解決可」を上流の .codex/ にまで拡大解釈しないこと。 経路自体の是正（source の一本化）は #1086 の裁定待ち。

Codex 経路では rules の解決順 3-1・3-2 とも成立しないため、rules 参照は手順 4 （解決できなかったと明示）に落ちる。その場合、正本の内容は 同梱 references/ と本 skill の 記述で代替し、plan.md の Questions / Unknowns に「正本 <path> を参照できなかった」旨を 記録する。

同梱リファレンス（<skill_dir>/references/）

plan.md の雛形が plan-template.md である理由: 承認境界 hook（EH-3）は basename plan.md を block 対象として判定する（パスではなく basename）。雛形を plan.md の名前で同梱すると、hook を配線した導入先で雛形そのものが編集不能になる。 配布名だけを変えており、生成する成果物のファイル名は plan.md のまま。

読む順序

下記 3〜5 の fallback にある <plugin_root> は、上の「参照解決順」手順 3-2 のとおり Bash で ${CLAUDE_PLUGIN_ROOT} を展開して得た絶対パスを指す（変数を含む文字列を そのまま Read しない）。

1. CLAUDE.md
2. AGENTS.md
3. .claude/rules/working-context.md → fallback <plugin_root>/rules/working-context.md （B フェーズ 3 ファイル同時生成・段階別出力・ゲート条件の正本）
4. .claude/rules/mode-classification.md → fallback <plugin_root>/rules/mode-classification.md （5 段階 mode + lite_eligible 派生属性の正本）
5. .claude/rules/hybrid-architecture.md → fallback <plugin_root>/rules/hybrid-architecture.md （Rule 1〜5 / handoff 必須化）
6. references/ai-driven-development.md（同梱。導入先が独自正本を持つ場合はそちらを優先）
   • 最低限: ## ワークフロー全体像、### タスク規模によるモード分岐（5 モード）、## ゲート条件、### Prompt 1: Plan + ToDo + Test Cases生成
7. docs/working/TASK-XXXX/pbi-input.md（導入先で作成する入力。配布物ではない。無ければ plan を開始しない）

Output

• docs/working/TASK-XXXX/plan.md
• docs/working/TASK-XXXX/todo.md
• docs/working/TASK-XXXX/test-cases.md
• docs/working/TASK-XXXX/INDEX.md（任意・無ければ生成）
• docs/working/TASK-XXXX/decision-log.jsonl（初期化）

Rules

フロー（詳細は正本参照）

• B-1 / B-2 / B-3 フローおよび plan.md 必須セクション（確認事項 / アプローチ比較 / Mode判定 / lite_eligible 等）は同梱 references/ai-driven-development.md の ### Prompt 1: Plan + ToDo + Test Cases生成 と .claude/rules/mode-classification.md を 正本 とする。skill は順序のみを示す。生成物の雛形は同梱 references/plan-template.md / references/todo.md / references/test-cases.md を使う。
• Planの設計判断は上流正本 docs/ai/plan-design-principles.md を基準とし、導入先では下記「Plan Design Principles」節を配布用の実行サマリとして使う。新しい bundled reference を増やさず、既存の SKILL.md 同期経路を再利用する。
• Principles は常に判断へ利用するが、artifactへは material な判断だけを残す。ultra-light / light で空セクションや儀式的 N/A を増やさない。
• B-1（最大 3 問の確認質問）→ 事前メトリクス検証 (mandatory gate) → B-2（2〜3 案の trade-off 比較）→ B-3（3 ファイル同時生成）

Plan Design Principles（#1335 / 配布用実行サマリ）

上流の詳細正本は docs/ai/plan-design-principles.md。docs/** が届かない plugin / Codex / install.sh 導入先でも同じ判断を実行できるよう、必要最小限の規範を本SKILLへ埋め込む。本SKILLは既存 scripts/sync-plugin-plangate.sh の skill 同期で配布される。

Plan作成では次の6原則を使う。Review checklistへ個別展開せず、作成時の判断ガイドとして適用する。

1. Evidence Before Design — 推測より現行実装・テスト・docs・履歴・実測を優先する
2. Minimum Sufficient Design — 現在のACを満たす最小十分な設計をbaselineにする
3. Explicit Responsibility & Boundary — Task / module / workflow等の責務を1文で説明できる粒度にする
4. Abstraction Requires Evidence — code similarityだけで共通化せず、knowledge/invariant/change reason/current needを確認する
5. Extension Is Conditional — OCP/DIP/Compositionは実在する境界・variationがある場合だけ発火する
6. Design for Verification — Design Decisionをobservable Behavior / Contract / Invariantと検証方法へ接続する

新しい abstraction / interface / dependency / extension point と Contract / Invariant は、AC / current constraint / existing behavior / domain rule / architecture constraint / measured evidence の現在根拠へ trace できなければ採用しない。

事前メトリクス検証 (B-1 → B-2 mandatory gate / #351 TASK-0117)

正本: 同梱 references/plan-metrics-verification.md （導入先が独自正本を保持する場合はそちらを優先。どちらも解決できない環境では以下の要約に従い、正本未参照である旨を plan に記録する）

「全部 / 全件 / 残り N 件」系の対象は 実数を取得 してから B-2 へ進む。

検証コマンド例 (.git / node_modules 等を除外):

grep -rln --exclude-dir={.git,node_modules,dist,docs/working} <symbol> --include='*.md' -- . | wc -l
find . -name <pattern> -not -path './.git/*' -not -path './node_modules/*' | wc -l
# 推奨: rg --files <path> | wc -l

判定基準 (実数 / AI 見積もり):

• ≥ 3 倍 → スコープ縮小 or 別タスクへ切替
• 1〜3 倍 → 採用、plan の Risks に記録
• < 1 倍 → 採用、Mode を 1 段下げる候補

plan.md template に ## Metrics Evidence 欄を必須化 (実数 / 見積もり / ratio / 判定 を残す出力契約 / AC-8)。

未取得時の分岐 (安全側 / R-001/R-004): 実数取得不能 / Plan Health 未算出 / 「全件」系の対象が曖昧な場合は 必ず Mode 引き上げ側に倒す (mode-classification.md AC-8 安全側不変条件と一貫)。

todo.md 規約

• タスク粒度 2-5 分、Owner: agent / human 必須、depends_on / files 必須
• L-0〜V-4・PR 作成は workflow-conductor が自動制御するため含めない
• 各タスクに rollback: を記載（戻し手順）。必須=high-risk / critical の実装タスク。standard 以下は任意、検証/読取のみは rollback:不要 と明記可
• rollback 手順が長い場合はタスク直下に補助ブロックで記述してよい

test-cases.md 規約

• 各 AC → テストケースのマッピング必須、Edge case を含める
• AC以外の重要な Contract / Invariant / Regression / Conditional Requirement を検証する場合は Verification Trace に存在理由とSource/Evidenceを残す
• Contract / Invariant はテストを作るために後付けで発明しない。AC / 既存挙動 / Domain Rule / Architecture Constraint / 実測 Evidence の最低1つへ trace する
• Trace（なぜtestが存在するか）と 期待値の出所（なぜexpectedが正しいか）を分離する
• 各ケースの期待値に出所を明記する（デザイン実測 / 規約 / 既存実装）
• 出所が 規約 の期待値は、## Convention Evidence に 規約の記述 / 実値 / 一致 / 判定 を残す（#934）。 事前メトリクス検証が「全部 / 全件」系に実数を要求するのと同じ理由で、規約由来の期待値には実値との突合を要求する
• 不一致（規約 ≠ 実値）のときは AC に採用しない。安全側に倒して plan の 🚩 人間確認ポイントへ落とし、 規約と実装のどちらを正とするかは人間の設計判断に委ねる（mode-classification.md の安全側不変条件と一貫）。 AI が黙って片側へ寄せて一括変更しない

Minimum Sufficient Test Set（#936 → #960 / #1335）

Test Case は現在の要求を証明する最小十分な集合へ収束させる。

• 各 Test Case は distinct な Trace ID、または同じ Trace に対する distinct な failure / boundary / compatibility / security evidence を説明する
• 同じ Trace + 同じ failure mode を実質的に重複して証明するケースは、差に意味がなければ統合する
• 「念のため」「生成できるから」「ケース数を増やすため」だけでは追加しない
• hard な件数上限は置かない。高リスク変更で distinct な検証要求が増えることは許容する
• mode は Test Case 件数の cap ではなく、materiality / 記述密度に使う

Minimize redundant proofs, not meaningful coverage.

変更タイプ別 Verification / TDD

Always RED first を一般則にしない。変更タイプに適した事前証拠を持ち、変更後に同じ契約を再検証する。

• new behavior: failing test (RED) → minimum implementation → GREEN → refactor
• bug fix: regression test reproduces failure (RED) → fix → GREEN
• behavior-preserving refactor: characterization / existing tests GREEN → refactor → GREEN + behavior-preservation evidence
• docs / config / generated artifact: deterministic baseline → change → deterministic validation

RefactorではRedの状態で構造変更を進めない。Characterization Test / Preparatory Refactoring / Knowledge Deltaの詳細は #867 の責務とし、本skillで再定義しない。

監査

• decision-log.jsonl に B-1/B-2/B-3 の主要判断を append-only で記録
• mode が critical で lite_eligible=true の場合は人間の C-3 明示承認記録が前提（mode-classification.md AC-11）

計画の構造化観点（river-review rr-upstream-create-plan-001 由来 / #517 受け入れ）

plan.md 生成時、以下の観点を Work Breakdown / Risks に反映する:

1. 仮説と確定事項の分離 — 判断に必要な事実が欠けていれば Questions / Unknowns に 質問として先出しし、仮説（未確認の前提）と確定事項を混ぜない。情報不足のまま 推測で進めない
2. リスクの 3 点セット — Risks には 内容 / 検証手段 / Fallback を揃える。 不確実性（互換性・性能・移行・セキュリティ）ごとに検証方法が無いリスクを残さない
3. 人間ゲートの明示 — 設計確認・仕様確認など人間レビューが必要なブレーキ ポイントを Work Breakdown の 🚩 チェックポイントとして明示する（自己設置 Gate は 勝手に解除しない — responsibility-classes.md 準拠）
4. 速く学べる順 — ステップは検証が早く回る順に並べ、クリティカルパスを明示。 並列可能な作業はまとめて示す

出典: river-review rr-upstream-create-plan-001（skill インベントリ監査で 「plan を作る側 = PlanGate の責務」と整理され移管。s977043/river-review#1105）

CLI 呼び出し

配布と対象 project root は別の問題（#962 / #1144）: plugin / install.sh --claude / Codex は bin/plangate と enforcement scripts を導入先へ配布しない。そのため CLI を使うには PlanGate の clone と、その bin/plangate への PATH または絶対パスが必要。 ただし #1497 以降、CLI が利用できる場合の対象 project root は全コマンド共通で --project-root → PLANGATE_PROJECT_ROOT → cwd の git root → CLI root fallback の順に解決される。導入先の git repo で PATH 上の plangate を実行すれば、その導入先が 既定の対象になる。CLI が無いことを理由にゲートや検証を黙って省略してはならない。

#1497 で downstream 契約を明示検証したのは status / validate / approve / read-only doctor（および work-dir を明示する render）。doctor --fix は #1144 の enforcement 配布が解決するまで downstream では rc=2 / no-write で fail-closed。 script-relative helper に委譲するコマンドは、root resolver が存在しても自動的に downstream 対応になるとは扱わず、下表・フォールバックの個別契約に従う。

呼び出し表記: 上流 clone の cwd では bin/plangate、導入先で PATH を通している場合は plangate を使う。別の対象を明示する場合は plangate --project-root <dir> ...。 ./scripts/ai-dev-workflow はこの project-root resolver の対象外で、引き続き上流 clone 基準。

project root 契約: plangate の TASK-XXXX は選択済み project root の docs/working/TASK-XXXX を基準に解決する。これは scripts/ai-dev-workflow の script-relative root 解決とは別契約である。

CLI 不在時のフォールバック（導入先では既定）

scripts/ai-dev-workflow と bin/plangate は 3 経路のいずれでも導入先に 配置されない。根拠は経路ごとに異なる:

• install.sh --claude 経由: コピー対象が agents / skills / commands / rules の 4 ディレクトリに限られ、bin/ も scripts/ も対象外
• plugin（Claude marketplace）経由: ${CLAUDE_PLUGIN_ROOT}/scripts/ は存在するが中身は install-plangate-skills.sh のみ。bin/ はバンドルに無い
• Codex 経由: 配置されるのは skills のみ

上表の「導入先 + PATH に無い（既定）」に該当する場合は次に従う:

1. 手動生成に切り替える — 「Output」の 5 ファイルを skill の手順どおり手で作る。 B-1 →（事前メトリクス検証）→ B-2 → B-3 の順序と出力契約は CLI の有無に関わらず不変

2. plan_hash 整合検証は標準コマンドで代替する（スキップしない） — plangate validate の plan_hash 検査は plan.md の素の sha256（正規化・前処理なし）と c3.json の plan_hash から sha256: prefix を除いた値の単純比較なので、CLI 無しで再現できる:

   # 算出（sha256sum が無い環境では shasum -a 256 を使う）
   sha256sum docs/working/TASK-XXXX/plan.md | awk '{print $1}'
   # 突合先: docs/working/TASK-XXXX/approvals/c3.json の "plan_hash": "sha256:<この値>"

   不一致なら C-3 承認後に plan が改変されている → exec に進まず、再承認 （c3.json の plan_hash 更新）または plan の revert を行う。 sha256sum / shasum の両方とも無い場合に限りスキップし、その事実を decision-log.jsonl と plan.md に記録して 「機械検証済み」と書かない （未検証を検証済みと誤記しない）

3. ゲートは人手で維持する — plan_hash を照合する hook も導入先には配線されないため、 item 2 の突合は exec 開始前に自分で実行する。C-3 は人間の明示承認記録 （docs/working/TASK-XXXX/approvals/c3.json 相当）で成立させ、CLI が無いことを理由に C-3 を省略しない
4. CLI による機械検証が必要なら PlanGate の clone を用意し、導入先 repo の cwd から plangate validate TASK-XXXX を実行するか、任意の cwd から plangate --project-root <導入先repo> validate TASK-XXXX を実行する。 既存の validate --dir <TASKディレクトリ> も明示パス指定として利用できる

次フェーズへ

plan 完了後は plan-review-gate skill で C-1 → C-2 → C-3（c3.json APPROVED）。exec は ai-dev-exec skill。