技術計画の作成

注記: 現在の年は2026年です。 計画の日付付けおよび最新ドキュメントの検索時に使用してください。

spec-brainstorm は何を構築するかを定義します。spec-plan はどのように構築するかを定義します。spec-work は計画を実行します。事前のブレインストームは有用なコンテキストですが、必須ではありません — spec-plan はあらゆる入力から機能します。要件ドキュメント、バグレポート、機能アイデア、または大まかな説明から動作します。

直接呼び出されたときは、常に計画を立ててください。 直接呼び出しを「計画タスクではない」と分類してワークフローを放棄しないでください。入力が不明確な場合は、澄み渡った質問をするか計画ブートストラップ（Phase 0.4）を使用して十分なコンテキストを確立してください — ただし、常に計画ワークフロー内に留まってください。

このワークフローは耐久性のある実装計画を生成します。これはコードを実装したり、テストを実行したり、実行時の結果から学んだりするものではありません。答えがコード変更と実際の動作確認に依存する場合、それは spec-plan ではなく spec-work に属します。

ワークフロー契約概要

使用時機

望ましい成果が計画に十分明確な場合、要件ドキュメントが実装計画準備完了な場合、または既存計画が深掘り必要な場合に使用します。

使用しないとき

コードの実装、テストの実行証拠、完成ドキュメントの見直し（計画変更なし）、不明瞭なプロダクト定義（spec-brainstorm に属する）の解決、タスクパック状態の生成、または生成ランタイムアセットの書き換えに使用しないでください。

入力

機能/リクエスト説明、要件ドキュメントパス、深掘り対象の既存計画パス、バグレポート、大まかなタスク説明、または非ソフトウェア計画プロンプト。オプションでプロジェクト標準、グラフ準備状況の事実、パッケージ/テストコンテキスト、および計画コンテキストとしての近隣ソース証拠。

出力

耐久性のある計画ドキュメントまたは目標、非目標、要件、実装ユニット、ファイル/テスト参照、シーケンス、リスク、仮定、およびポスト計画ハンドオフオプションを持つインプレース計画深掘り。

成果物

適切なドキュメント場所の計画ファイル、再利用ソースドキュメントリンク、オプションのドキュメント見直し知見または計画ハンドオフ出力、および実行ランアーティファクトなし。

失敗モード

空のまたは曖昧な入力は遮断的な澄み渡った質問または計画ブートストラップが必要。失敗したリポジトリ/無読取可能なソースドキュメントは黙って無視されるのではなく表面化します。低下した標準/グラフ事実は助言のままです。実装依存の質問は spec-work に延期されます。

ワークフロー

ソースとスコープを解決し、必要なリポジトリ/研究コンテキストを収集し、計画を構造化し、必要に応じて信頼度/ドキュメント見直しチェックを実行し、適切な計画ハンドオフを提示します。

ダウンストリーム消費者

spec-write-tasks、spec-work、spec-doc-review、イシュー作成、Proof/HITL レビューパス、および人間実装レビューア。

コンテキスト方向付けアンカー

現在のユーザーリクエストまたは要件、既存の計画またはタスクパック、AGENTS.md / CLAUDE.md / プロジェクト役割ドキュメント、.spec-first/standards/project-shape.json、.spec-first/standards/standards-candidates.json、.spec-first/standards/glue-map.json、および利用可能な場合は最新標準検証結果、パッケージマニフェストおよびコマンドレジストリ、近隣実装ファイル、近隣テスト、および適用可能な場合は git diff または変更ファイルから方向付けてください。標準消費契約: confirmed -> ハード プロジェクトコンテキスト。observed / imported / suggested -> 助言的コンテキスト。conflict -> 解決またはコール アウトする計画内のリスク コンテキスト。unknown -> ユーザー/プロジェクト証拠に対する質問コンテキスト。検証が失敗した、欠落している、trust_level=degraded を報告している、consumption_boundary=advisory_only を報告している、または workspace-advisory-only を含んでいる場合は、標準アーティファクトを低下した/助言的のみとして消費してください。workspace-advisory-only に遭遇する場合、spec-standards --repo <child> を実行してユーザーに child-local 標準ベースラインを取得することを推奨できます。glue-map.json をワークフロー状態機械ではなく再利用優先実装境界に使用してください。具体的な消費例については docs/examples/standards-glue-consumption-examples.md を参照してください。その例は使用法を明確にしており、計画スコープを展開しません。外部ツールは検査を優先できますが、スコープ権限を定義しません。LLM は依然として明示的なリポジトリコンテキストとソース計画制約から候補変更サーフェスを選択します。

インタラクション方法

ユーザーに質問するときは、プラットフォームのブロッキング質問ツール（Claude Code の AskUserQuestion または Codex の request_user_input）を使用してください。必要に応じて、スキーマ読み込みが必須の場合（例：Codex 編集モード）ではなく、ハーネスにブロッキング ツールが存在しない場合またはコールがエラーになる場合のみチャット内のオプションを番号付けにフォールバックしてください。質問を黙って スキップしないでください。

