From c335a295116842f2c5d148be2c4d77a10302f9c7 Mon Sep 17 00:00:00 2001
From: mpaulosky <60372079+mpaulosky@users.noreply.github.com>
Date: Sun, 19 Apr 2026 09:40:17 -0700
Subject: [PATCH 1/4] docs(squad): align model and roster guidance (#20)

Align squad model-selection guidance with the active task-aware policy,
then reconcile roster, routing, and casting metadata with the current
charters and review workflow.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .copilot/skills/client-compatibility/SKILL.md |  2 +-
 .copilot/skills/economy-mode/SKILL.md         |  6 ++--
 .copilot/skills/model-selection/SKILL.md      |  4 +--
 .github/agents/squad.agent.md                 | 36 +++++++++----------
 .squad/agents/aragorn/charter.md              |  3 +-
 .squad/agents/boromir/charter.md              |  5 +--
 .squad/agents/gandalf/charter.md              |  3 +-
 .squad/agents/gimli/charter.md                |  2 +-
 .squad/agents/legolas/charter.md              |  2 +-
 .squad/agents/sam/charter.md                  |  2 +-
 .squad/casting/registry.json                  | 12 +++----
 .squad/routing.md                             | 14 ++++----
 .squad/team.md                                |  6 ++--
 .squad/templates/squad.agent.md               | 36 +++++++++----------
 14 files changed, 68 insertions(+), 65 deletions(-)

diff --git a/.copilot/skills/client-compatibility/SKILL.md b/.copilot/skills/client-compatibility/SKILL.md
index da3e9460..fc553baa 100644
--- a/.copilot/skills/client-compatibility/SKILL.md
+++ b/.copilot/skills/client-compatibility/SKILL.md
@@ -58,7 +58,7 @@ The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitH
 **Example 1: CLI parallel spawn**
 ```typescript
 // Coordinator detects task tool available → CLI mode
-task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... })
+task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.6", ... })
 task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... })
 // Later: read_agent for both
 ```
diff --git a/.copilot/skills/economy-mode/SKILL.md b/.copilot/skills/economy-mode/SKILL.md
index 696e778c..346d86b4 100644
--- a/.copilot/skills/economy-mode/SKILL.md
+++ b/.copilot/skills/economy-mode/SKILL.md
@@ -40,10 +40,10 @@ When economy mode is **active**, Layer 3 auto-selection uses this table instead
 
 | Task Output | Normal Mode | Economy Mode |
 |-------------|-------------|--------------|
-| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
-| Writing prompts or agent designs | `claude-sonnet-4.5` | `gpt-4.1` or `gpt-5-mini` |
+| Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.6` | `gpt-4.1` or `gpt-5-mini` |
+| Writing prompts or agent designs | `claude-sonnet-4.6` | `gpt-4.1` or `gpt-5-mini` |
 | Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` |
-| Architecture, code review, security audits | `claude-opus-4.5` | `claude-sonnet-4.5` |
+| Architecture, code review, security audits | `claude-opus-4.6` | `claude-sonnet-4.6` |
 | Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` |
 
 **Prefer `gpt-4.1` over `gpt-5-mini`** when the task involves structured output or agentic tool use. Prefer `gpt-5-mini` for pure text generation tasks where latency matters.
diff --git a/.copilot/skills/model-selection/SKILL.md b/.copilot/skills/model-selection/SKILL.md
index 4c6866fd..6faa30bf 100644
--- a/.copilot/skills/model-selection/SKILL.md
+++ b/.copilot/skills/model-selection/SKILL.md
@@ -109,9 +109,9 @@ After resolving the model and including it in the spawn template, this skill is
 If a model is unavailable (rate limit, plan restriction), retry within the same tier:
 
 ```
-Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.6
+Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5
 Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4
-Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-4.1 → gpt-5-mini
 ```
 
 **Never fall UP in tier.** A fast task won't land on a premium model via fallback.
diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 32704d61..8ccb3928 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -356,21 +356,21 @@ Before spawning an agent, determine which model to use. Check these layers in or
 
 | Task Output | Model | Tier | Rule |
 |-------------|-------|------|------|
-| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. |
-| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. |
+| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. |
+| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. |
 | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. |
-| Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. |
+| Visual/design work requiring image analysis | `claude-opus-4.6` | Premium | Vision capability required. Overrides cost rule. |
 
 **Role-to-model mapping** (applying cost-first principle):
 
 | Role | Default Model | Why | Override When |
 |------|--------------|-----|---------------|
-| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` |
-| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` |
-| Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku |
+| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` |
+| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` |
+| Lead / Architect | auto (per-task) | Mixed: review needs depth, planning needs cost | Architecture proposals or reviewer gates → premium; triage/planning → haiku |
 | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku |
-| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` |
-| Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
+| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` |
+| Designer / Visual | `claude-opus-4.6` | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
 | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — |
 | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) |
 | Git / Release | `claude-haiku-4.5` | Mechanical ops — changelogs, tags, version bumps | — (never bump mechanical ops) |
@@ -378,7 +378,7 @@ Before spawning an agent, determine which model to use. Check these layers in or
 **Task complexity adjustments** (apply at most ONE — no cascading):
 - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents)
 - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps
-- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines)
+- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines)
 - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection
 
 **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced.
@@ -388,9 +388,9 @@ Before spawning an agent, determine which model to use. Check these layers in or
 If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback.
 
 ```
-Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param)
-Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param)
-Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param)
+Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param)
+Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4 → gpt-5.2 → (omit model param)
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-4.1 → gpt-5-mini → (omit model param)
 ```
 
 `(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.
@@ -413,7 +413,7 @@ prompt: |
   ...
 ```
 
-Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default.
+Only set `model` when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
 
 If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
 
@@ -422,8 +422,8 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m
 When spawning, include the model in your acknowledgment:
 
 ```
-🔧 Fenster (claude-sonnet-4.5) — refactoring auth module
-🎨 Redfoot (claude-opus-4.5 · vision) — designing color system
+🔧 Fenster (claude-sonnet-4.6) — refactoring auth module
+🎨 Redfoot (claude-opus-4.6 · vision) — designing color system
 📋 Scribe (claude-haiku-4.5 · fast) — logging session
 ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal
 📝 McManus (claude-haiku-4.5 · fast) — updating docs
@@ -433,9 +433,9 @@ Include tier annotation only when the model was bumped or a specialist was chose
 
 **Valid models (current platform catalog):**
 
-Premium: `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5`
-Standard: `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview`
-Fast/Cheap: `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1`
+Premium: `claude-opus-4.7`, `claude-opus-4.6`, `claude-opus-4.5`
+Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gemini-3-pro-preview`
+Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5-mini`, `gpt-4.1`
 
 ### Client Compatibility
 
diff --git a/.squad/agents/aragorn/charter.md b/.squad/agents/aragorn/charter.md
index 7112dc28..09e77d2a 100644
--- a/.squad/agents/aragorn/charter.md
+++ b/.squad/agents/aragorn/charter.md
@@ -35,7 +35,8 @@ You are Aragorn, the Lead Developer on the {ProjectName} project. You own archit
 
 ## Model
 Preferred: auto
-- Code review, architecture decisions → claude-sonnet-4.5
+- Architecture proposals, reviewer gates → claude-opus-4.6
+- Code review, design-heavy implementation work → claude-sonnet-4.6
 - Triage, planning, issue routing → claude-haiku-4.5
 
 ## Critical Rules
diff --git a/.squad/agents/boromir/charter.md b/.squad/agents/boromir/charter.md
index 4f32fbbb..7b06d013 100644
--- a/.squad/agents/boromir/charter.md
+++ b/.squad/agents/boromir/charter.md
@@ -29,5 +29,6 @@ You are Boromir, the DevOps engineer on the {ProjectName} project. You own CI/CD
 4. Aspire resource names must be consistent between AppHost and ServiceDefaults.
 
 ## Model
-Preferred: claude-haiku-4.5 (mostly config/YAML — not application code)
-Override: claude-sonnet-4.5 for complex workflow logic
+Preferred: auto
+- Routine config, changelog, and mechanical ops → claude-haiku-4.5
+- Complex workflow, AppHost, and CI logic → claude-sonnet-4.6
diff --git a/.squad/agents/gandalf/charter.md b/.squad/agents/gandalf/charter.md
index 6bfbe3c5..8cd2f0b3 100644
--- a/.squad/agents/gandalf/charter.md
+++ b/.squad/agents/gandalf/charter.md
@@ -4,7 +4,8 @@
 You are Gandalf, the Security Officer for {ProjectName}. Your squad label is **squad:gandalf** and your emoji is 🔒 Security.
 
 ## Model
-- **Preferred:** auto (standard for code/config, fast for analysis)
+- **Preferred:** auto (premium for security audits and review gates,
+  standard for remediation changes, fast for triage)
 
 ## Mission
 Guard {ProjectName} against security threats. Ensure authentication and authorization are correctly implemented using Auth0. Audit the application for vulnerabilities — SQL injection, XSS, CSRF, insecure endpoints, improper authorization boundaries, secrets in code, and any other intrusion vector. Make the application hostile to attackers and welcoming only to authorized users.
diff --git a/.squad/agents/gimli/charter.md b/.squad/agents/gimli/charter.md
index f8fa865b..3d4000c2 100644
--- a/.squad/agents/gimli/charter.md
+++ b/.squad/agents/gimli/charter.md
@@ -43,4 +43,4 @@ You are Gimli, the Tester on the {ProjectName} project. You own unit tests, inte
 8. File-scoped namespaces, tab indentation
 
 ## Model
-Preferred: claude-sonnet-4.5 (writes test code)
+Preferred: auto (test authoring resolves to claude-sonnet-4.6)
diff --git a/.squad/agents/legolas/charter.md b/.squad/agents/legolas/charter.md
index 49e9d80d..a76dcc36 100644
--- a/.squad/agents/legolas/charter.md
+++ b/.squad/agents/legolas/charter.md
@@ -49,7 +49,7 @@ Before working on any theme, dark/light mode, FOUC, localStorage, or color palet
 Key patterns it covers: unified `tailwind-color-theme` storage key, anti-FOUC IIFE placement in `<head>`, Blazor navigation hooks (`enhancedload` + `blazor:navigated`), MutationObserver guard, and `themeManager` JS object coordination.
 
 ## Model
-Preferred: claude-sonnet-4.5 (writes code)
+Preferred: auto (frontend implementation resolves to claude-sonnet-4.6)
 
 ## Naming Conventions
 - Component files: `{Name}Component.razor`
diff --git a/.squad/agents/sam/charter.md b/.squad/agents/sam/charter.md
index b832686e..414aac3d 100644
--- a/.squad/agents/sam/charter.md
+++ b/.squad/agents/sam/charter.md
@@ -30,4 +30,4 @@ You are Sam, the Backend Developer on the {ProjectName} project. You own MongoDB
 - Some repositories use `{Entity}Dto` directly while others use domain Models
 
 ## Model
-Preferred: claude-sonnet-4.5 (writes code)
+Preferred: auto (backend implementation resolves to claude-sonnet-4.6)
diff --git a/.squad/casting/registry.json b/.squad/casting/registry.json
index 595e8d62..6a9a70da 100644
--- a/.squad/casting/registry.json
+++ b/.squad/casting/registry.json
@@ -52,19 +52,19 @@
     },
     {
       "name": "Gandalf",
-      "role": "Reviewer",
+      "role": "Security / Auth",
       "legacy_named": true,
       "status": "active",
       "charter_path": ".squad/agents/gandalf/charter.md",
-      "notes": "Code review gate, quality"
+      "notes": "Auth, secrets, vulnerability review"
     },
     {
       "name": "Frodo",
-      "role": "Security",
+      "role": "Tech Writer",
       "legacy_named": true,
       "status": "active",
       "charter_path": ".squad/agents/frodo/charter.md",
-      "notes": "Auth, secrets, vulnerabilities"
+      "notes": "XML docs, README, CONTRIBUTING"
     },
     {
       "name": "Pippin",
@@ -76,11 +76,11 @@
     },
     {
       "name": "Bilbo",
-      "role": "Research",
+      "role": "Tech Blogger",
       "legacy_named": true,
       "status": "active",
       "charter_path": ".squad/agents/bilbo/charter.md",
-      "notes": "Spikes, POCs, investigations"
+      "notes": "Blog posts, release posts, GitHub Pages content"
     },
     {
       "name": "Ralph",
diff --git a/.squad/routing.md b/.squad/routing.md
index 211b306f..dc0f56ec 100644
--- a/.squad/routing.md
+++ b/.squad/routing.md
@@ -11,11 +11,11 @@ How to decide who handles what.
 | Blazor UI, components, features, layout | Legolas | Feature slices, pages, components, Auth UI, NavMenu |
 | Unit, Architecture & Integration tests | Gimli | xUnit, FluentAssertions, NSubstitute, NetArchTest, coverage |
 | CI/CD, build pipeline, Aspire config, infra | Boromir | GitHub Actions workflows, AppHost resources, Docker |
-| Code review gate, quality assurance | Gandalf | PR approval/rejection, coding standards, pattern enforcement |
-| Auth0, security, secrets management | Frodo | Auth0 roles, Management API, token claims, secrets |
+| Security review, Auth0, secrets management | Gandalf | Auth0 roles, token claims, secrets, vulnerability review |
+| Tech writing, XML docs, API docs | Frodo | XML docs, inline comments, API docs, focused README updates |
 | Docs, README, ADRs, changelogs, summaries | Pippin | README.md, ARCHITECTURE.md, CONTRIBUTING.md, release notes |
-| Research, spikes, POCs, library evaluation | Bilbo | Technology comparisons, proof-of-concept prototypes |
-| Code review | Gandalf | Review PRs, check quality, suggest improvements |
+| Developer blog, release posts, GitHub Pages content | Bilbo | `docs/blog/`, release summaries, GitHub Pages updates |
+| Code review | Aragorn | Review PRs, check quality, suggest improvements |
 | Testing | Gimli | Write tests, find edge cases, verify fixes |
 | Scope & priorities | Aragorn | What to build next, trade-offs, decisions |
 | Session logging | Scribe | Automatic — never needs routing |
@@ -43,9 +43,9 @@ spawn prompt:
 | Domain | Asset | When to Inject |
 |--------|-------|----------------|
 | Blazor Tailwind theming, dark/light mode, FOUC, localStorage, color themes | `.squad/skills/blazor-tailwind-theme-persistence/SKILL.md` | Any Legolas task touching App.razor, NavMenu, MainLayout, theme toggle, or `tailwind-color-theme` storage key |
-| Auth0 Management API, M2M, role operations | `.squad/skills/auth0-management-api/SKILL.md` | Any Frodo or Legolas task touching UserManagementHandler, role operations, Management API integration, or Auth0 configuration changes. Owner: Frodo (Tech Writer). |
-| Auth0 security, secrets, authorization | `.squad/skills/auth0-management-security/SKILL.md` | Any security audit, secrets review, or auth configuration change. All squad members reference this for authorization boundary and secrets management rules. Owner: Frodo (Tech Writer). |
-| MongoDB DBA patterns, runtime wiring, indexing | `.squad/skills/mongodb-dba-patterns/SKILL.md` | Any Sam, Gimli, Boromir, or Frodo task touching Mongo wiring, mapping, indexing, backups, upgrades, or shared environment hardening. Owner: Sam (Backend). Audience: Gimli (verification), Boromir (environment), Frodo (secrets/TLS). |
+| Auth0 Management API, M2M, role operations | `.squad/skills/auth0-management-api/SKILL.md` | Any Gandalf or Legolas task touching UserManagementHandler, role operations, Management API integration, or Auth0 configuration changes. Owner: Gandalf (Security). |
+| Auth0 security, secrets, authorization | `.squad/skills/auth0-management-security/SKILL.md` | Any security audit, secrets review, or auth configuration change. All squad members reference this for authorization boundary and secrets management rules. Owner: Gandalf (Security). |
+| MongoDB DBA patterns, runtime wiring, indexing | `.squad/skills/mongodb-dba-patterns/SKILL.md` | Any Sam, Gimli, Boromir, or Gandalf task touching Mongo wiring, mapping, indexing, backups, upgrades, or shared environment hardening. Owner: Sam (Backend). Audience: Gimli (verification), Boromir (environment), Gandalf (secrets/TLS). |
 | MongoDB filter patterns, list queries, caching | `.squad/skills/mongodb-filter-pattern/SKILL.md` | Any Sam or Gimli task touching query contracts, cache-key changes, list filtering, repository standardization, or handler-level caching. Owner: Sam (Backend). Supporting: Gimli (Tester). |
 | Mongo-backed integration tests | `.squad/skills/testcontainers-shared-fixture/SKILL.md` | Any Gimli or Sam task touching `tests/Integration.Tests/`, `MongoDbFixture`, collection definitions, or new repository/handler integration coverage against MongoDB. Owner: Gimli (Tester). |
 | Running-browser UI verification | `.squad/skills/webapp-testing/SKILL.md` | Any Gimli or Legolas task that already has bUnit coverage but still needs runtime verification of JS interop, Auth0 redirects, or AppHost smoke behavior. Do **not** inject this for ordinary unit/bUnit work or to create a new browser-test project. Owner: Gimli (Tester). |
diff --git a/.squad/team.md b/.squad/team.md
index e72f224e..14cf7a0f 100644
--- a/.squad/team.md
+++ b/.squad/team.md
@@ -17,10 +17,10 @@
 | Legolas | Frontend / Blazor | Blazor Server UI, components | Active |
 | Gimli | Tester | Unit, Architecture & Integration tests | Active |
 | Boromir | DevOps / Infra | CI/CD, Aspire config, Docker | Active |
-| Gandalf | Reviewer | Code review gate, quality | Active |
-| Frodo | Security | Auth, secrets, vulnerabilities | Active |
+| Gandalf | Security / Auth | Auth, secrets, vulnerability review | Active |
+| Frodo | Tech Writer | XML docs, README, CONTRIBUTING | Active |
 | Pippin | Docs | Summaries, ADRs, changelogs | Active |
-| Bilbo | Research | Spikes, POCs, investigations | Active |
+| Bilbo | Tech Blogger | Blog posts, release posts, GitHub Pages | Active |
 | Ralph | Meta | Squad maintenance | Active |
 | Scribe | Scribe | Logs and records | Active |
 
diff --git a/.squad/templates/squad.agent.md b/.squad/templates/squad.agent.md
index 2dfbd064..2d5d0388 100644
--- a/.squad/templates/squad.agent.md
+++ b/.squad/templates/squad.agent.md
@@ -356,21 +356,21 @@ Before spawning an agent, determine which model to use. Check these layers in or
 
 | Task Output | Model | Tier | Rule |
 |-------------|-------|------|------|
-| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.5` | Standard | Quality and accuracy matter for code. Use standard tier. |
-| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | Standard | Prompts are executable — treat like code. |
+| Writing code (implementation, refactoring, test code, bug fixes) | `claude-sonnet-4.6` | Standard | Quality and accuracy matter for code. Use standard tier. |
+| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.6` | Standard | Prompts are executable — treat like code. |
 | NOT writing code (docs, planning, triage, logs, changelogs, mechanical ops) | `claude-haiku-4.5` | Fast | Cost first. Haiku handles non-code tasks. |
-| Visual/design work requiring image analysis | `claude-opus-4.5` | Premium | Vision capability required. Overrides cost rule. |
+| Visual/design work requiring image analysis | `claude-opus-4.6` | Premium | Vision capability required. Overrides cost rule. |
 
 **Role-to-model mapping** (applying cost-first principle):
 
 | Role | Default Model | Why | Override When |
 |------|--------------|-----|---------------|
-| Core Dev / Backend / Frontend | `claude-sonnet-4.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` |
-| Tester / QA | `claude-sonnet-4.5` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` |
-| Lead / Architect | auto (per-task) | Mixed: code review needs quality, planning needs cost | Architecture proposals → premium; triage/planning → haiku |
+| Core Dev / Backend / Frontend | `claude-sonnet-4.6` | Writes code — quality first | Heavy code gen → `gpt-5.3-codex` |
+| Tester / QA | `claude-sonnet-4.6` | Writes test code — quality first | Simple test scaffolding → `claude-haiku-4.5` |
+| Lead / Architect | auto (per-task) | Mixed: review needs depth, planning needs cost | Architecture proposals or reviewer gates → premium; triage/planning → haiku |
 | Prompt Engineer | auto (per-task) | Mixed: prompt design is like code, research is not | Prompt architecture → sonnet; research/analysis → haiku |
-| Copilot SDK Expert | `claude-sonnet-4.5` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` |
-| Designer / Visual | `claude-opus-4.5` | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
+| Copilot SDK Expert | `claude-sonnet-4.6` | Technical analysis that often touches code | Pure research → `claude-haiku-4.5` |
+| Designer / Visual | `claude-opus-4.6` | Vision-capable model required | — (never downgrade — vision is non-negotiable) |
 | DevRel / Writer | `claude-haiku-4.5` | Docs and writing — not code | — |
 | Scribe / Logger | `claude-haiku-4.5` | Mechanical file ops — cheapest possible | — (never bump Scribe) |
 | Git / Release | `claude-haiku-4.5` | Mechanical ops — changelogs, tags, version bumps | — (never bump mechanical ops) |
@@ -378,7 +378,7 @@ Before spawning an agent, determine which model to use. Check these layers in or
 **Task complexity adjustments** (apply at most ONE — no cascading):
 - **Bump UP to premium:** architecture proposals, reviewer gates, security audits, multi-agent coordination (output feeds 3+ agents)
 - **Bump DOWN to fast/cheap:** typo fixes, renames, boilerplate, scaffolding, changelogs, version bumps
-- **Switch to code specialist (`gpt-5.2-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines)
+- **Switch to code specialist (`gpt-5.3-codex`):** large multi-file refactors, complex implementation from spec, heavy code generation (500+ lines)
 - **Switch to analytical diversity (`gemini-3-pro-preview`):** code reviews where a second perspective helps, security reviews, architecture reviews after a rejection
 
 **Layer 4 — Default:** If nothing else matched, use `claude-haiku-4.5`. Cost wins when in doubt, unless code is being produced.
@@ -388,9 +388,9 @@ Before spawning an agent, determine which model to use. Check these layers in or
 If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback.
 
 ```
-Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param)
-Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param)
-Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (omit model param)
+Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param)
+Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4 → gpt-5.2 → (omit model param)
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-4.1 → gpt-5-mini → (omit model param)
 ```
 
 `(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.
@@ -413,7 +413,7 @@ prompt: |
   ...
 ```
 
-Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, you MAY omit the `model` parameter — the platform uses it as default.
+Only set `model` when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
 
 If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
 
@@ -422,8 +422,8 @@ If you've exhausted the fallback chain and reached nuclear fallback, omit the `m
 When spawning, include the model in your acknowledgment:
 
 ```
-🔧 Fenster (claude-sonnet-4.5) — refactoring auth module
-🎨 Redfoot (claude-opus-4.5 · vision) — designing color system
+🔧 Fenster (claude-sonnet-4.6) — refactoring auth module
+🎨 Redfoot (claude-opus-4.6 · vision) — designing color system
 📋 Scribe (claude-haiku-4.5 · fast) — logging session
 ⚡ Keaton (claude-opus-4.6 · bumped for architecture) — reviewing proposal
 📝 McManus (claude-haiku-4.5 · fast) — updating docs
@@ -433,9 +433,9 @@ Include tier annotation only when the model was bumped or a specialist was chose
 
 **Valid models (current platform catalog):**
 
-Premium: `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5`
-Standard: `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview`
-Fast/Cheap: `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1`
+Premium: `claude-opus-4.7`, `claude-opus-4.6`, `claude-opus-4.5`
+Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gemini-3-pro-preview`
+Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5-mini`, `gpt-4.1`
 
 ### Client Compatibility
 

From 9d832fd8a9e7b6406c27f36432b9e036c25e4613 Mon Sep 17 00:00:00 2001
From: mpaulosky <60372079+mpaulosky@users.noreply.github.com>
Date: Sun, 19 Apr 2026 09:58:56 -0700
Subject: [PATCH 2/4] docs(squad): add issue-first branch flow (#20)

Update the squad workflow so push-capable work resolves an existing open
issue first and only creates a new issue when no open match exists.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .github/agents/squad.agent.md                 | 20 ++++++++++++
 .squad/templates/copilot-instructions.md      |  7 +++++
 .squad/templates/issue-lifecycle.md           | 31 +++++++++++++++++++
 .squad/templates/skills/git-workflow/SKILL.md | 26 ++++++++++++----
 .squad/templates/squad.agent.md               | 20 ++++++++++++
 5 files changed, 98 insertions(+), 6 deletions(-)

diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 8ccb3928..4e0badcc 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -146,6 +146,25 @@ For each squad member with assigned issues, note them in the session context. Wh
 
 **Proactive issue pickup:** If a user starts a session and there are open `squad:{member}` issues, mention them: *"Hey {user}, {AgentName} has an open issue — #42: Fix auth endpoint timeout. Want them to pick it up?"*
 
+**Issue-first branch sourcing:** For any push-capable work that requires a
+`squad/{issue-number}-{slug}` branch and the user did **not** provide an issue
+number, resolve the issue number before asking the user for branch details:
+
+1. Check the current GitHub repository for relevant **open** issues. Prefer the
+   GitHub MCP tools when available; otherwise use `gh issue list` or
+   `gh issue search`.
+2. If one open issue clearly matches the requested change, reuse that issue
+   number.
+3. If multiple open issues are plausible matches, show the candidates and ask
+   the user which one to use.
+4. If no open issue matches, create a new GitHub issue from the requested
+   change summary, then use that new issue number for branch naming.
+5. Only after the issue number is resolved should the coordinator derive the
+   branch name `squad/{issue-number}-{slug}`.
+
+This avoids guessed or duplicated issue numbers when preparing branches, commits,
+and PR metadata.
+
 **Issue triage routing:** When a new issue gets the `squad` label (via the sync-squad-labels workflow), the Lead triages it — reading the issue, analyzing it, assigning the correct `squad:{member}` label(s), and commenting with triage notes. The Lead can also reassign by swapping labels.
 
 **⚡ Read `.squad/team.md` (roster), `.squad/routing.md` (routing), and `.squad/casting/registry.json` (persistent names) as parallel tool calls in a single turn. Do NOT read these sequentially.**
@@ -1083,6 +1102,7 @@ Before connecting to a GitHub repository, verify that the `gh` CLI is available
 | "show the backlog" / "what issues are open?" | List issues from connected repo |
 | "work on issue #N" / "pick up #N" | Route issue to appropriate agent |
 | "work on all issues" / "start the backlog" | Route all open issues (batched) |
+| "push these changes" / "open a PR" with no issue number | Resolve matching open issue first; if none exists, create one before branching |
 
 ---
 
diff --git a/.squad/templates/copilot-instructions.md b/.squad/templates/copilot-instructions.md
index ddc20f12..da7d70ae 100644
--- a/.squad/templates/copilot-instructions.md
+++ b/.squad/templates/copilot-instructions.md
@@ -29,6 +29,13 @@ squad/{issue-number}-{kebab-case-slug}
 ```
 Example: `squad/42-fix-login-validation`
 
+Before asking the user for an issue number or branch slug for push-capable
+work, first inspect the current GitHub repository for relevant **open** issues.
+Reuse a matching open issue when one exists. If no open issue matches, create a
+new issue from the requested change summary and use its number for the squad
+branch. Ask the user only when multiple open issues are plausible matches or
+the issue description needs clarification.
+
 ## PR Guidelines
 
 When opening a PR:
diff --git a/.squad/templates/issue-lifecycle.md b/.squad/templates/issue-lifecycle.md
index 574c205a..988c06c0 100644
--- a/.squad/templates/issue-lifecycle.md
+++ b/.squad/templates/issue-lifecycle.md
@@ -115,10 +115,41 @@ gh issue view {number} --json number,title,body,labels,assignees
 az boards work-item show --id {id} --output json
 ```
 
+### 1.5 Direct Request Issue Resolution
+
+**Trigger:** User asks to start push-capable work, branch current changes, or
+open a PR, but does **not** provide an issue number.
+
+**Actions:**
+1. Check the current GitHub repository for **open** issues related to the
+   requested change.
+2. If one open issue clearly matches, reuse that issue number.
+3. If multiple open issues are plausible matches, ask the user which one to
+   use.
+4. If no open issue matches, create a new issue using the requested change
+   summary, then use that new issue number for the branch.
+5. Continue with branch creation using `squad/{issue-number}-{slug}`.
+
+**Issue lookup commands (GitHub):**
+```bash
+# Prefer MCP/server integrations when available. CLI fallback:
+gh issue list --state open --limit 50 --json number,title,body,labels
+gh issue search "repo:{owner}/{repo} state:open {keywords}"
+```
+
+**Issue creation command (GitHub):**
+```bash
+gh issue create --title "{derived title}" \
+  --body "{request summary}\n\n## Requested changes\n- {change 1}\n- {change 2}"
+```
+
 ### 2. Branch Creation (Start Work)
 
 **Trigger:** Agent accepts issue assignment and begins work.
 
+**Prerequisite:** The issue number is already resolved from triage **or** from
+the direct-request issue resolution flow above.
+
 **Actions:**
 1. Ensure working on latest base branch (usually `main` or `dev`)
 2. Create feature branch using Squad naming convention
diff --git a/.squad/templates/skills/git-workflow/SKILL.md b/.squad/templates/skills/git-workflow/SKILL.md
index bfa0b859..612d93da 100644
--- a/.squad/templates/skills/git-workflow/SKILL.md
+++ b/.squad/templates/skills/git-workflow/SKILL.md
@@ -26,32 +26,46 @@ Examples:
 
 ## Workflow for Issue Work
 
-1. **Branch from dev:**
+1. **Resolve the issue number first:**
+   - Check for a matching **open** issue in the current GitHub repo before
+     creating a branch.
+   - Reuse that issue if it already describes the requested work.
+   - If no open issue matches, create a new issue from the requested change
+     summary and use the returned issue number.
+   - Ask the user only when multiple open issues are plausible matches.
+   ```bash
+   gh issue list --state open --limit 50 --json number,title,body,labels
+   gh issue search "repo:{owner}/{repo} state:open {keywords}"
+   # If no match:
+   gh issue create --title "{derived title}" --body "{request summary}"
+   ```
+
+2. **Branch from dev:**
    ```bash
    git checkout dev
    git pull origin dev
    git checkout -b squad/{issue-number}-{slug}
    ```
 
-2. **Mark issue in-progress:**
+3. **Mark issue in-progress:**
    ```bash
    gh issue edit {number} --add-label "status:in-progress"
    ```
 
-3. **Create draft PR targeting dev:**
+4. **Create draft PR targeting dev:**
    ```bash
    gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft
    ```
 
-4. **Do the work.** Make changes, write tests, commit with issue reference.
+5. **Do the work.** Make changes, write tests, commit with issue reference.
 
-5. **Push and mark ready:**
+6. **Push and mark ready:**
    ```bash
    git push -u origin squad/{issue-number}-{slug}
    gh pr ready
    ```
 
-6. **After merge to dev:**
+7. **After merge to dev:**
    ```bash
    git checkout dev
    git pull origin dev
diff --git a/.squad/templates/squad.agent.md b/.squad/templates/squad.agent.md
index 2d5d0388..e9417bde 100644
--- a/.squad/templates/squad.agent.md
+++ b/.squad/templates/squad.agent.md
@@ -146,6 +146,25 @@ For each squad member with assigned issues, note them in the session context. Wh
 
 **Proactive issue pickup:** If a user starts a session and there are open `squad:{member}` issues, mention them: *"Hey {user}, {AgentName} has an open issue — #42: Fix auth endpoint timeout. Want them to pick it up?"*
 
+**Issue-first branch sourcing:** For any push-capable work that requires a
+`squad/{issue-number}-{slug}` branch and the user did **not** provide an issue
+number, resolve the issue number before asking the user for branch details:
+
+1. Check the current GitHub repository for relevant **open** issues. Prefer the
+   GitHub MCP tools when available; otherwise use `gh issue list` or
+   `gh issue search`.
+2. If one open issue clearly matches the requested change, reuse that issue
+   number.
+3. If multiple open issues are plausible matches, show the candidates and ask
+   the user which one to use.
+4. If no open issue matches, create a new GitHub issue from the requested
+   change summary, then use that new issue number for branch naming.
+5. Only after the issue number is resolved should the coordinator derive the
+   branch name `squad/{issue-number}-{slug}`.
+
+This avoids guessed or duplicated issue numbers when preparing branches, commits,
+and PR metadata.
+
 **Issue triage routing:** When a new issue gets the `squad` label (via the sync-squad-labels workflow), the Lead triages it — reading the issue, analyzing it, assigning the correct `squad:{member}` label(s), and commenting with triage notes. The Lead can also reassign by swapping labels.
 
 **⚡ Read `.squad/team.md` (roster), `.squad/routing.md` (routing), and `.squad/casting/registry.json` (persistent names) as parallel tool calls in a single turn. Do NOT read these sequentially.**
@@ -1083,6 +1102,7 @@ Before connecting to a GitHub repository, verify that the `gh` CLI is available
 | "show the backlog" / "what issues are open?" | List issues from connected repo |
 | "work on issue #N" / "pick up #N" | Route issue to appropriate agent |
 | "work on all issues" / "start the backlog" | Route all open issues (batched) |
+| "push these changes" / "open a PR" with no issue number | Resolve matching open issue first; if none exists, create one before branching |
 
 ---
 

From bfa79977f4f1b566dc52b4a15407f12c4f73b4b9 Mon Sep 17 00:00:00 2001
From: mpaulosky <60372079+mpaulosky@users.noreply.github.com>
Date: Sun, 19 Apr 2026 10:03:58 -0700
Subject: [PATCH 3/4] docs(squad): reconcile model fallback guidance (#20)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .copilot/skills/economy-mode/SKILL.md            |  3 ++-
 .copilot/skills/model-selection/SKILL.md         |  6 +++++-
 .github/agents/squad.agent.md                    | 10 +++++++---
 .squad/templates/skills/model-selection/SKILL.md | 10 +++++++---
 .squad/templates/squad.agent.md                  | 10 +++++++---
 5 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/.copilot/skills/economy-mode/SKILL.md b/.copilot/skills/economy-mode/SKILL.md
index 346d86b4..ce37f07c 100644
--- a/.copilot/skills/economy-mode/SKILL.md
+++ b/.copilot/skills/economy-mode/SKILL.md
@@ -43,7 +43,8 @@ When economy mode is **active**, Layer 3 auto-selection uses this table instead
 | Writing code (implementation, refactoring, bug fixes) | `claude-sonnet-4.6` | `gpt-4.1` or `gpt-5-mini` |
 | Writing prompts or agent designs | `claude-sonnet-4.6` | `gpt-4.1` or `gpt-5-mini` |
 | Docs, planning, triage, changelogs, mechanical ops | `claude-haiku-4.5` | `gpt-4.1` or `gpt-5-mini` |
-| Architecture, code review, security audits | `claude-opus-4.6` | `claude-sonnet-4.6` |
+| Code review | `claude-sonnet-4.6` | `gpt-4.1` or `gpt-5-mini` |
+| Architecture proposals, reviewer gates, security audits | `claude-opus-4.6` | `claude-sonnet-4.6` |
 | Scribe / logger / mechanical file ops | `claude-haiku-4.5` | `gpt-4.1` |
 
 **Prefer `gpt-4.1` over `gpt-5-mini`** when the task involves structured output or agentic tool use. Prefer `gpt-5-mini` for pure text generation tasks where latency matters.
diff --git a/.copilot/skills/model-selection/SKILL.md b/.copilot/skills/model-selection/SKILL.md
index 6faa30bf..bbe069e2 100644
--- a/.copilot/skills/model-selection/SKILL.md
+++ b/.copilot/skills/model-selection/SKILL.md
@@ -106,7 +106,8 @@ After resolving the model and including it in the spawn template, this skill is
 
 ## Fallback Chains
 
-If a model is unavailable (rate limit, plan restriction), retry within the same tier:
+If a model is unavailable (rate limit, plan restriction), retry within the same
+tier until the documented chain is exhausted:
 
 ```
 Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5
@@ -114,4 +115,7 @@ Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex
 Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-4.1 → gpt-5-mini
 ```
 
+If the user explicitly selects `claude-opus-4.7`, start at the top of the
+premium chain with `claude-opus-4.6` as the first fallback.
+
 **Never fall UP in tier.** A fast task won't land on a premium model via fallback.
diff --git a/.github/agents/squad.agent.md b/.github/agents/squad.agent.md
index 4e0badcc..3058d32b 100644
--- a/.github/agents/squad.agent.md
+++ b/.github/agents/squad.agent.md
@@ -404,7 +404,7 @@ Before spawning an agent, determine which model to use. Check these layers in or
 
 **Fallback chains — when a model is unavailable:**
 
-If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback.
+If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the relevant chain until that chain is exhausted. Do NOT tell the user about fallback attempts.
 
 ```
 Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param)
@@ -432,7 +432,7 @@ prompt: |
   ...
 ```
 
-Only set `model` when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
+Pass the resolved model as the `model` parameter on `task` tool calls when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
 
 If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
 
@@ -452,10 +452,14 @@ Include tier annotation only when the model was bumped or a specialist was chose
 
 **Valid models (current platform catalog):**
 
-Premium: `claude-opus-4.7`, `claude-opus-4.6`, `claude-opus-4.5`
+Premium: `claude-opus-4.7` (explicit override), `claude-opus-4.6`, `claude-opus-4.5`
 Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gemini-3-pro-preview`
 Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5-mini`, `gpt-4.1`
 
+Task-aware auto and the fallback chains above standardize on `claude-opus-4.6`
+for premium work. Use `claude-opus-4.7` only when the user or config
+explicitly requests it.
+
 ### Client Compatibility
 
 Squad runs on multiple Copilot surfaces. The coordinator MUST detect its platform and adapt spawning behavior accordingly. See `docs/scenarios/client-compatibility.md` for the full compatibility matrix.
diff --git a/.squad/templates/skills/model-selection/SKILL.md b/.squad/templates/skills/model-selection/SKILL.md
index 4c6866fd..a3624e32 100644
--- a/.squad/templates/skills/model-selection/SKILL.md
+++ b/.squad/templates/skills/model-selection/SKILL.md
@@ -106,12 +106,16 @@ After resolving the model and including it in the spawn template, this skill is
 
 ## Fallback Chains
 
-If a model is unavailable (rate limit, plan restriction), retry within the same tier:
+If a model is unavailable (rate limit, plan restriction), retry within the same
+tier until the documented chain is exhausted:
 
 ```
-Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.6
+Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5
 Standard: claude-sonnet-4.6 → gpt-5.4 → claude-sonnet-4.5 → gpt-5.3-codex → claude-sonnet-4
-Fast:     claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-4.1 → gpt-5-mini
 ```
 
 **Never fall UP in tier.** A fast task won't land on a premium model via fallback.
+
+If the user explicitly selects `claude-opus-4.7`, start at the top of the
+premium chain with `claude-opus-4.6` as the first fallback.
diff --git a/.squad/templates/squad.agent.md b/.squad/templates/squad.agent.md
index e9417bde..74fbf358 100644
--- a/.squad/templates/squad.agent.md
+++ b/.squad/templates/squad.agent.md
@@ -404,7 +404,7 @@ Before spawning an agent, determine which model to use. Check these layers in or
 
 **Fallback chains — when a model is unavailable:**
 
-If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the chain. Do NOT tell the user about fallback attempts. Maximum 3 retries before jumping to the nuclear fallback.
+If a spawn fails because the selected model is unavailable (plan restriction, org policy, rate limit, deprecation, or any other reason), silently retry with the next model in the relevant chain until that chain is exhausted. Do NOT tell the user about fallback attempts.
 
 ```
 Premium:  claude-opus-4.6 → claude-opus-4.5 → claude-sonnet-4.6 → claude-sonnet-4.5 → (omit model param)
@@ -432,7 +432,7 @@ prompt: |
   ...
 ```
 
-Only set `model` when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
+Pass the resolved model as the `model` parameter on `task` tool calls when it differs from the platform default. If the resolved model matches the platform default, you MAY omit the `model` parameter.
 
 If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
 
@@ -452,10 +452,14 @@ Include tier annotation only when the model was bumped or a specialist was chose
 
 **Valid models (current platform catalog):**
 
-Premium: `claude-opus-4.7`, `claude-opus-4.6`, `claude-opus-4.5`
+Premium: `claude-opus-4.7` (explicit override), `claude-opus-4.6`, `claude-opus-4.5`
 Standard: `claude-sonnet-4.6`, `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.4`, `gpt-5.3-codex`, `gpt-5.2-codex`, `gpt-5.2`, `gemini-3-pro-preview`
 Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5-mini`, `gpt-4.1`
 
+Task-aware auto and the fallback chains above standardize on `claude-opus-4.6`
+for premium work. Use `claude-opus-4.7` only when the user or config
+explicitly requests it.
+
 ### Client Compatibility
 
 Squad runs on multiple Copilot surfaces. The coordinator MUST detect its platform and adapt spawning behavior accordingly. See `docs/scenarios/client-compatibility.md` for the full compatibility matrix.

From c952dd686cc04227bb66b2157e0d818dea5a0880 Mon Sep 17 00:00:00 2001
From: mpaulosky <60372079+mpaulosky@users.noreply.github.com>
Date: Sun, 19 Apr 2026 10:15:51 -0700
Subject: [PATCH 4/4] docs(squad): watch PR checks faster

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .squad/playbooks/pr-merge-process.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/.squad/playbooks/pr-merge-process.md b/.squad/playbooks/pr-merge-process.md
index af17d2cb..169417a2 100644
--- a/.squad/playbooks/pr-merge-process.md
+++ b/.squad/playbooks/pr-merge-process.md
@@ -2,7 +2,7 @@
 
 **Owner:** Aragorn (Lead) + Ralph (Work Monitor)
 **Ref:** `.squad/ceremonies.md` (PR Review Gate, Standard Task Workflow)
-**Last Updated:** 2026-04-13
+**Last Updated:** 2026-04-19
 
 ---
 
@@ -42,8 +42,8 @@ gh pr create \
 Do NOT request review until CI is green:
 
 ```bash
-# Poll CI status
-gh pr checks <PR-number>
+# Watch CI status (refresh every 5 seconds)
+gh pr checks <PR-number> --watch --interval 5
 # All checks must show ✅ before proceeding
 ```
 
@@ -55,7 +55,7 @@ Ralph MUST verify ALL of the following before spawning reviewers. Any failing ga
 
 | Gate                | Command                                             | Expected                   |
 | ------------------- | --------------------------------------------------- | -------------------------- |
-| CI green            | `gh pr checks <N>`                                  | All passing                |
+| CI green            | `gh pr checks <N> --watch --interval 5`             | All passing                |
 | No conflicts        | `gh pr view <N> --json mergeable -q .mergeable`     | `MERGEABLE`                |
 | PR template filled  | `gh pr view <N> --json body`                        | Contains filled checkboxes |
 | Branch is `squad/*` | `gh pr view <N> --json headRefName -q .headRefName` | Starts with `squad/`       |