| 1 | # SquadScope Model Routing Policy |
| 2 | |
| 3 | **Effective:** 2026-06-06 |
| 4 | **Issue:** #273 |
| 5 | **Status:** Team Policy |
| 6 | |
| 7 | ## Executive Summary |
| 8 | |
| 9 | This policy defines when SquadScope agents use expensive high-reasoning models (GPT-5.5, GPT-5.3-Codex, Claude Opus) vs. cost-effective models (Claude Haiku, GPT mini). The goal is to **maximize value per dollar** by reserving premium models for work requiring high-quality reasoning, while keeping routine tasks efficient. |
| 10 | |
| 11 | **Governing principle:** Cost first, **unless code is being produced**. Visual/design work always uses premium vision-capable models. Cross-family review assignments reduce correlated blind spots. |
| 12 | |
| 13 | **Pricing source:** [GitHub Copilot Models and Pricing](https://docs.github.com/en/copilot/reference/copilot-billing/models-and-pricing), fetched 2026-06-06. Pricing assumptions must be reviewed every two months. |
| 14 | |
| 15 | The scheduled workflow `.github/workflows/copilot-pricing-review.yml` runs every two months to open or update a review issue when the table is due. It is notification-only and must not change pricing data without a PR. |
| 16 | |
| 17 | --- |
| 18 | |
| 19 | ## Model Selection Hierarchy |
| 20 | |
| 21 | The model selection process follows a 6-layer hierarchy (Layers 0–5 plus fallback chains). The first matching layer wins. |
| 22 | |
| 23 | ### Layer 0: Persistent Configuration |
| 24 | |
| 25 | Read `.squad/config.json` on every session start: |
| 26 | |
| 27 | ```json |
| 28 | { |
| 29 | "version": 1, |
| 30 | "defaultModel": "claude-sonnet-4.6", |
| 31 | "agentModelOverrides": { |
| 32 | "leela": "claude-opus-4.5", |
| 33 | "fry": "claude-haiku-4.5" |
| 34 | } |
| 35 | } |
| 36 | ``` |
| 37 | |
| 38 | - **`defaultModel`:** Applied to all agents unless overridden. Persists across sessions. |
| 39 | - **`agentModelOverrides`:** Agent-specific overrides. Typed as `{agentName: modelString}`. |
| 40 | - **Update when:** User says "always use X" or "use X for {agent}". Save once, apply always. |
| 41 | |
| 42 | ### Layer 1: Session Directive |
| 43 | |
| 44 | Did the user specify a model for **this session only**? Examples: |
| 45 | - "Use GPT-5.5 for this task" |
| 46 | - "Cut costs — use Haiku for everything today" |
| 47 | - "Run a code review with Opus" |
| 48 | |
| 49 | Session directives persist until the session ends or are contradicted. They take precedence over persistent config. |
| 50 | |
| 51 | ### Layer 2: Charter Preference |
| 52 | |
| 53 | Does the agent's charter (in `.squad/agents/{name}/charter.md`) contain a `## Model` section with `Preferred: {model}`? |
| 54 | |
| 55 | Example: |
| 56 | ```markdown |
| 57 | ## Model |
| 58 | |
| 59 | Preferred: claude-opus-4.5 |
| 60 | Rationale: Leela's reviews require sophisticated code analysis. |
| 61 | ``` |
| 62 | |
| 63 | If yes, use that model unless overridden by Layers 0 or 1. |
| 64 | |
| 65 | ### Layer 3: Task-Aware Auto-Selection |
| 66 | |
| 67 | If no override was specified, **determine the task output type** and select accordingly: |
| 68 | |
| 69 | #### Code or Technical Implementation |
| 70 | |
| 71 | **Output type:** Produces code files, code reviews, architecture diagrams, complex technical documentation |
| 72 | **Model selection logic:** |
| 73 | |
| 74 | - **Heavy code generation (500+ lines or multi-file refactor)** → `gpt-5.3-codex` or `claude-sonnet-4.6` (highest code quality) |
| 75 | - **Standard code tasks** → `claude-sonnet-4.6` (balance of quality and speed) |
| 76 | - **Simple scaffolding or boilerplate** → `claude-haiku-4.5` (cost-effective for mechanical code) |
| 77 | |
| 78 | #### Non-Code (Docs, Planning, Analysis, Triage, Logs) |
| 79 | |
| 80 | **Output type:** Markdown docs, decision logs, planning docs, test case definitions, changelog entries, operational reports |
| 81 | **Model selection:** `claude-haiku-4.5` (cost wins when code is not produced) |
| 82 | |
| 83 | #### Visual / Design Work |
| 84 | |
| 85 | **Output type:** Image analysis, UI/UX feedback, design evaluation, visual accessibility |
| 86 | **Model selection:** `claude-opus-4.5` (vision capability required; never downgrade) |
| 87 | |
| 88 | ### Layer 4: Role-to-Model Mapping |
| 89 | |
| 90 | When task-aware selection is active, use this table to resolve defaults for each role: |
| 91 | |
| 92 | | Role | Default Model | Why | Exceptions | |
| 93 | |---|---|---|---| |
| 94 | | **Core Dev / Backend / Frontend** | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen (500+ lines) → `gpt-5.3-codex` | |
| 95 | | **Tester / QA** | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` | |
| 96 | | **Lead / Architect** | *per-task* | Mixed: code review needs quality, planning needs cost | See task-aware rules above | |
| 97 | | **Prompt Engineer** | *per-task* | Prompt design ≈ code work; research is not | Prompt architecture → `claude-sonnet-4.6`; research → `claude-haiku-4.5` | |
| 98 | | **Copilot SDK Expert** | `claude-sonnet-4.6` | Technical analysis often touches code | Pure research → `claude-haiku-4.5` | |
| 99 | | **Designer / Visual** | `claude-opus-4.5` | Vision required; never downgrade | — | |
| 100 | | **DevRel / Writer** | `claude-haiku-4.5` | Docs and writing — not code | — | |
| 101 | | **Scribe / Logger** | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — | |
| 102 | | **Git / Release** | `claude-haiku-4.5` | Mechanical ops (changelogs, tags, version bumps) | — | |
| 103 | |
| 104 | ### Layer 5: Fallback Chains |
| 105 | |
| 106 | If a selected model is unavailable (plan restriction, deprecation, rate limit, org policy), **retry with the next model in the chain**. When degrading from a requested model, acknowledge the change to the user (see **User notification** guidance in Handling Unavailability section below). |
| 107 | |
| 108 | **Fallback chains (in priority order):** |
| 109 | |
| 110 | **Premium chain (Opus/high-reasoning):** |
| 111 | ``` |
| 112 | claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model) |
| 113 | ``` |
| 114 | |
| 115 | **Standard chain (Sonnet/mid-tier):** |
| 116 | ``` |
| 117 | claude-sonnet-4.6 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model) |
| 118 | ``` |
| 119 | |
| 120 | **Fast chain (Haiku/budget):** |
| 121 | ``` |
| 122 | claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini → gpt-5.4-nano → (omit model) |
| 123 | ``` |
| 124 | |
| 125 | `(omit model)` = Call the tool without the `model` parameter. The platform default applies (nuclear fallback — always works). |
| 126 | |
| 127 | **Fallback rules:** |
| 128 | - If user specified a provider (e.g., "use Claude only"), fall back within that provider only |
| 129 | - Never fall back **up** in tier — a fast task should not land on a premium model |
| 130 | - Log fallbacks to `.squad/orchestration-log/` for debugging, but don't surface to user unless asked |
| 131 | - Maximum 3 retries before hitting nuclear fallback |
| 132 | |
| 133 | --- |
| 134 | |
| 135 | ## When to Use GPT-5.5 |
| 136 | |
| 137 | > **Note:** GPT-5.5 is referenced in the model recommendations as a high-cost/high-reasoning choice. Availability varies by Copilot surface and plan (see **Caveats** section below). |
| 138 | |
| 139 | ### Justified Use Cases |
| 140 | |
| 141 | GPT-5.5 is justified when **all** of the following hold: |
| 142 | |
| 143 | 1. **High-reasoning/editorial judgment required:** |
| 144 | - Architectural decisions for multi-agent coordination |
| 145 | - Code reviews where subtle logic errors could have high impact |
| 146 | - Security audits and vulnerability assessment |
| 147 | - Editorial policy decisions for SquadScope (e.g., what constitutes "signal" vs. "noise") |
| 148 | |
| 149 | 2. **Output feeds 3+ downstream agents or components:** |
| 150 | - A decision made by this agent enables or blocks work for multiple teams |
| 151 | - Example: Lead architecture proposal → informs 4 dev team implementations |
| 152 | |
| 153 | 3. **Cost is secondary to quality:** |
| 154 | - The cost of a mistake (slow rework, security issue, architectural debt) exceeds the model cost delta |
| 155 | |
| 156 | ### Not Justified |
| 157 | |
| 158 | GPT-5.5 is **not** justified for: |
| 159 | - Routine code scaffolding or boilerplate generation |
| 160 | - Single-file bug fixes or typo corrections |
| 161 | - Data transformation, JSON parsing, or mechanical renames |
| 162 | - Content generation where quality is "good enough" (not requiring highest judgment) |
| 163 | - Any task where the output is disposable (e.g., draft planning docs that will be replaced) |
| 164 | |
| 165 | ### Mandatory Restrictions |
| 166 | |
| 167 | - **Never use GPT-5.5 for:** Scribe/logging tasks, changelog generation, version bumps, or any mechanical operation |
| 168 | - **Never cascade:** Only one agent per workflow should use GPT-5.5. If two agents in the same workflow both need high reasoning, use GPT-5.5 for the one that feeds the other (upstream agent wins) |
| 169 | |
| 170 | --- |
| 171 | |
| 172 | ## Cross-Family Code Review & Rubber-Duck Rules |
| 173 | |
| 174 | ### When to Use Cross-Family Review |
| 175 | |
| 176 | Use agents from **different model families** (Claude vs. GPT vs. Gemini) when reviewing code to reduce correlated blind spots. |
| 177 | |
| 178 | **Definition of families:** |
| 179 | - **Claude family:** Claude Opus, Claude Sonnet, Claude Haiku |
| 180 | - **GPT family:** GPT-5.x, GPT-4.x, GPT mini |
| 181 | - **Gemini family:** Gemini Pro, Gemini Flash |
| 182 | |
| 183 | ### Review Assignment Policy |
| 184 | |
| 185 | For code reviews and security audits, assign reviewers as follows: |
| 186 | |
| 187 | 1. **Primary reviewer:** Lead or QA agent (per charter; typically highest-reasoning model available) |
| 188 | 2. **Cross-family reviewer:** Agent from a different family as the primary |
| 189 | - If primary is Claude Sonnet → secondary is GPT-5.3-Codex or Gemini Pro |
| 190 | - If primary is GPT-5.3-Codex → secondary is Claude Sonnet or Gemini Pro |
| 191 | - If primary is Gemini → secondary is Claude Sonnet or GPT |
| 192 | |
| 193 | **Example workflow:** |
| 194 | ``` |
| 195 | 1. Leela (Claude Opus) performs primary code review → finds X, Y, Z issues |
| 196 | 2. Fry (GPT-5.3-Codex) performs cross-family review → catches W issue (correlated blind spot) |
| 197 | 3. Result: Combined coverage X, Y, Z, W |
| 198 | ``` |
| 199 | |
| 200 | ### Rubber-Duck Reviews (Lightweight) |
| 201 | |
| 202 | For lightweight code clarity reviews or rubber-duck debugging: |
| 203 | - Use any available model from a **different family** than the code author |
| 204 | - No need to bump to premium if the primary reviewer already covered quality gates |
| 205 | - Example: Fry wrote the code in `claude-sonnet-4.6` context → Farnsworth (Gemini Flash) does rubber-duck for fresh perspective |
| 206 | |
| 207 | ### When Cross-Family Is Not Required |
| 208 | |
| 209 | - Single-developer features with no security implications |
| 210 | - Internal helper functions or tests (lower risk) |
| 211 | - Mechanical changes (renames, version bumps, boilerplate) |
| 212 | - Documentation-only changes |
| 213 | |
| 214 | --- |
| 215 | |
| 216 | ## Model Availability & Caveats |
| 217 | |
| 218 | ### By Copilot Surface |
| 219 | |
| 220 | **GitHub Copilot CLI (command line):** |
| 221 | - All models in standard/fast chains available |
| 222 | - Premium (Claude Opus, GPT-5.5) available if user has Copilot Pro or Business plan |
| 223 | - Haiku and mini models always available |
| 224 | |
| 225 | **GitHub Copilot in VS Code:** |
| 226 | - Standard models available (Claude Sonnet, GPT-5.x) |
| 227 | - Premium limited by plan |
| 228 | - Check VS Code market for current availability |
| 229 | |
| 230 | **GitHub Copilot Chat (web):** |
| 231 | - Limited model availability |
| 232 | - Premium/reasoning models may be restricted to Copilot Pro users |
| 233 | |
| 234 | **GitHub Copilot Coding Agent (cloud autonomous agent mode):** |
| 235 | - Model availability may differ from CLI/Chat depending on cloud agent configuration and plan |
| 236 | - Some models may have per-session or per-day limits |
| 237 | - Consult your cloud agent provisioning docs for availability specifics |
| 238 | |
| 239 | ### By Organization Plan |
| 240 | |
| 241 | | Plan | Models Available | Restrictions | |
| 242 | |---|---|---| |
| 243 | | **Free / Community** | Haiku, GPT mini | No Sonnet or premium; may have rate limits | |
| 244 | | **Copilot Free** | Haiku, GPT mini, Sonnet | No premium (Opus, GPT-5.5); limited requests | |
| 245 | | **Copilot Pro** | All models | Full access; may have per-session limits | |
| 246 | | **Copilot Business** | All models (enterprise rate limit pool) | Full access; shared rate limits per org | |
| 247 | | **GitHub Models API** | Limited pool per provider | Check `models-health` artifact before runs | |
| 248 | |
| 249 | ### Handling Unavailability |
| 250 | |
| 251 | 1. **Preflight check:** Before expensive runs, verify model availability via `models-health` check or test call |
| 252 | 2. **Fallback chain:** Use the fallback chain defined above (Layer 5) when a model is unavailable |
| 253 | 3. **Degradation logging:** Log degradation to `.squad/orchestration-log/` for audit trail |
| 254 | 4. **User notification:** If a task must degrade from requested model, acknowledge: *"Using {fallback_model} — {primary_model} unavailable on current plan."* |
| 255 | |
| 256 | ### Plan-Specific Guidance for SquadScope |
| 257 | |
| 258 | **SquadScope weekly analysis runs on:** GitHub Actions with Copilot CLI. GitHub Models/OpenAI fallback is not configured for analysis; Copilot failures fail closed or produce publish-ineligible diagnostic artifacts for operator triage. |
| 259 | **Assumed availability:** |
| 260 | - Claude Sonnet 4.6, Claude Haiku 4.5 |
| 261 | - GPT-5.3-Codex, GPT-5.4, GPT-5.4 mini, GPT-5 mini |
| 262 | - Gemini 3.1 Pro, Gemini 3 Flash, Gemini 3.5 Flash |
| 263 | |
| 264 | **High-cost operations** (analysis, reskill, complex code reviews): |
| 265 | - Check model availability before spawning |
| 266 | - Prefer Haiku for routine map/reduce tasks |
| 267 | - Use Sonnet for code writing; reserve Opus/GPT-5.5 for judgment calls only |
| 268 | |
| 269 | --- |
| 270 | |
| 271 | ## Configuration Examples |
| 272 | |
| 273 | ### Example 1: Cost-Focused Config |
| 274 | |
| 275 | ```json |
| 276 | { |
| 277 | "version": 1, |
| 278 | "defaultModel": "claude-haiku-4.5" |
| 279 | } |
| 280 | ``` |
| 281 | |
| 282 | All agents default to Haiku unless overridden by task type or charter. |
| 283 | |
| 284 | ### Example 2: Premium-Biased Config (for editorial/reasoning work) |
| 285 | |
| 286 | ```json |
| 287 | { |
| 288 | "version": 1, |
| 289 | "defaultModel": "claude-sonnet-4.6", |
| 290 | "agentModelOverrides": { |
| 291 | "leela": "claude-opus-4.5", |
| 292 | "fry": "gpt-5.3-codex" |
| 293 | } |
| 294 | } |
| 295 | ``` |
| 296 | |
| 297 | Leela (Lead) and Fry (code reviewer) get premium; others get Sonnet. |
| 298 | |
| 299 | ### Example 3: Mixed Config (typical for SquadScope) |
| 300 | |
| 301 | ```json |
| 302 | { |
| 303 | "version": 1, |
| 304 | "defaultModel": "claude-sonnet-4.6", |
| 305 | "agentModelOverrides": { |
| 306 | "bender": "claude-opus-4.5", |
| 307 | "scribe": "claude-haiku-4.5", |
| 308 | "ralph": "claude-haiku-4.5" |
| 309 | } |
| 310 | } |
| 311 | ``` |
| 312 | |
| 313 | Developers (Bender) and decision-makers (Leela/implicit) get Sonnet; review/coordination (Bender with Opus for complex reviews) gets premium; logging/monitoring (Scribe/Ralph) always budget. |
| 314 | |
| 315 | --- |
| 316 | |
| 317 | ## Decision Log & Rationale |
| 318 | |
| 319 | ### Principle: Cost First, Unless Code |
| 320 | |
| 321 | Copilot compute cost is measured per token and model tier. Within the same session: |
| 322 | - Deploying Opus instead of Sonnet costs ~3-4x more per token |
| 323 | - For non-code tasks (docs, planning, logs), token count is low → cost difference is negligible, but quality difference is also negligible |
| 324 | - For code tasks, quality difference is material (fewer bugs, better architecture) and value of better code > cost delta |
| 325 | |
| 326 | **Decision:** Haiku for all non-code. Sonnet/Codex for code. Opus/GPT-5 only for high-judgment work that feeds downstream decisions. |
| 327 | |
| 328 | ### Principle: Cross-Family Review Reduces Correlated Blind Spots |
| 329 | |
| 330 | Research in model behavior shows that different model families (Claude, GPT, Gemini) have different strengths: |
| 331 | - Claude excels at structured reasoning and following complex constraints |
| 332 | - GPT excels at diverse patterns and few-shot adaptation |
| 333 | - Gemini excels at multimodal tasks and certain low-resource languages |
| 334 | |
| 335 | **Decision:** Major code reviews and security audits should use 2 reviewers from different families. This catches blind spots unique to any single family. |
| 336 | |
| 337 | ### Principle: Rubber-Duck Is Cheap |
| 338 | |
| 339 | Rubber-duck reviews (explaining code to catch logic errors) benefit from: |
| 340 | - A fresh perspective (different agent, different training) |
| 341 | - Lower consequence (it's not a gate, just a check) |
| 342 | - High review velocity (ask all available reviewers) |
| 343 | |
| 344 | **Decision:** Assign rubber-duck reviews to any available model from a different family. No need to bump to premium. |
| 345 | |
| 346 | ### Principle: Editorial Judgment Requires Premium |
| 347 | |
| 348 | SquadScope's weekly analysis applies editorial judgment (signal vs. noise, trend significance). This judgment: |
| 349 | - Affects downstream publication and reader trust |
| 350 | - Cannot be easily validated or corrected |
| 351 | - Benefits from highest-reasoning capability |
| 352 | |
| 353 | **Decision:** Use GPT-5.5 or Claude Opus for analysis decisions that become published content. Use Sonnet for draft versions and candidate analysis. Use Haiku for data transformation and boilerplate only. |
| 354 | |
| 355 | --- |
| 356 | |
| 357 | ## FAQ |
| 358 | |
| 359 | ### Q: Can I force a specific model for all my work? |
| 360 | |
| 361 | **A:** Yes. Set `defaultModel` in `.squad/config.json`, or specify a session directive ("use GPT-5.5 for this session"). The Lead can also update agent charters to pin specific models to specific agents. |
| 362 | |
| 363 | ### Q: What if my org doesn't have access to GPT-5.5? |
| 364 | |
| 365 | **A:** Use the fallback chain. If GPT-5.5 is unavailable, it will fall back to `claude-sonnet-4.6` or `gpt-5.3-codex`. You'll get slightly lower quality but the same output type. Check `.squad/orchestration-log/` to see which model was actually used. |
| 366 | |
| 367 | ### Q: Should I always use premium for code reviews? |
| 368 | |
| 369 | **A:** No. Use premium (Opus/GPT-5.5) for code reviews when: |
| 370 | 1. The code impacts security or architectural stability, OR |
| 371 | 2. The code feeds downstream work for 3+ agents, OR |
| 372 | 3. You explicitly want cross-family review |
| 373 | Otherwise, Sonnet is sufficient for routine PRs. |
| 374 | |
| 375 | ### Q: Can I use different models for the same agent on different days? |
| 376 | |
| 377 | **A:** Yes. Session directives override persistent config. If you say "use Haiku today", it applies for this session only. The persistent config resumes tomorrow. Temporary overrides don't require config changes. |
| 378 | |
| 379 | ### Q: How do I know if a model is available? |
| 380 | |
| 381 | **A:** Check your Copilot surface docs or contact your account manager: |
| 382 | - **CLI users:** Run `gh copilot models list` to see available models on your plan |
| 383 | - **VS Code users:** Check the model selector in the Copilot Chat interface |
| 384 | - **GitHub Models API users:** Consult the GitHub Models availability page for current supported models |
| 385 | - **Business/Enterprise:** Contact your GitHub account team for plan-specific model access |
| 386 | |
| 387 | --- |
| 388 | |
| 389 | ## Approval & Governance |
| 390 | |
| 391 | **Owner:** Lead Architect (Leela) |
| 392 | **Last Updated:** 2026-06-06 |
| 393 | **Review Cycle:** Every two months for pricing assumptions (next: 2026-08-06); broader routing policy quarterly. |
| 394 | **Changes Require:** Issue + consensus from development team |
| 395 | |
| 396 | This policy is **descriptive** (documents current practice) and **prescriptive** (governs future decisions). Changes to this policy should be reflected in both `.squad/config.json` (if persistent config changes) and this document (for governance/principle changes). |