一度に1つの質問をしてください。自然なオプションが存在する場合は、簡潔な単一選択を優先してください。

機能説明

<feature_description> #$ARGUMENTS </feature_description>

上記の機能説明が空の場合は、ユーザーに尋ねてください： 「計画を立てたいのは何ですか? 頭に思い浮かんだタスク、目標、またはプロジェクトについて説明してください。」 その後、続行する前にユーザーの回応を待ってください。

入力が存在しているが不明確またはunderspecified の場合は、放棄しないでください — 1つまたは2つの澄み渡った質問をするか、Phase 0.4 の計画ブートストラップに進んで十分なコンテキストを確立してください。目標は常にユーザーが計画を立てるのを助けることであり、ワークフローを終了することではありません。

重要: 計画ドキュメント内のすべてのファイル参照は repo-relative パス（例：src/models/user.rb）を使用する必要があります。絶対パス（例：/Users/name/Code/project/src/models/user.rb）は使用しないでください。これはあらゆる場所に適用されます — 実装ユニット ファイル リスト、パターン参照、オリジン ドキュメント リンク、および散文メンション。絶対パスはマシン、ワークツリー、およびチームメイト間でポータビリティを破壊します。

コア原則

1. 要件を信頼の源として使用する - spec-brainstorm が要件ドキュメントを生成した場合、計画は動作を再発明するのではなく、それから構築する必要があります。
2. 決定、コードではない - アプローチ、境界、ファイル、依存関係、リスク、およびテストシナリオをキャプチャしてください。実装コードまたはシェルコマンド構成を事前に書かないでください。高レベルの技術設計を伝えるのに役立つ場合は、疑似コードスケッチまたはDSLグラマーは歓迎されます — ただし、それらは実装コードではなく方向的ガイダンスとして明示的にフレーム化される必要があります。
3. 構造化する前に調査する - 計画を最終化する前に、コードベース、制度的な学習、および外部ガイダンスを調査してください。
4. 成果物をサイズ適切にする - 小さい作業はコンパクト計画を取得します。大規模な作業はより多くの構造を取得します。哲学はすべての深さで同じままです。
5. 計画から実行発見を分離する - ここで計画時の質問を解決してください。実装時の不確実性を明示的に実装に延期してください。
6. 計画をポータブルに保つ - 計画はツール固有のエグゼキューター命令を埋め込まずに、生きたドキュメント、レビュー成果物、またはイシュー本文として動作する必要があります。
7. 重要な場合は実行姿勢を軽く保つ - リクエスト、オリジン ドキュメント、またはリポジトリ コンテキストが明確にテストファースト、特性化ファースト、または別の非デフォルト実行姿勢を示唆する場合、計画にその軽量信号を反映してください。計画をステップバイステップ実行構成に変えないでください。
8. ユーザー命名リソースを尊重する - ユーザーが特定のリソース — CLI、MCP サーバー、URL、ファイル、ドキュメント リンク、または事前成果物 — を命名する場合、それを提案ではなく権限のある入力として扱ってください。未知の場合は、それを発見してください（command -v、取得、読み取り）から利用不可能であると仮定する前に。それを一般的な代替物の代わりに使用してください。それが失敗するまたは存在しない場合は、黙って置き換えるのではなく、それを明示的に言ってください。

計画品質バー

すべての計画に含めるべき:

• 明確な問題フレームとスコープ境界
• リクエストまたはオリジン ドキュメントへの具体的な要件トレーサビリティ
• 提案された作業に対する Repo-relative ファイル パス（絶対パスは使用しません — 計画ルール参照）
• 機能ベアリング実装ユニットの明示的なテスト ファイル パス
• 決定とそのロジック（単なるタスク以上）
• 従うべき既存のパターンまたはコード参照
• 各機能ベアリング ユニットの列挙されたテスト シナリオ（実装者が計画変更を発明することなく正確に何をテストするかを知っている十分に具体的）
• 明確な依存関係とシーケンス

計画が準備完了なのは、実装者が計画を作成する際に計画を作成する必要がなく、自信を持って開始できるときです。

ワークフロー

Phase 0: 再開、ソース、およびスコープ

0.1 適切な場合に既存計画作業を再開

ユーザーが既存の計画ファイルを参照するか、docs/plans/ に明らかに最近の一致する計画がある場合：

• それを読む
• 既存計画を再開する場合
• 更新する場合、依然として関連するセクションのみを修正します。計画はユニット毎の進捗状態を運ばない — 進捗は spec-work により git から導出されるため、編集全体で保存する進捗はありません

深掘り意図: 計画に関連して「deepen」（または「deepening」）という言葉は、深掘りファスト パスの主なトリガーです。ユーザーが「deepen the plan」「deepen my plan」「run a deepening pass」または類似の言葉を言う場合、目標ドキュメントは要件ドキュメントではなく docs/plans/ の計画です。ユーザーが提供するパス、キーワード、またはコンテキストを使用して適切な計画を特定してください。パスが提供される場合、それが実際に計画ドキュメントであることを確認してください。マッチが明らかでない場合は、続行する前にユーザーに確認してください。

