@bradygaster/squad-cli 0.9.1 → 0.9.2-insider.5

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

@@ -1,117 +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.
+# 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

@@ -1,24 +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
+# 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

package/templates/skills/notification-routing/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: "notification-routing"
+description: "Route agent notifications to specific channels by type — prevent alert fatigue from single-channel flooding"
+domain: "communication"
+confidence: "high"
+source: "earned"
+---
+
+## Context
+
+When a Squad grows beyond a few agents, notifications flood a single channel — failure alerts drown in daily
+briefings, tech news buries security findings, and everything gets ignored. This is the pub-sub problem:
+a single message queue for everything is a recipe for missed alerts.
+
+The fix is **topic-based routing**: agents tag notifications with a channel type, and a routing function
+sends them to the appropriate destination.
+
+**Trigger symptoms:**
+- Important alerts missed because they're buried in routine notifications
+- Team members turning off notifications entirely (signal overwhelm)
+- Onboarding friction: "where do I look for X?"
+
+## Patterns
+
+### Channel Config Schema
+
+Define a `.squad/teams-channels.json` (or equivalent) mapping notification types to channel identifiers:
+
+```json
+{
+  "teamId": "your-team-id",
+  "channels": {
+    "notifications": "squad-alerts",
+    "tech-news":     "tech-news",
+    "security":      "security-findings",
+    "releases":      "release-announcements",
+    "daily-digest":  "daily-digest"
+  }
+}
+```
+
+Place this in `.squad/` (git-tracked, shared across the team). For platforms that use channel IDs instead of
+names (Teams, Slack), store the resolved ID alongside the name to avoid name-collision bugs:
+
+```json
+{
+  "channels": {
+    "notifications": { "name": "squad-alerts", "id": "channel-id-opaque-string" }
+  }
+}
+```
+
+### CHANNEL: Tag Convention
+
+Agents prefix their output with `CHANNEL:<type>` to signal where the notification should go:
+
+```
+CHANNEL:security
+Worf found 3 new CVEs in dependency scan: lodash@4.17.15, minimist@1.2.5
+```
+
+### Routing Dispatcher (shell pseudocode)
+
+```bash
+dispatch_notification() {
+  local raw_output="$1"
+  local channel="notifications"  # default
+
+  if echo "$raw_output" | grep -qE '^CHANNEL:[a-z][a-z0-9-]*'; then
+    channel=$(echo "$raw_output" | head -1 | cut -d: -f2)
+    raw_output=$(echo "$raw_output" | tail -n +2)
+  fi
+
+  send_notification --channel "$channel" --message "$raw_output"
+}
+```
+
+### Provider-Agnostic Adapter
+
+The routing layer is provider-agnostic. Plug in your platform adapter:
+
+```
+.squad/notify-adapter.sh   # Teams / Slack / Discord / webhook -- swappable
+```
+
+The routing config and CHANNEL: tags never change. Only the adapter changes per deployment.
+
+## Anti-Patterns
+
+**Never send all notification types to one channel:**
+```
+send_notification --channel "general" --message "$anything"
+```
+
+**Never use display names as identifiers (name collision risk):**
+```
+send_to_team --name "Squad" --channel "notifications"
+```
+
+Resolve channel IDs once at setup. Use IDs at runtime.
+
+## Distributed Systems Pattern
+
+This is **pub-sub with topic routing** -- the same principle as Kafka topics, RabbitMQ routing keys, and
+AWS SNS topic filtering. Route by type. Each consumer subscribes to the topics it cares about.

package/templates/skills/personal-squad/SKILL.md

@@ -1,57 +1,57 @@
-# Personal Squad — Skill Document
-
-## What is a Personal Squad?
-
-A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session.
-
-## Directory Structure
-
-```
-~/.config/squad/personal-squad/    # Linux/macOS
-%APPDATA%/squad/personal-squad/    # Windows
-├── agents/
-│   ├── {agent-name}/
-│   │   ├── charter.md
-│   │   └── history.md
-│   └── ...
-└── config.json                    # Optional: personal squad config
-```
-
-## How It Works
-
-1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory
-2. **Merge:** Personal agents are merged into the session cast alongside project agents
-3. **Ghost Protocol:** Personal agents can read project state but not write to it
-4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery
-
-## Commands
-
-- `squad personal init` — Bootstrap a personal squad directory
-- `squad personal list` — List your personal agents
-- `squad personal add {name} --role {role}` — Add a personal agent
-- `squad personal remove {name}` — Remove a personal agent
-- `squad cast` — Show the current session cast (project + personal)
-
-## Ghost Protocol
-
-See `templates/ghost-protocol.md` for the full rules. Key points:
-- Personal agents advise; project agents execute
-- No writes to project `.squad/` state
-- Transparent origin tagging in logs
-- Project agents take precedence on conflicts
-
-## Configuration
-
-Optional `config.json` in the personal squad directory:
-```json
-{
-  "defaultModel": "auto",
-  "ghostProtocol": true,
-  "agents": {}
-}
-```
-
-## Environment Variables
-
-- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery
-- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path
+# Personal Squad — Skill Document
+
+## What is a Personal Squad?
+
+A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session.
+
+## Directory Structure
+
+```
+~/.config/squad/personal-squad/    # Linux/macOS
+%APPDATA%/squad/personal-squad/    # Windows
+├── agents/
+│   ├── {agent-name}/
+│   │   ├── charter.md
+│   │   └── history.md
+│   └── ...
+└── config.json                    # Optional: personal squad config
+```
+
+## How It Works
+
+1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory
+2. **Merge:** Personal agents are merged into the session cast alongside project agents
+3. **Ghost Protocol:** Personal agents can read project state but not write to it
+4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery
+
+## Commands
+
+- `squad personal init` — Bootstrap a personal squad directory
+- `squad personal list` — List your personal agents
+- `squad personal add {name} --role {role}` — Add a personal agent
+- `squad personal remove {name}` — Remove a personal agent
+- `squad cast` — Show the current session cast (project + personal)
+
+## Ghost Protocol
+
+See `templates/ghost-protocol.md` for the full rules. Key points:
+- Personal agents advise; project agents execute
+- No writes to project `.squad/` state
+- Transparent origin tagging in logs
+- Project agents take precedence on conflicts
+
+## Configuration
+
+Optional `config.json` in the personal squad directory:
+```json
+{
+  "defaultModel": "auto",
+  "ghostProtocol": true,
+  "agents": {}
+}
+```
+
+## Environment Variables
+
+- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery
+- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path

