Repository navigation
fix: align model tier routing and catalog (#1749) - #1750
Conversation
🛫 PR Readiness Check
PR Scope: 📦🔧 Mixed (product + infrastructure)
|
| Status | Check | Details |
|---|---|---|
| ❌ | Single commit | 5 commits — consider squashing before review |
| ✅ | Not in draft | Ready for review |
| ❌ | Branch up to date | dev is 2 commit(s) ahead — rebase recommended |
| ❌ | Copilot review | No Copilot review yet — it may still be processing |
| ✅ | Changeset present | Changeset file found |
| ✅ | Scope clean | |
| ✅ | No merge conflicts | No merge conflicts |
| ✅ | Copilot threads resolved | 3 active Copilot thread(s) resolved (26 outdated skipped) |
| ❌ | CI passing | 6 check(s) still running |
Files Changed (85 files, +1137 −1322)
| File | +/− |
|---|---|
.changeset/lucky-model-routing.md |
+6 −0 |
.copilot/skills/model-selection/SKILL.md |
+36 −36 |
.gitattributes |
+3 −0 |
.github/agents/squad.agent.md |
+1 −1 |
.squad-templates/model-selection-reference.md |
+28 −28 |
.squad-templates/ralph-circuit-breaker.md |
+1 −1 |
.squad-templates/squad.agent.md |
+2 −2 |
.squad/skills/economy-mode/SKILL.md |
+8 −7 |
.squad/skills/model-selection/SKILL.md |
+12 −12 |
.squad/skills/squad-commands/SKILL.md |
+3 −3 |
.squad/skills/squad/SKILL.md |
+3 −3 |
README.md |
+1 −1 |
README.zh.md |
+1 −1 |
docs/_internal/internal/getting-started-journey.md |
+1 −1 |
docs/src/content/docs/concepts/parallel-work.md |
+19 −19 |
docs/src/content/docs/cookbook/recipes.md |
+2 −2 |
docs/src/content/docs/features/loop.md |
+1 −1 |
docs/src/content/docs/features/mcp-frontmatter.md |
+2 −2 |
docs/src/content/docs/features/model-selection.md |
+27 −27 |
docs/src/content/docs/features/ralph.md |
+2 −2 |
docs/src/content/docs/features/remote-control.md |
+3 −3 |
docs/src/content/docs/guide.md |
+1 −1 |
docs/src/content/docs/guide/build-autonomous-agent.md |
+4 −4 |
docs/src/content/docs/reference/api-reference.md |
+9 −9 |
docs/src/content/docs/reference/cli.md |
+3 −3 |
docs/src/content/docs/reference/config.md |
+6 −6 |
docs/src/content/docs/reference/sdk.md |
+193 −511 |
docs/src/content/docs/sample-prompts.md |
+1 −1 |
docs/src/content/docs/scenarios/client-compatibility.md |
+7 −7 |
docs/src/content/docs/scenarios/switching-models.md |
+57 −57 |
docs/src/content/docs/sdk-first-mode.md |
+6 −6 |
packages/squad-cli/src/cli/commands/economy.ts |
+3 −2 |
packages/squad-cli/src/cli/commands/models.ts |
+1 −1 |
packages/squad-cli/templates/model-selection-reference.md |
+28 −28 |
packages/squad-cli/templates/ralph-circuit-breaker.md |
+1 −1 |
packages/squad-cli/templates/skills/economy-mode/SKILL.md |
+8 −7 |
packages/squad-cli/templates/skills/model-selection/SKILL.md |
+12 −12 |
packages/squad-cli/templates/skills/release-process/SKILL.md |
+13 −0 |
packages/squad-cli/templates/skills/squad-commands/SKILL.md |
+3 −3 |
packages/squad-cli/templates/skills/squad/SKILL.md |
+3 −3 |
packages/squad-cli/templates/squad.agent.md.template |
+2 −2 |
packages/squad-sdk/src/agents/model-selector.ts |
+14 −9 |
packages/squad-sdk/src/builders/index.ts |
+3 −3 |
packages/squad-sdk/src/config/models.ts |
+119 −87 |
packages/squad-sdk/src/config/schema.ts |
+7 −7 |
packages/squad-sdk/src/runtime/constants.ts |
+9 −7 |
packages/squad-sdk/templates/model-selection-reference.md |
+28 −28 |
packages/squad-sdk/templates/ralph-circuit-breaker.md |
+1 −1 |
packages/squad-sdk/templates/skills/economy-mode/SKILL.md |
+8 −7 |
packages/squad-sdk/templates/skills/model-selection/SKILL.md |
+12 −12 |
| ... | +35 more files |
Total: +1137 −1322
This check runs automatically on every push. Fix any ❌ items and push again.
See CONTRIBUTING.md and PR Requirements for details.
🔴 Impact Analysis — PR #1750Risk tier: 🔴 CRITICAL 📊 Summary
🎯 Risk Factors
📦 Modules Affectedci-workflows (1 file)
copilot-config (1 file)
docs (18 files)
root (11 files)
scripts (1 file)
squad-cli (10 files)
squad-sdk (13 files)
squad-state (4 files)
templates (3 files)
tests (23 files)
|
|
🏗️ Architectural Review
Automated architectural review — informational only. |
c7776a9 to
d39a5fc
Compare
There was a problem hiding this comment.
Pull request overview
Aligns the SDK/CLI model catalog, tier inference, and fallback routing so that GPT-5.6 Luna leads the fast-tier fallback chain, GPT-5.6 Sol leads premium routing, GPT-5.6 Terra leads standard routing, and Gemini 3.1 Pro replaces the retired Gemini 2.5 Pro across code/tests/templates/docs.
Changes:
- Updated model catalog + tier inference to treat
gpt-5.6-solas premium,gpt-5.6-terraas standard, andgpt-5.6-lunaas fast, with updated default fallback chains (SDK runtime + config defaults). - Replaced
gemini-2.5-prowithgemini-3.1-proeverywhere and added/validatedclaude-opus-5. - Regenerated/updated templates, skills, docs, and tests to match the new routing order and catalog.
Reviewed changes
Copilot reviewed 72 out of 72 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| test/models.test.ts | Updates catalog + fallback-chain assertions for new tiers/models (Sol/Terra/Luna, Gemini 3.1 Pro, Opus 5). |
| test/models-refresh.test.ts | Updates display-name normalization test from Gemini 2.5 Pro to 3.1 Pro. |
| test/model-fallback.test.ts | Updates cross-tier fallback expectations for Sol-first premium and Luna-first fast chain. |
| test/integration.test.ts | Updates integration expectations for premium fallback chain (Sol-first) and whitespace cleanup. |
| test/config-schema.test.ts | Updates default schema tier expectations (fast contains Luna; premium contains Opus 5). |
| test/compat-v041.test.ts | Updates compat tests for new premium/standard/fast chain heads and Opus 5 presence. |
| test/catalog-refresh.test.ts | Refreshes catalog invariants: IDs, chain ordering, and Sol-in-premium assertions. |
| test/agents.test.ts | Updates per-agent model resolution tests for new routing and adds Sol premium classification coverage. |
| templates/model-selection-reference.md | Updates reference template for Opus 5 vision default, Gemini 3.1 Pro, and new fallback chains. |
| packages/squad-sdk/templates/skills/model-selection/SKILL.md | Updates SDK skill doc to match new routing/chains and model set. |
| packages/squad-sdk/templates/model-selection-reference.md | Updates SDK template reference with Opus 5, Gemini 3.1 Pro, and new chains. |
| packages/squad-sdk/src/runtime/constants.ts | Updates runtime fallback chains (Sol/Terra/Luna ordering; Gemini 3.1 Pro). |
| packages/squad-sdk/src/config/schema.ts | Updates DEFAULT_CONFIG tier lists to the new routing policy and catalog. |
| packages/squad-sdk/src/config/models.ts | Updates MODEL_CATALOG entries (tiers, Gemini swap, Opus 5, pricing metadata), fallback chains, and economy map. |
| packages/squad-sdk/src/agents/model-selector.ts | Improves tier inference by preferring catalog-backed tier lookup before heuristics. |
| packages/squad-cli/templates/skills/model-selection/SKILL.md | Updates CLI skill doc to match new routing/chains and model set. |
| packages/squad-cli/templates/model-selection-reference.md | Updates CLI template reference with Opus 5, Gemini 3.1 Pro, and new chains. |
| packages/squad-cli/src/cli/commands/models.ts | Updates inline example comment for Gemini 3.1 Pro normalization. |
| docs/src/content/docs/scenarios/switching-models.md | Updates docs for 17-model catalog and fast fallback emphasis (needs follow-up fixes for tier accuracy/chain presentation). |
| docs/src/content/docs/scenarios/client-compatibility.md | Updates documented fallback chains (currently duplicated premium chain). |
| docs/src/content/docs/features/model-selection.md | Updates model selection docs for 17-model catalog, chains, and economy mode (currently has inconsistencies). |
| docs/src/content/docs/concepts/parallel-work.md | Updates model selection docs and catalog/chains (currently missing Sol in premium list + duplicated premium line). |
| .squad/skills/model-selection/SKILL.md | Updates Squad skill fallback chains to new routing. |
| .squad-templates/model-selection-reference.md | Updates squad template reference with Opus 5/Gemini 3.1 Pro/new chains. |
| .copilot/skills/model-selection/SKILL.md | Updates Copilot skill reference with Opus 5/Gemini 3.1 Pro/new chains. |
| .changeset/lucky-model-routing.md | Adds patch changeset for SDK + CLI reflecting routing/catalog updates. |
Suppressed comments (4)
docs/src/content/docs/features/model-selection.md:99
- This section is labeled "16-Model Catalog" but states 17 models, and the tier lists currently only enumerate 16 (missing
gpt-5.6-sol, which the SDK catalogs as premium). Update the heading and include Sol in the premium list so the count matches.
## 16-Model Catalog
Squad supports 17 models across three tiers:
- **Premium:** claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6
docs/src/content/docs/features/model-selection.md:111
- The fallback-chain snippet shows two different "Premium" chains. Since premium routing now starts with
gpt-5.6-sol, keep a single Premium line to avoid implying there are two separate premium chains.
Premium: claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6
Premium: gpt-5.6-sol → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6
Standard: gpt-5.6-terra → claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-3.1-pro
Fast: gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini
**docs/src/content/docs/concepts/parallel-work.md:151**
* The fallback chain block lists two separate Premium lines, which suggests there are two different premium chains. Since premium routing is GPT Sol first, keep a single Premium line.
Premium: claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6
Premium: gpt-5.6-sol → claude-opus-5 → claude-opus-4.8 → claude-opus-4.7 → claude-opus-4.6 → claude-sonnet-4.6
Standard: gpt-5.6-terra → claude-sonnet-5 → claude-sonnet-4.6 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4.5 → gemini-3.1-pro
Fast: gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini
docs/src/content/docs/scenarios/switching-models.md:162
- The explanatory paragraph below the code block is Opus/Sonnet/Haiku-specific and no longer matches the updated routing (e.g., GPT Sol/Terra/Luna). Update it to a model-agnostic description of what happens when the chain is exhausted.
gpt-5.6-luna → claude-haiku-4.5 → gpt-5.4-mini → gpt-5-mini
If Opus is unavailable (rate limit, quota), Squad automatically uses Sonnet. If Sonnet is unavailable, it falls back to Haiku.
</details>
---
💡 <a href="/bradygaster/squad/new/dev?filename=.github/skills/code-review/SKILL.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add a `code-review` agent skill</a> or configure MCP servers for context-aware, tailored reviews. <a href="https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review#mcp-servers-and-agent-skills" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn more in the docs.</a>
d39a5fc to
0c31f89
Compare
|
sorry guys for such a large PR, i started with just trying to get the models updated and then it scope creeped all over the place, it was just one thing after the other. i am at an 80% vibe, i feel mostly good about this PR, there is a possibility that i dont understand squad good enough, but copilot is my friend. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 75 out of 75 changed files in this pull request and generated 1 comment.
Suppressed comments (3)
Previously missed (3) — in code that hasn't changed since the last review.
docs/src/content/docs/features/model-selection.md:101
- The "17-Model Catalog" premium list omits
gpt-5.6-sol, but the premium fallback chain below starts withgpt-5.6-sol. This is internally inconsistent and could confuse readers about whether Sol is premium-tier.
## 17-Model Catalog
Squad supports 17 models across three tiers:
- **Premium:** claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6
- **Standard:** gpt-5.6-terra, claude-sonnet-5, claude-sonnet-4.6, claude-sonnet-4.5, gpt-5.5, gpt-5.4, gpt-5.3-codex, gemini-3.1-pro
- **Fast/Cheap:** gpt-5.6-luna, claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini
docs/src/content/docs/reference/config.md:167
- The tier table says there are 17 models, but the premium/standard rows omit the new routing heads (
gpt-5.6-solfor premium andgpt-5.6-terrafor standard) and several catalog models (e.g.gpt-5.5,claude-sonnet-4.5,gemini-3.1-pro). This makes the reference inconsistent with the runtime routing and other docs.
| Tier | Models | Use Case |
|------|--------|----------|
| **premium** | claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6 | Architecture, code review |
| **standard** | claude-sonnet-5, claude-sonnet-4.6, gpt-5.4 | Most work |
| **fast** | gpt-5.6-luna, claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini | Triage, logging, quick tasks |
test/catalog-refresh.test.ts:125
- The ordering-invariants comment still says to prefer the newest model at index 0, but the assertions below now enforce a policy-based ordering (GPT-first for premium/standard). Updating the comment will keep the intent clear for future maintenance.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 75 out of 75 changed files in this pull request and generated no new comments.
Suppressed comments (4)
Previously missed (4) — in code that hasn't changed since the last review.
docs/src/content/docs/reference/config.md:167
- This table says “17 models across three tiers”, but the premium row omits
gpt-5.6-sol(now the first premium fallback) and the standard row is only a partial list. Either list all models per tier, or change the wording to indicate examples. Given the rest of the docs list the full 17-model catalog, it looks like the table should be updated to match.
| Tier | Models | Use Case |
|------|--------|----------|
| **premium** | claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6 | Architecture, code review |
| **standard** | claude-sonnet-5, claude-sonnet-4.6, gpt-5.4 | Most work |
| **fast** | gpt-5.6-luna, claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini | Triage, logging, quick tasks |
packages/squad-sdk/src/runtime/constants.ts:22
- This comment still says the fallback chains are ordered “newest per series first”, but the updated chains are now explicitly policy-driven (e.g., GPT-first for premium/standard). Updating the comment will prevent confusion for future edits.
docs/src/content/docs/features/model-selection.md:99 - The “17-Model Catalog” premium list omits
gpt-5.6-sol, but the fallback chain below (and the PR/issue intent) treatsgpt-5.6-solas a premium-tier model and first premium fallback. This makes the catalog section internally inconsistent.
- **Premium:** claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6
packages/squad-sdk/src/config/models.ts:139
- The catalog header comment says the 17-model subset was verified on 2026-07-04, but this same file notes the GPT-5.6 family was observed/reachable on 2026-07-13. The verification date should reflect the most recent catalog refresh to avoid misleading future updates.
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 78 out of 78 changed files in this pull request and generated 6 comments.
Suppressed comments (2)
Previously missed (2) — in code that hasn't changed since the last review.
docs/src/content/docs/features/model-selection.md:101
- The 17-model catalog list omits
gpt-5.6-sol, but the fallback chain immediately below (and SDK/CLI routing) treats it as a premium-tier model. The catalog list should include it to avoid confusing users.
- **Premium:** claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6
- **Standard:** gpt-5.6-terra, claude-sonnet-5, claude-sonnet-4.6, claude-sonnet-4.5, gpt-5.5, gpt-5.4, gpt-5.3-codex, gemini-3.1-pro
- **Fast/Cheap:** gpt-5.6-luna, claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini
docs/src/content/docs/reference/config.md:165
- The model config table’s premium tier list omits
gpt-5.6-sol, but elsewhere (SDK constants/docs) premium routing starts withgpt-5.6-sol. Keeping this table aligned avoids mismatched guidance.
| **premium** | claude-opus-5, claude-opus-4.8, claude-opus-4.7, claude-opus-4.6 | Architecture, code review |
| **standard** | gpt-5.6-terra, claude-sonnet-5, claude-sonnet-4.6, gpt-5.4 | Most work |
| **fast** | gpt-5.6-luna, claude-haiku-4.5, gpt-5.4-mini, gpt-5-mini | Triage, logging, quick tasks |
|
Oh my word, this is harder than what i thought it would be. 728 AIC so far, i feel like i am in over my head :( . This stuff is more complicated than i thought it was, kudo's to you guys. |
|
Good suggestion. I likes this approach, due to the fact GPT-Luna is much better performance and lesser on the cost wise. |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 84 out of 84 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
scripts/generate-api-docs.mjs:58
- The catch block assumes
erris an Error and accesseserr.message, butcatch (err)isunknownand can be a non-Error value. This can throw a secondary error and hide the original TypeDoc failure.
e7a96f2 to
b7142fd
Compare
b3432d0 to
fd520a4
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 84 out of 84 changed files in this pull request and generated 2 comments.
Suppressed comments (1)
templates/model-selection-reference.md:58
- This sentence defines “nuclear fallback” as omitting the model parameter, which conflicts with
MODELS.NUCLEAR_FALLBACKterminology. Rewording here keeps the doc consistent.
718de6d to
3c41681
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 84 out of 84 changed files in this pull request and generated 1 comment.
Suppressed comments (1)
.copilot/skills/model-selection/SKILL.md:64
- This sentence describes
(omit model param)as the "nuclear fallback". Elsewhere in the updated docs it’s described as the "platform default fallback" (letting the platform choose the model). Update this wording for consistency.
`(omit model param)` = call the `task` tool WITHOUT the `model` parameter. The platform uses its built-in default. This is the nuclear fallback — it always works.
Update premium, standard, and fast fallback chains, replace the retired Gemini 2.5 Pro catalog entry, and synchronize model-selection documentation and templates. Closes github#1749 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
3c41681 to
779bdc4
Compare
|
@tamirdresher, i have done my best to try to get the copilot review happy, can you check my PR and see what you think, sorry about it being so massive, i fix 1 thing and then it snowballs into the next thing. |
|
Sure. I'll be back from my vacation next week and will take a look |
@tamirdresher Thank you sir! Shalom. |
…ded deltas This branch forked before github#1788 landed, so merging dev conflicted on two files where the branch was silently carrying a stale-base regression rather than an intended change: - .gitattributes: the branch reverted the github#1788 LF rules (*.mjs, *.js, *.cjs, *.ps1, *.snap and the three shebanged .ts entrypoints). Restored dev's file and re-applied this branch's one real addition, the audit-trail union merge. - scripts/generate-api-docs.mjs: showed as a whole-file rewrite only because the missing *.mjs LF rule let it check out CRLF. Restored dev's LF file and re-applied the real change: execFileSync + Windows relative-path resolution. Net diff against dev for both files is now exactly the two intended deltas. Co-authored-by: Omzig <Omzig@users.noreply.github.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
docs/pagefind.yml and the two storage-provider-azure shell scripts were stored as CRLF blobs while .gitattributes requires LF, so every checkout produced a permanently dirty worktree and blocked merging dev into this branch. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Resolved .gitattributes and scripts/generate-api-docs.mjs by keeping this branch's versions, which already restore dev's content plus the two intended deltas (audit-trail union merge, execFileSync typedoc invocation). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
test/model-selector-policy.test.ts landed on dev via github#1445 after this branch forked, so it still asserted the pre-github#1749 visual mapping (claude-opus-4.6). github#1750 deliberately reroutes visual -> gpt-5.6-sol, consistently across model-selector.ts, lifecycle.test.ts, SKILL.md, templates, and docs. Updates the two stale assertions to match. Ceiling-downgrade target is unchanged (claude-sonnet-4.6), matching test/lifecycle.test.ts:406. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
@Omzig — resolved the conflicts and one stale-base test collision on your branch so this can land. Full disclosure on what I touched, since two of these looked scarier in the diff than they actually were. 1. Your branch forked before #1788 landed, which added LF normalization rules for I took
2. This file landed on I checked before touching it, because "change the test until it's green" is usually the wrong move. Your reroute is deliberate and consistently applied — That was the only red: 2 failures out of 7,752. Verified locally — One thing worth a second look, and it's your call, not mine. The issue body for #1749 says the PR "preserve[s] the \claude-opus-5\ visual/design route," but the shipped behavior sends visual work to Merging once CI is green. |
|
@bradygaster, thank you for doing the touch up on this and getting it merged in, about half way through i almost gave up, i was like, what am i doing!?!?!?!? |
Closes #1749
Summary
Align model catalog metadata, tier inference, fallback routing, and generated documentation across the SDK and CLI.
Changes
gemini-2.5-procatalog entry withgemini-3.1-pro.@bradygaster/squad-sdkand@bradygaster/squad-cli.Validation
gemini-2.5-proreferences remain.