「strengthen」「confidence」「gaps」「rigor」のような言葉は、単独では深掘り意図を トリガー するのに十分ではありません。これらの言葉は通常の編集リクエストに表示されます（「その図についてのセクションを強化する」「テスト シナリオにはギャップがある」）、全体的な深掘り パスを引き起こすべきではありません。リクエストが明確に全体として計画をターゲットし、特定のセクションまたはコンテンツ領域を命名しない場合のみそれを深掘り意図として扱ってください — そして、続行する前にユーザーに確認することを優先してください。

計画が特定され、完全に見える場合（すべてのメジャー セクション存在、実装ユニット定義済、status: active）:

• 計画に YAML frontmatter が不足している場合（非ソフトウェア計画は frontmatter の代わりに単純な # Title 見出しに Created: 日付を使用します）、Phase 5.3 の代わりに references/universal-planning.md にルーティングして編集または深掘りしてください。非ソフトウェア計画はソフトウェア信頼度優先チェックを使用しません。
• そうでない場合、対話モードで Phase 5.3（信頼度優先チェックと深掘り）へのショートカット。これは完全な計画ワークフローの再実行を回避し、ユーザーにどの知見を統合するかをコントロール与えます。

通常の編集リクエスト（例：「テスト シナリオを更新する」「新しい実装ユニットを追加する」「リスク セクションを強化する」）はファスト パスをトリガーすべきではありません — それらは標準的な再開フロー に従います。

計画に既に deepened: YYYY-MM-DD frontmatter フィールドがあり、再深掘りの明示的なユーザー リクエストがない場合、ファスト パスは依然として同じ信頼度ギャップ評価を適用します — 深掘りを強制しません。

0.1b タスク領域を分類

タスクがソフトウェアの構築、変更、またはアーキテクチャ化に関連する場合（コード、リポジトリ、API、データベース、または構築/変更/デプロイするリクエストを参照する場合）、Phase 0.2 に進みます。

ドメインが本当に曖昧な場合（例：他のコンテキストなしで「計画を立てるマイグレーション」）、ルーティング前にユーザーに尋ねてください。

それ以外の場合は、references/universal-planning.md を読んで、代わりにそのワークフローに従ってください。すべての後続フェーズをスキップしてください。命名されたツールまたはソースリンクはこのルーティングを変更しません — それらは Core Principle 8 で処理される入力です。

0.2 上流要件ドキュメントを検索

計画に質問をする前に、docs/brainstorms/ で *-requirements.md に一致するファイルを検索してください。

関連基準: 要件ドキュメントは以下の場合に関連しています:

• トピックが機能説明と意味的に一致する
• 過去30日以内に作成された（ドキュメントが明らかにまだ関連または明らかに古い場合は判断をオーバーライドする）
• 同じユーザー問題またはスコープをカバーしているとして見える

複数のソースドキュメントが一致する場合は、利用可能な場合はプラットフォームのブロッキング質問ツールを使用してどのドキュメントを使用するかを尋ねてください（インタラクション方法参照）。そうでない場合は、チャット内で番号付けオプションを提示し、続行する前にユーザーの返答を待ってください。

0.3 ソースドキュメントを主入力として使用

関連する要件ドキュメントが存在する場合:

1. それを徹底的に読む
2. それが計画のオリジン ドキュメントとして機能することを発表する
3. 以下のすべてを引き継ぐ:
   • オリジン frontmatter に spec_id が含まれている場合はそれを保有します。計画 frontmatter でそれを正確に保持してください。それはこのスペック チェーンのクロス成果物 アイデンティティです。
   • 問題フレーム
   • アクター（A-ID）、主要フロー（F-ID）、および受け入れ例（AE-ID）存在する場合 — 実装ユニットが尊重する必要がある制約として保持します
   • 要件と成功基準
   • スコープ境界（「後で延期」および「このプロダクトのアイデンティティ外」サブセクション存在する場合を含む）
   • 主要な決定とロジック
   • 依存関係または仮定
   • 未解決の質問、ブロッキング または延期かどうかを保持
4. ソースドキュメントを計画および研究への主入力として使用する
5. オリジン ドキュメント内のセクションまたコンテクストで重要な決定を参照してください。(see origin: <source-path>)
6. ソース コンテンツを黙って省略しないでください — オリジン ドキュメントが議論した場合、計画はそれに短く対処する必要があります。最終化する前に、オリジン ドキュメントの各セクションをスキャンして、何も削除されていないことを確認してください。

オリジン要件ドキュメントが spec_id のない従来ドキュメントの場合、デフォルトではオリジンを編集しないでください。新しい計画ローカル spec_id を生成し、オリジン アイデンティティが継承されなかったことを計画内に記述し、要件から計画へのリンクを弱いトレースとして扱ってください。ユーザーが明示的にオリジン要件ドキュメントをバックフィルするよう要求する場合、それを別の範囲付き編集として処理してください。

