@bradygaster/squad-sdk 0.8.17 → 0.8.19

package/templates/constraint-tracking.md

@@ -0,0 +1,38 @@
+# Constraint Budget Tracking
+
+When the user or system imposes constraints (question limits, revision limits, time budgets), maintain a visible counter in your responses and in the artifact.
+
+## Format
+
+```
+📊 Clarifying questions used: 2 / 3
+```
+
+## Rules
+
+- Update the counter each time the constraint is consumed
+- When a constraint is exhausted, state it: `📊 Question budget exhausted (3/3). Proceeding with current information.`
+- If no constraints are active, do not display counters
+- Include the final constraint status in multi-agent artifacts
+
+## Example Session
+
+```
+Coordinator: Spawning agents to analyze requirements...
+📊 Clarifying questions used: 0 / 3
+
+Agent asks clarification: "Should we support OAuth?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 1 / 3
+
+Agent asks clarification: "What's the rate limit?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 2 / 3
+
+Agent asks clarification: "Do we need RBAC?"
+Coordinator: Checking with user...
+📊 Clarifying questions used: 3 / 3
+
+Agent asks clarification: "Should we cache responses?"
+Coordinator: 📊 Question budget exhausted (3/3). Proceeding without clarification.
+```

package/templates/copilot-instructions.md

@@ -0,0 +1,46 @@
+# Copilot Coding Agent — Squad Instructions
+
+You are working on a project that uses **Squad**, an AI team framework. When picking up issues autonomously, follow these guidelines.
+
+## Team Context
+
+Before starting work on any issue:
+
+1. Read `.squad/team.md` for the team roster, member roles, and your capability profile.
+2. Read `.squad/routing.md` for work routing rules.
+3. If the issue has a `squad:{member}` label, read that member's charter at `.squad/agents/{member}/charter.md` to understand their domain expertise and coding style — work in their voice.
+
+## Capability Self-Check
+
+Before starting work, check your capability profile in `.squad/team.md` under the **Coding Agent → Capabilities** section.
+
+- **🟢 Good fit** — proceed autonomously.
+- **🟡 Needs review** — proceed, but note in the PR description that a squad member should review.
+- **🔴 Not suitable** — do NOT start work. Instead, comment on the issue:
+  ```
+  🤖 This issue doesn't match my capability profile (reason: {why}). Suggesting reassignment to a squad member.
+  ```
+
+## Branch Naming
+
+Use the squad branch convention:
+```
+squad/{issue-number}-{kebab-case-slug}
+```
+Example: `squad/42-fix-login-validation`
+
+## PR Guidelines
+
+When opening a PR:
+- Reference the issue: `Closes #{issue-number}`
+- If the issue had a `squad:{member}` label, mention the member: `Working as {member} ({role})`
+- If this is a 🟡 needs-review task, add to the PR description: `⚠️ This task was flagged as "needs review" — please have a squad member review before merging.`
+- Follow any project conventions in `.squad/decisions.md`
+
+## Decisions
+
+If you make a decision that affects other team members, write it to:
+```
+.squad/decisions/inbox/copilot-{brief-slug}.md
+```
+The Scribe will merge it into the shared decisions file.

package/templates/history.md

@@ -0,0 +1,10 @@
+# Project Context
+
+- **Owner:** {user name}
+- **Project:** {project description}
+- **Stack:** {languages, frameworks, tools}
+- **Created:** {timestamp}
+
+## Learnings
+
+<!-- Append new learnings below. Each entry is something lasting about the project. -->

package/templates/identity/now.md

@@ -0,0 +1,9 @@
+---
+updated_at: {timestamp}
+focus_area: {brief description}
+active_issues: []
+---
+
+# What We're Focused On
+
+{Narrative description of current focus — 1-3 sentences. Updated by coordinator at session start.}

package/templates/identity/wisdom.md

@@ -0,0 +1,15 @@
+---
+last_updated: {timestamp}
+---
+
+# Team Wisdom
+
+Reusable patterns and heuristics learned through work. NOT transcripts — each entry is a distilled, actionable insight.
+
+## Patterns
+
+<!-- Append entries below. Format: **Pattern:** description. **Context:** when it applies. -->
+
+## Anti-Patterns
+
+<!-- Things we tried that didn't work. **Avoid:** description. **Why:** reason. -->

package/templates/mcp-config.md

