@bradygaster/squad-cli 0.8.25 → 0.9.0

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

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

@@ -0,0 +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