@bradygaster/squad-sdk 0.9.0 → 0.9.1

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/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/project-conventions/SKILL.md

@@ -1,56 +1,56 @@
----
-name: "project-conventions"
-description: "Core conventions and patterns for this codebase"
-domain: "project-conventions"
-confidence: "medium"
-source: "template"
----
-
-## Context
-
-> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality.
-
-## Patterns
-
-### [Pattern Name]
-
-Describe a key convention or practice used in this codebase. Be specific about what to do and why.
-
-### Error Handling
-
-<!-- Example: How does your project handle errors? -->
-<!-- - Use try/catch with specific error types? -->
-<!-- - Log to a specific service? -->
-<!-- - Return error objects vs throwing? -->
-
-### Testing
-
-<!-- Example: What test framework? Where do tests live? How to run them? -->
-<!-- - Test framework: Jest/Vitest/node:test/etc. -->
-<!-- - Test location: test/, __tests__/, *.test.ts, etc. -->
-<!-- - Run command: npm test, etc. -->
-
-### Code Style
-
-<!-- Example: Linting, formatting, naming conventions -->
-<!-- - Linter: ESLint config? -->
-<!-- - Formatter: Prettier? -->
-<!-- - Naming: camelCase, snake_case, etc.? -->
-
-### File Structure
-
-<!-- Example: How is the project organized? -->
-<!-- - src/ — Source code -->
-<!-- - test/ — Tests -->
-<!-- - docs/ — Documentation -->
-
-## Examples
-
-```
-// Add code examples that demonstrate your conventions
-```
-
-## Anti-Patterns
-
-<!-- List things to avoid in this codebase -->
-- **[Anti-pattern]** — Explanation of what not to do and why.
+---
+name: "project-conventions"
+description: "Core conventions and patterns for this codebase"
+domain: "project-conventions"
+confidence: "medium"
+source: "template"
+---
+
+## Context
+
+> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality.
+
+## Patterns
+
+### [Pattern Name]
+
+Describe a key convention or practice used in this codebase. Be specific about what to do and why.
+
+### Error Handling
+
+<!-- Example: How does your project handle errors? -->
+<!-- - Use try/catch with specific error types? -->
+<!-- - Log to a specific service? -->
+<!-- - Return error objects vs throwing? -->
+
+### Testing
+
+<!-- Example: What test framework? Where do tests live? How to run them? -->
+<!-- - Test framework: Jest/Vitest/node:test/etc. -->
+<!-- - Test location: test/, __tests__/, *.test.ts, etc. -->
+<!-- - Run command: npm test, etc. -->
+
+### Code Style
+
+<!-- Example: Linting, formatting, naming conventions -->
+<!-- - Linter: ESLint config? -->
+<!-- - Formatter: Prettier? -->
+<!-- - Naming: camelCase, snake_case, etc.? -->
+
+### File Structure
+
+<!-- Example: How is the project organized? -->
+<!-- - src/ — Source code -->
+<!-- - test/ — Tests -->
+<!-- - docs/ — Documentation -->
+
+## Examples
+
+```
+// Add code examples that demonstrate your conventions
+```
+
+## Anti-Patterns
+
+<!-- List things to avoid in this codebase -->
+- **[Anti-pattern]** — Explanation of what not to do and why.