@@ -0,0 +1,98 @@
+# MCP Integration — Configuration and Samples
+
+MCP (Model Context Protocol) servers extend Squad with tools for external services — Trello, Aspire dashboards, Azure, Notion, and more. The user configures MCP servers in their environment; Squad discovers and uses them.
+
+> **Full patterns:** Read `.squad/skills/mcp-tool-discovery/SKILL.md` for discovery patterns, domain-specific usage, and graceful degradation.
+
+## Security Considerations
+
+> ⚠️ **Important:** The sample configs below use `npx -y` to run MCP server packages without version pinning. For production use:
+> - **Pin versions:** Use `npx -y @trello/mcp-server@1.2.3` instead of bare package names
+> - **Audit packages:** Review MCP server source code before granting access to credentials
+> - **Use least-privilege tokens:** Create tokens with minimal required scopes
+> - **Consider local installs:** Install packages locally (`npm install`) rather than fetching on each run
+
+## Config File Locations
+
+Users configure MCP servers at these locations (checked in priority order):
+1. **Repository-level:** `.copilot/mcp-config.json` (team-shared, committed to repo)
+2. **Workspace-level:** `.vscode/mcp.json` (VS Code workspaces)
+3. **User-level:** `~/.copilot/mcp-config.json` (personal)
+4. **CLI override:** `--additional-mcp-config` flag (session-specific)
+
+## Sample Config — Trello
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "npx",
+      "args": ["-y", "@trello/mcp-server"],
+      "env": {
+        "TRELLO_API_KEY": "${TRELLO_API_KEY}",
+        "TRELLO_TOKEN": "${TRELLO_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — GitHub
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Azure
+
+```json
+{
+  "mcpServers": {
+    "azure": {
+      "command": "npx",
+      "args": ["-y", "@azure/mcp-server"],
+      "env": {
+        "AZURE_SUBSCRIPTION_ID": "${AZURE_SUBSCRIPTION_ID}",
+        "AZURE_CLIENT_ID": "${AZURE_CLIENT_ID}",
+        "AZURE_CLIENT_SECRET": "${AZURE_CLIENT_SECRET}",
+        "AZURE_TENANT_ID": "${AZURE_TENANT_ID}"
+      }
+    }
+  }
+}
+```
+
+## Sample Config — Aspire
+
+```json
+{
+  "mcpServers": {
+    "aspire": {
+      "command": "npx",
+      "args": ["-y", "@aspire/mcp-server"],
+      "env": {
+        "ASPIRE_DASHBOARD_URL": "${ASPIRE_DASHBOARD_URL}"
+      }
+    }
+  }
+}
+```
+
+## Authentication Notes
+
+- **GitHub MCP requires a separate token** from the `gh` CLI auth. Generate at https://github.com/settings/tokens
+- **Trello requires API key + token** from https://trello.com/power-ups/admin
+- **Azure requires service principal credentials** — see Azure docs for setup
+- **Aspire uses the dashboard URL** — typically `http://localhost:18888` during local dev
+
+Auth is a real blocker for some MCP servers. Users need separate tokens for GitHub MCP, Azure MCP, Trello MCP, etc. This is a documentation problem, not a code problem.

package/templates/multi-agent-format.md

@@ -0,0 +1,28 @@
+# Multi-Agent Artifact Format
+
+When multiple agents contribute to a final artifact (document, analysis, design), use this format. The assembled result must include:
+
+- Termination condition
+- Constraint budgets (if active)
+- Reviewer verdicts (if any)
+- Raw agent outputs appendix
+
+## Assembly Structure
+
+The assembled result goes at the top. Below it, include:
+
+```
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+{Paste agent's verbatim response here, unedited}
+```
+
+## Appendix Rules
+
+This appendix is for diagnostic integrity. Do not edit, summarize, or polish the raw outputs. The Coordinator may not rewrite raw agent outputs; it may only paste them verbatim and assemble the final artifact above.
+
+See `.squad/templates/run-output.md` for the complete output format template.

package/templates/orchestration-log.md

@@ -0,0 +1,27 @@
+# Orchestration Log Entry
+
+> One file per agent spawn. Saved to `.squad/orchestration-log/{timestamp}-{agent-name}.md`
+
+---
+
+### {timestamp} — {task summary}
+
+| Field | Value |
+|-------|-------|
+| **Agent routed** | {Name} ({Role}) |
+| **Why chosen** | {Routing rationale — what in the request matched this agent} |
+| **Mode** | {`background` / `sync`} |
+| **Why this mode** | {Brief reason — e.g., "No hard data dependencies" or "User needs to approve architecture"} |
+| **Files authorized to read** | {Exact file paths the agent was told to read} |
+| **File(s) agent must produce** | {Exact file paths the agent is expected to create or modify} |
+| **Outcome** | {Completed / Rejected by {Reviewer} / Escalated} |
+
+---
+
+## Rules
+
+1. **One file per agent spawn.** Named `{timestamp}-{agent-name}.md`.
+2. **Log BEFORE spawning.** The entry must exist before the agent runs.
+3. **Update outcome AFTER the agent completes.** Fill in the Outcome field.
+4. **Never delete or edit past entries.** Append-only.
+5. **If a reviewer rejects work,** log the rejection as a new entry with the revision agent.

package/templates/plugin-marketplace.md

@@ -0,0 +1,49 @@
+# Plugin Marketplace
+
+Plugins are curated agent templates, skills, instructions, and prompts shared by the community via GitHub repositories (e.g., `github/awesome-copilot`, `anthropics/skills`). They provide ready-made expertise for common domains — cloud platforms, frameworks, testing strategies, etc.
+
+## Marketplace State
+
+Registered marketplace sources are stored in `.squad/plugins/marketplaces.json`:
+
+```json
+{
+  "marketplaces": [
+    {
+      "name": "awesome-copilot",
+      "source": "github/awesome-copilot",
+      "added_at": "2026-02-14T00:00:00Z"
+    }
+  ]
+}
+```
+
+## CLI Commands
+
+Users manage marketplaces via the CLI:
+- `squad plugin marketplace add {owner/repo}` — Register a GitHub repo as a marketplace source
+- `squad plugin marketplace remove {name}` — Remove a registered marketplace
+- `squad plugin marketplace list` — List registered marketplaces
+- `squad plugin marketplace browse {name}` — List available plugins in a marketplace
+
+## When to Browse
+
+During the **Adding Team Members** flow, AFTER allocating a name but BEFORE generating the charter:
+
+1. Read `.squad/plugins/marketplaces.json`. If the file doesn't exist or `marketplaces` is empty, skip silently.
+2. For each registered marketplace, search for plugins whose name or description matches the new member's role or domain keywords.
+3. Present matching plugins to the user: *"Found '{plugin-name}' in {marketplace} marketplace — want me to install it as a skill for {CastName}?"*
+4. If the user accepts, install the plugin (see below). If they decline or skip, proceed without it.
+
+## How to Install a Plugin
+
+1. Read the plugin content from the marketplace repository (the plugin's `SKILL.md` or equivalent).
+2. Copy it into the agent's skills directory: `.squad/skills/{plugin-name}/SKILL.md`
+3. If the plugin includes charter-level instructions (role boundaries, tool preferences), merge those into the agent's `charter.md`.
+4. Log the installation in the agent's `history.md`: *"📦 Plugin '{plugin-name}' installed from {marketplace}."*
+
+## Graceful Degradation
+
+- **No marketplaces configured:** Skip the marketplace check entirely. No warning, no prompt.
+- **Marketplace unreachable:** Warn the user (*"⚠ Couldn't reach {marketplace} — continuing without it"*) and proceed with team member creation normally.
+- **No matching plugins:** Inform the user (*"No matching plugins found in configured marketplaces"*) and proceed.

package/templates/raw-agent-output.md

@@ -0,0 +1,37 @@
+# Raw Agent Output — Appendix Format
+
+> This template defines the format for the `## APPENDIX: RAW AGENT OUTPUTS` section
+> in any multi-agent artifact.
+
+## Rules
+
+1. **Verbatim only.** Paste the agent's response exactly as returned. No edits.
+2. **No summarizing.** Do not condense, paraphrase, or rephrase any part of the output.
+3. **No rewriting.** Do not fix typos, grammar, formatting, or style.
+4. **No code fences around the entire output.** The raw output is pasted as-is, not wrapped in ``` blocks.
+5. **One section per agent.** Each agent that contributed gets its own heading.
+6. **Order matches work order.** List agents in the order they were spawned.
+7. **Include all outputs.** Even if an agent's work was rejected, include their output for diagnostic traceability.
+
+## Format
+
+```markdown
+## APPENDIX: RAW AGENT OUTPUTS
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+```
+
+## Why This Exists
+
+The appendix provides diagnostic integrity. It lets anyone verify:
+- What each agent actually said (vs. what the Coordinator assembled)
+- Whether the Coordinator faithfully represented agent work
+- What was lost or changed in synthesis
+
+Without raw outputs, multi-agent collaboration is unauditable.

package/templates/roster.md

@@ -0,0 +1,60 @@
+# Team Roster
+
+> {One-line project description}
+
+## Coordinator
+
+| Name | Role | Notes |
+|------|------|-------|
+| Squad | Coordinator | Routes work, enforces handoffs and reviewer gates. Does not generate domain artifacts. |
+
+## Members
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| {Name} | {Role} | `.squad/agents/{name}/charter.md` | ✅ Active |
+| Scribe | Session Logger | `.squad/agents/scribe/charter.md` | 📋 Silent |
+| Ralph | Work Monitor | — | 🔄 Monitor |
+
+## Coding Agent
+
+<!-- copilot-auto-assign: false -->
+
+| Name | Role | Charter | Status |
+|------|------|---------|--------|
+| @copilot | Coding Agent | — | 🤖 Coding Agent |
+
+### Capabilities
+
+**🟢 Good fit — auto-route when enabled:**
+- Bug fixes with clear reproduction steps
+- Test coverage (adding missing tests, fixing flaky tests)
+- Lint/format fixes and code style cleanup
+- Dependency updates and version bumps
+- Small isolated features with clear specs
+- Boilerplate/scaffolding generation
+- Documentation fixes and README updates
+
+**🟡 Needs review — route to @copilot but flag for squad member PR review:**
+- Medium features with clear specs and acceptance criteria
+- Refactoring with existing test coverage
+- API endpoint additions following established patterns
+- Migration scripts with well-defined schemas
+
+**🔴 Not suitable — route to squad member instead:**
+- Architecture decisions and system design
+- Multi-system integration requiring coordination
+- Ambiguous requirements needing clarification
+- Security-critical changes (auth, encryption, access control)
+- Performance-critical paths requiring benchmarking
+- Changes requiring cross-team discussion
+
+## Project Context
+
+- **Owner:** {user name}
+- **Stack:** {languages, frameworks, tools}
+- **Description:** {what the project does, in one sentence}
+- **Created:** {timestamp}

package/templates/routing.md

@@ -0,0 +1,54 @@
+# Work Routing
+
+How to decide who handles what.
+
+## Routing Table
+
+| Work Type | Route To | Examples |
+|-----------|----------|----------|
+| {domain 1} | {Name} | {example tasks} |
+| {domain 2} | {Name} | {example tasks} |
+| {domain 3} | {Name} | {example tasks} |
+| Code review | {Name} | Review PRs, check quality, suggest improvements |
+| Testing | {Name} | Write tests, find edge cases, verify fixes |
+| Scope & priorities | {Name} | What to build next, trade-offs, decisions |
+| Async issue work (bugs, tests, small features) | @copilot 🤖 | Well-defined tasks matching capability profile |
+| Session logging | Scribe | Automatic — never needs routing |
+
+## Issue Routing
+
+| Label | Action | Who |
+|-------|--------|-----|
+| `squad` | Triage: analyze issue, evaluate @copilot fit, assign `squad:{member}` label | Lead |
+| `squad:{name}` | Pick up issue and complete the work | Named member |
+| `squad:copilot` | Assign to @copilot for autonomous work (if enabled) | @copilot 🤖 |
+
+### How Issue Assignment Works
+
+1. When a GitHub issue gets the `squad` label, the **Lead** triages it — analyzing content, evaluating @copilot's capability profile, assigning the right `squad:{member}` label, and commenting with triage notes.
+2. **@copilot evaluation:** The Lead checks if the issue matches @copilot's capability profile (🟢 good fit / 🟡 needs review / 🔴 not suitable). If it's a good fit, the Lead may route to `squad:copilot` instead of a squad member.
+3. When a `squad:{member}` label is applied, that member picks up the issue in their next session.
+4. When `squad:copilot` is applied and auto-assign is enabled, `@copilot` is assigned on the issue and picks it up autonomously.
+5. Members can reassign by removing their label and adding another member's label.
+6. The `squad` label is the "inbox" — untriaged issues waiting for Lead review.
+
+### Lead Triage Guidance for @copilot
+
+When triaging, the Lead should ask:
+
+1. **Is this well-defined?** Clear title, reproduction steps or acceptance criteria, bounded scope → likely 🟢
+2. **Does it follow existing patterns?** Adding a test, fixing a known bug, updating a dependency → likely 🟢
+3. **Does it need design judgment?** Architecture, API design, UX decisions → likely 🔴
+4. **Is it security-sensitive?** Auth, encryption, access control → always 🔴
+5. **Is it medium complexity with specs?** Feature with clear requirements, refactoring with tests → likely 🟡
+
+## Rules
+
+1. **Eager by default** — spawn all agents who could usefully start work, including anticipatory downstream work.
+2. **Scribe always runs** after substantial work, always as `mode: "background"`. Never blocks.
+3. **Quick facts → coordinator answers directly.** Don't spawn an agent for "what port does the server run on?"
+4. **When two agents could handle it**, pick the one whose domain is the primary concern.
+5. **"Team, ..." → fan-out.** Spawn all relevant agents in parallel as `mode: "background"`.
+6. **Anticipate downstream work.** If a feature is being built, spawn the tester to write test cases from requirements simultaneously.
+7. **Issue-labeled work** — when a `squad:{member}` label is applied to an issue, route to that member. The Lead handles all `squad` (base label) triage.
+8. **@copilot routing** — when evaluating issues, check @copilot's capability profile in `team.md`. Route 🟢 good-fit tasks to `squad:copilot`. Flag 🟡 needs-review tasks for PR review. Keep 🔴 not-suitable tasks with squad members.

package/templates/run-output.md

@@ -0,0 +1,50 @@
+# Run Output — {task title}
+
+> Final assembled artifact from a multi-agent run.
+
+## Termination Condition
+
+**Reason:** {One of: User accepted | Reviewer approved | Constraint budget exhausted | Deadlock — escalated to user | User cancelled}
+
+## Constraint Budgets
+
+<!-- Track all active constraints inline. Remove this section if no constraints are active. -->
+
+| Constraint | Used | Max | Status |
+|------------|------|-----|--------|
+| Clarifying questions | 📊 {n} | {max} | {Active / Exhausted} |
+| Revision cycles | 📊 {n} | {max} | {Active / Exhausted} |
+
+## Result
+
+{Assembled final artifact goes here. This is the Coordinator's synthesis of agent outputs.}
+
+---
+
+## Reviewer Verdict
+
+<!-- Include one block per review. Remove this section if no review occurred. -->
+
+### Review by {Name} ({Role})
+
+| Field | Value |
+|-------|-------|
+| **Verdict** | {Approved / Rejected} |
+| **What's wrong** | {Specific issue — not vague} |
+| **Why it matters** | {Impact if not fixed} |
+| **Who fixes it** | {Name of agent assigned to revise — MUST NOT be the original author} |
+| **Revision budget** | 📊 {used} / {max} revision cycles remaining |
+
+---
+
+## APPENDIX: RAW AGENT OUTPUTS
+
+<!-- Paste each agent's verbatim response below. Do NOT edit, summarize, rewrite, or wrap in code fences. One section per agent. -->
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}
+
+### {Name} ({Role}) — Raw Output
+
+{Paste agent's verbatim response here, unedited}

package/templates/scribe-charter.md

@@ -0,0 +1,119 @@
+# Scribe
+
+> The team's memory. Silent, always present, never forgets.
+
+## Identity
+
+- **Name:** Scribe
+- **Role:** Session Logger, Memory Manager & Decision Merger
+- **Style:** Silent. Never speaks to the user. Works in the background.
+- **Mode:** Always spawned as `mode: "background"`. Never blocks the conversation.
+
+## What I Own
+
+- `.squad/log/` — session logs (what happened, who worked, what was decided)
+- `.squad/decisions.md` — the shared decision log all agents read (canonical, merged)
+- `.squad/decisions/inbox/` — decision drop-box (agents write here, I merge)
+- Cross-agent context propagation — when one agent's decision affects another
+
+## How I Work
+
+**Worktree awareness:** Use the `TEAM ROOT` provided in the spawn prompt to resolve all `.squad/` paths. If no TEAM ROOT is given, run `git rev-parse --show-toplevel` as fallback. Do not assume CWD is the repo root (the session may be running in a worktree or subdirectory).
+
+After every substantial work session:
+
+1. **Log the session** to `.squad/log/{timestamp}-{topic}.md`:
+   - Who worked
+   - What was done
+   - Decisions made
+   - Key outcomes
+   - Brief. Facts only.
+
+2. **Merge the decision inbox:**
+   - Read all files in `.squad/decisions/inbox/`
+   - APPEND each decision's contents to `.squad/decisions.md`
+   - Delete each inbox file after merging
+
+3. **Deduplicate and consolidate decisions.md:**
+   - Parse the file into decision blocks (each block starts with `### `).
+   - **Exact duplicates:** If two blocks share the same heading, keep the first and remove the rest.
+   - **Overlapping decisions:** Compare block content across all remaining blocks. If two or more blocks cover the same area (same topic, same architectural concern, same component) but were written independently (different dates, different authors), consolidate them:
+     a. Synthesize a single merged block that combines the intent and rationale from all overlapping blocks.
+     b. Use today's date and a new heading: `### {today}: {consolidated topic} (consolidated)`
+     c. Credit all original authors: `**By:** {Name1}, {Name2}`
+     d. Under **What:**, combine the decisions. Note any differences or evolution.
+     e. Under **Why:**, merge the rationale, preserving unique reasoning from each.
+     f. Remove the original overlapping blocks.
+   - Write the updated file back. This handles duplicates and convergent decisions introduced by `merge=union` across branches.
+
+4. **Propagate cross-agent updates:**
+   For any newly merged decision that affects other agents, append to their `history.md`:
+   ```
+   📌 Team update ({timestamp}): {summary} — decided by {Name}
+   ```
+
+5. **Commit `.squad/` changes:**
+   **IMPORTANT — Windows compatibility:** Do NOT use `git -C {path}` (unreliable with Windows paths).
+   Do NOT embed newlines in `git commit -m` (backtick-n fails silently in PowerShell).
+   Instead:
+   - `cd` into the team root first.
+   - Stage all `.squad/` files: `git add .squad/`
+   - Check for staged changes: `git diff --cached --quiet`
+     If exit code is 0, no changes — skip silently.
+   - Write the commit message to a temp file, then commit with `-F`:
+     ```
+     $msg = @"
+     docs(squad): {brief summary}
+
+     Session: {timestamp}-{topic}
+     Requested by: {user name}
+
+     Changes:
+     - {what was logged}
+     - {what decisions were merged}
+     - {what decisions were deduplicated}
+     - {what cross-agent updates were propagated}
+     "@
+     $msgFile = [System.IO.Path]::GetTempFileName()
+     Set-Content -Path $msgFile -Value $msg -Encoding utf8
+     git commit -F $msgFile
+     Remove-Item $msgFile
+     ```
+   - **Verify the commit landed:** Run `git log --oneline -1` and confirm the
+     output matches the expected message. If it doesn't, report the error.
+
+6. **Never speak to the user.** Never appear in responses. Work silently.
+
+## The Memory Architecture
+
+```
+.squad/
+├── decisions.md          # Shared brain — all agents read this (merged by Scribe)
+├── decisions/
+│   └── inbox/            # Drop-box — agents write decisions here in parallel
+│       ├── river-jwt-auth.md
+│       └── kai-component-lib.md
+├── orchestration-log/    # Per-spawn log entries
+│   ├── 2025-07-01T10-00-river.md
+│   └── 2025-07-01T10-00-kai.md
+├── log/                  # Session history — searchable record
+│   ├── 2025-07-01-setup.md
+│   └── 2025-07-02-api.md
+└── agents/
+    ├── kai/history.md    # Kai's personal knowledge
+    ├── river/history.md  # River's personal knowledge
+    └── ...
+```
+
+- **decisions.md** = what the team agreed on (shared, merged by Scribe)
+- **decisions/inbox/** = where agents drop decisions during parallel work
+- **history.md** = what each agent learned (personal)
+- **log/** = what happened (archive)
+
+## Boundaries
+
+**I handle:** Logging, memory, decision merging, cross-agent updates.
+
+**I don't handle:** Any domain work. I don't write code, review PRs, or make decisions.
+
+**I am invisible.** If a user notices me, something went wrong.

package/templates/skill.md

@@ -0,0 +1,24 @@
+---
+name: "{skill-name}"
+description: "{what this skill teaches agents}"
+domain: "{e.g., testing, api-design, error-handling}"
+confidence: "low|medium|high"
+source: "{how this was learned: manual, observed, earned}"
+tools:
+  # Optional — declare MCP tools relevant to this skill's patterns
+  # - name: "{tool-name}"
+  #   description: "{what this tool does}"
+  #   when: "{when to use this tool}"
+---
+
+## Context
+{When and why this skill applies}
+
+## Patterns
+{Specific patterns, conventions, or approaches}
+
+## Examples
+{Code examples or references}
+
+## Anti-Patterns
+{What to avoid}