/model-routing

name: model-routing
description: "Heuristics for choosing the right model tier (haiku/sonnet/opus) when delegating to agents. Loaded by orchestrating commands to inform agent selection."
alwaysApply: true

Model Routing Heuristics

When delegating work to agents, use these signals to select the right model tier. These are heuristics, not hard rules — the user can always override with `--quick` or `--thorough`.

Complexity Signals

| Signal | Simple (haiku/sonnet) | Moderate (sonnet) | Complex (opus) | |--------|----------------------|-------------------|----------------| | **File count** | 1-2 files | 3-8 files | 9+ files | | **Scope** | Single class/method | Single system | Multiple systems | | **Keywords** | "add field", "rename", "fix typo", "remove" | "implement", "refactor", "test" | "architect", "migrate", "optimize", "redesign" | | **Risk level** | No serialization, no networking | Serialization involved | Networking, threading, platform-specific | | **Patterns** | Obvious fix, boilerplate | Requires design choices | Requires trade-off reasoning |

Routing Decision Matrix

Haiku Tier — Fast, Cheap, Read-Only

**Agents:** `unity-scout`, `unity-linter` **Use when:**

• Quick codebase exploration before a larger task
• Fast validation pass (lint-style check)
• Finding files, symbols, or patterns
• Pre-flight checks before delegating to a heavier agent

**Never use for:** Writing code, modifying files, complex reasoning

Sonnet Tier — Balanced Speed/Quality

**Agents:** `unity-coder-lite`, `unity-fixer-lite`, `unity-reviewer`, `unity-test-runner`, `unity-build-runner`, `unity-migrator`, `unity-security-reviewer`, `unity-git-master` **Use when:**

• Single-file changes with clear requirements
• Code review against a known checklist
• Writing tests for existing code
• Build configuration
• Bug fixes where the cause is known or obvious
• Structured tasks with documented procedures (migrations, LFS setup)

Opus Tier — Deep Reasoning

**Agents:** `unity-coder`, `unity-fixer`, `unity-verifier`, `unity-optimizer`, `unity-prototyper`, `unity-shader-dev`, `unity-scene-builder`, `unity-ui-builder`, `unity-network-dev`, `unity-critic` **Use when:**

• Multi-system feature implementation
• Bug investigation requiring deep analysis
• Performance optimization (trade-off reasoning)
• Architecture decisions
• Shader math and visual programming
• Spatial reasoning (scene building)
• Challenging plans (critic role)

Integration with Commands

/unity-workflow — Phase 2 (Plan)

During the Plan phase, evaluate the requirements against the complexity signals above: 1. Count the estimated files to create/modify 2. Check for complexity keywords in the task description 3. Identify risk factors (serialization, networking, platform-specific) 4. Choose the agent tier accordingly:

• Simple requirements → route to `unity-coder-lite` (sonnet)
• Moderate requirements → route to `unity-coder` (opus)
• Complex multi-system → route to multiple agents via `/unity-team`

/unity-team — Agent Selection

When building a team, consider mixing tiers for efficiency:

• Use `unity-scout` (haiku) for the initial project scan
• Use sonnet agents for structured tasks (tests, review)
• Reserve opus agents for the creative/reasoning-heavy work
• The `--quick` flag swaps opus agents for their sonnet equivalents where available

Cost Awareness

| Tier | Relative Cost | Relative Speed | |------|--------------|----------------| | Haiku | 1x | Fastest | | Sonnet | 5x | Fast | | Opus | 25x | Slower |

For iterative work (verify-fix loops), prefer sonnet for early passes and opus for the final judgment pass. This can reduce costs by 50%+ on multi-iteration workflows.