Model Selection

Model Selection

Determines which LLM model to use for each agent spawn.

SCOPE

✅ THIS SKILL PRODUCES:

• A resolved model parameter for every task tool call
• Persistent model preferences in .squad/config.json
• Spawn acknowledgments that include the resolved model

❌ THIS SKILL DOES NOT PRODUCE:

• Code, tests, or documentation
• Model performance benchmarks
• Cost reports or billing artifacts

Context

Squad supports a curated model catalog across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions.

5-Layer Model Resolution Hierarchy

Resolution is first-match-wins — the highest layer with a value wins.

Key principle: Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost.

AGENT WORKFLOW

On Session Start

1. READ .squad/config.json
2. CHECK for defaultModel field — if present, this is the Layer 0 override for all spawns
3. CHECK for agentModelOverrides field — if present, these are per-agent Layer 0a overrides
4. STORE both values in session context for the duration

On Every Agent Spawn

1. CHECK Layer 0a: Is there an agentModelOverrides.{agentName} in config.json? → Use it.
2. CHECK Layer 0b: Is there a defaultModel in config.json? → Use it.
3. CHECK Layer 1: Did the user give a session directive? → Use it.
4. CHECK Layer 2: Does the agent's charter have a ## Model section? → Use it.
5. CHECK Layer 3: Determine task type:

• Code (implementation, tests, refactoring, bug fixes) → gpt-5.6-terra
• Prompts, agent designs → gpt-5.6-terra
• Visual/design with image analysis → gpt-5.6-sol
• Non-code (docs, planning, triage, changelogs) → gpt-5.6-luna

6. FALLBACK Layer 4: gpt-5.6-luna
7. INCLUDE model in spawn acknowledgment: 🔧 {Name} ({resolved_model}) — {task}

When User Sets a Preference

Trigger phrases: "always use X", "use X for everything", "switch to X", "default to X"

1. VALIDATE the model ID against the catalog
2. WRITE defaultModel to .squad/config.json (merge, don't overwrite)
3. ACKNOWLEDGE: ✅ Model preference saved: {model} — all future sessions will use this until changed.

Per-agent trigger: "use X for {agent}"

1. VALIDATE model ID
2. WRITE to agentModelOverrides.{agent} in .squad/config.json
3. ACKNOWLEDGE: ✅ {Agent} will always use {model} — saved to config.

When User Clears a Preference

Trigger phrases: "switch back to automatic", "clear model preference", "use default models"

1. REMOVE defaultModel from .squad/config.json
2. ACKNOWLEDGE: ✅ Model preference cleared — returning to automatic selection.

STOP

After resolving the model and including it in the spawn template, this skill is done. Do NOT:

• Generate model comparison reports
• Run benchmarks or speed tests
• Create new config files (only modify existing .squad/config.json)
• Change the model after spawn (fallback chains handle runtime failures)

Config Schema

.squad/config.json model-related fields:

jsonCopy code
{
  "version": 1,
  "defaultModel": "claude-opus-4.6",
  "agentModelOverrides": {
    "agent-alpha": "claude-sonnet-4.6",
    "agent-beta": "claude-haiku-4.5"
  }
}

• defaultModel — applies to ALL agents unless overridden by agentModelOverrides
• agentModelOverrides — per-agent overrides that take priority over defaultModel
• Both fields are optional. When absent, Layers 1-4 apply normally.

Fallback Chains

If a model is unavailable (rate limit, plan restriction), retry within the same tier:

Copy code
Premium:  gpt-5.6-sol → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6 → (omit model param)
Standard: gpt-5.6-terra → claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-3.1-pro → (omit model param)
Fast:     gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini → (omit model param)

Never fall UP in tier. A fast task won't land on a premium model via fallback.