関連する要件ドキュメントが存在しない場合、計画はユーザーのリクエストから直接進行できます。

0.4 計画ブートストラップ（要件ドキュメントまたは不明確な入力なし）

関連する要件ドキュメントが存在しない場合、または入力がより多くの構造が必要な場合:

• リクエストが直接技術計画に十分明確であるかどうかを評価する — その場合は Phase 0.5 に進みます
• 曖昧性が主にプロダクト フレーミング、ユーザー動作、またはスコープ定義である場合、spec-brainstorm を提案として推奨してください — ただし常にここで続行することも提供してください
• ユーザーがここで続行したい場合（または既に計画を望んでいることを明示的だった場合）、以下の計画ブートストラップを実行してください

計画ブートストラップは以下を確立すべき:

• 問題フレーム
• 意図された動作
• スコープ境界と明らかな非目標
• 成功基準
• ブロッキング質問または仮定

このブートストラップを簡潔に保ってください。直接入力の便利さを保存するために存在し、完全なブレインストームを置き換えるためではありません。

ブートストラップが未解決の大きなプロダクト質問を発見する場合:

• spec-brainstorm を再度推奨してください
• ユーザーがまだ続行したい場合、続行する前に明示的な仮定が必要です

ブートストラップが別のワークフローがユーザーをより良く機能することが明らかにする場合:

• バグ形状のプロンプト（ユーザーが壊れた動作、エラー メッセージ、回帰、または「機能しない」について説明している）— spec-debug をルート アウト オプションとして呼び出し、バグ サーフェスが現在のリポジトリまたは命名されたローカル リポジトリ パスで到達可能な場合は spec-plan を続行するオプションとして呼び出します。命名されたコードをローカルに見つけられない場合、spec-plan に留まります。ペーパー計画は到達不可能なサーフェスのための唯一の有用な出力かもしれません。

  バグが別のローカル パスにある場合、計画ワークフロー前に任意のクロス リポジトリ調査を発表してください。どのパスが読まれ、計画出力がどこに着地するかを発表します。ターゲット リポジトリは、ユーザーがリダイレクトしない限り、調査と計画作成の両方について デフォルトです。クロス リポジトリ ターゲット場所とワークフロー選択は別の決定です。間違ったリポジトリに計画を黙って書き込まないでください。

  ヘッドレス モードでは、ルート アウト メニューをスキップし、spec-plan で続行してください。自動ルーティング デバッグに入ることは、同期ユーザー 承認なしでワークフローを変更することになります。

• 実行準備完了の明確なタスク（既知のルート原因、明白な修正、アーキテクチャ上の決定なし）— spec-work を計画を続行するオプションとしてサイド バイ サイドで高速代替として提案します。ユーザーが決定します。

0.5 計画前に未解決の質問を分類

オリジン ドキュメントに「計画前に解決」または類似のブロッキング質問が含まれている場合:

• 続行する前に各を見直す
• ブロッキング質問の場合のみ、それが実際に技術的、建築的、または調査質問である場合に、それを計画保有作業に再分類します
• プロダクト動作、スコープ、または成功基準を変更する場合、ブロッカーとして保有してください

本当のプロダクト ブロッカーが残る場合:

• それらを明確に表面化する
• 利用可能な場合はプラットフォームのブロッキング質問ツール（インタラクション方法参照）を使用してユーザーに尋ねる:
  1. spec-brainstorm を再開してそれらを解決する
  2. それらを明示的な仮定または決定に変換して続行する
• 本当のブロッカーが未解決のままある間は計画を続行しないでください

0.6 計画深さを評価

作業を以下の計画深さのいずれかに分類:

• 軽量 - 小さい、明確に囲まれた、低い曖昧性
• 標準 - 通常の機能または何らかの技術上の決定を文書化が必要な囲まれたリファクタ
• 深い - クロスカッティング、戦略的、高いリスク、または高い曖昧性の実装作業

深さが不明確な場合、1つのターゲット質問をして続行します。

0.7 ソロ モード スコープ サマリー

停止。要約を構成する前に references/synthesis-summary.md を読んでください。 規律ルール、散文サマリー要件、3 バケット構造、アンチパターン ガイダンス、soft-cut 動作、自己リダイレクト サポート、ソロバリアント コンテンツ フォーカス、および計画セクションへのルーティングがすべてそこに住んでいます。

Phase 0.4 ブートストラップの後および Phase 1 研究が始まる前に、エージェントのエージェント スコープの合成をユーザーに表示してください。これは誤ったスコープで研究とサブエージェント注意を費やすことから保護します。

すべてのガードが真の場合のみ発火します:

