Recursive Router

recursive-router

Use this skill when recursive-mode and recursive-subagent have already established a delegated role and you want the route to be driven by a user-editable CLI/model policy instead of ad hoc controller choice.

This skill does not relax recursive-mode. Routed external output is still untrusted until the main agent verifies it against actual files, actual diffs, and actual recursive artifacts.

Controller Boundary

The main orchestrator remains the model the user is currently interacting with in their CLI, IDE, or agent session.

recursive-router does not become a second orchestrator or a second workflow spec. It only helps the current controller choose and invoke an external CLI/model for a bounded delegated role.

The current controller remains responsible for:

• selecting and sequencing the active recursive phase
• reading the governing recursive docs before delegation
• using recursive-subagent and the canonical review-bundle / prompt-bundle contract
• preparing the delegated context bundle or prompt bundle
• making sure routed roles receive the needed docs and exact output contract
• rejecting routed output that is incomplete, context-free, or off-contract
• deciding whether to repair, re-route, fall back, or continue the workflow
• fixing issues introduced by delegated output and rerunning the audit-repair loop until the real gates pass

Invocation Boundary

Router setup, local CLI discovery, and route reconfiguration are opt-in because those operations may inspect local CLI installs plus provider/model configuration on the user's device. Only run init, probe, configure, or other discovery/configuration steps when routing has been explicitly requested or an already active routed policy needs a refreshed inventory to execute.

Valid explicit routing examples include phrases containing:

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

When that kind of language appears for new setup, ask the user first whether they want to set up model routing between providers for this repo. Do not inspect local device state or modify routing policy for a new setup until the user confirms.

If the user declines or only wants an explanation of router behavior, do not inspect the local device and do not modify routing policy.

Once the user has explicitly requested routed delegation, or the selected canonical role already has an active configured external route, the router is in scope and the controller should not ask again whether to use it for that delegated slot. An active configured external route means the role has enabled: true, mode: "external-cli", a non-null cli, and a non-null model in /.recursive/config/recursive-router.json, or the user supplied an explicit route binding for that role.

If recursive-router-resolve returns external-cli, dispatch through recursive-router-invoke. Local/self-audit execution is only an acceptable substitute when the effective route resolves to fallback-local, local-only, blocked, or ask-user, and that route outcome must be recorded in the phase artifact or subagent action record. The controller may reject routed output after verification and repair locally, but it must record that rejection/repair instead of treating the local repair as proof that the routed role performed the assignment.

If recursive-router-invoke returns success: false or a nonzero exit_code, treat that routed attempt as failed even when output_text contains useful assistant text. Preserve the output as diagnostic evidence, record the failed attempt, then repair the prompt/context or ask the same routed role to fix the reported issue and retry. Do not accept the routed role, mark a phase gate PASS, or claim tester/implementer/reviewer completion from a nonzero-exit attempt.

Purpose

Use recursive-router to:

• probe which supported CLIs are available in the current environment
• inspect the generated discovery inventory of CLI ids and advertised models
• configure verified CLI/model bindings safely before writing policy
• resolve a subagent role to a configured CLI/model pair
• ask the user for unresolved role bindings when policy says ask
• preserve explicit fallback behavior when routed CLIs are unavailable

Trigger Examples

• 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

Canonical Paths

• Routing policy: /.recursive/config/recursive-router.json
• Discovery inventory: /.recursive/config/recursive-router-discovered.json

Canonical scripts are recursive-router-*. Legacy recursive-router-cli-* script names still exist only as compatibility wrappers; prefer the canonical names in new controller flows and docs.

Canonical Roles

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

orchestrator is explicit in the router policy so the controller role is visible in the same config surface, but it should remain local-only with fallback local-controller by default. It owns final integration, repair, and acceptance: other routed roles can propose bounded work, but the orchestrator must fix any defects they leave behind and make sure all required gates pass.

Legacy compatibility aliases still resolve to these stage-aligned roles:

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

Read Order

1. Read /.recursive/RECURSIVE.md.
2. Read ../recursive-subagent/SKILL.md.
3. Read /.recursive/config/recursive-router.json.
4. Read /.recursive/config/recursive-router-discovered.json.
5. Read /.recursive/memory/skills/SKILLS.md plus any relevant delegated-review or capability notes when the phase is capability-sensitive.

recursive-mode and recursive-subagent still own phase sequencing, audit standards, review-bundle rules, and acceptance criteria. Do not restate or weaken those here.

Required Behavior

