recursive-router

recursive-router

recursive-mode と recursive-subagent によって委任された役割がすでに確立されており、その経路を場当たり的なコントローラーの判断ではなく、ユーザーが編集可能な CLI／モデルポリシーに基づいて決定したい場合に、このスキルを使用します。

このスキルによって、recursive-mode の制約が緩和されることはありません。ルーティングされた外部出力は、メインエージェントが実際のファイル、実際の差分、実際の再帰アーティファクトと照合して検証するまでは、信頼できないものとして扱います。

コントローラーの境界

メインオーケストレーターは、ユーザーが現在 CLI、IDE、またはエージェントセッションで対話しているモデルのままです。

recursive-router が第 2 のオーケストレーターや第 2 のワークフロー仕様になることはありません。現在のコントローラーが、範囲を限定した委任役割に使用する外部 CLI／モデルを選択して呼び出せるよう支援するだけです。

現在のコントローラーは、引き続き次の責任を負います。

• アクティブな再帰フェーズを選択し、順序を決定する
• 委任前に、適用される再帰関連ドキュメントを読む
• recursive-subagent と、正式なレビュー用バンドル／プロンプト用バンドルの契約を使用する
• 委任するコンテキストバンドルまたはプロンプトバンドルを準備する
• ルーティングされた役割に、必要なドキュメントと正確な出力契約が渡されるようにする
• 不完全な出力、コンテキストを欠く出力、または契約に準拠しない出力を拒否する
• ワークフローを修正するか、再ルーティングするか、フォールバックするか、続行するかを判断する
• 委任された出力によって生じた問題を修正し、実際のゲートを通過するまで監査・修復ループを再実行する

呼び出しの境界

ルーターのセットアップ、ローカル CLI の検出、ルートの再設定はオプトインです。これらの操作では、ユーザーのデバイスにあるローカル CLI のインストール状況やプロバイダー／モデル設定を確認する場合があるためです。ルーティングが明示的に要求された場合、または実行にあたり、すでに有効なルーティングポリシーのインベントリを更新する必要がある場合に限り、init、probe、configure、その他の検出／設定手順を実行してください。

ルーティングを明示的に求めている例には、次の語句を含む表現があります。

• route
• routing
• router
• set model
• set provider
• configure routing
• configure model routing
• use <provider/model> for <role>

新規セットアップについてこのような表現があった場合は、まず、このリポジトリのプロバイダー間でモデルルーティングをセットアップするか、ユーザーに確認してください。ユーザーが承認するまでは、新規セットアップのためにローカルデバイスの状態を調べたり、ルーティングポリシーを変更したりしないでください。

ユーザーが拒否した場合、またはルーターの動作についての説明だけを求めている場合は、ローカルデバイスを調べたり、ルーティングポリシーを変更したりしないでください。

ユーザーがルーティングを伴う委任を明示的に要求した後、または選択された正式な役割に、有効な外部ルートがすでに設定されている場合は、ルーターを使用できます。その委任枠にルーターを使用するかどうか、コントローラーが再度尋ねる必要はありません。有効な外部ルートとは、その役割について /.recursive/config/recursive-router.json に enabled: true、mode: "external-cli"、null ではない cli、null ではない model が設定されている状態、またはユーザーがその役割に明示的なルートバインディングを指定した状態です。

recursive-router-resolve が external-cli を返した場合は、recursive-router-invoke を通じて実行してください。ローカル実行／セルフ監査で代用できるのは、有効なルートの解決結果が fallback-local、local-only、blocked、または ask-user の場合に限ります。また、そのルート結果をフェーズアーティファクトまたはサブエージェントのアクション記録に記録してください。コントローラーは、検証後にルーティングされた出力を拒否してローカルで修復してもかまいませんが、その拒否／修復を記録する必要があります。ローカルで修復したことを、ルーティングされた役割が割り当てを実行した証拠として扱ってはいけません。

