plan-it は何をしますか？
漠然とした要求→出荷可能なデリバリーパッケージに変換します。 これは計画指揮者であり、/build-itが始まるところで正確に終了するライフサイクルの規律ある前半部分です。ディスカバリー（現場の真実を調査）、スペック（設計ドキュメントを作成）、アジャイル分割（PRD、エピック、テスト、共有コントラクト）を実行し、引き継ぎます。
/plan-it ─────────────► docs/ + delivery/ ─────────────► /build-it
(ディスカバリー → 仕様 → 計画) (構築可能なパッケージ) (構築する)
人間が直接使用することも、新しい要求を受け取り、ワーカーを派遣する前にデリバリーパッケージに変換する必要がある任意のオーケストレーションコンダクターエージェントが使用することもできます。
5つの絶対ルール（単なる提案ではなく、強制すること）
これらは、すべての成功した実行から逆工学された耐荷重ルールです。1つでも違反すると、下流のビルドが逸脱するか、静かに失敗します。
-
並行計画の前に、共有CONTRACTを凍結する。 CONTRACTは法律です：正規エンティティ、スキーマ、API/インターフェース、列挙型、リポジトリ/ブランチマップ、および「出荷」の定義。チームはそれに従って記述し、横断的な発見は日付入りの修正（v1.0→v1.1…）としてそこにフィードバックします。凍結されたコントラクトなし→並行チームなし。
-
人間のみが決定できる判断を1つのゲートにバッチする。 不可逆的なこと（リポジトリトポロジ、ホスティング、製品名、アーキテクチャモード、自作か購入か）を事前に決定しないでください。それぞれに推奨事項を添えて一緒に提示し、人間に番号で回答させます。このゲートでは、人間がビジョンを注入します—単にオプションを選ぶだけではありません—あなたが提案しなかった概念を追加する余地を残してください。各回答を責任者 + 日付でロックします。
-
エージェントの出力をディスク上で検証する—「アイドル≠デリバリー済み」。 チームがアイドル状態になったとしても、ファイルを書き込んだことを意味しません。ファンアウト後、実際のパスが存在し、空でないことを確認してから進めてください。チームが出力をメッセージとして保持していた場合、正確な絶対パスに
Writeするよう指示してください。「完了」を決して信じないでください。 -
凍結前に、リポジトリではなく、実稼働システムに対して計画を接地する。 実行中のシステムに触れる計画の場合、リポジトリは仮説であり、デプロイされた現実が真実であり、それらは乖離します。CONTRACTを凍結する前に、実際のシステムに対して検証し、観測結果を（リポジトリから推測した推測ではなく）書き込みます。実戦で検証済み：あるプログラムでは、すべての途中修正がリポジトリから推測された仮定に実際が矛盾したことに起因していました—間違った正規識別子（マニフェストがデプロイ済みカタログから乖離していた）、存在するが死んだホストを指している設定値、「構築予定」のコンポーネントがすでにデプロイされていた、見つかった資格情報が間違っていた。具体的なチェックについては、フェーズ3の実稼働接地ゲートを参照してください。
-
散文ではなく、機械を実行する。 パイプラインの制御フローは
machine.json（明示的なステートチャート）に存在し、このドキュメントにはありません—この散文は機械を説明します。呼び出し時に、.plan-it/state.json（ターゲットプロジェクト内）を読み込むか初期化し、そのstateから再開します；すべての**遷移**でそれを書き込みます。各ガード付き遷移で、ガードのマップされたサブコマンド（node scripts/gate-check.mjs …）を実行し、**ゼロ以外の終了コードでは決して進行しない**—修正、再実行、そして遷移します。Nodeが利用できない場合は、同じチェックを手動で実行し、状態ファイルに記録します（劣化させ、決して壊さない）。完全なプロトコル：references/machine.md`。
決定論的コア（v2）—なぜ機械なのか
散文として書かれた制御フロー（「ステップ1を実行、ゲートを決してスキップしない」）は、決定論の文献では散文制御フローと呼ばれます：長く要約されやすいコンテキストをまたいだモデルの規律に依存し、時にはモデルがそれに従わないことがあります。v2はそれを適切な高度で反転させます—エッジでの非決定論、コアでの決定論：
machine.json— XState v5互換のパイプラインのステートチャート：15の状態、3つの人間ゲート（meta.gate+meta.human）、ガード付き遷移、parallelPlanning上のAMENDMENT自己ループ。stately.ai/vizに貼り付けて表示できます。.plan-it/state.json— 永続化された実行：現在の状態、ゲート承認（責任者+日付）、コントラクトバージョン、検証済みアーティファクトレジストリ、履歴。これにより、実行がクラッシュや新しいセッションでも存続します。scripts/gate-check.mjs— 終了コードとしてのガード：verify（ルール3、アイドル≠デリバリー）、freeze（ルール1、コントラクトなし→チームなし）、handoff（プレイブック§Fの機械化可能な半分）、state（ルール2、記録されたゲート）、adversary（ルール6/D4—障害モード深度：モデル化された機械は5つのカスケードクラスをカバーまたは放棄しなければなりません；線形ワークフローには該当なし）。LINT_CLEANおよびADVERSARY_CLEAN遷移（verify→adversaryGate→handoff）は最後の2つをゲートします。
あいまいなフェーズ—ディスカバリー、統合、スペック作成、判断—はLLM-at-the-node（マシン内でllmAtTheNodeとタグ付け）のままにします。それらを形式化しないでください；モデリングは、混乱を置き換える場合にのみ儀式となります。詳細、状態ファイルスキーマ、再開プロトコル：references/machine.md。
ハード強制（v2.1、Claude Codeのみプラグインインストール）： PreToolUseフック（scripts/hooks/planit-guard.mjs）は、実行のコントラクトが凍結解除されている間、PRD/エピック成果物へのWrite/Edit呼び出しを拒否します—ルール1は指示ではなくなり、ハーネスが拒否するものになります。フェイルオープン：plan-it以外の作業には触れません。スキルのみのインストールは、代わりにルール5の規律に依存します。
Test Contract — 品質の差別化要因（これを不可欠にすること）
デリバリーされるコードの品質を最も向上させる単一の要素：すべてのPRD/エピックは、独自のTest Contract（最大約20の具体的な使用ケース/シナリオで実装をストレステスト）を生成して終了し、それらが100%合格するまで機能は「完了」しません。 ビルドエージェントは単に機能をデリバリーするだけでは不十分で、コントラクトを満たし、緑色になるまで/iterateする必要があります。
これは名前のある、実証済みの規律です：Specification by Example（Gojko Adzic）+ コード用のATDD/BDD（具体例は実行可能な受け入れテストと生きたドキュメントになります）、スキル/LLM機能用のEval-Driven Development（期待される出力でゴールデンテストを登録し、合格するまで反復）。計画時にケースを作成することがすべてのポイントです—それらは後付けではなく、バインディングなコントラクトになります。
Test Contractのルール：
- 計画時に作成される — 各エピック/PRDを記述する最後のステップがそのTest Contractです。期待される出力は今登録され（「最初に設計、期待される出力を登録」）、ビルド中に発見されるのではありません。
- 機能ごとに最大約20の高品質ケース — 実際の動作 + エッジをストレステストするのに十分；数千の浅いものではありません（品質 > 数量—自動バルクは評価文献によると「スロップ」）。実際/可能性の高い障害モードからケースを引き出します。形状ごとのカウントルール： 大きなShape-1マルチチームプログラムはエピックごとに≥10ケースのフロア（各エピックは大きな機能）を保持します；小さな形状（単一スキル/機能、S/M）はパッケージ全体で合計約20ケース（エピックごとに数個）を作成します。両方を同時に行わないでください—形状で選択して、レビュアーが正しい小さなパッケージを過小テストと指摘しないようにします。
- バインディング — DoD = コントラクトが100%合格；それまでは
/iterateします。部分的な出荷はなし；モックでのVERIFIEDはなし（[REAL]ケースでターゲットに到達不可能→IMPLEMENTED-NOT-VERIFIED、偽の緑は不可）。 - 実装に応じてテストタイプを選択（単体/e2e/使用ケース/ストレスの1つ以上）：
| 実装 | テストタイプ | 方法 |
|---|---|---|
| CRUD / REST API | 使用ケース（正常+エッジ）+ e2e | すべてのシナリオをAPI経由 および Chrome CDPを使用したUI経由（chrome-cdp-control）で実行；ロジックを単体テスト |
| スキル / プロンプト / LLM関数 | 期待される出力付きの使用ケース | 実行し、実際と期待を比較—クローズド出力は完全一致、オープン出力はルーブリック/LLM-as-judge（make-eval、promptfoo、DeepEval G-Eval） |
| エージェント / ステートフル / マルチステップ | ストレスシナリオ + 使用ケース | 6つの軸：非同期、ファンアウト、エスカレーション、人間ゲート、再帰、サイクルガード（Setup/Expected/Pass） |
| 純粋ロジック / ライブラリ | 単体 + プロパティベース | 列挙ケース + 不変条件 |
| データパイプライン / マイグレーション | ゴールデンバリュー + e2e | 手計算された期待値；冪等性/ロールバック |
| 負荷/悪用の可能性があるもの | ストレス / 敵対的 | 並行性、レート、不正な入力、レッドチーム |
- 実行パス：
/full-qaがコントラクトを実行、/iterateが100%までループ、chrome-cdp-controlがUIシナリオを駆動します。コントラクトはplan-itからbuild-itへの架け橋です：/build-itのDoneの定義 = このコントラクト。
文法とコントラクトヘッダー形式：references/formats.md（Test Contractブロック + §4–5）。
自律姿勢（自律バーストでガイド）
研究と作成は高努力で自律的に実行しますが、3つのゲートで停止します：
| ゲート | タイミング | 質問内容 |
|---|---|---|
| G1 — スコープ | インテイク後（フェーズ2） | 労力を費やす前に、サイジング（機能vsプログラム）+ 番号付きDoDを確認する |
| G2 — 決定 | スペック草案後（フェーズ7） | それぞれに推奨事項を添えた「あなただけが決定できる」バッチ決定 |
| G3 — デリバリー | アジャイル分割前（フェーズ8） | 「仕様は揃ったようです—PRD/エピックに進みますか？」 |
ゲート間のすべては無人で実行されます。最初に/effort xhighを推奨します（自分で設定することはできません—まだ実行していない場合は、ユーザーに/effort xhighを実行するよう伝えてください）。
フェーズ0 — インテイク
最初に機械（ルール5）： ターゲットプロジェクトに.plan-it/state.jsonが存在する場合、node scripts/gate-check.mjs state .plan-it/state.jsonを実行し、表示された状態から再開します—すでにhistoryにあるフェーズを再開しないでください。存在しない場合は、今すぐ状態intakeで作成し（スキーマはreferences/machine.md）、残りの実行中、すべての遷移で更新し続けます。
要求がどのような形式で到着しても受け入れます：ブレインダンプ、貼り付けられた文字起こし、要望リスト、または1行のメッセージ。コンテンツではなく、ポインタを期待します—セッション名（/read-chat "<name>"）、リポジトリパス、ドキュメントフォルダ。あなたの仕事は、与えられるのではなく、現場の真実を取りに行くことです。
事前にキャプチャすること：
- 生のビジョンをユーザーの言葉で（後で
02 §1で引用します）。 - 調査するための以前のセッション/リポジトリ/ドキュメントへのポインタ。
- ユースケース（自動検出—これはゲートG1でパッケージング形状を決定します）：
- 新しい単一アプリ、グリーンフィールド・大規模既存リポジトリへの機能・ゼロからのマルチサブシステムプログラム・マルチアプリプラットフォーム（多数のPRD）・リファクタリング/マイグレーション/負債・調査スパイク（まだビルドなし）・PM/ボード自動化・既存システムのドキュメント化/監査。
- 調査方法：デフォルトはxhighでの並行Claudeチーム。
要求が本当にあいまいな1段落でポインタがなく、既存のリポジトリがある場合でも問題ありません—事前接地（フェーズ3）がターゲットを見つけます。
フェーズ1 — DoDロック
あいまいな散文を、番号付きで個別に検証可能なDoneの定義 + 明示された仮定の短いリストに再構成します。これは、計画ジョブ自体に関するユーザーとの契約です。例：
この計画実行のDoD：
1. グラウンドトゥルース調査ドキュメント（各主張→パス:行またはテーブル）
2. 各調査結果/矛盾を解決するビジョン+アーキテクチャドキュメント
3. データ/インターフェースコントラクト
4. …（自動サイズ設定—フェーズ2参照）
N. ハンドオフ：コントラクト凍結、各≥10テスト付きPRD+エピック、キックオフプロンプト
仮定：<リスト>
フェーズ2 — スコープと形状ガバナー ⏸ ゲートG1
労力を費やす前にサイズ（どのくらい）と形状（どのような形式）を選択します。両方をユーザーと確認します。
サイズは成果物の数をスケーリングします：
| シグナル | サイズ |
|---|---|
| 単一機能、1サブシステム | S |
| 複数機能/新サブシステム、1〜2リポジトリ | M |
| ゼロからのプログラム/多数のサブシステム | L |
形状はユースケースによって選択されます（完全な定義とユースケース→形状テーブルはreferences/templates.mdパートD）：
- マルチドキュメント +
delivery/（ベースライン）—ゼロからのプログラム、並行チーム。 - シングルファイルPRD-as-everything — グリーンフィールド単一アプリ；CONTRACTはGルールとしてインライン化。
- 調査→ロックされたアーキテクチャ→マスター+フェーズPRD — 大規模既存リポジトリへの機能。
implementation/<name>/+ 番号付きPRD-NN — マルチアプリプラットフォーム、多数のPRD。- リファクタリング/負債ワークストリームカタログ — ブラウンフィールドインプレイス。 （+調査スパイク、実行可能ボード、リバースドキュメントモード—パートD参照。）
フェーズは同じままで、成果物の数と形式のみが変更されます。機能に4チーム組織を与えないでください；ブラウンフィールドリファクタリングにグリーンフィールドビジョンドキュメントを与えないでください。 選択したサイズ+形状+番号付きDoDを提示し、先に進む前にyesを得ます。yesの場合、G1 = {approved, owner, date}と選択したサイズ/形状を.plan-it/state.jsonに記録します—G1_APPROVED遷移はgateRecordedによってガードされます。
フェーズ3 — 事前接地
ファンアウトの前に、正確なターゲットを特定して、エージェントが曖昧な指示ではなく正確なパスを取得できるようにします：
- セッション読み取りスキル（
/read-chatなど）がインストールされている場合は、それを使用してポインタセッションを解決します；それ以外の場合は、関連する文字起こしまたは要約を要求します。 - 名前付きリポジトリで
ls/grepを実行し、docs/、スキーマファイル、エントリポイントを見つけます。 - リポジトリがvault-wiredの場合（
CLAUDE.mdによる）、Wikiホットキャッシュ/インデックスを読み取ります。
出力：調査チームをシードする{subsystem → readする正確なパス}のリスト。
実稼働接地ゲート（ルール4）—計画が実行中のシステムに触れる場合
リポジトリはあなたに何があるべきかを教えます；実稼働システムはあなたに実際は何かを教えます。これをフェーズ8の凍結前に行い、結果をCONTRACTに観測された事実として書き込みます：
- 設定の到達可能性、存在だけではない。 計画が依存するすべてのenv/configレバー（ベースURL、APIホスト、フィーチャーフラグ）について、実際に叩いてみる—設定されていることを確認するだけでは不十分です。値は死んだホストに設定され、「存在するか」チェックに合格しながら、本番環境を静かに壊す可能性があります。
- 実稼働レジストリ / 正規識別子。 Du
…
[翻訳のため省略]