package/templates/skills/pr-screenshots/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: "pr-screenshots"
+description: "Capture Playwright screenshots and embed them in GitHub PR descriptions"
+domain: "pull-requests, visual-review, docs, testing"
+confidence: "high"
+source: "earned (multiple sessions establishing the pattern for PR #11 TypeDoc API reference)"
+---
+
+## Context
+
+When a PR includes visual changes (docs sites, UI components, generated pages), reviewers
+need to see what the PR delivers without checking out the branch. Screenshots belong in
+the **PR description body**, not as committed files and not as text descriptions.
+
+Use this skill whenever:
+- A PR touches docs site pages (Astro, Starlight, etc.)
+- A PR adds or changes UI components
+- A PR generates visual artifacts (TypeDoc, Storybook, diagrams)
+- Playwright tests already capture screenshots as part of testing
+
+## Patterns
+
+### 1. Capture screenshots with Playwright
+
+If Playwright tests already exist and produce screenshots, reuse those. Otherwise,
+write a minimal capture script:
+
+```javascript
+// scripts/capture-pr-screenshots.mjs
+import { chromium } from 'playwright';
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1280, height: 720 } });
+
+const screenshots = [
+  { url: 'http://localhost:4321/path/to/page', name: 'feature-landing' },
+  { url: 'http://localhost:4321/path/to/detail', name: 'feature-detail' },
+];
+
+for (const { url, name } of screenshots) {
+  await page.goto(url, { waitUntil: 'networkidle' });
+  await page.screenshot({ path: `screenshots/${name}.png`, fullPage: false });
+}
+
+await browser.close();
+```
+
+### 2. Host screenshots on a temporary branch
+
+GitHub PR descriptions render images via URLs. The `gh` CLI cannot upload binary
+images directly. Use a temporary orphan branch to host the images:
+
+```powershell
+# Save current branch
+$currentBranch = git branch --show-current
+
+# Create orphan branch with only screenshot files
+git checkout --orphan screenshots-temp
+git reset
+git add screenshots/*.png
+git commit -m "screenshots for PR review"
+git push origin screenshots-temp --force
+
+# Build raw URLs
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+# Each image: $base/{name}.png
+
+# Return to working branch
+git checkout -f $currentBranch
+```
+
+### 3. Embed in PR description
+
+Use `gh pr edit` with the raw URLs embedded as markdown images:
+
+```powershell
+$base = "https://raw.githubusercontent.com/{owner}/{repo}/screenshots-temp/screenshots"
+
+gh pr edit {PR_NUMBER} --repo {owner}/{repo} --body @"
+## {PR Title}
+
+### What this PR delivers
+- {bullet points of changes}
+
+---
+
+### Screenshots
+
+#### {Page/Feature Name}
+![{alt text}]($base/{name}.png)
+
+#### {Another Page}
+![{alt text}]($base/{another-name}.png)
+
+---
+
+### To verify locally
+```bash
+{commands to run locally}
+```
+"@
+```
+
+### 4. Cleanup after merge
+
+After the PR is merged, delete the temporary branch:
+
+```bash
+git push origin --delete screenshots-temp
+```
+
+### 5. Gitignore screenshots locally
+
+Screenshots are build artifacts — never commit them to feature branches:
+
+```gitignore
+# PR screenshots (hosted on temp branch, not committed to features)
+screenshots/
+docs/tests/screenshots/
+```
+
+## Examples
+
+### Example: Docs site PR with 3 pages
+
+1. Start dev server: `cd docs && npm run dev`
+2. Run Playwright tests (they capture screenshots as a side effect)
+3. Push screenshots to `screenshots-temp` branch
+4. Update PR body with embedded `![...]()` image references
+5. Reviewer sees the pages inline without checking out the branch
+
+### Example: Reusing existing Playwright test screenshots
+
+If tests at `docs/tests/*.spec.mjs` already save to `docs/tests/screenshots/`:
+
+```powershell
+cd docs && npx playwright test tests/api-reference.spec.mjs
+# Screenshots now at docs/tests/screenshots/*.png
+# Push those to screenshots-temp and embed in PR
+```
+
+## Anti-Patterns
+
+- ❌ **Committing screenshots to feature branches** — they bloat the repo and go stale
+- ❌ **Posting text descriptions instead of actual images** — reviewers can't see what they're getting
+- ❌ **Using `gh` CLI to "upload" images** — `gh issue comment` and `gh pr edit` don't support binary uploads
+- ❌ **Asking the user to manually drag-drop images** — automate it with the temp branch pattern
+- ❌ **Skipping screenshots for visual PRs** — if the PR changes what users see, show what users see
+- ❌ **Leaving the screenshots-temp branch around forever** — clean up after merge