recursive-router-invoke が success: false またはゼロ以外の exit_code を返した場合は、output_text に有用なアシスタントのテキストが含まれていても、そのルーティング試行は失敗として扱ってください。その出力は診断用の証拠として保持し、失敗した試行を記録したうえで、プロンプト／コンテキストを修正するか、同じルーティング先の役割に報告された問題の修正を依頼して再試行してください。ゼロ以外の終了コードの試行を、ルーティングされた役割の受け入れ、フェーズゲートの PASS 判定、またはテスター／実装担当者／レビュアーの完了として扱ってはいけません。

目的

recursive-router を使用して、次のことを行います。

• 現在の環境で利用可能な、サポート対象の CLI を調べます
• CLI ID と公開されているモデルの検出インベントリを確認します
• ポリシーを記述する前に、検証済みの CLI／モデルのバインディングを安全に設定します
• サブエージェントのロールを、設定済みの CLI／モデルのペアに解決します
• ポリシーが ask を指定している場合、未解決のロールバインディングについてユーザーに確認します
• ルーティング先の CLI が利用できない場合も、明示的なフォールバック動作を維持します

トリガーの例

• Set up routing between Codex, Kimi, and Opencode for this repo
• Use the router for delegated review roles
• Route code-reviewer through Kimi
• Set model bindings for the audit roles
• Configure model routing between providers

標準パス

• ルーティングポリシー：/.recursive/config/recursive-router.json
• 検出インベントリ：/.recursive/config/recursive-router-discovered.json

標準スクリプトは recursive-router-* です。 旧形式の recursive-router-cli-* スクリプト名は、互換性ラッパーとしてのみ残されています。新しいコントローラーフローやドキュメントでは、標準名を使用してください。

標準ロール

• orchestrator
• analyst
• planner
• implementer
• code-reviewer
• memory-auditor
• tester

コントローラーのロールを同じ設定領域で確認できるよう、ルーターポリシーでは orchestrator を明示します。ただし、デフォルトでは local-only とし、フォールバックは local-controller のままにしてください。最終的な統合、修正、受け入れ判定はこのロールが担います。ほかのルーティング対象ロールは範囲を限定した作業を提案できますが、オーケストレーターは、それらが残した不具合を修正し、必須のすべてのゲートに合格するようにしなければなりません。

旧形式の互換エイリアスも、引き続き次のステージ対応ロールに解決されます。

• phase-auditor -> analyst
• traceability-auditor -> planner
• bounded-implementer -> implementer
• test-reviewer -> tester

読み込み順序

1. /.recursive/RECURSIVE.md を読みます。
2. ../recursive-subagent/SKILL.md を読みます。
3. /.recursive/config/recursive-router.json を読みます。
4. /.recursive/config/recursive-router-discovered.json を読みます。
5. /.recursive/memory/skills/SKILLS.md を読みます。また、フェーズが機能に左右される場合は、関連する委任レビューや機能に関するメモも読みます。

フェーズの順序、監査基準、レビューバンドルのルール、受け入れ基準は、引き続き recursive-mode と recursive-subagent が定めます。ここでそれらを再記述したり、緩和したりしないでください。

必須の動作

• ルーティングは recursive-subagent の拡張であり、置き換えるものではありません。
• 現在の CLI／IDE／エージェントセッションが、引き続き単一のワークフローコントローラーとなります。ルーティングされた CLI はアシスタントであり、自律的なフェーズ管理者ではありません。
• ユーザーが明示的にルーティングを呼び出し、セットアップを確認していない限り、ローカルの CLI／プロバイダー／モデルの状態をスキャンしないでください。
• 外部 CLI は引き続き任意のインフラストラクチャです。
• ルーティングされた CLI やモデルを使用できない場合は、フェーズの基準を引き下げず、設定されたフォールバック動作に従ってください。
• ポリシーが ask の場合、CLI／モデルのバインディングを勝手に推測して設定しないでください。
• ルーティングされた出力は、実際のリポジトリの状態に照らしてメインエージェントが検証するまで、受け入れてはいけません。
• ルーティングされたロールに、フェーズ、入力、受け入れ基準を選ばせないでください。
• 最終的な受け入れの責任は、ルーティングされたロールにはありません。オーケストレーターが監査・修正のループを担い、フェーズゲートに実際に合格するまで修正または再ルーティングを続ける必要があります。
• ディスパッチする前に、ルーティングされたロールに実質的なコンテキストバンドルを提供してください。具体的には、正規のレビュー用バンドルまたはプロンプトバンドルのパス、正確な成果物のパス、関連する上流ドキュメント、必須のチェック、正確な出力形式を含めます。
• ルーター固有のワークフロー説明を新たに作るのではなく、00-requirements.md、01-as-is.md、02-to-be-plan.md、現在のフェーズの成果物、生成されたレビュー用バンドルなど、正規のワークフロー成果物を参照する簡潔なディスパッチプロンプトを優先してください。
• ルーティングされたモデルが作業を成功させるために具体的なコンテキストを必要としているのに、「ドキュメントを読んで」のような曖昧なファイル参照だけで作業を委任しないでください。
• ルーティングされたモデルの指示順守が不十分だった場合は、その割り当てに必要な具体的な要件、成果物、またはセクションの抜粋をプロンプトに含め、それらを引用または遵守していない出力は却下してください。

