@bradygaster/squad-sdk 0.8.24 → 0.9.0

package/templates/skills/git-workflow/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: "git-workflow"
+description: "Squad branching model: dev-first workflow with insiders preview channel"
+domain: "version-control"
+confidence: "high"
+source: "team-decision"
+---
+
+## Context
+
+Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.**
+
+| Branch | Purpose | Publishes |
+|--------|---------|-----------|
+| `main` | Released, tagged, in-npm code only | `npm publish` on tag |
+| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge |
+| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync |
+
+## Branch Naming Convention
+
+Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}`
+
+Examples:
+- `squad/195-fix-version-stamp-bug`
+- `squad/42-add-profile-api`
+
+## Workflow for Issue Work
+
+1. **Branch from dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b squad/{issue-number}-{slug}
+   ```
+
+2. **Mark issue in-progress:**
+   ```bash
+   gh issue edit {number} --add-label "status:in-progress"
+   ```
+
+3. **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. **Push and mark ready:**
+   ```bash
+   git push -u origin squad/{issue-number}-{slug}
+   gh pr ready
+   ```
+
+6. **After merge to dev:**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git branch -d squad/{issue-number}-{slug}
+   git push origin --delete squad/{issue-number}-{slug}
+   ```
+
+## Parallel Multi-Issue Work (Worktrees)
+
+When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead.
+
+### When to Use Worktrees vs Sequential
+
+| Scenario | Strategy |
+|----------|----------|
+| Single issue | Standard workflow above — no worktree needed |
+| 2+ simultaneous issues in same repo | Worktrees — one per issue |
+| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) |
+
+### Setup
+
+From the main clone (must be on dev or any branch):
+
+```bash
+# Ensure dev is current
+git fetch origin dev
+
+# Create a worktree per issue — siblings to the main clone
+git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev
+git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev
+```
+
+**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`).
+
+Each worktree:
+- Has its own working directory and index
+- Is on its own `squad/{issue-number}-{slug}` branch from dev
+- Shares the same `.git` object store (disk-efficient)
+
+### Per-Worktree Agent Workflow
+
+Each agent operates inside its worktree exactly like the single-issue workflow:
+
+```bash
+cd ../squad-195
+
+# Work normally — commits, tests, pushes
+git add -A && git commit -m "fix: stamp bug (#195)"
+git push -u origin squad/195-fix-stamp-bug
+
+# Create PR targeting dev
+gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft
+```
+
+All PRs target `dev` independently. Agents never interfere with each other's filesystem.
+
+### .squad/ State in Worktrees
+
+The `.squad/` directory exists in each worktree as a copy. This is safe because:
+- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs)
+- Each agent appends to its own section; union merge reconciles on PR merge to dev
+- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only
+
+### Cleanup After Merge
+
+After a worktree's PR is merged to dev:
+
+```bash
+# From the main clone
+git worktree remove ../squad-195
+git worktree prune          # clean stale metadata
+git branch -d squad/195-fix-stamp-bug
+git push origin --delete squad/195-fix-stamp-bug
+```
+
+If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state.
+
+---
+
+## Multi-Repo Downstream Scenarios
+
+When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad):
+
+### Setup
+
+Clone downstream repos as siblings to the main repo:
+
+```
+~/work/
+  squad-pr/          # main repo
+  squad-sdk/         # downstream dependency
+  user-app/          # consumer project
+```
+
+Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use `squad/{issue-number}-{slug}`.
+
+### Coordinated PRs
+
+- Create PRs in each repo independently
+- Link them in PR descriptions:
+  ```
+  Closes #42
+
+  **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature)
+  ```
+- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli)
+
+### Local Linking for Testing
+
+Before pushing, verify cross-repo changes work together:
+
+```bash
+# Node.js / npm
+cd ../squad-sdk && npm link
+cd ../squad-pr && npm link squad-sdk
+
+# Go
+# Use replace directive in go.mod:
+# replace github.com/org/squad-sdk => ../squad-sdk
+
+# Python
+cd ../squad-sdk && pip install -e .
+```
+
+**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs.
+
+### Worktrees + Multi-Repo
+
+These compose naturally. You can have:
+- Multiple worktrees in the main repo (parallel issues)
+- Separate clones for downstream repos
+- Each combination operates independently
+
+---
+
+## Anti-Patterns
+
+- ❌ Branching from main (branch from dev)
+- ❌ PR targeting main directly (target dev)
+- ❌ Non-conforming branch names (must be squad/{number}-{slug})
+- ❌ Committing directly to main or dev (use PRs)
+- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead)
+- ❌ Using worktrees for cross-repo work (use separate clones)
+- ❌ Leaving stale worktrees after PR merge (clean up immediately)
+
+## Promotion Pipeline
+
+- dev → insiders: Automated sync on green build
+- dev → main: Manual merge when ready for stable release, then tag
+- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent

