Model Selection

Each subagent has a default model set in its YAML frontmatter. Project-level overrides live in .spexso/config.json. Developers can also override the orchestrator model per session with the --model flag on /spexso-start.

Default model per agent

Agent	Default	Rationale
planner	opus	Complex spec decomposition — quality matters
tester	sonnet	Structured task: acceptance criteria are given
builder	sonnet	Structured task: tests are the spec
reviewer	sonnet	Clear patterns; manually set opus in models.reviewer for L/XL-heavy projects
researcher	sonnet	Synthesis and web search — haiku is too shallow
issue-runner	sonnet	Sequences one issue end-to-end for the marathon — orchestration, not authoring

Size→model dial

The issue's size:: label (xs/s/m/l/xl) maps 1-to-1 to the model used for tester and builder dispatches, via modelBySize in .spexso/config.json:

size::	model (default)
xs, s	sonnet
m, l, xl	opus

The dial beats the per-role models entry for tester/builder; planner and reviewer are never dialed — plan and review quality stay constant regardless of task size. The label is the single source of truth for intensity: dial a task up or down by changing its size:: label, not by editing config. Resolution is mechanical: npx spexso model <role> [size]. Reasoning effort stays static per agent frontmatter (spexso agents sync) — Claude Code has no per-dispatch effort override. Sizes not present in the dial fall through to the per-role models entry (or the role default).

Per-project override

Configure during /spexso-setup or edit directly:

// .spexso/config.json
{
  "targetBranch": "main",
  "models": {
    "planner": "opus",
    "tester": "sonnet",
    "builder": "sonnet",
    "reviewer": "sonnet",
    "researcher": "sonnet"
  }
}

Changes take effect immediately — no restart needed. The orchestrator reads the config before each subagent spawn.

Per-session override

# Override the orchestrator model for this session
/spexso-start 42 --model opus

# Faster and cheaper
/spexso-start 42 --model sonnet

The --model flag overrides the orchestrator only. Subagent models still follow config.json (or their frontmatter defaults if config is missing).