• Routing is an extension of recursive-subagent, not a replacement for it.
• The current CLI/IDE/agent session remains the single workflow controller; routed CLIs are assistants, not autonomous phase managers.
• Do not scan local CLI/provider/model state unless the user explicitly invoked routing and confirmed setup.
• External CLIs remain optional infrastructure.
• If a routed CLI or model cannot be used, follow configured fallback behavior instead of weakening the phase standard.
• When policy says ask, do not silently invent CLI/model bindings.
• No routed output may be accepted without main-agent verification against real repo state.
• Do not let a routed role choose its own phase, inputs, or acceptance standard.
• Routed roles do not own final acceptance. The orchestrator remains responsible for the audit-repair loop and must keep repairing or rerouting until the phase gates actually pass.
• Before dispatch, give the routed role a real context bundle: canonical review bundle or prompt bundle path, exact artifact paths, relevant upstream docs, required checks, and exact output shape.
• Prefer brief dispatch prompts that point at canonical workflow artifacts such as 00-requirements.md, 01-as-is.md, 02-to-be-plan.md, the active phase artifact, or a generated review bundle, instead of inventing a second router-specific workflow narrative.
• Do not delegate using only vague file references such as "read the docs" when the routed model needs concrete context to succeed.
• If a routed model has shown weak instruction-following, inline the specific requirement, artifact, or section excerpts needed for that assignment and reject any output that does not cite or follow them.

Discovery

Use the router scripts to initialize, probe, validate, and resolve routing:

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

Built-in discovery targets are:

• codex
• kimi
• opencode

Built-in model discovery sources are:

• codex: codex app-server --listen stdio:// with native model/list, falling back to ~/.codex/models_cache.json when app-server discovery is unavailable
• kimi: configured model aliases from ~/.kimi/config.toml so routed values match what kimi --model ... accepts
• opencode: configured/authenticated CLI inventory from opencode models

For opencode, router discovery should use the CLI's configured/authenticated provider and model inventory, so the routed model choices come from the user's real opencode setup rather than a hardcoded list.

For opencode, provider-qualified model ids such as github-copilot/... and opencode/... are valid routed targets when they appear in the authenticated inventory.

For codex, routed transport should prefer the native app-server protocol rather than codex exec when a downstream dispatcher needs to actually send a prompt.

Do not rely on a nonexistent top-level codex model command for automation. For manual spot checks, codex exec -m <model> is useful, but discovery authority should still come from app-server model/list.

For kimi, do not treat /model as an automation surface. /model is an in-session interactive picker, not a top-level discovery command, and routed config must use invocable alias keys rather than the raw underlying model slug.

Launcher details can differ across operating systems, shells, and devices. Treat the built-in adapter commands as defaults only. If the real local launcher or invocation shape differs, explore the environment first and then record that machine-specific binding in cli_overrides for a built-in CLI or custom_clis for a fully custom adapter instead of hardcoding a repo-wide path or wrapper assumption.

Custom CLIs may also be defined in the routing policy.

Policy timeout behavior:

• Default probe timeout is 50000 ms.
• Default invoke timeout is 180000 ms.
• Legacy router policies that predate defaults.invoke_timeout_ms are still valid; they inherit the current default invoke timeout instead of failing validation.

Windows launcher notes learned from live routing

• If npm or PATH shims have been removed, bind codex or opencode through cli_overrides to the real executable path instead of assuming codex.cmd or opencode.cmd still exists.
• For codex, point the override at a real codex.exe that supports app-server; keep the routed transport on the native app-server path.
• For opencode, use the dedicated CLI binary such as opencode-cli.exe, not the desktop app wrapper such as OpenCode.exe.
• For simple one-shot kimi shell calls, kimi --quiet --prompt "..." works, but the CLI may still append session metadata like <choice>STOP</choice> and resume instructions.
• When another agent needs machine-readable kimi output, prefer kimi --work-dir "<repo>" --print --output-format stream-json --max-ralph-iterations 0 --prompt "..." and parse only assistant text from the structured stream. Setting max Ralph iterations to 0 keeps one-shot routed tasks from inheriting local loop-control choices such as <choice>STOP</choice>.
• If the caller speaks ACP and wants a persistent server instead of one-shot shell delegation, kimi acp is the supported Kimi ACP entrypoint.
• For simple one-shot opencode shell calls, opencode-cli.exe run "..." works; for machine-readable orchestration, prefer opencode-cli.exe run --format json --dir "<repo>" "...".
• If the caller speaks ACP and wants a persistent server instead of one-shot shell delegation, use opencode-cli.exe acp --cwd "<repo>" rather than the desktop wrapper.
• Pass an explicit working directory when delegating real tasks: kimi uses --work-dir, and opencode uses --dir.
• Use ACP mode only when the upstream caller actually speaks ACP. For normal routed delegation, prefer kimi --print ... or opencode-cli.exe run ....
• ACP server entrypoints for kimi and opencode were verified directly through CLI help on this machine. ACP client/router patterns such as acpx are not assumed available until they are verified in the current environment.