v-planning

v-planning

DAG の縦方向のステップとして実装計画を作成します。各ステップは、価値を提供する完全なスライス（1 つの機能に対する DB + API + UI + テスト）であり、QA を実施できます。DAG では機能レベルの依存関係を表すため、依存関係のないステップはサブエージェントによって並行して実装できます。

出力する計画は、次のディレクトリです：thoughts/<username|shared>/plans/YYYY-MM-DD-description/

root.md            # Overview, mermaid DAG, step index, Global Verification
step-1.md          # frontmatter (id, name, depends_on) + Success Criteria
step-2.md
└── step-N.md

セットアップ（開始前）

1. 自律モード — 呼び出し元のコマンドによって渡されます。指定がない場合は、Critical をデフォルトにします。

   モード	動作
   Autopilot	独自に調査し、計画ディレクトリ全体を作成して、最終レビューのみを依頼します
   Critical（デフォルト）	調査の各ステップ後、草案の作成前に確認の質問をします。特に DAG の分割では設計上の選択肢を提示します
   Verbose	各サブステップで確認します。理解を検証し、範囲を確認し、不明点を提示して、各ステップファイルの作成前に確認します

2. コミットの希望 — Autopilot 以外の場合、AskUserQuestion を使って一度だけ質問します：

   質問	選択肢
   「手動検証に合格した後、各ステップの完了時にコミットを作成しますか？」	1. はい（推奨）、2. いいえ。コミットは自分で行います

3. 過去の学び — 任意のサブスキル： ~/.agentic-learnings.json が存在する場合は、最初に /learning recall <topic> を実行します。

10 のルール

1. まず骨組みを作成する — 調査を始める前に、計画モードを終了し、cc-plugin/base/skills/v-planning/templates/root.md を使って root.md と計画ディレクトリを作成します。（ユーザー名がわかっている場合は、たとえば taras のようにその名前を使用します。そうでない場合は thoughts/shared/ を使用します。）ステップファイルは、ルール 4 に従って DAG ができるにつれて追加します。ディレクトリは段階的に充実していくため、ユーザーは早い段階で方向を修正できます。

2. 負荷の高い作業はすべてサブエージェントに任せる — ファイルの読み取り、調査、検証を行います。デフォルトは run_in_background: true です。生のツール出力をメインセッションに出さないでください。 サブエージェントの一覧：codebase-locator（ファイルを探す）、codebase-analyzer（現在の実装を把握する）、codebase-pattern-finder（類似機能を探す）、context7 MCP（ライブラリ／フレームワークの詳細）、Explore または general-purpose（言及されたファイルを読む）。

3. AskUserQuestion で質問する — 規約については desplega:ask-user を参照してください。チャットで箇条書きの質問を直接投げかけないでください。

4. Critical／Verbose では各ステップ後に質問し、その後ループする — 計画の各セクションを順番に進めます：現在の状態の分析 → 実装アプローチ → DAG の分割 → ステップごとの詳細。各セクションでは、サブエージェントを起動 → 調査結果を統合（file:line 参照を含める）→ 不足点について AskUserQuestion で質問 → 草案を作成 → 次のセクションへ進みます。

   • DAG の分割：縦方向のスライス（個別に QA を実施できるもの）、それらの依存関係、明示的な統合ステップの有無を特定します。ステップのリスト案と mermaid グラフを提示し、ステップファイルを作成する前に AskUserQuestion で構成を確認します。
   • ステップごとの詳細：cc-plugin/base/skills/v-planning/templates/step.md から各 step-<n>.md を作成します。Frontmatter の depends_on: [step-X, ...] が正規の定義です。root.md の mermaid グラフとステップ一覧の表は派生ビューなので、常に同期させてください。

5. 各ステップに具体的な成果物を設ける（縦方向のスライス） — 各ステップの Overview では、完了時にどのファイル／機能／出力が存在するかを明記します。各ステップは単独で QA を実施できる必要があります。 レイヤーだけを対象とするステップ（「DB マイグレーション」「エンドポイントだけ」など）は問題の兆候です。縦方向のスライスにまとめてください。「X の改善」や「Y のリファクタリング」も問題の兆候です。

6. 作業の証明：自動検証と自動 QA を最大限にする — 実行可能なコマンド（低レベル）とエージェントによる QA（browser-use、スクリーンショットの差分、CLI のウォークスルー）を最大限活用します。手動検証は例外とします。各ステップには個別の Success Criteria ブロックを設けます。root.md の ## Global Verification には、DAG 全体の完了後にのみ実行する横断的なチェックを記載します。desplega:qa ドキュメントへのリンクを含む ### QA Spec (optional): は、日常的なステップごとのチェックではなく、横断的、または詳細な証拠を必要とする QA に使用します。