• Phase 0.2 は上流のブレインストーム ドキュメントを見つけませんでした
• Phase 0.4 は debug、work、またはユニバーサル計画へのルーティングではなく spec-plan に留まりました
• Phase 0.5 は未解決のブロッカーなしで消去されました
• 実行は再開ノーマル または深掘りインテント などの Phase 0.1 ファスト パスではありません

brainstorm-sourced 呼び出しのための Phase 0.7 をスキップしてください。それらは研究後の Phase 5.1.5 を使用します。ヘッドレス モードでは、合成を構成しますがユーザー確認を求めないでください。Phase 1 研究に進み、その後、推論された賭けを計画作成時に ## Assumptions にルーティングしてください。

Phase 1: コンテキストの収集

1.1 ローカル研究（常に実行）

研究エージェントへの入力として渡す簡潔な計画コンテキスト サマリー（段落1〜2程度）を準備してください:

• オリジン ドキュメントが存在する場合、そのドキュメントから問題フレーム、要件、および主要な決定を要約してください
• それ以外の場合は機能説明を直接使用してください

計画研究エージェントは読み取り専用です。ホスト機能が存在する場合、直接計画ワークフロー呼び出しはこの文書化された研究フェーズを認可します。サブエージェント確認を求めないでください。利用可能な場合はアクティブ ホストのエージェント ディスパッチ プリミティブを使用し（spawn_agent を含む）、権限モード オーバーライドを省略し、ディスパッチを命名された研究エージェントに制限してください。Codex だけの理由で機能を低下させないでください。

ディスパッチが利用不可、明示的に無効、または容量以外の理由で失敗する場合、対応する エージェント プロファイルを読んで、現在のエージェント内で明示的なフォールバックとして適用することにより、同じ研究をシーケンシャルで実行してください。計画生成は研究ディスパッチが利用不可の場合でも完了する必要があります。ディスパッチはレイテンシとコンテキスト分離を改善し、正確性ではありません。

以下の読み取り専用研究エージェントを利用可能な場合は並列でディスパッチするか、明示的なシーケンシャル/インライン フォールバックを実行:

• spec-repo-research-analyst — スコープ: テクノロジー、アーキテクチャ、パターン。入力: {計画コンテキスト サマリー}。
• spec-learnings-researcher — 入力: {計画コンテキスト サマリー}。 以下を収集:
• テクノロジー スタックとバージョン（セクション 1.2 でより鮮明な外部研究決定を行うために使用）
• 従うべきアーキテクチャ パターンおよび規則
• 実装パターン、関連ファイル、モジュール、およびテスト
• 計画に材料的に影響する AGENTS.md ガイダンス、互換性フォールバックとしてのみ存在する場合は CLAUDE.md を使用
• docs/solutions/ からの制度的学習

Slack コンテキスト （オプトイン） — 自動ディスパッチしないでください。条件によってルーティング:

• 利用可能なツール + ユーザーが尋ねた: spec-slack-researcher をディスパッチしてください。オリジン ドキュメントに Slack コンテキスト セクションがある場合は、ユーザーがギャップに焦点を当てるように逐語的に渡してください。統合に知見を含めてください。
• 利用可能なツール + ユーザーが尋ねなかった: 出力で以下を注釈してください: 「Slack ツールが検出されました。いつでも組織コンテキストについて Slack を検索するよう言ってください、または次のプロンプトにそれを含めてください。」
• ツール なし + ユーザーが尋ねた: 出力で以下を注釈してください: 「Slack コンテキストが要求されましたが、利用可能な Slack ツールはありません。Slack プラグインをインストールおよび認証して組織コンテキスト検索を有効にしてください。」

1.1a グラフ準備状況の事実（オプション、制限あり）

現在の cwd が複数の子 Git リポジトリを含む非 Git 親ワークスペースの場合、最初に意図されたプロジェクト ターゲットを解決してください。単一リポジトリ計画は、グラフ準備状況を読む前にワークスペース相対子パスを使用して上位レベル target_repo を命名する必要があります。クロス リポジトリ計画は、ワークスペース全体の書き込みスコープを暗示するのではなく、実装ユニットごとに target_repo を命名する必要があります。利用可能なアクティブ リポジトリまたは明示的なクロス リポジトリ スコープがない場合、計画作成前にユーザーに子リポジトリ間で意味的に選択するよう要求してください。スクリプトまたはグラフ事実が意味的に子リポジトリ間で選択することを許可しないでください。

親ワークスペース読み取り専用計画質問の場合は、利用可能な場合は助言的 workspace-graph-targets.v1 事実を消費するか、読み取り専用ワークスペース グラフ ターゲット リゾルバを実行してそれらを生成します。primary 子を GitNexus 優先証拠の制限付き候補リポジトリとして扱い、degraded-fallback 子を制限付きでのみ含め、stale、dirty-uncertain、setup-ready-bootstrap-required、および unavailable 子を計画が明示的に低下した フォールバックを記録する場合を除き、プライマリ証拠から除外してください。LLM は依然として明示的なリポジトリ コンテキストおよび証拠からセマンティック ターゲット リポジトリを選択します。リゾルバは決定的な準備状況事実のみを供給します。コード編集、テスト、変更ログ更新、またはコミットをリード可能な任意の実装計画は、計画またはユニット レベルで target_repo を命名する必要があります。

