ideation

アイデア出し

構造化されていないブレインダンプを、何かを書く前に共通認識を築く対話形式のインタビューを通じて、実装成果物に変換します。HTML はインタラクティブな意思決定（可視化、比較、ミッションブリーフの契約）に使用し、Markdown は参照ドキュメント（仕様書、PRD）に使用します。

ワークフロー

INTAKE → INTERVIEW LOOP → CONTRACT.HTML → PHASING → SPEC.MD GENERATION → HANDOFF
              ↓                  ↓             ↓             ↓                ↓
         Accept the mess    One question    Mission       Repeatable?      Phase track
                            at a time,      Brief with      ↓              + copy buttons
                            explore code    confidence   Template +        in contract
                            + show HTML     + scope      per-phase
                            examples        tiers        deltas

フェーズ 1～2：インタビュー

完全なインテークおよびインタビューループのプロセスについては、${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md を読み、指示に従ってください。フェーズ 3 に進む前に、そこに記載されているすべてのフェーズを実行してください。

詳細なスコアリング基準については、${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md を読んでください。

フェーズ 3：契約（HTML）

確信度が 95% 以上になったら、ミッションブリーフの契約を HTML ドキュメントとして生成します。それ以前には生成しないでください。

1. コンテキストから明らかでない場合は、AskUserQuestion を使ってプロジェクト名を確認します

2. ディレクトリ名をケバブケースに変換します（これが slug になります）

3. 出力ディレクトリ ./docs/ideation/{slug}/ を作成します

4. 出力ディレクトリに contract-data.json を書き込みます。これは ContractData スキーマに準拠した JSON ファイルです。CLI がこのファイルから HTML を生成します。この JSON には、インタビューで得られたすべての内容を記録します。

   {
     "projectName": "Human-Readable Name",
     "slug": "kebab-case-name",
     "date": "YYYY-MM-DD",
     "status": "Draft",
     "supersedes": null,
     "confidence": {
       "score": 96,
       "dimensions": [
         { "key": "scope", "score": 100, "label": "Scope", "reason": "One sentence explaining the score" },
         { "key": "risk", "score": 92, "label": "Risk", "reason": "One sentence" },
         { "key": "effort", "score": 95, "label": "Effort", "reason": "One sentence" },
         { "key": "clarity", "score": 98, "label": "Clarity", "reason": "One sentence" },
         { "key": "tests", "score": 95, "label": "Tests", "reason": "One sentence" }
       ]
     },
     "problem": ["paragraph 1", "paragraph 2"],
     "goals": ["Measurable goal 1", "Measurable goal 2"],
     "successCriteria": ["Pass/fail criterion 1", "Pass/fail criterion 2"],
     "scope": {
       "mvp": [{"item": "Core feature", "reason": "Why it's MVP"}],
       "full": [{"item": "Full feature", "reason": "Optional rationale"}],
       "stretch": [{"item": "Stretch feature"}],
       "outOfScope": [{"item": "Excluded item", "reason": "Why excluded"}],
       "future": ["Deferred idea 1"]
     },
     "execution": {
       "strategy": "Sequential",
       "phases": [
         {
           "title": "Phase name",
           "risk": "low",
           "blocking": true,
           "specPath": "docs/ideation/slug/spec-phase-1.md",
           "notes": "Brief description of what this phase covers"
         }
       ],
       "agentTeamPrompt": "only if 2+ phases parallelizable"
     }
   }
   

   確信度の各項目： 各項目に数値スコア（0～100）と 1 文の理由を設定します。全体の score はヒーローに表示され、各項目には内訳が表示されます。

   フェーズのフィールド： risk（high/medium/low）、blocking（ブール値）、specPath（仕様書へのパス）、notes（簡潔な説明）。省略可能：kind（人によるチェックポイントの場合は "gate"）、prereqs（依存先となるフェーズ名の配列）。

5. 契約ジェネレーターを実行します：

   npx tsx ${CLAUDE_PLUGIN_ROOT}/scripts/contract-gen.ts \
     --input ./docs/ideation/{slug}/contract-data.json \
     --output ./docs/ideation/{slug}/contract.html
   

   CLI がリネージを自動処理します。contract.html がすでに存在する場合は contract-{date}.html に名前を変更し、supersedes リンクを設定します。

6. ブラウザーで開きます：open ./docs/ideation/{slug}/contract.html（macOS）または xdg-open（Linux）を実行します

7. AskUserQuestion を使って承認を得ます。スコープ階層に関する質問を含めてください。

Question: "Does this contract capture your intent? Which scope tier should we target?"
Options:
- "Approved — Full scope (Recommended)" - Build MVP + Full tiers
- "Approved — MVP scope" - Ship the minimum viable version first
- "Approved — Stretch scope" - Include MVP + Full + Stretch tiers
- "Needs changes" - Some parts need revision before approving
- "Start over" - Fundamentally off track, re-interview

承認されたスコープ階層によって、仕様書に含める内容が決まります。選択した階層の範囲外にある項目は「今後の検討事項」に移します。

承認されなかった場合： フィードバックに基づいて修正します。フィードバックから根本的な誤解が判明した場合は、インタビューループに戻ります。それ以外の場合は、HTML ファイルを書き直してブラウザーで再度開きます。承認されるまで繰り返します。

契約が明示的に承認されるまで、先に進まないでください。

フェーズ 4：フェーズ分けと仕様作成

契約が承認されたら、フェーズを決定し、Markdown 形式の仕様書を生成します。PRD は省略可能です。

4.1 ワークフローの選択

AskUserQuestion を使って、次の質問をします。

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs (Recommended)" — Contract defines what, specs define how. Faster.
- "PRDs then specs" — Adds a requirements layer for stakeholder alignment.

4.2 フェーズの決定

契約を分析し、スコープを論理的な実装フェーズに分割します。

小規模プロジェクトの簡略化： スコープが 1 つのフェーズで実装できるほど小さい場合（コンポーネントが 1～3 個、変更対象のファイルが約 10 個未満）は、フェーズ分けを完全に省略します。フェーズ番号のない単一の spec.md を生成し、直接引き継ぎに進みます。シンプルさで十分な場合に、無理に構成を増やさないでください。

フェーズ分けの基準（複数フェーズのプロジェクトの場合）：

• 依存関係（最初に何を構築する必要があるか？）
• リスク（リスクの高い項目に早めに取り組む）
• 価値の提供（各フェーズの完了後、ユーザーにメリットがあるか？）
• 複雑さ（各フェーズの作業量を均等にする）

一般的なフェーズ分け：

• フェーズ 1：コア機能／インフラストラクチャ
• フェーズ 2 以降：機能、機能強化、追加の統合
• フェーズ N：今後の検討事項

繰り返しパターンを検出： 入力だけが異なる同じ構造のフェーズが 3 つ以上ある場合（例：「{language} 向け SDK サポートの追加」）、その旨を記録します。これは仕様書の生成方法に影響します（4.4 を参照）。

### 4.3 PRD の生成（ユーザーが「PRD の後に仕様書」を選択した場合のみ）

各フェーズについて、Read ツールを使って references/prd-template.md を読み込み、prd-phase-{n}.md を生成します。

以下を含めます。

• フェーズの概要と根拠
• このフェーズのユーザーストーリー
• 機能要件（グループ化）
• 非機能要件
• 依存関係（前提条件と成果物）
• 受け入れ基準

AskUserQuestion を使って、すべての PRD をレビュー用に提示します。

Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract

ユーザーが明示的に承認するまで、修正を繰り返します。

4.4 実装仕様書の生成

Read ツールを使って references/spec-template.md を読み込み、spec-phase-{n}.md を生成します。仕様ファイルは必要になった時点で作成し、フェーズの詳細が確定した場合にのみ生成します。

標準フェーズ（それぞれ独立）

各フェーズについて、以下を含む完全な spec-phase-{n}.md を生成します。

• 技術的アプローチ — 高レベルの戦略
• フィードバック戦略 — 内部ループのコマンド、プレイグラウンド、根拠
• ファイル変更 — 新規／変更／削除の識別を含む表
• 実装の詳細 — コンポーネントごとのセクション。それぞれにフィードバックループ（プレイグラウンド → 実験 → チェックコマンド）を含めます
• テスト要件 — テストファイルとカバレッジの表
• 障害モード — コンポーネント、障害、トリガー、影響、緩和策の列を含む表
• 検証コマンド — コードブロック

既存コードを参照する： インタビューでのコードベース調査により関連するパターンが特定された場合、仕様書の実装の詳細に「従うべきパターン：path/to/similar/file.ts」を含めます。

フィードバックループの設計： 反復的なコンポーネントごとに、プレイグラウンド（操作する環境）、実験（パラメーター化されたチェック）、チェックコマンド（最速の単一検証）を定義します。フィードバックの仕組みはコンポーネントの種類に合わせます。データレイヤーではテスト、UI では開発サーバー、API では curl スクリプトを使い、設定／型ではループを完全に省略します。コンポーネントの種類ごとのマッピングと設計基準の全容については、${CLAUDE_PLUGIN_ROOT}/references/feedback-loop-guide.md を参照してください。

障害モードの命名： 複雑なコンポーネントごとに、「どのような障害が起こるか」を考えます。仕様書の障害モードの表には、名前付きの障害、データのシャドウパス（nil、空、古いデータ）、エッジケース（並行アクセス、入力サイズ超過、権限不足）を記入します。単純なコンポーネント（設定、型、定数）では、障害モードの列挙を省略します。

繰り返し可能なフェーズ（3 フェーズ以上で同じパターンに従う場合）

複数のフェーズが同じ構造を共有する（例：「{SDK} のサポートを追加」）場合、ほぼ同一の完全な仕様書を N 個生成するのではなく、次のようにします。

1. 完全なテンプレート仕様書を 1 つ生成する — spec-template-{pattern-name}.md — 変動する部分にはプレースホルダーを使い、詳細な実装手順を記載します。

2. フェーズごとの簡易差分ファイルを生成する — spec-phase-{n}.md — 以下のみを記載します。

   • フェーズ固有の入力（例：言語名、パッケージマネージャー、フレームワーク）
   • テンプレートとの差異（このフェーズで異なる点）
   • フェーズ固有の懸念事項やエッジケース
   • テンプレートへの参照：「以下の入力を使って spec-template-{pattern-name}.md に従ってください」

4.5 仕様書のレビュー用提示

引き継ぎに進む前に、フェーズの内訳と仕様書をユーザーに提示し、承認を得ます。

仕様書を提示する前に、 ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md の Spec Feedback Quality チェックリストを使って、フィードバックループの品質を評価します。各仕様書を自己レビューします。

• 良好： すべての反復的なコンポーネントにフィードバックループがあり、内部ループのコマンドが定義され、単純なコンポーネントは正しく省略されている → 仕様書をそのまま提示
• 十分： ほとんどのコンポーネントにループがあるが、一部に不足がある → 不足している内容について注記を添えて仕様書を提示
• 不十分： フィードバック戦略のセクションがない、または複雑なコンポーネントにループがまったくない → 提示する前に仕様書を修正

不十分な場合は、まず不足を解消します。反復的なコンポーネントにフィードバックループがない仕様書は提示しないでください。

AskUserQuestion を使います。

Question: "Do these specs look correct? (Review them in your browser)"
Options:
- "Approved" - Specs look good, proceed to execution handoff
- "Adjust approach" - Implementation strategy needs changes
- "Missing components" - Some files or steps are missing
- "Revisit phases" - Phase breakdown needs restructuring

承認されなかった場合は、フィードバックに基づいて該当する仕様書を修正し、再提示します。承認されるまで繰り返します。

フェーズ 5：実行の引き継ぎ

仕様が承認されたら、契約書の HTML に実行計画を追加し、/ideation:execute-spec 用の Markdown 仕様書を自動生成します。

5.1 オーケストレーション戦略の分析

アイデア出しからの引き継ぎ時にタスクを作成しないでください。タスクは一時的なものであり、ユーザーが新しいセッションを開始すると失われます。各 /ideation:execute-spec セッションで、独自の詳細な実装タスクが作成されます。

フェーズの依存関係グラフを分析し、最適な実行戦略を決定します。

並列化可能なフェーズを検出する：

• どのフェーズが何によってブロックされているかを確認します
• 2 つ以上のフェーズが同じ単一のブロッカー（例：すべてがフェーズ 1 のみでブロックされている）を共有する場合、それらは並列化可能です
• フェーズが直線的な連鎖（フェーズ 2 → フェーズ 3 → フェーズ 4）を形成する場合、それらは逐次的です
• 混合グラフには、並列セグメントと逐次セグメントの両方があります

推奨戦略を決定する：

パターン	推奨
すべてのフェーズが逐次的（連鎖）	逐次実行 — 一度に 1 セッション
独立したフェーズが 2 つ以上	エージェントチーム — リードがチームメイトを並列にオーケストレーションします
依存関係が混在	ハイブリッド — 依存関係のある連鎖は逐次実行し、独立したグループはエージェントチームで実行します

5.2 実行計画を契約データに反映する

contract-data.json を最終的な実行計画で更新し、contract-gen.ts を再実行します。これにより契約書が完全に自己完結し、初めて内容を確認する人でも実行方法を正確に把握できます。

1. フェーズトラック — execution.phases に、フェーズのタイトル、リスク、ブロッカー、仕様書のパス、メモ、人的承認ゲートを入力します。CLI はリスクに応じた色分けで水平のフェーズトラックを表示します。

2. 実行コマンド — CLI は /ideation:autopilot と各 /ideation:execute-spec コマンドのコピーボタンを表示します。

3. エージェントチームのプロンプト — 2 つ以上のフェーズが並列化可能な場合にのみ設定します。execution.agentTeamPrompt を設定すると、CLI はコピーボタン付きの折りたたみセクションに表示します。プロジェクトが完全に逐次的な場合は、このフィールドをまったく記述しないでください。

共有ファイルの検出： エージェントチームのプロンプトを書く前に、仕様書の「変更ファイル」セクションを確認します。複数の仕様書で同じファイルを変更する場合は、調整に関する注記を含めます。

Coordinate on shared files ({list}) to avoid merge conflicts —
only one teammate should modify a shared file at a time.

バッチ処理： 並列化可能なフェーズが 5 つを超える場合は、実行手順に最優先のバッチから開始するよう記載します。

更新後、生成し直した契約書をブラウザーで開き直します。

5.3 契約書の Markdown を生成する

references/contract-template.md から、contract.html と同じ内容の contract.md を生成します。これは execute-spec の系譜検出に必要です。実行計画のセクションを含めます。

仕様書と PRD はフェーズ 4 ですでに Markdown になっているため、変換は不要です。

5.4 引き継ぎの概要を提示する

契約書の更新と MD 仕様書の生成後、会話形式で簡潔な概要を提示します。

必ず含める内容：

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

Open contract.html in your browser to review the full plan — phase track,
execution commands, and scope are all in the Mission Brief.

Specs (spec-phase-*.md) are ready. To execute all phases:
  /ideation:autopilot

Or run individual phases manually:
  /ideation:execute-spec docs/ideation/{project-name}/spec-phase-1.md

デフォルトとして /ideation:autopilot を推奨します。契約書を読み込み、依存関係グラフに沿って各フェーズにサブエージェントを割り当て（可能な場合は並列に実行）、失敗があった場合にのみ停止します。より細かく制御したい場合は、手動で /ideation:execute-spec を実行できます。

出力成果物

すべての成果物は ./docs/ideation/{project-name}/ に書き出されます。

_comparison.html                   # Ephemeral decision aid (deleted after choice is made)
contract.html                      # Mission Brief contract (for review)
contract.md                        # Plain contract (for execute-spec lineage)
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
...
spec-phase-1.md                    # Implementation spec (for execute-spec)
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase delta or full spec
...

同梱リソース

共有リファレンス（プラグインのルート）

• ${CLAUDE_PLUGIN_ROOT}/references/interview-engine.md - インタビューエンジン（フェーズ 1～2）
• ${CLAUDE_PLUGIN_ROOT}/references/confidence-rubric.md - 信頼度評価の採点基準と仕様フィードバックの品質基準
• ${CLAUDE_PLUGIN_ROOT}/references/feedback-loop-guide.md - 仕様フィードバックループのコンポーネントタイプ対応表と設計基準
• ${CLAUDE_PLUGIN_ROOT}/references/workflow-example.md - エンドツーエンドのワークフローの手順

スキルの参考資料

HTML（インタラクティブな成果物 — 契約、探索、インタビュー用の可視化）：

• references/html-guide.md - HTML コンポーネントライブラリ、デザイントークン、制約事項
• references/contract-template.html - インタラクティブな HTML 契約テンプレート

Markdown（仕様、PRD、execute-spec 用の契約文）：

• references/contract-template.md - プレーンな契約テンプレート
• references/prd-template.md - プレーンな PRD テンプレート
• references/spec-template.md - プレーンな仕様テンプレート

例

出力を作成する際の参考となる、完成済み成果物の例：

• examples/contract-example.md - ブックマーク機能の記入済み MD 契約書
• examples/prd-example.md - 同じ機能の記入済み MD PRD（フェーズ 1）
• examples/spec-example.md - 同じ機能の記入済み MD 仕様書

成果物を作成する際は、文体、構成、詳細度の参考としてこれらの例を参照してください。

意思決定のための HTML 可視化

インタビューとフェーズ分けの段階では、視覚的な情報がユーザーの意思決定に役立つ場合、一時的な HTML ページを作成してください。これらは一時的な補助資料です。作成して確認した後、削除します。

使用する場面：

• インタビューの例 — ユーザーが選択する UI モックアップ、レイアウト案、コンポーネント構成を提示する
• アーキテクチャの比較 — トレードオフが明確に異なる、有効なアプローチを 2～3 件並べて提示する
• フェーズ分けの戦略 — 「コア優先 vs. リスク優先 vs. 価値優先」の依存関係の流れを可視化する
• オーケストレーション戦略 — シーケンシャル、並列、ハイブリッドの各方式をタイムラインで可視化する
• テキストよりも視覚的なレイアウトのほうがトレードオフを明確にできる意思決定全般

手順：

1. references/html-guide.md のコンポーネントを使い、プロジェクトのアイデア出しディレクトリに _comparison.html（または _examples.html、_mockup.html — 一時ファイルであることを示すため、先頭に _ を付けます）を作成します
2. 各選択肢をカードまたは列で提示し、名前、説明、トレードオフ、および適切な場合は図を含めます
3. ブラウザーで開きます：open ./docs/ideation/{project-name}/_comparison.html
4. 質問文でブラウザー表示を参照し、AskUserQuestion で質問します
5. ユーザーが選択したら、一時ファイルを削除します。目的を果たしたためです

使用しない場面： 単純な「はい／いいえ」の決定、推奨案が明らかに最善である選択、またはテキストで説明したほうが早い決定。不要な視覚資料で作業の流れを遅らせないでください。

重要な注意事項

• HTML はインタラクティブな成果物専用です — 契約書と一時的な意思決定の可視化に使用します。仕様書と PRD は Markdown で作成します。
• テンプレートを作成する前に Read ツールで読み込んでください。 フェーズ 3 の前に references/html-guide.md を必ず読み、契約書を作成する前に references/contract-template.html を必ず読んでください。仕様書を作成する前に references/spec-template.md を読んでください。
• すべての質問と承認には AskUserQuestion を使用してください。 一度に質問は 1 つとし、推奨する回答を添えてください。
• 確信度は慎重に採点してください。 不確かな場合は低めに採点します。質問数に固定の上限はありません。
• HTML の成果物は作成後にブラウザーで開いてください。 open（macOS）または xdg-open（Linux）を使用します。
• ファイルは必要になってから作成してください。 先回りして作成せず、決定が確定してから作成します。
• 仕様書では既存コードのパターンを参照してください — 実際のファイルパスを使って「従うべきパターン」を記載します。
• 小規模なプロジェクトにフェーズは不要です。 コンポーネントが 1～3 個なら、仕様書は 1 つにまとめます。繰り返し可能なフェーズにはテンプレートと差分を使用します。
• 仕様書だけで完結するようにしてください — PRD や契約書を読み直さなくても実装できるだけの詳細を記載します。