検出

ルータースクリプトを使用して、ルーティングを初期化、プローブ、検証、解決します。

python ./.recursive/scripts/recursive-router-init.py --repo-root .
python ./.recursive/scripts/recursive-router-probe.py --repo-root . --json
python ./.recursive/scripts/recursive-router-configure.py --repo-root . --set code-reviewer=codex:gpt-5.4-mini --json
python ./.recursive/scripts/recursive-router-invoke.py --repo-root . --role code-reviewer --prompt-file "./.recursive/run/<run-id>/router-prompts/code-reviewer-bundle.md" --json
python ./.recursive/scripts/recursive-router-validate.py --repo-root .
python ./.recursive/scripts/recursive-router-resolve.py --repo-root . --role code-reviewer --json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-probe.ps1 -RepoRoot . -Json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-configure.ps1 -RepoRoot . -Set code-reviewer=codex:gpt-5.4-mini -Json
pwsh -NoProfile -File ./.recursive/scripts/recursive-router-invoke.ps1 -RepoRoot . -Role code-reviewer -PromptFile "./.recursive/run/<run-id>/router-prompts/code-reviewer-bundle.md" -Json

組み込みの検出対象は次のとおりです。

• codex
• kimi
• opencode

組み込みのモデル検出ソースは次のとおりです。

• codex：ネイティブの model/list を使う codex app-server --listen stdio://。app-server で検出できない場合は、~/.codex/models_cache.json にフォールバックします
• kimi：~/.kimi/config.toml の設定済みモデルエイリアス。ルーティングされる値が kimi --model ... で受け付けられる値と一致するようにします
• opencode：opencode models から取得する、設定済み／認証済みの CLI インベントリ

opencode では、ルーターによる検出で CLI の設定済み／認証済みプロバイダーとモデルのインベントリを使用し、ハードコードされたリストではなく、ユーザーの実際の opencode 設定に基づいてルーティング先のモデルを選択するようにしてください。

opencode では、認証済みインベントリに含まれている場合、github-copilot/... や opencode/... などのプロバイダー修飾付きモデル ID を有効なルーティング先として使用できます。

codex では、下流のディスパッチャーがプロンプトを実際に送信する必要がある場合、ルーティング時のトランスポートには codex exec よりもネイティブの app-server プロトコルを優先してください。

自動化で、存在しないトップレベルの codex model コマンドに依存してはいけません。手動で簡単に確認する場合は codex exec -m <model> が便利ですが、検出の基準には引き続き app-server の model/list を使用してください。

kimi では、/model を自動化のインターフェースとして扱わないでください。/model はセッション内の対話型ピッカーであり、トップレベルの検出コマンドではありません。また、ルーティング設定では、基盤となるモデルのスラッグではなく、呼び出し可能なエイリアスキーを使用する必要があります。

