@bradygaster/squad-cli 0.8.25 → 0.9.1

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`:
+   - 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/agent-collaboration/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "agent-collaboration"
+description: "Standard collaboration patterns for all squad agents — worktree awareness, decisions, cross-agent communication"
+domain: "team-workflow"
+confidence: "high"
+source: "extracted from charter boilerplate — identical content in 18+ agent charters"
+---
+
+## Context
+
+Every agent on the team follows identical collaboration patterns for worktree awareness, decision recording, and cross-agent communication. These were previously duplicated in every charter's Collaboration section (~300 bytes × 18 agents = ~5.4KB of redundant context). Now centralized here.
+
+The coordinator's spawn prompt already instructs agents to read decisions.md and their history.md. This skill adds the patterns for WRITING decisions and requesting help.
+
+## Patterns
+
+### Worktree Awareness
+Use the `TEAM ROOT` path provided in your spawn prompt. All `.squad/` paths are relative to this root. If TEAM ROOT is not provided (rare), run `git rev-parse --show-toplevel` as fallback. Never assume CWD is the repo root.
+
+### Decision Recording
+After making a decision that affects other team members, write it to:
+`.squad/decisions/inbox/{your-name}-{brief-slug}.md`
+
+Format:
+```
+### {date}: {decision title}
+**By:** {Your Name}
+**What:** {the decision}
+**Why:** {rationale}
+```
+
+### Cross-Agent Communication
+If you need another team member's input, say so in your response. The coordinator will bring them in. Don't try to do work outside your domain.
+
+### Reviewer Protocol
+If you have reviewer authority and reject work: the original author is locked out from revising that artifact. A different agent must own the revision. State who should revise in your rejection response.
+
+## Anti-Patterns
+- Don't read all agent charters — you only need your own context + decisions.md
+- Don't write directly to `.squad/decisions.md` — always use the inbox drop-box
+- Don't modify other agents' history.md files — that's Scribe's job
+- Don't assume CWD is the repo root — always use TEAM ROOT

package/templates/skills/agent-conduct/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: "agent-conduct"
+description: "Shared hard rules enforced across all squad agents"
+domain: "team-governance"
+confidence: "high"
+source: "reskill extraction — Product Isolation Rule and Peer Quality Check appeared in all 20 agent charters"
+---
+
+## Context
+
+Every squad agent must follow these two hard rules. They were previously duplicated in every charter. Now they live here as a shared skill, loaded once.
+
+## Patterns
+
+### Product Isolation Rule (hard rule)
+Tests, CI workflows, and product code must NEVER depend on specific agent names from any particular squad. "Our squad" must not impact "the squad." No hardcoded references to agent names (Flight, EECOM, FIDO, etc.) in test assertions, CI configs, or product logic. Use generic/parameterized values. If a test needs agent names, use obviously-fake test fixtures (e.g., "test-agent-1", "TestBot").
+
+### Peer Quality Check (hard rule)
+Before finishing work, verify your changes don't break existing tests. Run the test suite for files you touched. If CI has been failing, check your changes aren't contributing to the problem. When you learn from mistakes, update your history.md.
+
+## Anti-Patterns
+- Don't hardcode dev team agent names in product code or tests
+- Don't skip test verification before declaring work done
+- Don't ignore pre-existing CI failures that your changes may worsen

package/templates/skills/architectural-proposals/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: "architectural-proposals"
+description: "How to write comprehensive architectural proposals that drive alignment before code is written"
+domain: "architecture, product-direction"
+confidence: "high"
+source: "earned (2026-02-21 interactive shell proposal)"
+tools:
+  - name: "view"
+    description: "Read existing codebase, prior decisions, and team context before proposing changes"
+    when: "Always read .squad/decisions.md, relevant PRDs, and current architecture docs before writing proposal"
+  - name: "create"
+    description: "Create proposal in docs/proposals/ with structured format"
+    when: "After gathering context, before any implementation work begins"
+---
+
+## Context
+
+Proposals create alignment before code is written. Cheaper to change a doc than refactor code. Use this pattern when:
+- Architecture shifts invalidate existing assumptions
+- Product direction changes require new foundation
+- Multiple waves/milestones will be affected by a decision
+- External dependencies (Copilot CLI, SDK APIs) change
+
+## Patterns
+
+### Proposal Structure (docs/proposals/)
+
+**Required sections:**
+1. **Problem Statement** — Why current state is broken (specific, measurable evidence)
+2. **Proposed Architecture** — Solution with technical specifics (not hand-waving)
+3. **What Changes** — Impact on existing work (waves, milestones, modules)
+4. **What Stays the Same** — Preserve existing functionality (no regression)
+5. **Key Decisions Needed** — Explicit choices with recommendations
+6. **Risks and Mitigations** — Likelihood + impact + mitigation strategy
+7. **Scope** — What's in v1, what's deferred (timeline clarity)
+
+**Optional sections:**
+- Implementation Plan (high-level milestones)
+- Success Criteria (measurable outcomes)
+- Open Questions (unresolved items)
+- Appendix (prior art, alternatives considered)
+
+### Tone Ceiling Enforcement
+
+**Always:**
+- Cite specific evidence (user reports, performance data, failure modes)
+- Justify recommendations with technical rationale
+- Acknowledge trade-offs (no perfect solutions)
+- Be specific about APIs, libraries, file paths
+
+**Never:**
+- Hype ("revolutionary", "game-changing")
+- Hand-waving ("we'll figure it out later")
+- Unsubstantiated claims ("users will love this")
+- Vague timelines ("soon", "eventually")
+
+### Wave Restructuring Pattern
+
+When a proposal invalidates existing wave structure:
+1. **Acknowledge the shift:** "This becomes Wave 0 (Foundation)"
+2. **Cascade impacts:** Adjust downstream waves (Wave 1, Wave 2, Wave 3)
+3. **Preserve non-blocking work:** Identify what can proceed in parallel
+4. **Update dependencies:** Document new blocking relationships
+
+**Example (Interactive Shell):**
+- Wave 0 (NEW): Interactive Shell — blocks all other waves
+- Wave 1 (ADJUSTED): npm Distribution — shell bundled in cli.js
+- Wave 2 (DEFERRED): SquadUI — waits for shell foundation
+- Wave 3 (ADJUSTED): Public Docs — now documents shell as primary interface
+
+### Decision Framing
+
+**Format:** "Recommendation: X (recommended) or alternatives?"
+
+**Components:**
+- Recommendation (pick one, justify)
+- Alternatives (what else was considered)
+- Decision rationale (why recommended option wins)
+- Needs sign-off from (which agents/roles must approve)
+
+**Example:**
+```
+### 1. Terminal UI Library: `ink` (recommended) or alternatives?
+
+**Recommendation:** `ink`  
+**Alternatives:** `blessed`, raw readline  
+**Decision rationale:** Component model enables testable UI. Battle-tested ecosystem.
+
+**Needs sign-off from:** Brady (product direction), Fortier (runtime performance)
+```
+
+### Risk Documentation
+
+**Format per risk:**
+- **Risk:** Specific failure mode
+- **Likelihood:** Low / Medium / High (not percentages)
+- **Impact:** Low / Medium / High
+- **Mitigation:** Concrete actions (measurable)
+
+**Example:**
+```
+### Risk 2: SDK Streaming Reliability
+
+**Risk:** SDK streaming events might drop messages or arrive out of order.  
+**Likelihood:** Low (SDK is production-grade).  
+**Impact:** High — broken streaming makes shell unusable.
+
+**Mitigation:**
+- Add integration test: Send 1000-message stream, verify all deltas arrive in order
+- Implement fallback: If streaming fails, fall back to polling session state
+- Log all SDK events to `.squad/orchestration-log/sdk-events.jsonl` for debugging
+```
+
+## Examples
+
+**File references from interactive shell proposal:**
+- Full proposal: `docs/proposals/squad-interactive-shell.md`
+- User directive: `.squad/decisions/inbox/copilot-directive-2026-02-21T202535Z.md`
+- Team decisions: `.squad/decisions.md`
+- Current architecture: `docs/architecture/module-map.md`, `docs/prd-23-release-readiness.md`
+
+**Key patterns demonstrated:**
+1. Read user directive first (understand the "why")
+2. Survey current architecture (module map, existing waves)
+3. Research SDK APIs (exploration task to validate feasibility)
+4. Document problem with specific evidence (unreliable handoffs, zero visibility, UX mismatch)
+5. Propose solution with technical specifics (ink components, SDK session management, spawn.ts module)
+6. Restructure waves when foundation shifts (Wave 0 becomes blocker)
+7. Preserve backward compatibility (squad.agent.md still works, VS Code mode unchanged)
+8. Frame decisions explicitly (5 key decisions with recommendations)
+9. Document risks with mitigations (5 risks, each with concrete actions)
+10. Define scope (what's in v1 vs. deferred)
+
+## Anti-Patterns
+
+**Avoid:**
+- ❌ Proposals without problem statements (solution-first thinking)
+- ❌ Vague architecture ("we'll use a shell") — be specific (ink components, session registry, spawn.ts)
+- ❌ Ignoring existing work — always document impact on waves/milestones
+- ❌ No risk analysis — every architecture has risks, document them
+- ❌ Unbounded scope — draw the v1 line explicitly
+- ❌ Missing decision ownership — always say "needs sign-off from X"
+- ❌ No backward compatibility plan — users don't care about your replatform
+- ❌ Hand-waving timelines ("a few weeks") — be specific (2-3 weeks, 1 engineer full-time)
+
+**Red flags in proposal reviews:**
+- "Users will love this" (citation needed)
+- "We'll figure out X later" (scope creep incoming)
+- "This is revolutionary" (tone ceiling violation)
+- No section on "What Stays the Same" (regression risk)
+- No risks documented (wishful thinking)