標準的なグラフ準備状況アーティファクトが存在するかどうかを確認:

• .spec-first/graph/graph-facts.json
• .spec-first/impact/bootstrap-impact-capabilities.json

両方のアーティファクトが存在する場合、記録された準備状況事実をコンパイルされた準備状況事実として読んでから、グラフ証拠をどの程度信頼するかを決定します。記録された source_revision および worktree_dirty を現在のリポジトリ スナップショットと比較してください。いずれかが現在のスナップショットと異なる場合、グラフ事実を stale として報告し、それらを現在のプライマリ証拠として扱わないでください。

いずれかのアーティファクトを有効な JSON として読み込めない場合、グラフ準備状況を理由 invalid-json で blocked として扱い、Graph Readiness ブロック内に正確なアーティファクト パスおよび解析/読み取りエラーを命名し、ライブ MCP 証拠または制限付きダイレクト リポジトリ読み取りで計画を続行してください。グラフ アーティファクトを spec-plan から書き換え、削除、または黙って再生成しないでください。決定的な修復は spec-graph-bootstrap / spec-mcp-setup に属します。

アーティファクトが存在しない、ブロックされている、setup-not-ready、stale、または degraded の場合、計画は続行します。制限付きダイレクト リポジトリ読み取りに完全にフォール バックする前に、関連する MCP ツールが現在のセッションに読み込まれていて、計画質問がそれから利益を得る場合は、ライブ MCP 証拠を試してください。GitNexus の場合、これは gitnexus_query、gitnexus_context または gitnexus_impact などの MCP ツールを呼び出して具体的な計画質問を呼び出し、成功した応答をセッション ローカル証拠として扱うことを意味します。ライブ GitNexus が definitions を返しても processes / process_symbols がない場合は、runtime_mcp_evidence: partial-definitions-only を記録してください。それらの定義をローカル ファイル/シンボル ポインタとしてのみ使用し、その後 code-review-graph、Serena、または制限付きダイレクト リポジトリ読み取りで補足してください。成功または部分的なライブ MCP 呼び出しは、コンパイルされた query_ready を変更しません。.spec-first/graph/graph-facts.json を現在にしません。計画グラフ準備状況として書き込まれるべきではありません。MCP ツールが利用不可、失敗、またはプロバイダー ステータスが graph_ready=false / provider-crash を報告する場合、そうしてください。制限付きダイレクト リポジトリ読み取りおよび必要に応じたローカル研究を使用します。グラフ準備状況は証拠コンテキストであり、計画ゲートではありません。

生成された計画で、Context & Research の前に機械テスト可能な Graph Readiness ブロックを含めてください:

## Graph Readiness

- target_repo:
- status: primary | degraded-fallback | stale | blocked | setup-not-ready | unavailable
- source_revision:
- current_revision:
- stale:
- primary_providers:
- degraded_providers:
- fallback_capabilities:
- runtime_mcp_evidence:
- confidence:
- limitations:

標準的なアーティファクトが欠落している場合は status: unavailable を使用してください。degraded-fallback の場合、使用可能なプライマリ プロバイダー、フォールバック機能、および成功した、部分的な、または失敗したライブ MCP 証拠を制限付きで述べてください。blocked または setup-not-ready の場合は、事実を報告し、ツールが実際に応答する場合のみライブ MCP 証拠を使用します。それ以外の場合は、可能な場合は制限付きダイレクト リポジトリ読み取りを使用します。これをコンテキスト選択、インパクト分析、レビュー証拠、またはタスクレベル アーティファクトに展開しないでください。

1.1b 実行姿勢信号を検出

計画が軽量実行姿勢信号を運ぶべきかどうかを決定してください。

以下のような信号を探してください:

• ユーザーが明示的に TDD、テストファースト、または特性化ファーストの作業をリクエストする
• オリジン ドキュメントはテストファースト実装または従来コードの探索的硬化を要求している
• ローカル研究は対象領域が従来、弱くテストされた、または歴史的に脆弱であることを示し、動作変更前の特性化カバレッジを示唆しています

信号が明確な場合は、関連する実装ユニット内でそれを黙って運んでください。

姿勢がシーケンスまたはリスクを材料的に変更し、責任を持って推論できない場合にのみユーザーに尋ねてください。

1.2 外部研究を決定

オリジン ドキュメント、ユーザー信号、およびローカル知見に基づいて、外部研究が価値を追加するかどうかを決定してください。

行間を読んでください。 これまでの会話から信号に注意を払ってください:

• ユーザー精通度 — 特定のファイルまたはパターンを指していますか? 彼らはおそらくコードベースをよく知っています。
• ユーザー意図 — 速度または徹底性を望んでいますか? 探索または実行ですか?
• トピック リスク — セキュリティ、支払い、外部 API はユーザー信号に関係なく、より多くの注意保証されます。
• 不確実性レベル — アプローチは明確ですか、それともまだオープン エンドですか?

