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.