# Model routing

> **This file is the project's answer to "which model runs what."** It is filled once, at first initialization, by `/model-routing` (or `/project-init`), and re-run whenever the model lineup or your plan changes. Everything else in the kit refers to *lanes*, never to a model ID — so the kit survives Cursor's model list changing under it.

## Status

| Field | Value |
| --- | --- |
| Routing filled | **yes** |
| Plan / access | Operator-confirmed suggested split (picker verification pending for lead) |
| Filled on | 2026-08-13 |
| Verified against the model picker | partial — operator accepted profile-table IDs; lead must match picker |

## The four lanes

| Lane | Filled value | Roles that run on it | Best use | Avoid |
| --- | --- | --- | --- | --- |
| **lead** | `grok-4.5` | the Cursor session itself — the model in your picker, not a file | framing, routing, judging evidence, fast-path edits | deep implementation it should have delegated |
| **strong** | `claude-opus-5` | critic · security-auditor · system-steward · planner · gauntlet-critic | adversarial review, security analysis, architecture, gauntlet refereeing, final synthesis | retrieval, boilerplate, deterministic work |
| **mid** | `composer-2.5` | builder · integrator · ux-ui-designer · ux-psychologist | implementation, debugging, ordinary planning, design work | novel high-consequence decisions without review |
| **fast** | `composer-2.5-fast` | scout · verifier · learning-steward | narrow search, running checks, extraction, lesson capture | architecture, ambiguous change, security sign-off |

**Routing test:** can a cheap model succeed given a precise contract and a deterministic verifier? Yes → **fast**. Known-pattern implementation → **mid**. Otherwise → **strong**, then verify independently.

**The referee is never cheaper than the builder.** `gauntlet-critic` sits on the `strong` lane by construction: a referee weaker than the thing it judges rubber-stamps. This is also why `Auto` is disallowed on `strong` — a parity verdict from a router that may have silently downgraded is not a verdict. If the strong lane is collapsed, every parity call needs owner sign-off.

Escalate a role one lane only after a concrete failure at its current lane, and record a permanent escalation in `docs/DECISIONS.md`. When lanes span two vendors, that is a feature: put the second vendor on **cross-model critique** rather than on a second builder.

## The lead lane is a human setting, not a file

This is the one thing Cursor does differently from every other harness in this repo. Subagent models live in frontmatter and are writable. **The lead's model is whatever is selected in the Cursor model picker** — no project file can set it, and no agent can change it.

So the lead row above is a *recorded intent*, not an enforced binding. Three consequences:

1. `/model-routing` asks you to select the lead model in the picker yourself, then records what you chose.
2. The `sessionStart` hook (`.cursor/hooks/session-context.mjs`) reads the model Cursor reports for the session and compares it against this row, so a drifted picker shows up as a line in the session context rather than as a mysteriously expensive week.
3. If you work in **Auto** mode, write `Auto (Cost)`, `Auto (Balance)`, or `Auto (Intelligence)` in the lead row. Auto is a legitimate lead choice — it is not a legitimate `strong` lane, because a router that may downgrade under load cannot be the independent judge the quality gates assume.

## Where the lane values actually land

Filling this table is not the end of the job. `/model-routing` propagates the values, and all three must agree:

1. **This table** — the human-readable contract.
2. **`.cursor/agents/*.md` frontmatter** — each subagent carries `lane: fast|mid|strong` and gets its `model:` line written from that lane. `model: inherit` means "run on whatever the lead is running" — the safe default the kit ships with, not a bug, but also the reason an unbound kit has no cost split at all.
3. **The model picker** — set by you, for the lead lane, and re-checked by the sessionStart hook.

## Model profiles

Cursor manages the model list itself, and it changes with releases. The families below were current when this kit was written (2026-08-11). **Confirm every ID in the model picker before writing it** — an ID that no longer exists fails the Task call rather than degrading gracefully.

| Family | Typical IDs | Fits | Notes |
| --- | --- | --- | --- |
| Cursor Composer | `composer-2.5`, `composer-2.5-fast` | **mid** (Composer), **fast** (Fast) | Cursor's own agentic coding model — trained for exactly the builder/integrator loop, and usually the cheapest capable `mid`. |
| Grok | `grok-4.5`, `grok-4.5-fast` | **mid** or **lead**, **fast** | Cursor-tuned for long-running work; a reasonable lead when sessions are long. |
| Claude | `claude-opus-5`, `claude-fable-5`, `claude-sonnet-5` | **strong** (Opus/Fable), **mid** (Sonnet) | Strongest adversarial-review behavior in this list; the default `strong` pick. |
| GPT | `gpt-5.6-terra`, `gpt-5.6-sol`, `gpt-5.6-luna` | **strong** → **mid** → **fast** | A whole ladder inside one family; useful when you want the cross-model critic to come from elsewhere. |
| Gemini | `gemini-3.1-pro`, `gemini-3.6-flash` | **strong**/**mid**, **fast** | Flash is a strong `fast` lane for search-and-check work. |
| Auto | `Auto (Cost)`, `Auto (Balance)`, `Auto (Intelligence)` | **lead** only | Routes for you; never assign it to `strong` (see above). |

A sensible starting split, if you have no preference: `fast` = `composer-2.5-fast`, `mid` = `composer-2.5`, `strong` = `claude-opus-5` (referee and critic), lead = whatever you already like driving. Confirm all four in the picker.

### Collapsed and constrained lanes

A lane is a *role assignment*, not a promise of four distinct models. Legitimate collapses:

- **One model, four lanes.** Supported. Separation of creation from judgment survives because every subagent gets its own clean context window — but the *capability* asymmetry is gone, so say so below.
- **Two models.** A cheap `fast`/`mid` plus a genuinely strong lane for critic and security-auditor is the highest-value split when budget is tight.
- **Degraded lanes must be recorded.** If `strong` is not genuinely stronger than `mid`, write it in the Notes and treat every high-risk gate as needing a human reviewer — the kit's gates assume an independent, more capable judge exists.

### Notes (this fill)

- Four distinct models; no collapse.
- Cross-vendor critique: Composer builds, Claude Opus judges — intentional.
- Lead recorded as `grok-4.5` from the suggested split (“whatever you already like driving”) matching this init session’s model family. Select it in the picker.

## Change log

| Date | Change | Reason |
| --- | --- | --- |
| 2026-08-13 | initial routing filled — lead `grok-4.5`, strong `claude-opus-5`, mid `composer-2.5`, fast `composer-2.5-fast` | `/project-init`; operator accepted suggested split |