spec-repo-research-analyst のテクノロジー コンテキストを活用:

spec-repo-research-analyst 出力には、構造化されたテクノロジーとインフラストラクチャのサマリーが含まれます。より鮮明な外部研究決定を行うために使用してください:

• 特定のフレームワークとバージョンが検出された場合（例：Rails 7.2、Next.js 14、Go 1.22）、それらの正確な識別子を spec-framework-docs-researcher に渡し、バージョン固有のドキュメントを取得します
• フィーチャーがリポジトリにおいて確立されたテクノロジー層に関連する場合（例：新しい背景ジョブを計画するときの既存の Sidekiq ジョブ）、外部研究をスキップすることを優先してください — ローカルパターンは十分でしょう
• フィーチャーが検出された不在または薄いテクノロジー層に関連する場合（例：新しい gRPC サービスを計画するときにプロトファイルが存在しない）、外部研究を優先してください — 従うべきローカルパターンはありません
• スキャンがデプロイメント インフラストラクチャ（Docker、K8s、serverless）を検出した場合、計画コンテキストがダウンストリーム エージェントで記述してください。デプロイメント制約を説明できるように。
• スキャンがモノリポを検出し、特定のサービスにスコープされた場合、そのサービスのテク コンテキストをダウンストリーム 研究エージェントに渡してください — すべてのサービスの集計ではなく。スキャンが特定のスコープなしでワークスペース マップを表示した場合、機能説明を使用して関連するサービスを特定してから、研究を進めてください

常に外部研究を優先:

• トピックが高リスク: セキュリティ、支払い、プライバシー、外部 API、マイグレーション、コンプライアンス
• コードベースが関連するローカル パターンを欠落 — この計画が必要なパターンの直接例が 3 個未満
• 隣接領域のローカル パターンは存在するが、正確な領域には存在しない — 例：コードベースには HTTP クライアントはあるが、webhook レシーバーはない、または背景ジョブはあるがイベント駆動型 pub/sub はない。隣接パターンはチームがテクノロジー層に満足していることを示唆しますが、ドメイン固有の落とし穴は知らないかもしれません。この信号が存在する場合、外部研究クエリを一般的なテクノロジーではなくドメイン ギャップの周辺に具体的にフレーム化してください
• ユーザーが不慣れな領域を探索している
• テクノロジー スキャンで関連するレイヤーがコードベースに不在または薄い

外部研究をスキップ:

• コードベースは既に強いローカルパターンを示す — 直接例が複数（隣接ドメインではなく）、最近タッチ、現在の規則に従う
• ユーザーは既に意図された形を知っている
• 追加の外部コンテキストは実用的な価値をほとんど追加しません
• テクノロジー スキャンで関連するレイヤーがしっかり確立されていて、従うべき既存の例がある

決定を簡潔に発表してから続行してください。例:

• 「あなたのコードベースはこのための堅実なパターンを持っています。外部研究なしで進めています。」
• 「これは支払い処理に関与しているため、最初に現在のベストプラクティスを調査します。」

1.3 外部研究（条件付き）

Step 1.2 が外部研究が有用であることを示す場合、利用可能な場合は以下の読み取り専用エージェントを並列でディスパッチするか、現在のエージェント内で順序立てた/インラインで実行:

• spec-best-practices-researcher — 入力: {計画コンテキスト サマリー}。
• spec-framework-docs-researcher — 入力: {計画コンテキスト サマリー}。

1.4 研究を統合

以下を要約:

• 関連するコードベース パターンおよびファイル パス
• 関連する制度的学習
• 収集された場合、Slack の会話からの組織コンテキスト（フィーチャーに関連する以前の議論、決定、またはドメイン知識）
• 外部参照およびベストプラクティス（収集された場合）
• 関連するイシュー、PR、または以前のアート
• 計画を材料的に形作るべき制約

1.4b 外部契約サーフェスが明らかになった場合は深さを再分類

現在の分類が軽量で、Phase 1 研究がこれらの外部契約サーフェスのいずれかに触れることが判明した場合は、標準に再分類:

• 外部システム、CI、または他のリポジトリにより消費される環境変数
• エクスポートされたパブリック API、CLI フラグ、またはコマンド ラインインターフェース契約
• CI/CD 設定ファイル（.github/workflows/、Dockerfile、デプロイメント スクリプト）
• ダウンストリーム コンシューマーによってインポートされた共有タイプまたはインターフェース
• 外部 URL またはリンク他のシステムからリンクされたドキュメント

これにより、フロー分析（Phase 1.5）が実行され、信頼度優先チェック（Phase 5.3）が重要なセクション ボーナスを適用することが保証されます。再分類を簡潔に発表してください: 「標準に再分類 — この変更は [環境変数 / エクスポートされた API / CI 設定] に関連する外部コンシューマーを含みます。」