7. 分割を提案する — 1つのステップに4つを超えるサブステップ、または2つを超える個別の懸念事項がある場合は、複数のDAGノードに分割します（依存関係を適切に接続してください）。DAG全体が1回の並列実装セッションに収まらない場合は、複数のプランに分割します（例：コントラクト → ストレージ → UI）。線形DAGも許容されますが、その場合は指摘する価値があります。線形の planning スキルのほうが適している可能性があります。

8. 率直に異議を唱える — プランが大きすぎる、曖昧、懸念事項が混在している、または明白なリスクがある場合は、desplega:feedback を使います。沈黙は、破滅的な共感です。

9. プランを提示する前に、Haiku サブエージェントで構造を検証します（general-purpose、model: haiku）。以下を確認します。すべての step-<n>.md に3つの成功基準サブセクション（自動検証 + 自動 QA + 手動検証）があること。すべての項目が - [ ] 形式であること。自動チェックが実行可能なコマンドであること。各ステップの depends_on が既存のステップ ID を参照していること。DAG に循環がないこと。root.md の mermaid グラフとステップインデックステーブルがステップの frontmatter と一致していること。すべてのステップの frontmatter に status: ready があること（これは新規プランであり、状態遷移は /v-implement の実行中に発生します）。参照先のパスが存在すること。提示する前に修正を適用します。

10. 新しいセッションに引き継ぐ — ここでは実装しないでください。 終了時の手順：

    1. （Autopilot の場合を除き）/file-review:file-review <plan-dir>/root.md を開き、コメントに対応します。必要に応じて、個々の step-<n>.md ファイルを開いて再確認します。

    2. 必要に応じて、ギャップ分析のために desplega:reviewing を呼び出します（AskUserQuestion で提案します）。

    3. 任意のサブスキル： 重要な知見が得られた場合は、/learning capture で記録します。

    4. いずれかのステップに ### QA Spec (optional): ブロックがある場合は、引き継ぎ前に desplega:qa を使って QA ドキュメント（thoughts/<username|shared>/qa/YYYY-MM-DD-[feature].md）を生成します。シナリオはプランではなく、ドキュメントに記載します。

    5. AskUserQuestion で尋ねます。

       質問	選択肢
       "プランの準備ができました。次はどうしますか？"	1. 新しいセッションで実装する、2. 先に /review を実行する、3. 今回はここまで（プランを保留する）

    6. 次の内容を明確に伝えます。"新しい Claude Code セッションを開き、/desplega:v-implement <plan-dir> を実行してください。新しいセッションを使うことで、実装のコンテキストをクリーンに保てます。"

DAG の詳細

• 依存関係の正本は frontmatter です。 root.md の mermaid グラフは frontmatter から生成されます。両者が一致しない場合は、frontmatter を優先します。
• 各ステップを自己完結させます。 root.md のプランレベルのコンテキストに加え、1つの step-<n>.md だけを渡されたサブエージェントが、兄弟ステップを読まずに実装できる必要があります。
• frontmatter が実行状態を保持します。 各ステップの初期状態は status: ready です。desplega:step-running は状態を claimed → done と遷移させます（再試行可能な失敗時は ready に戻します）。claimed の間は assignee / claimed_at も書き込みます。これにより、同じプランディレクトリを複数のオーケストレーターインスタンスから安全に実行できます。ステップ本文（必要な変更、成功基準）は実行中に変更しません。変更されるのは frontmatter とチェックボックスの状態のみです。
• 必要に応じて統合ステップを明示します。 並列で進める兄弟ステップの非自明な統合作業（横断的な e2e、共有領域の調整など）が必要な場合は、depends_on: [step-X, step-Y, ...] を持つ明示的な step-N を追加し、その作業を「統合 + e2e」とします。それ以外の場合、DAG は末端ノードで終了します。

コミットの統合

Setup でステップごとのコミットが有効になっている場合：

• 各ステップの手動検証に合格した後、[step-N] <brief description> 形式でコミットします。
• 手動検証に合格したという明示的な確認を得てからコミットします。
• それ以外の場合はスキップし、コミットはユーザーが行います。

成功基準の形式（必須）

正規の形式と見出し階層は、以下に記載されています。

• cc-plugin/base/skills/v-planning/templates/root.md（## Global Verification）
• cc-plugin/base/skills/v-planning/templates/step.md（ステップごとの3分類の成功基準）

構造の検証は自動的に実行されます（ルール9、Haiku サブエージェント）。