@bradygaster/squad-cli 0.8.20 → 0.8.23

package/templates/routing.md

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

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

@@ -1,119 +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` (use filename-safe timestamps — replace colons with hyphens, e.g., `2026-02-23T20-16-27Z` not `2026-02-23T20:16:27Z`, for Windows compatibility):
-   - 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(ai-team): {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.
+# 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` (use filename-safe timestamps — replace colons with hyphens, e.g., `2026-02-23T20-16-27Z` not `2026-02-23T20:16:27Z`, for Windows compatibility):
+   - 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(ai-team): {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

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

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

@@ -1,69 +1,69 @@
----
-name: "squad-conventions"
-description: "Core conventions and patterns used in the Squad codebase"
-domain: "project-conventions"
-confidence: "high"
-source: "manual"
----
-
-## Context
-These conventions apply to all work on the Squad CLI tool (`create-squad`). Squad is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Squad source code.
-
-## Patterns
-
-### Zero Dependencies
-Squad has zero runtime dependencies. Everything uses Node.js built-ins (`fs`, `path`, `os`, `child_process`). Do not add packages to `dependencies` in `package.json`. This is a hard constraint, not a preference.
-
-### Node.js Built-in Test Runner
-Tests use `node:test` and `node:assert/strict` — no test frameworks. Run with `npm test`. Test files live in `test/`. The test command is `node --test test/`.
-
-### Error Handling — `fatal()` Pattern
-All user-facing errors use the `fatal(msg)` function which prints a red `✗` prefix and exits with code 1. Never throw unhandled exceptions or print raw stack traces. The global `uncaughtException` handler calls `fatal()` as a safety net.
-
-### ANSI Color Constants
-Colors are defined as constants at the top of `index.js`: `GREEN`, `RED`, `DIM`, `BOLD`, `RESET`. Use these constants — do not inline ANSI escape codes.
-
-### File Structure
-- `.squad/` — Team state (user-owned, never overwritten by upgrades)
-- `.squad/templates/` — Template files copied from `templates/` (Squad-owned, overwritten on upgrade)
-- `.github/agents/squad.agent.md` — Coordinator prompt (Squad-owned, overwritten on upgrade)
-- `templates/` — Source templates shipped with the npm package
-- `.squad/skills/` — Team skills in SKILL.md format (user-owned)
-- `.squad/decisions/inbox/` — Drop-box for parallel decision writes
-
-### Windows Compatibility
-Always use `path.join()` for file paths — never hardcode `/` or `\` separators. Squad must work on Windows, macOS, and Linux. All tests must pass on all platforms.
-
-### Init Idempotency
-The init flow uses a skip-if-exists pattern: if a file or directory already exists, skip it and report "already exists." Never overwrite user state during init. The upgrade flow overwrites only Squad-owned files.
-
-### Copy Pattern
-`copyRecursive(src, target)` handles both files and directories. It creates parent directories with `{ recursive: true }` and uses `fs.copyFileSync` for files.
-
-## Examples
-
-```javascript
-// Error handling
-function fatal(msg) {
-  console.error(`${RED}✗${RESET} ${msg}`);
-  process.exit(1);
-}
-
-// File path construction (Windows-safe)
-const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
-
-// Skip-if-exists pattern
-if (!fs.existsSync(ceremoniesDest)) {
-  fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
-  console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
-} else {
-  console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
-}
-```
-
-## Anti-Patterns
-- **Adding npm dependencies** — Squad is zero-dep. Use Node.js built-ins only.
-- **Hardcoded path separators** — Never use `/` or `\` directly. Always `path.join()`.
-- **Overwriting user state on init** — Init skips existing files. Only upgrade overwrites Squad-owned files.
-- **Raw stack traces** — All errors go through `fatal()`. Users see clean messages, not stack traces.
-- **Inline ANSI codes** — Use the color constants (`GREEN`, `RED`, `DIM`, `BOLD`, `RESET`).
+---
+name: "squad-conventions"
+description: "Core conventions and patterns used in the Squad codebase"
+domain: "project-conventions"
+confidence: "high"
+source: "manual"
+---
+
+## Context
+These conventions apply to all work on the Squad CLI tool (`create-squad`). Squad is a zero-dependency Node.js package that adds AI agent teams to any project. Understanding these patterns is essential before modifying any Squad source code.
+
+## Patterns
+
+### Zero Dependencies
+Squad has zero runtime dependencies. Everything uses Node.js built-ins (`fs`, `path`, `os`, `child_process`). Do not add packages to `dependencies` in `package.json`. This is a hard constraint, not a preference.
+
+### Node.js Built-in Test Runner
+Tests use `node:test` and `node:assert/strict` — no test frameworks. Run with `npm test`. Test files live in `test/`. The test command is `node --test test/`.
+
+### Error Handling — `fatal()` Pattern
+All user-facing errors use the `fatal(msg)` function which prints a red `✗` prefix and exits with code 1. Never throw unhandled exceptions or print raw stack traces. The global `uncaughtException` handler calls `fatal()` as a safety net.
+
+### ANSI Color Constants
+Colors are defined as constants at the top of `index.js`: `GREEN`, `RED`, `DIM`, `BOLD`, `RESET`. Use these constants — do not inline ANSI escape codes.
+
+### File Structure
+- `.squad/` — Team state (user-owned, never overwritten by upgrades)
+- `.squad/templates/` — Template files copied from `templates/` (Squad-owned, overwritten on upgrade)
+- `.github/agents/squad.agent.md` — Coordinator prompt (Squad-owned, overwritten on upgrade)
+- `templates/` — Source templates shipped with the npm package
+- `.squad/skills/` — Team skills in SKILL.md format (user-owned)
+- `.squad/decisions/inbox/` — Drop-box for parallel decision writes
+
+### Windows Compatibility
+Always use `path.join()` for file paths — never hardcode `/` or `\` separators. Squad must work on Windows, macOS, and Linux. All tests must pass on all platforms.
+
+### Init Idempotency
+The init flow uses a skip-if-exists pattern: if a file or directory already exists, skip it and report "already exists." Never overwrite user state during init. The upgrade flow overwrites only Squad-owned files.
+
+### Copy Pattern
+`copyRecursive(src, target)` handles both files and directories. It creates parent directories with `{ recursive: true }` and uses `fs.copyFileSync` for files.
+
+## Examples
+
+```javascript
+// Error handling
+function fatal(msg) {
+  console.error(`${RED}✗${RESET} ${msg}`);
+  process.exit(1);
+}
+
+// File path construction (Windows-safe)
+const agentDest = path.join(dest, '.github', 'agents', 'squad.agent.md');
+
+// Skip-if-exists pattern
+if (!fs.existsSync(ceremoniesDest)) {
+  fs.copyFileSync(ceremoniesSrc, ceremoniesDest);
+  console.log(`${GREEN}✓${RESET} .squad/ceremonies.md`);
+} else {
+  console.log(`${DIM}ceremonies.md already exists — skipping${RESET}`);
+}
+```
+
+## Anti-Patterns
+- **Adding npm dependencies** — Squad is zero-dep. Use Node.js built-ins only.
+- **Hardcoded path separators** — Never use `/` or `\` directly. Always `path.join()`.
+- **Overwriting user state on init** — Init skips existing files. Only upgrade overwrites Squad-owned files.
+- **Raw stack traces** — All errors go through `fatal()`. Users see clean messages, not stack traces.
+- **Inline ANSI codes** — Use the color constants (`GREEN`, `RED`, `DIM`, `BOLD`, `RESET`).