ランチャーの詳細は、オペレーティングシステム、シェル、デバイスによって異なる場合があります。組み込みアダプターコマンドはあくまでデフォルトとして扱ってください。実際のローカルランチャーや呼び出し形式が異なる場合は、まず環境を調べてください。そのうえで、リポジトリ全体に適用されるパスやラッパーを想定してハードコードするのではなく、組み込み CLI なら cli_overrides、完全なカスタムアダプターなら custom_clis に、そのマシン固有の設定を記録してください。

カスタム CLI はルーティングポリシーでも定義できます。

ポリシーのタイムアウト動作：

• デフォルトのプローブタイムアウトは 50000 ms です。
• デフォルトの呼び出しタイムアウトは 180000 ms です。
• defaults.invoke_timeout_ms が導入される前のレガシールーターポリシーも引き続き有効です。検証に失敗するのではなく、現在のデフォルトの呼び出しタイムアウトを継承します。

ライブルーティングで得られた Windows ランチャーに関する知見

• npm または PATH のシムが削除されている場合は、codex.cmd または opencode.cmd がまだ存在すると想定せず、cli_overrides を使って codex または opencode を実際の実行ファイルのパスに紐付けてください。
• codex では、app-server をサポートする実際の codex.exe をオーバーライド先に指定し、ルーティングされたトランスポートにはネイティブの app-server パスを使用してください。
• opencode では、OpenCode.exe のようなデスクトップアプリのラッパーではなく、opencode-cli.exe などの専用 CLI バイナリを使用してください。
• 単純な一回限りの kimi シェル呼び出しには、kimi --quiet --prompt "..." が使えます。ただし、CLI が <choice>STOP</choice> などのセッションメタデータや再開手順を追加する場合があります。
• 別のエージェントが機械可読な kimi の出力を必要とする場合は、kimi --work-dir "<repo>" --print --output-format stream-json --max-ralph-iterations 0 --prompt "..." を優先し、構造化ストリームからアシスタントのテキストだけを解析してください。最大 Ralph 反復回数を 0 に設定すると、一回限りのルーティングタスクが、<choice>STOP</choice> などのローカルなループ制御の選択を引き継がずに済みます。
• 呼び出し元が ACP を使用し、一回限りのシェル委譲ではなく永続的なサーバーを必要とする場合は、kimi acp がサポート対象の Kimi ACP エントリポイントです。
• 単純な一回限りの opencode シェル呼び出しには、opencode-cli.exe run "..." が使えます。機械可読なオーケストレーションには、opencode-cli.exe run --format json --dir "<repo>" "..." を優先してください。
• 呼び出し元が ACP を使用し、一回限りのシェル委譲ではなく永続的なサーバーを必要とする場合は、デスクトップラッパーではなく opencode-cli.exe acp --cwd "<repo>" を使用してください。
• 実際のタスクを委譲する場合は、作業ディレクトリを明示的に指定してください。kimi では --work-dir、opencode では --dir を使用します。
• ACP モードは、上流の呼び出し元が実際に ACP を使用している場合にのみ使ってください。通常のルーティングされた委譲では、kimi --print ... または opencode-cli.exe run ... を優先してください。
• kimi と opencode の ACP サーバーエントリポイントは、このマシンで CLI のヘルプを直接確認して検証済みです。acpx などの ACP クライアント／ルーターパターンは、現在の環境で検証されるまで利用可能と想定しないでください。

推奨されるルーティングワークフロー