1.5 フローおよびエッジケース分析（条件付き）

標準または深い計画の場合、またはユーザー フロー完全性がまだ不明瞭な場合は、利用可能な場合は読み取り専用フロー アナライザーをディスパッチするか、現在のエージェント内で同じ分析をシーケンシャル/インラインで実行:

• spec-spec-flow-analyzer — 入力: {計画コンテキスト サマリー、研究知見}。

出力を以下に使用:

• 欠落したエッジケース、状態遷移、またはハンドオフ ギャップを識別する
• 要件トレースまたは検証戦略を強化する
• 計画を材料的に改善するフロー詳細のみを追加する

Phase 2: 計画質問を解決

計画質問リストを以下から構築:

• オリジン ドキュメント内の延期質問
• リポジトリまたは外部研究で発見されたギャップ
• 有用な計画を生成するために必要な技術上の決定

各質問について、以下のいずれかであるかどうかを決定:

• 計画中に解決 - 回答はリポジトリ コンテキスト、ドキュメント、またはユーザー選択から知得可能
• 実装に延期 - 回答はコード変更、ランタイム動作、または実行時発見に依存

回答がアーキテクチャ、スコープ、シーケンス、またはリスクに材料的に影響し、責任を持って推論できない場合のみ、ユーザーに尋ねてください。利用可能な場合はプラットフォームのブロッキング質問ツール（インタラクション方法参照）を使用してください。

このフェーズでテストを実行したり、アプリをビルドしたり、ランタイム動作をプローブしたりしないでください。 目標は強力な計画を生成することであり、部分的な実行ではありません。

Phase 3: 計画を構造化

3.1 タイトルおよびファイル命名

• 従来の形式（feat: Add user authentication または fix: Prevent checkout double-submit など）を使用して、明確で検索可能なタイトルを作成してください
• 計画タイプを決定: feat、fix、または refactor
• リポジトリ規則に従ってファイル名を構築: docs/plans/YYYY-MM-DD-NNN-<type>-<descriptive-name>-plan.md
  • docs/plans/ が存在しない場合は作成してください
  • 既存ファイルを本日の日付について確認して、次の順序番号を決定してください（ゼロパディング 3 桁、001 から開始）
  • 説明名を簡潔に保つ（3～5 語）および kebab-cased
  • 例: 2026-01-15-001-feat-user-authentication-flow-plan.md、2026-02-03-002-fix-checkout-race-condition-plan.md
  • 回避: 欠落した順序番号、「new-feature」のような曖昧な名前、無効な文字（コロン、スペース）
• 計画 frontmatter spec_id を設定:
  • 計画が spec_id を持つオリジン要件ドキュメントを持つ場合、計画ファイル名も <type> を含みますが、その値を正確に継承してください。
  • オリジン要件ドキュメントが従来で spec_id を欠落している場合、計画ファイル名シーケンスと slug から計画ローカル spec_id を生成し、オリジン アイデンティティが継承されなかったことを問題フレーム内またはコンテキスト & 研究内に述べてください。
  • オリジン ドキュメントがない場合、計画ファイル名シーケンスと slug から新しい spec_id を生成してください。
  • 新しい spec_id を鋳造する前に、docs/brainstorms/、docs/plans/、および docs/tasks/ frontmatter をスキャンしてください。同じ spec_id が既に存在し、origin / source_plan リンクはそれが同じ spec チェーンに属することを証明しない場合、ローカル シーケンスをインクリメントするか、ユーザーに確認するよう依頼してください。
  • 通常の編集、計画深掘り、タスク パック再構築、および作業/レビュー ハンドオフ全体で spec_id を保持してください。代替実装計画、独立した配信チェーン、または同じオリジンからの放棄置換作業の場合、既存の spec_id を継承するか新しい spec チェーンを作成するかを決定し、計画内の理由を記録してください。

3.2 ステークホルダーおよび影響認識

標準または深い計画の場合、この変更の影響を受ける人（エンドユーザー、開発者、オペレーション、他のチーム）および計画の形成方法を簡潔に検討してください。クロスカッティング作業の場合は、System-Wide Impact セクション内に影響を受けたパーティを記録してください。

3.3 作業を実装ユニットに分割

作業を論理実装ユニットに分割してください。各ユニットは、実装者が通常アトミック コミットとして着地できる1つの意味のある変更を表すべきです。

良いユニット:

• 1つのコンポーネント、動作、またはインテグレーション シームに焦点を当てている
• 通常関連ファイルの小さなクラスターに触れている
• 依存関係によってオーダーされている
• 事前コード記述なしで実行するのに十分に具体的

回避:

• 2～5 分の マイクロステップ
• 複数の無関係な懸念にまたがるユニット
• 実装者が計画を再度発明する必要がある ほど曖昧なユニット

各ユニットは、Phase 3.5 で割り当てられた安定した計画ローカル U-ID を保有します（U1、U2、…）。U-ID は再順序付け、分割、削除全体で生