deckhearth/.cursor/rules/model-routing.mdc

---
description: Model tier defaults for the agent pipeline — Composer Standard for architect; fast/Grok for build and audit; Sonnet 5 escalation
alwaysApply: true
---

# Model routing (cost-aware pipeline, v0.7)

Cursor subagent roles in `.cursor/agents/role-*.md` declare a `model:` in frontmatter. **Invoke roles from the Agents dropdown** (or a fresh chat pinned to that role) so the configured model applies. Parent chats on Opus that spawn Task subagents may override role models — see `docs/model-routing-policy.md` (or `docs/agent-context/model-routing-policy.md`).

## Default session model

- **Parent chat (ad hoc work):** `auto` or `composer-2.5-fast`.
- **Escalate to Sonnet 5** (`claude-sonnet-5-thinking-medium`) for failed implementer briefs or architect-flagged security/schema work.
- **Opus** (`claude-4.6-opus-high-thinking`) only when a brief sets `recommended_model: claude-4.6-opus-high-thinking`.
- **Never use Opus 4.7 / xhigh** for routine pipeline work.

## Per-role tiers (canonical, v0.7)

| Tier | Roles | Model |
| --- | --- | --- |
| Standard | architect | `composer-2.5` (Standard mode in picker) |
| Fast | conductor, ia-architect, ui-designer, ux-reviewer, implementer | `composer-2.5-fast` |
| Audit | reviewer, design-system-auditor, a11y-auditor | `cursor-grok-4.5-high` |
| Security | security-auditor | `gpt-5.6-terra-medium` |
| Auto | doc-writer | `auto` |

Read `model_policy:` from the convoy frontmatter when present; it overrides these defaults for that convoy.

## Context discipline (biggest cost lever)

- Implementers and auditors: read **only** the brief + files in `files:` — not the whole convoy, not `prisma/schema.prisma` unless listed.
- Audits: diff + brief only; no repo-wide grep sweeps.
- Stop and ask before any single chat exceeds ~5M tokens; start a fresh scoped chat instead.

## Metrics

After each role, log `model=` and `model_tier=` via `scripts/log-convoy-event.sh` (see each role's Metrics section).