1. リポジトリにルーター設定のひな形がまだない場合は、init を実行します。
2. probe を実行し、/.recursive/config/recursive-router-discovered.json を確認します。
3. 未解決のロールの割り当てがあれば、ユーザーに簡潔な role=cli:model 形式で確認します。
4. recursive-router-configure.py または .ps1 を使って指定された割り当てを適用し、保存前に各ルートが検証されるようにします。
5. recursive-subagent の契約に従い、委任する割り当てを正確に反映した標準レビュー用バンドルまたはルーティング済みプロンプトバンドルを作成または更新します。
6. そのロールをディスパッチするリポジトリ／ワークツリーで、/.recursive/config/recursive-router.json と /.recursive/config/recursive-router-discovered.json が存在し、最新であることを確認します。検出インベントリはローカルにあり、未追跡の場合があるため、新しいワークツリーでルートを解決する前に更新またはコピーします。
7. 委任された実行の直前に、対象のロールについて resolve を実行し、フォールバックの動作が実環境の最新状態に保たれるようにします。
8. 判定が external-cli の場合は、recursive-router-invoke.py または .ps1 を使って範囲を限定した割り当てをディスパッチし、メタデータと出力のパスを記録したうえで、受け入れ前に実際のリポジトリの状態と照合して結果を検証します。
9. 呼び出しに失敗した場合は、コンテキストまたはディスパッチプロンプトを修正し、同じルーティング済みロールを再実行します。サブエージェントの出力で修正可能な問題が特定された場合、コントローラーは、そのルーティング済みロールに対し、担当範囲内で修正するよう明示的に指示してから、コントローラーによる検証とルーティング済みチェックを再実行します。

コントローラーが変更を行う場合は、手動でポリシーを編集するよりも設定スクリプトを優先します。設定と検証をまとめて行うことで、不正または古い割り当てが気付かれずに保存されるのを防げます。

コントローラーが実際にルーティングされた作業をディスパッチする場合は、独自のシェルスニペットや一度限りのヘルパースクリプトよりも、呼び出しスクリプトを優先します。これにより、ルートの解決、ランチャーの選択、トランスポートの処理、出力の取得を、リポジトリがサポートする方法で行えます。

委任ペイロードの形式

ルーターは、実際の再帰的アーティファクトを重複させるのではなく、それらを参照する簡潔なディスパッチプロンプトを渡す必要があります。一般的なペイロードの要素は次のとおりです。

• 委任するロール
• 現在のフェーズとアーティファクトのパス
• 標準レビュー用バンドルのパスまたはプロンプトバンドルのパス
• 読み込む必要がある上流のドキュメント。通常は、00-requirements.md、01-as-is.md、02-to-be-plan.md などの現在の実行ドキュメント、または現在監査中のアーティファクトを含みます
• recursive-subagent または生成されたレビュー用バンドルが定める、正確な出力契約

ルーターの役割は、そのバンドルを選択された CLI／モデルにルーティングし、出力を返すことです。ルーターが、代わりとなるワークフロールールを独自に作ってはなりません。

ユーザープロンプト

ルーティング先のロールが未解決の場合は、以下を示す簡潔なロールベースの質問を提示します。

• 検出された CLI ID
• バージョン文字列（利用可能な場合）
• 検出されたモデル一覧（利用可能な場合）
• 未解決のロール
• /.recursive/config/recursive-router.json
• /.recursive/config/recursive-router-discovered.json

質問の例：

I found these CLIs in this environment:
- codex (available, version 1.2.3)
- kimi (available, version 1.32.0)

Please choose a CLI and model for these roles in /.recursive/config/recursive-router.json.
For valid CLI ids and model ids, check /.recursive/config/recursive-router-discovered.json.

Unresolved roles:
- analyst
- code-reviewer

有効な簡潔な回答：

analyst=codex:gpt-5
code-reviewer=kimi:kimi-code/kimi-for-coding

ユーザーの回答後は、1 つ以上の --set role=cli:model バインディングを指定して、recursive-router-configure.py または .ps1 を優先的に使用します。設定コマンドは、/.recursive/config/recursive-router.json に書き込む前に、選択したモデルへライブプロンプトを送信して、提案されたルートをそれぞれ検証する必要があります。いずれかの検証に失敗した場合は、変更の一部だけを保存してはいけません。ユーザーがポリシーファイルを直接編集した場合は、手動編集を確認せずに上書きするのではなく、ファイルを再読み込みします。

ライブルーティングから得られた検証ガイダンス：

• codex の検証には、汎用 CLI テンプレートの呼び出しではなく、app-server トランスポートを使用してください。
• kimi の検証には設定済みのエイリアスを使用してください。要求されたトークンを出力した後でも、終了コードがゼロ以外になる場合があります。トークンをモデルに到達できた証拠として扱い、終了コードはアクションレコードに記録してください。
• opencode の検証には、opencode models が返す、プロバイダー名が付いた正確なモデル ID を使用してください。
• 検証によって証明できるのは、ルートに到達できることだけです。ルーティング先のロールが実際の割り当てに十分なコンテキストを持つことまでは 証明できません。コントローラーは実際にディスパッチする際も、必要なドキュメントと出力仕様をまとめる必要があります。

