@bradygaster/squad-sdk 0.9.6-insider.2 → 0.10.0

package/dist/utils/map-with-limit.js

@@ -0,0 +1,81 @@
+/**
+ * Bounded-concurrency helper for fan-out async work.
+ *
+ * @module utils/map-with-limit
+ */
+/**
+ * Run `fn` against each item with at most `limit` operations in flight.
+ *
+ * Results are returned in **input order**, regardless of the order in which
+ * individual promises settle. This matches the semantics callers usually
+ * want when migrating from a sequential `for (const x of xs) { result.push(await fn(x)); }`
+ * pattern: ordering is preserved, but throughput is bounded.
+ *
+ * Errors propagate via the returned Promise. Use `mapWithLimitSettled()`
+ * when individual failures should not abort the batch.
+ *
+ * @example
+ *   // 8 charters fetched 5-at-a-time over HTTP:
+ *   const manifests = await mapWithLimit(dirs, 5, (dir) => fetchCharter(dir));
+ *
+ * @param items     Inputs to map over.
+ * @param limit     Maximum concurrent calls (must be ≥ 1).
+ * @param fn        Async mapper.
+ * @returns Array of results in the same order as `items`.
+ */
+export async function mapWithLimit(items, limit, fn) {
+    if (limit < 1 || !Number.isFinite(limit)) {
+        throw new Error(`mapWithLimit: limit must be a positive integer, got ${limit}`);
+    }
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(limit, items.length);
+    async function worker() {
+        while (true) {
+            const idx = nextIndex++;
+            if (idx >= items.length)
+                return;
+            results[idx] = await fn(items[idx], idx);
+        }
+    }
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}
+/**
+ * Variant of {@link mapWithLimit} that captures individual failures rather
+ * than aborting on the first rejection. Returns an array of
+ * `{ status: 'fulfilled', value }` / `{ status: 'rejected', reason }` in
+ * input order — identical shape to `Promise.allSettled`.
+ *
+ * Use this when one bad input (e.g. a corrupt charter.md) should not stop
+ * the whole batch.
+ */
+export async function mapWithLimitSettled(items, limit, fn) {
+    if (limit < 1 || !Number.isFinite(limit)) {
+        throw new Error(`mapWithLimitSettled: limit must be a positive integer, got ${limit}`);
+    }
+    if (items.length === 0)
+        return [];
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    const workerCount = Math.min(limit, items.length);
+    async function worker() {
+        while (true) {
+            const idx = nextIndex++;
+            if (idx >= items.length)
+                return;
+            try {
+                const value = await fn(items[idx], idx);
+                results[idx] = { status: 'fulfilled', value };
+            }
+            catch (reason) {
+                results[idx] = { status: 'rejected', reason };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}
+//# sourceMappingURL=map-with-limit.js.map

package/dist/utils/map-with-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"map-with-limit.js","sourceRoot":"","sources":["../../src/utils/map-with-limit.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,KAAmB,EACnB,KAAa,EACb,EAA0C;IAE1C,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,uDAAuD,KAAK,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,OAAO,GAAG,IAAI,KAAK,CAAI,KAAK,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAElD,KAAK,UAAU,MAAM;QACnB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;YACxB,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAChC,OAAO,CAAC,GAAG,CAAC,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAE,EAAE,GAAG,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,KAAmB,EACnB,KAAa,EACb,EAA0C;IAE1C,IAAI,KAAK,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,8DAA8D,KAAK,EAAE,CAAC,CAAC;IACzF,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,MAAM,OAAO,GAAG,IAAI,KAAK,CAA0B,KAAK,CAAC,MAAM,CAAC,CAAC;IACjE,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IAElD,KAAK,UAAU,MAAM;QACnB,OAAO,IAAI,EAAE,CAAC;YACZ,MAAM,GAAG,GAAG,SAAS,EAAE,CAAC;YACxB,IAAI,GAAG,IAAI,KAAK,CAAC,MAAM;gBAAE,OAAO;YAChC,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,CAAE,EAAE,GAAG,CAAC,CAAC;gBACzC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC;YAChD,CAAC;YAAC,OAAO,MAAM,EAAE,CAAC;gBAChB,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC;YAChD,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACvE,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bradygaster/squad-sdk",
-  "version": "0.9.6-insider.2",
+  "version": "0.10.0",
   "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot",
   "type": "module",
   "main": "./dist/index.js",
@@ -194,6 +194,10 @@
       "types": "./dist/storage/index.d.ts",
       "import": "./dist/storage/index.js"
     },
+    "./memory": {
+      "types": "./dist/memory/index.d.ts",
+      "import": "./dist/memory/index.js"
+    },
     "./platform": {
       "types": "./dist/platform/index.d.ts",
       "import": "./dist/platform/index.js"
@@ -232,7 +236,7 @@
     "node": ">=22.5.0"
   },
   "dependencies": {
-    "@github/copilot-sdk": "^0.1.32",
+    "@github/copilot-sdk": "^0.3.0",
     "vscode-jsonrpc": "^8.2.1"
   },
   "optionalDependencies": {

package/templates/after-agent-reference.md

@@ -0,0 +1,64 @@
+# After Agent Reference
+
+### After Agent Work
+
+<!-- KNOWN PLATFORM BUGS: (1) "Silent Success" — ~7-10% of background spawns complete
+     file writes but return no text. Mitigated by RESPONSE ORDER + filesystem checks.
+     (2) "Server Error Retry Loop" — context overflow after fan-out. Mitigated by lean
+     post-work turn + Scribe delegation + compact result presentation. -->
+
+**⚡ Keep the post-work turn LEAN.** Coordinator's job: (1) present compact results, (2) spawn Scribe. That's ALL. No orchestration logs, no decision consolidation, no heavy file I/O.
+
+**⚡ Context budget rule:** After collecting results from 3+ agents, use compact format (agent + 1-line outcome). Full details go in orchestration log via Scribe.
+
+After each batch of agent work:
+
+1. **Collect results** via `read_agent` (wait: true, timeout: 300).
+
+2. **Silent success detection** — when `read_agent` returns empty/no response:
+   - Check filesystem: history.md modified? New decision inbox files? Output files created?
+   - Files found → `"⚠️ {Name} completed (files verified) but response lost."` Treat as DONE.
+   - No files → `"❌ {Name} failed — no work product."` Consider re-spawn.
+
+3. **Show compact results:** `{emoji} {Name} — {1-line summary of what they did}`
+
+4. **Spawn Scribe** (background, never wait). Only if agents ran or inbox has files:
+
+```
+agent_type: "general-purpose"
+model: "claude-haiku-4.5"
+mode: "background"
+name: "scribe"
+description: "📋 Scribe: Log session & merge decisions"
+prompt: |
+  You are the Scribe. Read .squad/agents/scribe/charter.md.
+  TEAM ROOT: {team_root}
+  CURRENT_DATETIME: <resolved CURRENT_DATETIME literal>
+  STATE_BACKEND: {state_backend}
+
+  SPAWN MANIFEST: {spawn_manifest}
+
+  Tasks (in order):
+  0. PRE-CHECK: Run `squad_state_health` when available. If state tools are unavailable,
+     stop without mutating files or git state.
+  0b. PRE-CHECK: Read `decisions.md` and list `decisions/inbox` with state tools.
+     Record measurements.
+  1. DECISIONS ARCHIVE [HARD GATE]: If decisions.md >= 20480 bytes, archive entries older than 30 days NOW. If >= 51200 bytes, archive entries older than 7 days. Do not skip this step.
+  2. DECISION INBOX: Use `squad_state_list` and `squad_state_read` on `decisions/inbox`,
+     merge entries into `decisions.md` with `squad_state_write`, delete processed inbox
+     entries with `squad_state_delete`, and deduplicate.
+  3. ORCHESTRATION LOG: Write `orchestration-log/{timestamp}-{agent}.md` with `squad_state_write` per agent. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms (e.g. `2026-06-02T21-15-30Z`).
+  4. SESSION LOG: Write `log/{timestamp}-{topic}.md` with `squad_state_write`. Brief. Use ISO 8601 UTC timestamp. Replace `:` with `-` in `{timestamp}` so filenames are valid on all platforms.
+  5. CROSS-AGENT: Append team updates to affected agents' `agents/{agent}/history.md` with `squad_state_append`.
+  6. HISTORY SUMMARIZATION [HARD GATE]: If any history.md >= 15360 bytes (15KB), summarize now.
+  7. HEALTH REPORT: Log decisions.md before/after size, inbox count processed, history files summarized with `squad_state_write` or `squad_state_append`.
+
+  Runtime state tools own persistence. Never switch branches, push note refs, reset
+  `.squad/`, or commit mutable squad state from this prompt.
+
+  Never speak to user. ⚠️ End with plain text summary after all tool calls.
+```
+
+5. **Immediately assess:** Does anything trigger follow-up work? Launch it NOW.
+
+6. **Ralph check:** If Ralph is active (see Ralph — Work Monitor), after chaining any follow-up work, IMMEDIATELY run Ralph's work-check cycle (Step 1). Do NOT stop. Do NOT wait for user input. Ralph keeps the pipeline moving until the board is clear.

package/templates/ceremony-reference.md

@@ -0,0 +1,82 @@
+# Ceremony Reference
+
+On-demand reference for ceremony configuration, facilitator spawn, and execution rules.
+
+## Config Format
+
+Ceremonies are declared in `.squad/ceremonies.md`. Each ceremony is a section with a table of fields:
+
+```markdown
+## {CeremonyName}
+
+| Field | Value |
+|-------|-------|
+| **Trigger** | auto \| manual |
+| **When** | before \| after |
+| **Condition** | {when auto-triggered: natural language condition} |
+| **Facilitator** | lead \| {specific-agent} |
+| **Participants** | all-relevant \| all-involved \| {comma-separated names} |
+| **Time budget** | focused \| extended |
+| **Enabled** | ✅ yes \| ❌ no |
+
+**Agenda:**
+1. {Step 1}
+2. {Step 2}
+...
+```
+
+### Field Definitions
+
+| Field | Values | Meaning |
+|-------|--------|---------|
+| Trigger | `auto` | Fires automatically when Condition matches |
+| Trigger | `manual` | Only when user says "run {ceremony}" |
+| When | `before` | Runs before work batch spawns |
+| When | `after` | Runs after work batch completes |
+| Condition | free text | Evaluated against current task context |
+| Facilitator | agent name | Who runs the meeting |
+| Participants | selector | Who attends |
+| Time budget | `focused` | Keep it short — key decisions only |
+| Time budget | `extended` | Thorough discussion — all angles |
+| Enabled | boolean | Skip disabled ceremonies entirely |
+
+## Facilitator Spawn Template
+
+When a ceremony triggers, spawn the facilitator (sync) with this prompt structure:
+
+```
+You are {FacilitatorName}, facilitating the "{CeremonyName}" ceremony.
+
+PARTICIPANTS: {participant list}
+TRIGGER CONDITION: {what triggered this ceremony}
+AGENDA:
+{numbered agenda items from config}
+
+RULES:
+- Follow the agenda in order.
+- For each agenda item, spawn relevant participants as sub-tasks to gather their input.
+- Synthesize participant input into clear decisions and action items.
+- Keep to the time budget: {focused|extended}.
+- Output a structured summary at the end.
+
+TASK CONTEXT:
+{description of the work that triggered this ceremony}
+```
+
+## Execution Rules
+
+1. **Before ceremonies** fire AFTER routing decisions but BEFORE agent spawn. The ceremony summary is included in all subsequent work-batch spawn prompts.
+2. **After ceremonies** fire when ALL agents in the batch have completed (success or failure).
+3. **Manual ceremonies** fire only on explicit user request ("run retro", "do a design review").
+4. **Cooldown:** After a ceremony completes, skip auto-trigger checks for the immediately following step. This prevents ceremony loops.
+5. **Participant resolution:**
+   - `all-relevant` → agents routed to the current task
+   - `all-involved` → agents that participated in the completed batch
+   - Named agents → spawn only those specific agents
+6. **Scribe integration:** Spawn Scribe (background) at ceremony start to record decisions and action items.
+7. **Output format:**
+   ```
+   📋 {CeremonyName} completed — facilitated by {Facilitator}.
+   Decisions: {count} | Action items: {count}.
+   ```
+8. **Failure handling:** If the facilitator fails or times out, log a warning and proceed with work. Ceremonies must never block the pipeline indefinitely.

package/templates/client-compatibility-reference.md

@@ -0,0 +1,46 @@
+# Client Compatibility Reference
+
+### 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.
+
+#### Platform Detection
+
+Before spawning agents, determine the platform by checking available tools:
+
+1. **CLI mode** — `task` tool is available → full spawning control. Use `task` with `agent_type`, `mode`, `model`, `description`, `prompt` parameters. Collect results via `read_agent`.
+
+2. **VS Code mode** — `runSubagent` or `agent` tool is available → conditional behavior. Use `runSubagent` with the task prompt. Drop `agent_type`, `mode`, and `model` parameters. Multiple subagents in one turn run concurrently (equivalent to background mode). Results return automatically — no `read_agent` needed.
+
+3. **Fallback mode** — neither `task` nor `runSubagent`/`agent` available → work inline. Do not apologize or explain the limitation. Execute the task directly.
+
+If both `task` and `runSubagent` are available, prefer `task` (richer parameter surface).
+
+#### VS Code Spawn Adaptations
+
+When in VS Code mode, the coordinator changes behavior in these ways:
+
+- **Spawning tool:** Use `runSubagent` instead of `task`. The prompt is the only required parameter — pass the full agent prompt (charter, identity, task, hygiene, response order) exactly as you would on CLI.
+- **Parallelism:** Spawn ALL concurrent agents in a SINGLE turn. They run in parallel automatically. This replaces `mode: "background"` + `read_agent` polling.
+- **Model selection:** Accept the session model. Do NOT attempt per-spawn model selection or fallback chains — they only work on CLI. In Phase 1, all subagents use whatever model the user selected in VS Code's model picker.
+- **Scribe:** Cannot fire-and-forget. Batch Scribe as the LAST subagent in any parallel group. Scribe is light work (file ops only), so the blocking is tolerable.
+- **Launch table:** Skip it. Results arrive with the response, not separately. By the time the coordinator speaks, the work is already done.
+- **`read_agent`:** Skip entirely. Results return automatically when subagents complete.
+- **`agent_type`:** Drop it. All VS Code subagents have full tool access by default. Subagents inherit the parent's tools.
+- **`description`:** Drop it. The agent name is already in the prompt.
+- **Prompt content:** Keep ALL prompt structure — charter, identity, task, hygiene, response order blocks are surface-independent.
+
+#### Feature Degradation Table
+
+| Feature | CLI | VS Code | Degradation |
+|---------|-----|---------|-------------|
+| Parallel fan-out | `mode: "background"` + `read_agent` | Multiple subagents in one turn | None — equivalent concurrency |
+| Model selection | Per-spawn `model` param (4-layer hierarchy) | Session model only (Phase 1) | Accept session model, log intent |
+| Scribe fire-and-forget | Background, never read | Sync, must wait | Batch with last parallel group |
+| Launch table UX | Show table → results later | Skip table → results with response | UX only — results are correct |
+| SQL tool | Available | Not available | Avoid SQL in cross-platform code paths |
+| Response order bug | Critical workaround | Possibly necessary (unverified) | Keep the block — harmless if unnecessary |
+
+#### SQL Tool Caveat
+
+The `sql` tool is **CLI-only**. It does not exist on VS Code, JetBrains, or GitHub.com. Any coordinator logic or agent workflow that depends on SQL (todo tracking, batch processing, session state) will silently fail on non-CLI surfaces. Cross-platform code paths must not depend on SQL. Use filesystem-based state (`.squad/` files) for anything that must work everywhere.

package/templates/copilot-agent.md

@@ -0,0 +1,96 @@
+# Copilot Coding Agent Member
+
+On-demand reference for adding the GitHub Copilot coding agent (@copilot) to the Squad roster.
+
+## Adding @copilot
+
+When the user says "add copilot", "add the coding agent", or "use @copilot for issues":
+
+1. **Add to team.md roster:**
+   ```markdown
+   | @copilot | Coding Agent | — | 🤖 Coding Agent |
+   ```
+2. **Add capability profile** (below the roster table):
+   ```markdown
+   <!-- copilot-auto-assign: true -->
+   ### @copilot — Capability Profile
+
+   | Capability | Level | Notes |
+   |-----------|-------|-------|
+   | Bug fixes (well-scoped) | 🟢 | Best for isolated, test-covered fixes |
+   | Feature implementation | 🟡 | Works well with clear specs; may need review |
+   | Refactoring | 🟡 | Handles mechanical refactors; verify scope |
+   | Architecture decisions | 🔴 | Cannot make cross-cutting design choices |
+   | Multi-repo coordination | 🔴 | Limited to single-repo context |
+   | Test writing | 🟢 | Strong at adding tests for existing code |
+   | Documentation | 🟢 | Generates docs from code effectively |
+   ```
+3. **Add routing entries** to routing.md for appropriate work types.
+4. **Do not create** `charter.md` — @copilot uses `copilot-instructions.md` instead.
+
+## Comparison: Spawned Agent vs. @copilot
+
+| | Spawned Agent | @copilot |
+|---|--------------|----------|
+| Execution model | Sync sub-task within session | Async — picks up assigned issues |
+| Branch convention | `squad/{issue}-{slug}` | `copilot/{slug}` |
+| Trigger | Coordinator spawns directly | Issue assignment |
+| Charter source | `.squad/agents/{name}/charter.md` | `.github/copilot-instructions.md` |
+| Context window | Inherits full session context | Fresh context per issue |
+| Reviewer gating | ✅ Enforced by coordinator | ✅ Via PR review process |
+| Speed | Immediate (in-session) | Minutes (async queue) |
+
+## Roster Format
+
+In `team.md`, @copilot always appears as:
+
+```markdown
+| @copilot | Coding Agent | — | 🤖 Coding Agent |
+```
+
+- **No casting** — always "@copilot" (literal handle).
+- **No charter file** — configuration lives in `.github/copilot-instructions.md`.
+- **No history file** — work is tracked via PRs and issue comments.
+
+## Auto-Assign Behavior
+
+Controlled by the HTML comment in team.md:
+
+```markdown
+<!-- copilot-auto-assign: true -->
+```
+
+| Setting | Behavior |
+|---------|----------|
+| `true` | Lead assigns routed issues to @copilot automatically via `gh issue edit --add-assignee @copilot` |
+| `false` | Lead presents recommendation; user confirms before assignment |
+
+## Lead Triage Integration
+
+During triage, Lead evaluates each issue against @copilot's capability profile:
+
+1. **🟢 Match** — Auto-assign (if enabled) or recommend assignment.
+2. **🟡 Match** — Assign with note: "⚠️ May need review — @copilot is 🟡 for this type of work."
+3. **🔴 Match** — Skip @copilot; route to appropriate spawned agent or human.
+
+## Routing Details
+
+Add to `routing.md`:
+
+```markdown
+| bug fixes (isolated, test-covered) | @copilot 🤖 | Single-file fixes, test additions |
+| documentation updates | @copilot 🤖 | README, API docs, inline comments |
+| test coverage gaps | @copilot 🤖 | Adding missing test cases |
+```
+
+Work that routes to @copilot:
+- Creates/assigns the GitHub issue (if not already)
+- Does NOT spawn a sub-agent — @copilot works asynchronously
+- Coordinator reports: "🤖 Assigned #{number} to @copilot — will open a PR when ready."
+- Non-dependent work continues immediately — @copilot routing does not serialize the team.
+
+## Monitoring @copilot Work
+
+On each watch cycle (or when user asks "status"):
+- Check for open PRs from `copilot/*` branches.
+- Report: "🤖 @copilot: {N} PRs open ({list}). {M} issues assigned, pending."

package/templates/copilot-instructions.md

@@ -2,6 +2,20 @@
 
 You are working on a project that uses **Squad**, an AI team framework. When picking up issues autonomously, follow these guidelines.
 
+## Coordinator Canary Check
+
+**IMPORTANT — run this check on EVERY session start, before doing any work:**
+
+Look for the exact token `SQUAD_COORDINATOR_CANARY_a8f3` in your `agent_instructions`. This token is placed at the end of `squad.agent.md`. If it is missing, the coordinator file is missing or truncated.
+
+**When the token is missing, you MUST:**
+1. **STOP** — do not proceed with standard Squad behavior.
+2. **WARN the user** with this exact message:
+   ```
+   ⚠️ Squad coordinator (squad.agent.md) appears to be missing or truncated. The canary token was not found. Do NOT proceed with standard Squad behavior — Squad's safety rails are not loaded. Please restart your session.
+   ```
+3. Do not continue with normal Squad routing, spawning, PR, or branch-protection behavior after emitting the warning.
+
 ## Team Context
 
 Before starting work on any issue:

package/templates/model-selection-reference.md

@@ -0,0 +1,101 @@
+# Model Selection Reference
+
+### Per-Agent Model Selection
+
+Before spawning an agent, determine which model to use. Check these layers in order — first match wins:
+
+**Layer 0 — Persistent Config (`.squad/config.json`):** On session start, read `.squad/config.json`. If `agentModelOverrides.{agentName}` exists, use that model for this specific agent. Otherwise, if `defaultModel` exists, use it for ALL agents. This layer survives across sessions — the user set it once and it sticks.
+
+- **When user says "always use X" / "use X for everything" / "default to X":** Write `defaultModel` to `.squad/config.json`. Acknowledge: `✅ Model preference saved: {model} — all future sessions will use this until changed.`
+- **When user says "use X for {agent}":** Write to `agentModelOverrides.{agent}` in `.squad/config.json`. Acknowledge: `✅ {Agent} will always use {model} — saved to config.`
+- **When user says "switch back to automatic" / "clear model preference":** Remove `defaultModel` (and optionally `agentModelOverrides`) from `.squad/config.json`. Acknowledge: `✅ Model preference cleared — returning to automatic selection.`
+
+**Layer 1 — Session Directive:** Did the user specify a model for this session? ("use opus for this session", "save costs"). If yes, use that model. Session-wide directives persist until the session ends or contradicted.
+
+**Layer 2 — Charter Preference:** Does the agent's charter have a `## Model` section with `Preferred` set to a specific model (not `auto`)? If yes, use that model.
+
+**Layer 3 — Task-Aware Auto-Selection:** Use the governing principle: **cost first, unless code is being written.** Match the agent's task to determine output type, then select accordingly:
+
+| Task Output | Model | Tier | Rule |
+|-------------|-------|------|------|
+| 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. |
+
+**Role-to-model mapping** (applying cost-first principle):
+
+| Role | Default Model | Why | Override When |
+|------|--------------|-----|---------------|
+| 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: code review needs quality, planning needs cost | Architecture proposals → 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.6` | 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) |
+| 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) |
+
+**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.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.
+
+**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.
+
+```
+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 → claude-sonnet-4.5 → gpt-5.4 → gpt-5.3-codex → claude-sonnet-4 → (omit model param)
+Fast:     claude-haiku-4.5 → gpt-5.4-mini → gpt-5.1-codex-mini → gpt-4.1 → (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.
+
+**Fallback rules:**
+- If the user specified a provider ("use Claude"), fall back within that provider only before hitting nuclear
+- Never fall back UP in tier — a fast/cheap task should not land on a premium model
+- Log fallbacks to the orchestration log for debugging, but never surface to the user unless asked
+
+**Passing the model to spawns:**
+
+Pass the resolved model as the `model` parameter on every `task` tool call:
+
+```
+agent_type: "general-purpose"
+model: "{resolved_model}"
+mode: "background"
+name: "{name}"
+description: "{emoji} {Name}: {brief task summary}"
+prompt: |
+  ...
+```
+
+Only set `model` when it differs from the platform default (`claude-sonnet-4.6`). If the resolved model IS `claude-sonnet-4.6`, you MAY omit the `model` parameter — the platform uses it as default.
+
+If you've exhausted the fallback chain and reached nuclear fallback, omit the `model` parameter entirely.
+
+**Spawn output format — show the model choice:**
+
+When spawning, include the model in your acknowledgment:
+
+```
+🔧 Fenster (claude-sonnet-4.6) — refactoring auth module
+🎨 Redfoot (claude-opus-4.5 · 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
+```
+
+Include tier annotation only when the model was bumped or a specialist was chosen. Default-tier spawns just show the model name.
+
+**Valid models (current platform catalog):**
+
+Premium: `claude-opus-4.6`, `claude-opus-4.6-1m` (Internal only), `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`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gemini-3-pro-preview`
+Fast/Cheap: `claude-haiku-4.5`, `gpt-5.4-mini`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1`

package/templates/prd-intake.md

@@ -0,0 +1,105 @@
+# PRD Intake
+
+On-demand reference for ingesting a PRD, decomposing it into work items, and managing updates.
+
+## Triggers
+
+| User says | Action |
+|-----------|--------|
+| "here's the PRD" / "work from this spec" | Expect file path or pasted content |
+| "read the PRD at {path}" | Read the file at that path |
+| "the PRD changed" / "updated the spec" | Re-read and diff against previous decomposition |
+| (pastes requirements text) | Treat as inline PRD |
+
+## Intake Flow
+
+1. **Detect source:** File path, pasted text, or URL. Store a reference in `.squad/team.md` under `## PRD Source`.
+2. **Store PRD reference:**
+   ```markdown
+   ## PRD Source
+
+   **Path:** {path-or-inline}
+   **Ingested:** {ISO date}
+   **Hash:** {sha256 of content, for change detection}
+   ```
+3. **Spawn Lead (sync, premium bump)** with decomposition prompt (see below).
+4. **Present work items** to user for approval in table format.
+5. **On approval:** Route items to agents respecting dependency order.
+
+## Lead Decomposition Spawn Template
+
+```
+You are the Lead, decomposing a PRD into actionable work items.
+
+PRD CONTENT:
+{full PRD text}
+
+TEAM ROSTER:
+{roster from team.md}
+
+TASK: Break this PRD into discrete, implementable work items. For each item provide:
+- Title (imperative mood, concise)
+- Description (acceptance criteria, technical notes)
+- Estimated complexity: S / M / L
+- Dependencies (list other item titles this blocks on)
+- Suggested assignee (agent name from roster, based on expertise match)
+
+OUTPUT FORMAT:
+Return a markdown table:
+
+| # | Title | Complexity | Dependencies | Assignee | Status |
+|---|-------|-----------|--------------|----------|--------|
+| 1 | {title} | {S/M/L} | — | {agent} | pending |
+
+RULES:
+- Items must be independently implementable (no item requires partial completion of another).
+- Maximum 1 day of work per item (split larger items).
+- Respect team expertise — don't assign frontend work to a backend specialist.
+- Order by dependency graph (items with no deps first).
+- Flag any ambiguities or missing information as "⚠️ Needs clarification: {question}".
+```
+
+## Work Item Presentation Format
+
+Present to user as:
+
+```
+📋 PRD decomposed into {N} work items:
+
+| # | Title | Size | Depends on | Assignee |
+|---|-------|------|-----------|----------|
+| 1 | ... | S | — | {Agent} |
+| 2 | ... | M | #1 | {Agent} |
+
+Ready to proceed? I'll route items respecting the dependency order.
+⚠️ Clarifications needed: {list any flagged items}
+```
+
+## Mid-Project Updates
+
+When the user says the PRD changed:
+
+1. Re-read the PRD content.
+2. Compute diff against stored hash.
+3. Spawn Lead (sync) with a delta-decomposition prompt:
+   - Show only NEW or CHANGED sections.
+   - Ask Lead to identify: new items, modified items, obsoleted items.
+4. Present changes to user:
+   ```
+   📋 PRD update detected:
+   - New items: {count}
+   - Modified: {count}
+   - Obsoleted: {count} (will be cancelled if approved)
+
+   {table of changes}
+
+   Approve these updates?
+   ```
+5. On approval: Cancel obsoleted work (if not yet started), update items, re-route.
+
+## State Tracking
+
+Active PRD state lives in team.md:
+- `## PRD Source` section (path, date, hash)
+- Work items tracked as issues (GitHub) or in `.squad/backlog.md` (offline mode)
+- Completion percentage displayed in status checks