package/templates/skills/github-multi-account/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: github-multi-account
+description: Detect and set up account-locked gh aliases for multi-account GitHub. The AI reads this skill, detects accounts, asks the user which is personal/work, and runs the setup automatically.
+confidence: high
+source: https://github.com/tamirdresher/squad-skills/tree/main/plugins/github-multi-account
+author: tamirdresher
+---
+
+# GitHub Multi-Account — AI-Driven Setup
+
+## When to Activate
+When the user has multiple GitHub accounts (check with `gh auth status`). If you see 2+ accounts listed, this skill applies.
+
+## What to Do (as the AI agent)
+
+### Step 1: Detect accounts
+Run: `gh auth status`
+Look for multiple accounts. Note which usernames are listed.
+
+### Step 2: Ask the user
+Ask: "I see you have multiple GitHub accounts: {list them}. Which one is your personal account and which is your work/EMU account?"
+
+### Step 3: Run the setup automatically
+Once the user confirms, do ALL of this for them:
+
+```powershell
+# 1. Define the functions
+$personal = "THEIR_PERSONAL_USERNAME"
+$work = "THEIR_WORK_USERNAME"
+
+# 2. Add to PowerShell profile
+$profilePath = $PROFILE.CurrentUserAllHosts
+if (!(Test-Path $profilePath)) { New-Item -Path $profilePath -Force | Out-Null }
+$existing = Get-Content $profilePath -Raw -ErrorAction SilentlyContinue
+if ($existing -notmatch "gh-personal") {
+    $block = @"
+
+# === GitHub Multi-Account Aliases ===
+function gh-personal { gh auth switch --user $personal 2>`$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user $work 2>`$null | Out-Null; gh @args }
+Set-Alias ghp gh-personal
+Set-Alias ghw gh-work
+"@
+    Add-Content -Path $profilePath -Value $block
+}
+
+# 3. Create CMD wrappers
+$binDir = Join-Path $env:USERPROFILE ".squad\bin"
+if (!(Test-Path $binDir)) { New-Item -ItemType Directory -Path $binDir -Force | Out-Null }
+"@echo off`ngh auth switch --user $personal >nul 2>&1`ngh %*" | Out-File "$binDir\ghp.cmd" -Encoding ascii
+"@echo off`ngh auth switch --user $work >nul 2>&1`ngh %*" | Out-File "$binDir\ghw.cmd" -Encoding ascii
+
+# 4. Add to PATH
+$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
+if ($userPath -notmatch [regex]::Escape($binDir)) {
+    [Environment]::SetEnvironmentVariable("PATH", "$binDir;$userPath", "User")
+    $env:PATH = "$binDir;$env:PATH"
+}
+
+# 5. Load in current session
+function gh-personal { gh auth switch --user $personal 2>$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user $work 2>$null | Out-Null; gh @args }
+Set-Alias ghp gh-personal
+Set-Alias ghw gh-work
+```
+
+### Step 4: Verify for the user
+Run these and show the results:
+```powershell
+ghp api user --jq '.login'   # should show personal username
+ghw api user --jq '.login'   # should show work username
+```
+
+### Step 5: Tell the user
+"All set! From now on use `ghp` for personal repos and `ghw` for work repos. I'll use them too."
+
+## After Setup — Usage Rules
+
+1. **NEVER** use bare `gh` for repo operations — always `ghp` or `ghw`
+2. **NEVER** manually `gh auth switch` — the aliases handle it
+3. Determine alias by repo owner:
+   - Personal account repos → `ghp` / `gh-personal`
+   - Work/EMU account repos → `ghw` / `gh-work`
+
+## Repo-Specific Account Binding
+
+This repo (`bradygaster/squad`) is bound to the **bradygaster** (personal) account.
+All `gh` operations in this repo MUST use `ghp` / `gh-personal`.
+
+## For Squad Agents
+At the TOP of any script touching GitHub, define:
+```powershell
+function gh-personal { gh auth switch --user bradygaster 2>$null | Out-Null; gh @args }
+function gh-work { gh auth switch --user bradyg_microsoft 2>$null | Out-Null; gh @args }
+```

