crucible は何をしますか？
並列ドメイン探索 → 敵対的検証 → 計画 → 検証 → SPEC → 実装 → PR。
ファイル所有権ルール
サブエージェントはファイルを書き込みません。 結果はテキストとして返します。オーケストレーター（あなた）がすべての成果物を書き込みます。ファイルはフェーズ間の引き継ぎ手段であり、サブエージェントのメモリはその役割を果たしません。
セットアップ
呼び出しから以下を解析します。
- ドメイン（必須） — 監査対象のユーザー向け領域（例:
player、curator） - スコープヒント（オプション） — ドメイン内の焦点を絞る範囲（例:
lobby SSE、role selection）
出力ディレクトリを決定: .crucible/run-<N>/（Nは未使用の最小整数）
事前実行チェック: .crucible/ スキャンして既存の実行ディレクトリを確認。各 findings.json を読み取り、確認済みのIDをスキップリストとしてフェーズ1のエージェントに渡します。既知の修正済み問題を再発見せず、ギャップに集中します。
今回の実行で書き込まれるファイル（すべてオーケストレーターが作成）:
| ファイル | フェーズ | 役割 |
|---|---|---|
codebase-map.md | 1 | 下流の全エージェントにそのまま注入されるコンテキスト |
recon-<domain>.json | 1 | ドメインごとの生の発見事項 |
findings.json | 1→2→4 | 統合された発見事項。各フェーズで判定が追加される |
PLAN.md | 3 | 優先順位付けされた修正計画 |
SPEC.md | 5 | 発見事項ごとの変更前/変更後のコードとテストケース |
フェーズ1 — 探索 (Recon)
エージェントを起動する前に、references/recon-phase.md を必ず読んでください。
宣言されたドメインごとに1つの調査エージェントを、すべて並列に起動します。各エージェントにコードベースパス、ドメイン名、スコープヒント（あれば）、既知のスキップIDを渡します。
エージェントはJSONテキストを返します。エージェントが散文を返した場合は、assets/findings-schema.json の正確なスキーマ形状で1回だけ再プロンプトします。再度失敗した場合は、空の recon-<domain>.json（[]）を書き込み、codebase-map.md に失敗を記録します。続行します — 1つのドメインの失敗は回復可能であり、実行を中止しないでください。
有効な応答を収集した後:
- エージェント応答ごとに
recon-<domain>.jsonを書き込む codebase-map.mdを統合 — 主要なファイルパス、ドメイン境界、共有モジュール、規約- すべてのドメインの発見事項を
findings.jsonにマージする
完了条件: すべてのドメインに recon-<domain>.json が存在し、codebase-map.md と findings.json が書き込まれていること。フェーズ2までは references/adversarial-phase.md をロードしないでください。
フェーズ2 — 敵対的レビュー (Adversarial Review)
エージェントを起動する前に、references/adversarial-phase.md を必ず読んでください。
発見事項ごとに1つの汎用エージェントを起動します（同じドメインの発見事項はまとめてバッチ処理）。各エージェントは発見事項のJSONと codebase-map.md を受け取ります — 探索エージェントの推論プロセスは渡しません。独立性の境界が品質のゲートです。
エージェントはコード証拠とともに CONFIRMED / REJECTED / DOWNGRADED を返します。各判定を findings.json の該当エントリに追加します。node scripts/validate-findings.cjs findings.json を実行し、スキーマエラーを修正してからフェーズ3に進みます。
バリデーター自体が実行できない場合 — node がPATHにない、スクリプトまたはそのスキーマが欠落している、使用法エラー、または検証開始前のなんらかの失敗（Failed to load schema、Failed to parse JSON） — これは合格ではありません。⚠ findings unvalidated — validator unavailable: <reason> を発見事項出力とSPEC引き継ぎの先頭に記載し、続行します。スキーマ却下はその逆であり、常にブロックします。発見事項を修正し、再実行し、却下されたまま進めないでください。現時点では両方とも終了コード 1 を返すため、終了コードではなくエラーテキストを読み取ってください。
完了条件: すべての発見事項に adversarial_verdict フィールドが存在すること。スキーマ検証が合格すること。この時点以降、references/recon-phase.md を再ロードしないでください。
フェーズ3 — 計画統合 (Plan Synthesis)
発見事項ゼロチェック: 統合前に findings.json 内の確認済み + 格下げエントリをカウントします。ゼロの場合、.crucible/run-<N>/REPORT.md に「敵対的レビュー後、実行可能な発見事項はありませんでした」という1行だけを書き込みます。停止します — PRは作成しません。
findings.json の確認済み + 格下げ発見事項を PLAN.md に統合:
- P1 (重大/高): 壊れたコアフロー、データ損失、永続的な切断
- P2 (中): ユーザーに見えるエラー、リカバリパスの欠落
- P3 (低): 洗練不足、ドキュメントのずれ、コピー問題
根本原因を共有する発見事項をグループ化 — 1つの修正で複数を排除できる場合があります。グループ化する場合、グループ内で最も高い重大度がグループの優先度を設定します。グループ化された発見事項に競合する修正アプローチがある場合は分割します — 根本原因の共有は修正の共有を意味しません。依存関係が存在する場合は修正順序を宣言します。却下された発見事項は完全に除外されます。
完了条件: PLAN.md が書き込まれていること。すべての確認済み発見事項が正確に1回出現すること。
フェーズ4 — 独立検証 (Independent Verification)
P1 + P2 の発見事項ごとに1つの調査エージェントを、すべて並列に起動します。各エージェントには「あなたはこの発見事項を書きませんでした。すべての事実主張を現在のソースコードに対して検証してください。」と伝えます。
各エージェントは以下をチェック: ファイルがパスに存在するか、行番号が記述されたコードと一致するか、スコープ名が正しいか、記述されたパターンが実際に出現するか。VERIFIED / CORRECTED [field: wrong → right] / REJECTED [reason] を返します。
すべての修正を PLAN.md と findings.json に適用します。スキーマ検証を再度実行します。PLAN.md と findings.json は一致している必要があります — 成果物間の不一致は許されません。
完了条件: すべてのP1+P2発見事項が検証済み。すべての修正が適用済み。スキーマが合格すること。
フェーズ5 — SPEC
確認済み発見事項ごとに1つのセクション（P1 → P2 → P3 の順）を含む SPEC.md を書き込みます:
- 正確なファイルパス + 行範囲（検証済み）
- 変更前のコード（疑似コードではなく実際のソース）
- 変更後のコード（具体的な修正）
- テストケース: テストが検証すべき動作ごとに1文
node scripts/validate-findings.cjs findings.json 最終チェックを実行します。
完了条件: すべてのPLAN.mdエントリにSPECセクションが存在すること。検証が合格すること。
フェーズ6 — 引き継ぎ (Handoff)
- ユーザー向けの動作を変更する発見事項についてフロードキュメント（
docs/flows/）を更新する SPEC.mdを指定してimplementスキルを呼び出す- PRを作成する — これは人間がループに入るゲートです。中間承認は要求しません
PR本文: PLAN.md へのリンク、重大度別の発見事項数、SPEC.md へのリンク、更新されたフロードキュメントのリスト。
禁止事項 (NEVER)
-
サブエージェントにファイルを書かせてはいけない 代わりに: エージェントに内容をテキストで返させ、自分でファイルを書き込んでください。 理由: クロスフェーズの状態はファイルに存在します。エージェントが直接書き込むと、オーケストレーターは正規のコピーを失い、フェーズ4の修正後に成果物を調整できなくなります。
-
敵対的エージェントに探索エージェントの推論連鎖を与えてはいけない 代わりに: 構造化された発見事項（JSON）と
codebase-map.mdのみを渡してください。 理由: 探索エージェントのロジックを見ると、敵対的エージェントが同じ前提に固定されます — 独立性の境界が誤検知を排除するのです。 -
スキーマ検証に失敗したままフェーズ2を越えて進めてはいけない 代わりに: 計画を統合する前に
findings.jsonの失敗フィールドを修正してください。 理由: 不正な発見事項に基づいて構築されたPLANは、間違ったファイルパスと行番号を持つSPECを生成し、implementスキルが使用できなくなります。 -
P1/P2の発見事項に
verification: "pending"があるままSPEC.mdを書いてはいけない 代わりに:node scripts/validate-findings.cjs findings.json --pre-specを実行し、すべての失敗を解決してからフェーズ5に進んでください。 理由:--pre-specガードはバリデータースクリプトに存在しますが、呼び出されなければ見えません — この呼び出しをスキップしたエージェントは、未検証のファイルパスでSPECを作成し、間違った行番号をimplementに静かに渡すことになります。