plan-decompose

name	plan-decompose
description	プランモードで練り上げた実装計画が1ファイルに収まらないほど大きくなった場合に、SSOT（overview.md）+ フェーズ索引（README.md）+ フェーズ別詳細（phase-N-*.md）の複数ファイル構成に分割して出力するスキル。出力先ディレクトリは引数で指定するか、なければユーザーに確認する。各ドキュメントはコードを含まず「何を作るか」「どの順でどう作るか」を記述する設計文書。「プランが大きすぎる」「フェーズに分けたい」「プランをドキュメント化したい」「計画ドキュメントを出力して」と言われたとき、またはExitPlanModeで確定したプランが長大で1回の実装セッションに収まらないと判断したときに使う。
license	MIT
argument-hint	[出力先ディレクトリ]
disable-model-invocation	true

plan-decompose

大きな実装計画を、仕様（何を作るか）と実装計画（どの順でどう作るか）に分離した複数ファイルへ分割し、指定された出力先ディレクトリに出力する。

なぜ分割するか

プランモードの1ファイルに全フェーズのコードまで書き込むと、次の問題が起きる：

• 後続フェーズの詳細が先行フェーズの実装で陳腐化し、「計画」と「実際に確定した仕様」がずれる
• 1ファイルが肥大化し、フェーズ単位で実装を進めるセッションのコンテキストを圧迫する
• 「何を作るか（仕様）」と「どの順で作るか（段取り）」が混ざり、フェーズ後半で仕様変更が起きたときにどこを直せばいいか分からなくなる

これを避けるため、仕様はoverview.mdに一本化し、各フェーズドキュメントは仕様を再定義せず参照する。フェーズドキュメントにコードは書かない（実装方針は「どのクラス/モジュールに何の責務を置くか」という設計判断に留め、具体的なコードは実装フェーズで書く）。

適用判断

以下のいずれかに当てはまる場合に分割を提案する（自動発火はしないが、ユーザーに大きさを聞かれたら判断材料にする）：

• フェーズ数がおおよそ4つ以上になりそう
• 1つのプランファイルが数百行を超え、フェーズ間の依存関係が複雑
• 実装を複数のPRに分けて進める前提がある

小さい計画（1〜2 PRで完結する）は分割の恩恵が薄いので、通常のプランモードのまま進めることを勧める。

手順

1. 出力先を決める

引数でディレクトリが指定されていればそれを使う。指定がなければ必ずユーザーに出力先ディレクトリを尋ねる（決め打ちしない）。

このリポジトリに計画ドキュメントを置く既存の場所（例: doc/plans/、docs/plans/ など）があればそれを軽く確認し、命名・配置の一貫性を合わせる。

2. プラン内容をフェーズに分解する

会話内で練り上げた実装計画（またはExitPlanModeで確定したプラン文字列）から、以下を抽出する：

• 仕様: 目的・スコープ（含む/含まない）・設計原則・公開インターフェース・データフロー・非対象。実装の順序に関係なく成り立つ内容。
• フェーズ分割: 1フェーズ = 1 PRを原則に、依存関係で自然に区切れる単位に分ける。並行可能なフェーズがあれば明示する。
• フェーズ間の依存: どのフェーズが完了していればどのフェーズに着手できるか。

依存関係が複雑な場合はMermaidのgraph TDで依存グラフを書く。

3. overview.md（SSOT）を書く

references/overview-template.md の構成に従う。設計仕様の単一参照元として、フェーズに依存しない「何を作るか」を書く。実装コードは含めない。フェーズをまたいで確定していない決定事項があれば、末尾に「実装時に確定させる決定事項」としてリストアップし、どのフェーズで確定させるかはREADME.md側にマッピングする。

4. README.md（フェーズ索引）を書く

references/readme-template.md の構成に従う。次を含める：

• 各ドキュメントの役割分担（overview.mdは仕様、README.md+phase-N-*.mdは計画、という原則を明記）
• フェーズ一覧表（フェーズ番号・タイトル・要約・依存）
• 依存グラフ（Mermaid）
• 各フェーズドキュメントへのリンク
• 各phase-N-*.mdが従う共通テンプレート（節構成）の宣言
• overview.mdの「決定事項」→ どのフェーズで確定するかのマッピング表

5. 各phase-N-*.mdを書く

references/phase-template.md の構成に従う。共通節構成（目的・スコープ・前提と依存・実装方針・変更ファイル・受け入れ条件・テスト観点・リスクと決定事項・参照）を全フェーズで統一する。

• 目的は1〜3行 + overview.mdの該当節番号へのリンク
• 実装方針はコードを書かない。責務配置（どのファイル/クラスに何を担わせるか）と設計判断の要点のみ
• 受け入れ条件はcheckbox形式。「CIが緑」のような共通条件は全フェーズに含める
• 参照は必ずoverview.mdの節番号にリンクし、仕様の再掲を避ける

フェーズ数が多い場合も、1フェーズ = 1ファイルを崩さない。フェーズ内でさらに分けたくなったら、それは2フェーズに分割すべきというサインとして扱う。

6. 整合性を確認する

• 各phase-N-*.mdの「参照」節がoverview.mdの実在する節番号を指しているか
• README.mdの依存グラフとフェーズ一覧表の依存列が一致しているか
• overview.mdに書いた「決定事項」が漏れなくいずれかのフェーズにマッピングされているか

7. 完了報告

作成したファイル一覧と、次にすべきこと（例: 「各フェーズは着手前にphase-N-*.mdを対象に新規プランモードで詳細を練り直してから実装に進められます」）を簡潔に伝える。

ドキュメントは生きた文書として運用する

このスキルで作るのは「一度書いたら終わり」の計画書ではない。実際の開発では次のように使う想定であり、overview.mdをSSOTとして機能させ続けるにはこの運用が欠かせない：

1. 各フェーズに着手する前に、そのフェーズのphase-N-*.mdを対象にして新規のプランモードに入り、着手時点の最新状況を踏まえて詳細計画を練り直す（骨格から詳細への肉付け）。
2. 実装を進める中で、phase-N-*.mdに書いた前提・スコープ・実装方針と食い違う判断が必要になったら、実装完了後にまとめてではなくその場で該当ファイルを書き換える。
3. その見直しがoverview.mdの決定事項や他フェーズの前提に影響するなら、overview.md / README.md / 影響する他のphase-N-*.mdも連動して更新する（片方だけ直して仕様と計画がずれたままにしない）。

このルールはphase-template.mdのテンプレート内に定型文として組み込まれているため、plan-decomposeが生成したphase-N-*.mdには自動的に付与される。生成後にこの注記を削除しない。

参照

• references/overview-template.md — overview.mdのテンプレートと各節の書き方
• references/readme-template.md — README.md（フェーズ索引）のテンプレート
• references/phase-template.md — phase-N-*.mdの共通テンプレート