package/templates/skills/history-hygiene/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: history-hygiene
+description: Record final outcomes to history.md, not intermediate requests or reversed decisions
+domain: documentation, team-collaboration
+confidence: high
+source: earned (Kobayashi v0.6.0 incident, team intervention)
+---
+
+## Context
+
+History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake.
+
+## Patterns
+
+- **Record the final outcome**, not the initial request.
+- **Wait for confirmation** before writing to history — don't log intermediate states.
+- **If a decision reverses**, update the entry immediately — don't leave stale data.
+- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened.
+
+## Examples
+
+✓ **Correct:**
+- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)"
+- "Reverted to Node 18 per Brady's explicit request on 2024-01-15"
+
+✗ **Incorrect:**
+- "Brady directed v0.6.0" (when later reversed)
+- Recording what was *requested* instead of what *actually happened*
+- Logging entries before outcome is confirmed
+
+## Anti-Patterns
+
+- Writing intermediate or "for now" states to disk
+- Attributing decisions without confirming final direction
+- Treating history like a draft — history is the source of truth
+- Assuming readers will cross-reference or verify; they won't

package/templates/skills/humanizer/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "humanizer"
+description: "Tone enforcement patterns for external-facing community responses"
+domain: "communication, tone, community"
+confidence: "low"
+source: "manual (RFC #426 — PAO External Communications)"
+---
+
+## Context
+
+Use this skill whenever PAO drafts external-facing responses for issues or discussions.
+
+- Tone must be warm, helpful, and human-sounding — never robotic or corporate.
+- Brady's constraint applies everywhere: **Humanized tone is mandatory**.
+- This applies to **all external-facing content** drafted by PAO in Phase 1 issues/discussions workflows.
+
+## Patterns
+
+1. **Warm opening** — Start with acknowledgment ("Thanks for reporting this", "Great question!")
+2. **Active voice** — "We're looking into this" not "This is being investigated"
+3. **Second person** — Address the person directly ("you" not "the user")
+4. **Conversational connectors** — "That said...", "Here's what we found...", "Quick note:"
+5. **Specific, not vague** — "This affects the casting module in v0.8.x" not "We are aware of issues"
+6. **Empathy markers** — "I can see how that would be frustrating", "Good catch!"
+7. **Action-oriented closes** — "Let us know if that helps!" not "Please advise if further assistance is required"
+8. **Uncertainty is OK** — "We're not 100% sure yet, but here's what we think is happening..." is better than false confidence
+9. **Profanity filter** — Never include profanity, slurs, or aggressive language, even when quoting
+10. **Baseline comparison** — Responses should align with tone of 5-10 "gold standard" responses (>80% similarity threshold)
+11. **Empathetic disagreement** — "We hear you. That's a fair concern." before explaining the reasoning
+12. **Information request** — Ask for specific details, not open-ended "can you provide more info?"
+13. **No link-dumping** — Don't just paste URLs. Provide context: "Check out the [getting started guide](url) — specifically the section on routing" not just a bare link
+
+## Examples
+
+### 1. Welcome
+
+```text
+Hey {author}! Welcome to Squad 👋 Thanks for opening this.
+{substantive response}
+Let us know if you have questions — happy to help!
+```
+
+### 2. Troubleshooting
+
+```text
+Thanks for the detailed report, {author}!
+Here's what we think is happening: {explanation}
+{steps or workaround}
+Let us know if that helps, or if you're seeing something different.
+```
+
+### 3. Feature guidance
+
+```text
+Great question! {context on current state}
+{guidance or workaround}
+We've noted this as a potential improvement — {tracking info if applicable}.
+```
+
+### 4. Redirect
+
+```text
+Thanks for reaching out! This one is actually better suited for {correct location}.
+{brief explanation of why}
+Feel free to open it there — they'll be able to help!
+```
+
+### 5. Acknowledgment
+
+```text
+Good catch, {author}. We've confirmed this is a real issue.
+{what we know so far}
+We'll update this thread when we have a fix. Thanks for flagging it!
+```
+
+### 6. Closing
+
+```text
+This should be resolved in {version/PR}! 🎉
+{brief summary of what changed}
+Thanks for reporting this, {author} — it made Squad better.
+```
+
+### 7. Technical uncertainty
+
+```text
+Interesting find, {author}. We're not 100% sure what's causing this yet.
+Here's what we've ruled out: {list}
+We'd love more context if you have it — {specific ask}.
+We'll dig deeper and update this thread.
+```
+
+## Anti-Patterns
+
+- ❌ Corporate speak: "We appreciate your patience as we investigate this matter"
+- ❌ Marketing hype: "Squad is the BEST way to..." or "This amazing feature..."
+- ❌ Passive voice: "It has been determined that..." or "The issue is being tracked"
+- ❌ Dismissive: "This works as designed" without empathy
+- ❌ Over-promising: "We'll ship this next week" without commitment from the team
+- ❌ Empty acknowledgment: "Thanks for your feedback" with no substance
+- ❌ Robot signatures: "Best regards, PAO" or "Sincerely, The Squad Team"
+- ❌ Excessive emoji: More than 1-2 emoji per response
+- ❌ Quoting profanity: Even when the original issue contains it, paraphrase instead
+- ❌ Link-dumping: Pasting URLs without context ("See: https://...")
+- ❌ Open-ended info requests: "Can you provide more information?" without specifying what information