フォールバック動作

ルーティングの決定結果は、次のいずれかになります。

• external-cli
• local-only
• fallback-local
• blocked
• ask-user

フォールバックは明示し、監査可能にする必要があります。理由を記録せずに、ルーティングされた委任からローカルパスへ黙って切り替えてはいけません。

監査可能性

ルーティングされた委任を使用または試行した場合、フェーズの成果物とアクションレコードに次の項目を記録します。

• Routing Mode
• Routed Role
• Routed CLI
• Routed Model
• Routing Config Path
• Routing Discovery Path
• Routing Resolution Basis
• 該当する場合は Routing Fallback Reason
• Controller Orchestrator
• Delegated Context Bundle

.recursive/scripts/recursive-subagent-action.py または .ps1 を使用して、次のようなルーティング済みアクションレコードの詳細を記録します。

• Router Used
• CLI Probe Summary
• Prompt Bundle Path
• Invocation Exit Code
• Output Capture Paths

ルーティングされたアシスタントの出力、標準出力／標準エラーの生のトランスクリプト、呼び出しメタデータは、例として /.recursive/run/<run-id>/evidence/router/ のような、実行証跡ツリー内に保存します。最初のプロンプトバンドルは、/.recursive/run/<run-id>/router-prompts/ のような実行単位のプロンプトバンドル用の場所に保存し、Prompt Bundle Path として記載します。再利用可能なリポジトリでトップレベルの /.recursive/router-prompts/ を初期化してはいけません。生のトランスクリプトを /.recursive/run/<run-id>/subagents/ の直下に保存してはいけません。subagents/ 内のすべての Markdown ファイルは正式なサブエージェントアクションレコードであり、アクションレコードのスキーマを満たす必要があります。アクションレコードからは、evidence/router/ 内のトランスクリプトファイルとメタデータファイルを参照できます。

ルーティングされたプロンプトで、セクション分けや引用の厳密さが重要な場合は、次の内容を含む、永続的なプロンプトバンドルを優先してください。

• ロールと範囲を限定した割り当て
• レビュー対象の成果物パス
• 上流の正確なドキュメントまたはレビューバンドルのパス
• 指示追従が弱いモデルに必要な場合は、関連する抜粋をインラインで記載
• 必須セクション見出しと最初の行の規則
• 明示的な却下条件

警告

• 設定が不完全で、ポリシーが ask を指定している場合は、CLI とモデルのバインディングを決して捏造しないでください。
• 外部 CLI を必須にしないでください。
• コントローラーが recursive-router-configure.py または .ps1 を使用できる場合は、確認していないバインディングを保存しないでください。
• 現在のセッションで、ルーターをメインコントローラーの代替として扱わないでください。
• Kimi には ~/.kimi/config.toml の生の model = "..." 値を設定しないでください。kimi --model ... が受け付けるエイリアスキーを使用してください。
• Codex が無効なモデルをすべて十分早い段階で拒否し、モデルの探索に使えるとは考えないでください。判断の根拠として、app-server の model/list と探索インベントリを優先してください。
• ルーティングされた外部出力は、実際のファイル、実際の差分、実際の再帰的アーティファクトに照らしてコントローラーが検証するまで、受け入れないでください。
• success: false またはゼロ以外の exit_code を含むルーティングされた試行は受け入れないでください。修正して再試行するか、明示的なフォールバックを記録してください。
• 生のルーティング済みトランスクリプトを subagents/ の下に Markdown ファイルとして保存しないでください。生のルーター証跡は evidence/router/ に置き、適切なアクション記録を subagents/ の下に作成してください。
• ルーティングされた役割の成功に、コンテキストの同梱や厳密な出力形式の指示が必要な場合、ファイルパスだけを単独で示して委任しないでください。