package/templates/skills/init-mode/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: "init-mode"
+description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)"
+domain: "orchestration"
+confidence: "high"
+source: "extracted"
+tools:
+  - name: "ask_user"
+    description: "Confirm team roster with selectable menu"
+    when: "Phase 1 proposal — requires explicit user confirmation"
+---
+
+## Context
+
+Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2).
+
+## Patterns
+
+### Phase 1: Propose the Team
+
+No team exists yet. Propose one — but **DO NOT create any files until the user confirms.**
+
+1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.**
+2. Ask: *"What are you building? (language, stack, what it does)"*
+3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section):
+   - Determine team size (typically 4–5 + Scribe).
+   - Determine assignment shape from the user's project description.
+   - Derive resonance signals from the session and repo context.
+   - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available.
+   - Scribe is always "Scribe" — exempt from casting.
+   - Ralph is always "Ralph" — exempt from casting.
+4. Propose the team with their cast names. Example (names will vary per cast):
+
+```
+🏗️  {CastName1}  — Lead          Scope, decisions, code review
+⚛️  {CastName2}  — Frontend Dev  React, UI, components
+🔧  {CastName3}  — Backend Dev   APIs, database, services
+🧪  {CastName4}  — Tester        Tests, quality, edge cases
+📋  Scribe       — (silent)      Memory, decisions, session logs
+🔄  Ralph        — (monitor)     Work queue, backlog, keep-alive
+```
+
+5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu:
+   - **question:** *"Look right?"*
+   - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]`
+
+**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.**
+
+### Phase 2: Create the Team
+
+**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes").
+
+> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms.
+
+6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/).
+
+**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id).
+
+**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing.
+
+**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks.
+
+**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches:
+```
+.squad/decisions.md merge=union
+.squad/agents/*/history.md merge=union
+.squad/log/** merge=union
+.squad/orchestration-log/** merge=union
+```
+The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically.
+
+7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"*
+
+8. **Post-setup input sources** (optional — ask after team is created, not during casting):
+   - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow
+   - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow
+   - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section
+   - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment
+   - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately.
+
+## Examples
+
+**Example flow:**
+1. Coordinator detects no team.md → Init Mode
+2. Runs `git config user.name` → "Brady"
+3. Asks: *"Hey Brady, what are you building?"*
+4. User: *"TypeScript CLI tool with GitHub API integration"*
+5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe
+6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph
+7. Uses `ask_user` with choices → user selects "Yes, hire this team"
+8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents
+9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"*
+
+## Anti-Patterns
+
+- ❌ Creating files before user confirms Phase 1
+- ❌ Mixing agents from different universes in the same cast
+- ❌ Skipping the `ask_user` tool and assuming confirmation
+- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role"
+- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows)
+- ❌ Forgetting to initialize `.squad/casting/` state files
+- ❌ Reading or storing `git config user.email` (PII violation)

package/templates/skills/model-selection/SKILL.md

@@ -0,0 +1,117 @@
+# Model Selection
+
+> Determines which LLM model to use for each agent spawn.
+
+## SCOPE
+
+✅ THIS SKILL PRODUCES:
+- A resolved `model` parameter for every `task` tool call
+- Persistent model preferences in `.squad/config.json`
+- Spawn acknowledgments that include the resolved model
+
+❌ THIS SKILL DOES NOT PRODUCE:
+- Code, tests, or documentation
+- Model performance benchmarks
+- Cost reports or billing artifacts
+
+## Context
+
+Squad supports 18+ models across three tiers (premium, standard, fast). The coordinator must select the right model for each agent spawn. Users can set persistent preferences that survive across sessions.
+
+## 5-Layer Model Resolution Hierarchy
+
+Resolution is **first-match-wins** — the highest layer with a value wins.
+
+| Layer | Name | Source | Persistence |
+|-------|------|--------|-------------|
+| **0a** | Per-Agent Config | `.squad/config.json` → `agentModelOverrides.{name}` | Persistent (survives sessions) |
+| **0b** | Global Config | `.squad/config.json` → `defaultModel` | Persistent (survives sessions) |
+| **1** | Session Directive | User said "use X" in current session | Session-only |
+| **2** | Charter Preference | Agent's `charter.md` → `## Model` section | Persistent (in charter) |
+| **3** | Task-Aware Auto | Code → sonnet, docs → haiku, visual → opus | Computed per-spawn |
+| **4** | Default | `claude-haiku-4.5` | Hardcoded fallback |
+
+**Key principle:** Layer 0 (persistent config) beats everything. If the user said "always use opus" and it was saved to config.json, every agent gets opus regardless of role or task type. This is intentional — the user explicitly chose quality over cost.
+
+## AGENT WORKFLOW
+
+### On Session Start
+
+1. READ `.squad/config.json`
+2. CHECK for `defaultModel` field — if present, this is the Layer 0 override for all spawns
+3. CHECK for `agentModelOverrides` field — if present, these are per-agent Layer 0a overrides
+4. STORE both values in session context for the duration
+
+### On Every Agent Spawn
+
+1. CHECK Layer 0a: Is there an `agentModelOverrides.{agentName}` in config.json? → Use it.
+2. CHECK Layer 0b: Is there a `defaultModel` in config.json? → Use it.
+3. CHECK Layer 1: Did the user give a session directive? → Use it.
+4. CHECK Layer 2: Does the agent's charter have a `## Model` section? → Use it.
+5. CHECK Layer 3: Determine task type:
+   - Code (implementation, tests, refactoring, bug fixes) → `claude-sonnet-4.6`
+   - Prompts, agent designs → `claude-sonnet-4.6`
+   - Visual/design with image analysis → `claude-opus-4.6`
+   - Non-code (docs, planning, triage, changelogs) → `claude-haiku-4.5`
+6. FALLBACK Layer 4: `claude-haiku-4.5`
+7. INCLUDE model in spawn acknowledgment: `🔧 {Name} ({resolved_model}) — {task}`
+
+### When User Sets a Preference
+
+**Trigger phrases:** "always use X", "use X for everything", "switch to X", "default to X"
+
+1. VALIDATE the model ID against the catalog (18+ models)
+2. WRITE `defaultModel` to `.squad/config.json` (merge, don't overwrite)
+3. ACKNOWLEDGE: `✅ Model preference saved: {model} — all future sessions will use this until changed.`
+
+**Per-agent trigger:** "use X for {agent}"
+
+1. VALIDATE model ID
+2. WRITE to `agentModelOverrides.{agent}` in `.squad/config.json`
+3. ACKNOWLEDGE: `✅ {Agent} will always use {model} — saved to config.`
+
+### When User Clears a Preference
+
+**Trigger phrases:** "switch back to automatic", "clear model preference", "use default models"
+
+1. REMOVE `defaultModel` from `.squad/config.json`
+2. ACKNOWLEDGE: `✅ Model preference cleared — returning to automatic selection.`
+
+### STOP
+
+After resolving the model and including it in the spawn template, this skill is done. Do NOT:
+- Generate model comparison reports
+- Run benchmarks or speed tests
+- Create new config files (only modify existing `.squad/config.json`)
+- Change the model after spawn (fallback chains handle runtime failures)
+
+## Config Schema
+
+`.squad/config.json` model-related fields:
+
+```json
+{
+  "version": 1,
+  "defaultModel": "claude-opus-4.6",
+  "agentModelOverrides": {
+    "fenster": "claude-sonnet-4.6",
+    "mcmanus": "claude-haiku-4.5"
+  }
+}
+```
+
+- `defaultModel` — applies to ALL agents unless overridden by `agentModelOverrides`
+- `agentModelOverrides` — per-agent overrides that take priority over `defaultModel`
+- Both fields are optional. When absent, Layers 1-4 apply normally.
+
+## Fallback Chains
+
+If a model is unavailable (rate limit, plan restriction), retry within the same tier:
+
+```
+Premium:  claude-opus-4.6 → claude-opus-4.6-fast → claude-opus-4.5 → claude-sonnet-4.6
+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
+```
+
+**Never fall UP in tier.** A fast task won't land on a premium model via fallback.

package/templates/skills/nap/SKILL.md

@@ -0,0 +1,24 @@
+# Skill: nap
+
+> Context hygiene — compress, prune, archive .squad/ state
+
+## What It Does
+
+Reclaims context window budget by compressing agent histories, pruning old logs,
+archiving stale decisions, and cleaning orphaned inbox files.
+
+## When To Use
+
+- Before heavy fan-out work (many agents will spawn)
+- When history.md files exceed 15KB
+- When .squad/ total size exceeds 1MB
+- After long-running sessions or sprints
+
+## Invocation
+
+- CLI: `squad nap` / `squad nap --deep` / `squad nap --dry-run`
+- REPL: `/nap` / `/nap --dry-run` / `/nap --deep`
+
+## Confidence
+
+medium — Confirmed by team vote (4-1) and initial implementation