diff --git a/.squad/agents/fido/history.md b/.squad/agents/fido/history.md index bd1bf13b5..1e17ffd69 100644 --- a/.squad/agents/fido/history.md +++ b/.squad/agents/fido/history.md @@ -31,6 +31,32 @@ Both PRs show CI build failures (missing SDK exports: listRoles, searchRoles, getCategories, getRoleById, generateCharterFromRole). Investigation confirmed this is a **pre-existing issue on dev branch** (CI runs #23109355116, #23108671446 also fail). Local builds succeed. Not introduced by either PR. **Lesson reinforced:** When reviewing PRs with CI failures, always check if dev branch has the same failures. Don't block PRs for pre-existing platform issues. +### PR #380 Quality Gate Review — FAIL (Test Assertion Sync Violation) (2026-03-14T03:35:00Z) + +**TEST FAILURE:** `test/docs-build.test.ts > features directory contains all expected markdown files` — Expected 33 files, found 34. + +**ROOT CAUSE:** PR #380 added `distributed-mesh.md` (new feature) and correctly added `distributed-mesh` to EXPECTED_FEATURES array. However, the base branch (dev @ dea678b) already contains `built-in-roles.md` (added in commit 83fd050, PR #368 on 2026-03-12), which was NOT in the test's expected list. The PR author updated the array to add their new feature but failed to notice the pre-existing gap. + +**BASELINE COMPARISON:** +- Dev branch: 15 failures (docs-build, init tests [12 failures, missing skill templates], aspire-integration, cli-packaging-smoke) +- PR branch (before sync): Same 15 failures +- PR branch (after sync script): **3 failures** — aspire-integration (Docker), cli-packaging-smoke (npm install), and **1 NEW FAILURE in docs-build.test.ts** + +**POSITIVE FINDINGS:** +- ✅ PR FIXED 12 test failures in test/init.test.ts by introducing `scripts/sync-skill-templates.mjs` and integrating it into prebuild +- ✅ Sync script works correctly (syncs 15 skills from .squad/skills/ to package templates) +- ✅ Build succeeds cleanly with sync script +- ✅ No regression in existing test coverage (4142 tests passing vs 4084 on baseline) +- ✅ `distributed-mesh.md` documentation file properly added to features directory +- ✅ No new dependencies in package.json (only build script changes) + +**REQUIRED FIX:** Add `'built-in-roles'` to EXPECTED_FEATURES array in test/docs-build.test.ts. Array should be 34 items total (33 existing features + distributed-mesh). + +**COVERAGE GAP:** No unit tests for the distributed mesh feature itself. PR is templates + docs only, which aligns with the stated "no code changes" design decision. Future work should add tests for mesh sync logic when implemented. + +**VERDICT:** FAIL — Cannot merge until test assertion is corrected. The sync script is a major quality improvement (fixes 12 tests), but the test count mismatch must be resolved. + +**Test counts:** 4113 passed, 1 failed, 34 skipped, 46 todo (PR branch with 3 suites failing: aspire [pre-existing], cli-packaging [pre-existing], docs-build [NEW]). ### Name-Agnostic Testing Pattern Tests reading live .squad/ files (team.md, routing.md) must assert structure/behavior, not specific agent names. Names change during team rebirths. Two classes of tests: (1) live-file tests — must survive rebirths, use property checks, (2) inline-fixture tests — self-contained, can hardcode names. See ralph-triage.test.ts for the canonical pattern. diff --git a/.squad/agents/flight/history.md b/.squad/agents/flight/history.md index ee25dcedf..61166be14 100644 --- a/.squad/agents/flight/history.md +++ b/.squad/agents/flight/history.md @@ -27,3 +27,10 @@ Created `.squad/skills/content-triage/SKILL.md` to codify the boundary heuristic 📌 Team update (2026-03-14T22-01-14Z): Distributed mesh integrated with deterministic skill pattern — decided by Procedures, PAO, Flight, Network +--- + +## Sprint Prioritization Pattern + +**Backlog triage methodology (47-issue analysis):** +Rank by: (1) bugs with active user impact, (2) quality/test gaps blocking GA release, (3) high-ROI features unblocking downstream work. Current sprint Top 10 identifies 3 bugs (WSL crash, SDK init regression, VS Code crash), 3 quality gates (SDK feature parity testing), and 4 governance/architecture decisions (opt-in roles, ADR archive, docs gaps, upstream sync). This pattern scales: categorize all open issues by type → sort each category by impact/urgency → interleave across sprint capacity to balance stability (bugs/quality) with velocity (features). Squad GA is gated by quality #340, #341, #347 and user-facing regressions #363, #337 — these must ship in parallel next sprint. + diff --git a/.squad/decisions-archive.md b/.squad/decisions-archive.md index a02605d0e..3d75e459f 100644 --- a/.squad/decisions-archive.md +++ b/.squad/decisions-archive.md @@ -4244,3 +4244,47 @@ Created two deliverables: **By:** Brady (via Copilot) **What:** DO NOT merge PR #547 (Squad Remote Control). Do not touch #547 at all. **Why:** User request — captured for team memory + +# Decision: CLI sessions use approve-all permission handler + +**Date:** 2025-07-14 +**Author:** Fenster (Core Dev) +**Issue:** #651 + +## Context + +The Copilot SDK requires an onPermissionRequest handler when creating sessions. This handler was defined in our adapter types (SquadSessionConfig) but was never wired in the CLI shell's 4 createSession() calls. External users hit a raw SDK error with no guidance. + +## Decision + +All CLI shell session creation calls now pass onPermissionRequest: approveAllPermissions, a handler that returns { kind: 'approved' } for every request. The CLI runs locally with user trust — there is no interactive permission prompt. + +SDK consumers (programmatic API users) still control their own handler. The SDK's createSession in dapter/client.ts now catches the raw permission error and wraps it with a clear message explaining how to fix it. + +## Impact + +- **CLI users:** Error is gone. All permissions auto-approved (matches existing CLI trust model). +- **SDK consumers:** Better error message if they forget to pass onPermissionRequest. +- **Types:** SquadPermissionHandler, SquadPermissionRequest, SquadPermissionRequestResult are now exported from @bradygaster/squad-sdk/client for reuse. +### 2025-07-24: Multi-Squad Global Config Layout +**By:** Fenster (Core Dev) +**Issue:** #652 +**PR:** #691 + +## What + +Squad now supports a global squads.json registry at the platform config root (%APPDATA%/squad/ on Windows, ~/.config/squad/ on Linux/macOS). Each named squad is registered with a name, path, and creation timestamp. Resolution follows a 5-step chain: explicit name → SQUAD_NAME env var → active in squads.json → "default" → legacy ~/.squad fallback. + +## Why + +Users need to manage multiple squads (personal, work, experiments) without conflicts. A global registry decouples squad identity from the current working directory and enables future CLI commands (squad list, squad switch, etc.) in Phase 2. + +## Migration Strategy + +Migration is **non-destructive and registration-only**. When esolveSquadPath() detects a legacy ~/.squad layout without an existing squads.json, it registers that path as the "default" squad. No files are moved, copied, or renamed. This eliminates data loss risk on first upgrade. + +## Impact + +- All future squad path resolution should go through esolveSquadPath() from multi-squad.ts +- Existing esolveSquad() and esolveSquadPaths() in esolution.ts remain unchanged (project-local .squad/ walk-up) +- Phase 2 CLI commands will consume these SDK functions directly diff --git a/.squad/decisions.md b/.squad/decisions.md index 4633b0d45..b4664b9b1 100644 --- a/.squad/decisions.md +++ b/.squad/decisions.md @@ -942,53 +942,6 @@ esolveSquadForProject() ## Why Duplicated separator logic was found in 3 files (App.tsx, AgentPanel.tsx, MessageStream.tsx). Consolidation to a single component prevents drift and makes it trivial to change separator style globally. The info hierarchy and whitespace conventions ensure visual consistency as new components are added. - -# Decision: CLI sessions use approve-all permission handler - -**Date:** 2025-07-14 -**Author:** Fenster (Core Dev) -**Issue:** #651 - -## Context - -The Copilot SDK requires an `onPermissionRequest` handler when creating sessions. This handler was defined in our adapter types (`SquadSessionConfig`) but was never wired in the CLI shell's 4 `createSession()` calls. External users hit a raw SDK error with no guidance. - -## Decision - -All CLI shell session creation calls now pass `onPermissionRequest: approveAllPermissions`, a handler that returns `{ kind: 'approved' }` for every request. The CLI runs locally with user trust — there is no interactive permission prompt. - -SDK consumers (programmatic API users) still control their own handler. The SDK's `createSession` in `adapter/client.ts` now catches the raw permission error and wraps it with a clear message explaining how to fix it. - -## Impact - -- **CLI users:** Error is gone. All permissions auto-approved (matches existing CLI trust model). -- **SDK consumers:** Better error message if they forget to pass `onPermissionRequest`. -- **Types:** `SquadPermissionHandler`, `SquadPermissionRequest`, `SquadPermissionRequestResult` are now exported from `@bradygaster/squad-sdk/client` for reuse. - -### 2026-03-01: Multi-Squad Global Config Layout -**By:** Fenster (Core Dev) -**Date:** 2025-07-24 -**Issue:** #652 -**PR:** #691 - -## What - -Squad now supports a global `squads.json` registry at the platform config root (`%APPDATA%/squad/` on Windows, `~/.config/squad/` on Linux/macOS). Each named squad is registered with a name, path, and creation timestamp. Resolution follows a 5-step chain: explicit name → `SQUAD_NAME` env var → active in squads.json → "default" → legacy `~/.squad` fallback. - -## Why - -Users need to manage multiple squads (personal, work, experiments) without conflicts. A global registry decouples squad identity from the current working directory and enables future CLI commands (`squad list`, `squad switch`, etc.) in Phase 2. - -## Migration Strategy - -Migration is **non-destructive and registration-only**. When `resolveSquadPath()` detects a legacy `~/.squad` layout without an existing `squads.json`, it registers that path as the "default" squad. No files are moved, copied, or renamed. This eliminates data loss risk on first upgrade. - -## Impact - -- All future squad path resolution should go through `resolveSquadPath()` from `multi-squad.ts` -- Existing `resolveSquad()` and `resolveSquadPaths()` in `resolution.ts` remain unchanged (project-local `.squad/` walk-up) -- Phase 2 CLI commands will consume these SDK functions directly - ### 2026-03-01: PR #547 Remote Control Feature — Architectural Review **By:** Fenster **Date:** 2026-03-01 @@ -5559,3 +5512,4 @@ The feature page provides practical setup steps and respects the tone ceiling --- + diff --git a/docs/src/content/docs/features/copilot-coding-agent.md b/docs/src/content/docs/features/copilot-coding-agent.md index 8cb0a8b6a..f9b10bba8 100644 --- a/docs/src/content/docs/features/copilot-coding-agent.md +++ b/docs/src/content/docs/features/copilot-coding-agent.md @@ -33,8 +33,11 @@ gh secret set COPILOT_ASSIGN_TOKEN git add .github/ .squad/ && git commit -m "feat: add copilot to squad" && git push # 5. Test — label any issue with squad:copilot +gh issue edit --add-label "squad:copilot" ``` +> **Why can't I use `gh issue edit --add-assignee "@copilot"`?** Bot accounts cannot be assigned via the GitHub CLI the same way as human users. Use label-based assignment instead. See [FAQ: Why doesn't gh issue edit --add-assignee "@copilot" work?](../guide/faq.md#why-doesnt-gh-issue-edit---add-assignee-copilot-work) for details. + --- ## Enabling @copilot diff --git a/docs/src/content/docs/guide.md b/docs/src/content/docs/guide.md index bd7842423..6c2b66bd6 100644 --- a/docs/src/content/docs/guide.md +++ b/docs/src/content/docs/guide.md @@ -8,12 +8,37 @@ It is not a chatbot wearing hats. Each team member is spawned as a real sub-agen --- +## Which CLI should I use? + +**Use GitHub Copilot CLI for day-to-day work.** It's the recommended interface for interacting with your Squad — full agent spawning, model selection, and conversational access to all features. + +**Use Squad CLI for setup and operations:** +- Initial setup: `squad init` +- Diagnostics: `squad doctor` +- Continuous triage: `squad triage --interval 10` +- Aspire dashboard: `squad aspire` +- Export/import: `squad export` and `squad import` + +**Common workflow:** +```bash +# Terminal 1: Run continuous triage (Squad CLI) +squad triage --interval 10 + +# Terminal 2: Work with your team (GitHub Copilot CLI) +gh copilot +> @squad what issues are ready to work? +``` + +Both CLIs read and write the same `.squad/` directory, so state stays synchronized. For more details, see [FAQ: Which CLI should I use?](guide/faq.md#which-cli-should-i-use) and [Client Compatibility Matrix](scenarios/client-compatibility.md). + +--- + ## Supported Platforms Squad is designed for **GitHub Copilot CLI** and ships with full support. **VS Code is now fully supported with zero code changes** — agents work identically on both platforms. **Current state:** -- ✅ **GitHub Copilot CLI** — fully supported. This is the primary platform. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode. +- ✅ **GitHub Copilot CLI** — fully supported. This is the recommended interface for day-to-day work. Uses the stable `task` tool for sub-agent spawning, per-spawn model selection, and background mode. - ✅ **VS Code Copilot** — fully supported (v0.4.0+). VS Code uses `runSubagent` for parallel execution and supports full `.ai-team/` read/write. See [Client Compatibility Matrix](scenarios/client-compatibility.md) for details. - ❌ **Other platforms** — JetBrains IDEs and other runtimes are untested. GitHub.com web-based Copilot is untested. diff --git a/docs/src/content/docs/guide/faq.md b/docs/src/content/docs/guide/faq.md new file mode 100644 index 000000000..00279363b --- /dev/null +++ b/docs/src/content/docs/guide/faq.md @@ -0,0 +1,277 @@ +# Frequently asked questions + +> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. + + +Common questions, troubleshooting tips, and clarifications based on community feedback. Can't find your answer? [Open an issue](https://github.com/bradygaster/squad/issues/new). + +--- + +## Which CLI should I use? + +**Short answer:** Use **GitHub Copilot CLI** for day-to-day work. Use **Squad CLI** for setup, diagnostics, and specific features. + +**Why GitHub Copilot CLI?** +- Full agent spawning capabilities +- Access to all Squad features through natural conversation +- Model selection and background execution +- No manual commands — just describe what you need + +**When to use Squad CLI:** +- Initial setup: `squad init` +- Diagnostics: `squad doctor` +- Continuous triage: `squad triage --interval 10` +- Aspire dashboard: `squad aspire` +- Export/import: `squad export` and `squad import` +- Remote phone access: `squad start --tunnel` + +**Common workflow pattern:** +```bash +# Terminal 1: Run continuous triage +squad triage --interval 10 + +# Terminal 2: Work with your team +gh copilot +> @squad what issues are ready to work? +``` + +For a detailed feature comparison, see [Client Compatibility Matrix](../scenarios/client-compatibility.md). + +--- + +## Why doesn't `gh issue edit --add-assignee "@copilot"` work? + +**Problem:** Running `gh issue edit --add-assignee "@copilot"` (or variants like `copilot-swe-agent[bot]`) fails locally, even with a Personal Access Token. + +**Why this happens:** The GitHub Copilot coding agent is a bot account. Bot accounts cannot be assigned to issues via the GitHub CLI in the same way as human users — the GitHub API restricts direct assignment of bot accounts through standard endpoints. + +**Recommended workaround:** Use **label-based assignment** through the GitHub Actions workflow: + +1. Add the `squad:copilot` label to the issue: + ```bash + gh issue edit --add-label "squad:copilot" + ``` + +2. The auto-assign workflow (`.github/workflows/squad-copilot-auto-assign.yml`) detects the label and assigns @copilot automatically. + +**Prerequisites for auto-assign:** +- You must create a **GitHub Classic Personal Access Token** with `repo` scope +- Add it as a repository secret: `gh secret set COPILOT_ASSIGN_TOKEN` +- The workflow uses this token to perform the assignment on your behalf + +See [Copilot Coding Agent](../features/copilot-coding-agent.md) for full setup instructions. + +--- + +## I don't see anything on the Aspire dashboard + +**Problem:** You ran `squad aspire` and opened the dashboard, but no telemetry is showing up. + +**Why this happens:** The Aspire dashboard integration **requires the Squad CLI**. It is not available when using GitHub Copilot CLI directly. + +**How to fix:** +1. Ensure you started Aspire with the Squad CLI: + ```bash + squad aspire + ``` + +2. Confirm the container is running: + ```bash + docker ps | grep aspire-dashboard + ``` + +3. Look for the dashboard URL in the output (usually `http://localhost:18888`) + +4. Run a Squad CLI command that generates telemetry: + ```bash + squad doctor + squad triage + ``` + +5. Refresh the Aspire dashboard — you should see traces, metrics, and logs appear + +**Note:** GitHub Copilot CLI sessions do **not** send telemetry to Aspire. Only Squad CLI commands emit OpenTelemetry data to the dashboard. + +See [Using Squad with the Aspire Dashboard](../scenarios/aspire-dashboard.md) for details. + +--- + +## `squad doctor` complains about absolute path for teamRoot + +**Problem:** Running `squad doctor` shows a warning like: + +``` +⚠ teamRoot uses absolute path — consider making it relative +``` + +**Why this matters:** Absolute paths (e.g., `C:\Users\me\squad\` or `/Users/me/squad/`) break portability. If you share the squad with a teammate or clone it to a new machine, the absolute path won't resolve correctly. + +**How to fix:** Make the `teamRoot` path **relative to the project root**. + +**Example — Before (absolute):** +```json +{ + "teamRoot": "C:\\Users\\me\\repos\\my-team\\.squad" +} +``` + +**Example — After (relative):** +```json +{ + "teamRoot": ".squad" +} +``` + +**For linked teams (dual-root mode):** + +If your project links to a remote team repository: + +```json +{ + "teamRoot": "../team-repo/.squad" +} +``` + +The path should be relative to your **project root** (where `.squad/` or `squad.config.ts` lives), not to the `.squad/` directory itself. + +**Verify the fix:** +```bash +squad doctor +``` + +You should see `✓ teamRoot is relative` or no warning. + +--- + +## Can I use Squad CLI and GitHub Copilot CLI at the same time? + +Yes! They complement each other: + +- **Squad CLI** provides infrastructure: triage, Aspire observability, export/import, diagnostics +- **GitHub Copilot CLI** provides conversational interface to your team + +**Recommended setup:** +- Run `squad triage --interval 10` in a dedicated terminal (or as a cron job / GitHub Action) +- Use `gh copilot` (or `@squad` in VS Code) for all team interactions +- Use `squad doctor` or `squad aspire` for diagnostics when needed + +Both CLIs read and write the same `.squad/` directory, so state stays synchronized. + +--- + +## What's the difference between Ralph and triage? + +**Ralph** and **triage** are different names for the same functionality: + +- **`squad ralph`** is the legacy command name +- **`squad triage`** is the new primary command name (as of v0.8.26) +- Both commands do the same thing: monitor GitHub issues, apply routing rules, and assign work to team members + +**Migration path:** +- Existing scripts using `squad ralph` will continue to work (it's an alias) +- New projects should use `squad triage` in documentation and automation +- The `ralph/` directory in `.squad/` remains unchanged for backward compatibility + +--- + +## How do I add a new agent to my squad? + +**In conversation (recommended):** + +``` +gh copilot +> @squad I want to add a new agent +> Role: Security specialist +> Name: Guardian +> Expertise: OWASP, dependency scanning, secrets detection +``` + +Squad will create the charter, update the team roster, and add routing rules. + +**Manual creation:** + +1. Create a charter file in `.squad/agents//charter.md` +2. Update `.squad/team.md` to include the new agent in the roster +3. Add routing rules in `.squad/routing.md` (if applicable) +4. Optionally add a history file in `.squad/agents//history.md` + +See [Team Setup](../features/team-setup.md) for details. + +--- + +## What happens if I run `squad init` twice? + +Nothing breaks! `squad init` is **idempotent** — it's safe to run multiple times. + +**What it does:** +- Checks if `.squad/` exists; if yes, does nothing +- Copies missing templates from `.ai-team-templates/` to `.squad/` +- Updates `.github/workflows/` with Squad Actions (skips existing files) +- Adds `.github/agents/squad.agent.md` if missing + +**Use cases:** +- Recover from partial initialization +- Update workflows after a Squad upgrade +- Add missing templates without overwriting custom changes + +--- + +## Can I use Squad without GitHub Issues? + +Yes, but with limitations. + +**What works without GitHub Issues:** +- Conversational team interaction (`@squad`, `gh copilot`) +- Agent spawning and parallel execution +- Memory, decisions, and knowledge sharing +- Skills and ceremonies +- Export/import for portability + +**What requires GitHub Issues:** +- Ralph/triage auto-assignment +- Issue-driven development workflows +- Project board integration +- Label-based routing +- Copilot coding agent auto-assignment + +If you're using GitLab, see [GitLab Issues](../features/gitlab-issues.md) for integration options. + +--- + +## How do I reset my squad without losing decisions? + +**Option 1: Archive and start fresh** +```bash +# Export current state +squad export --out backup-$(date +%Y%m%d).json + +# Remove .squad/ +rm -rf .squad/ + +# Reinitialize +squad init +``` + +Manually copy decisions from the backup JSON or `.squad/decisions.md` if you archived it separately. + +**Option 2: Selective cleanup** +```bash +# Remove agent state but keep team structure +rm -rf .squad/agents/*/history.md +rm -rf .squad/sessions/ + +# Keep .squad/decisions.md, .squad/team.md, .squad/routing.md +``` + +See [Disaster Recovery](../scenarios/disaster-recovery.md) for more recovery patterns. + +--- + +## Where should I report bugs or request features? + +[Open an issue on GitHub](https://github.com/bradygaster/squad/issues/new) with: +- **Environment:** OS, Node.js version, Squad version (`squad --version`) +- **Reproduction steps:** What you ran, what happened, what you expected +- **Output:** Copy the full terminal output, including any errors + +For questions or discussions, use [GitHub Discussions](https://github.com/bradygaster/squad/discussions). diff --git a/docs/src/content/docs/reference/cli.md b/docs/src/content/docs/reference/cli.md index c88d42f0e..0add97f50 100644 --- a/docs/src/content/docs/reference/cli.md +++ b/docs/src/content/docs/reference/cli.md @@ -298,6 +298,28 @@ git clone my-project && cd my-project && squad doctor The doctor always exits cleanly (no error code) because it's a diagnostic tool, not a gate. Use it to troubleshoot setup issues, validate team state, or run before opening an issue on GitHub. +### Common Issues + +**Absolute path warning for teamRoot:** + +If you see `⚠ teamRoot uses absolute path — consider making it relative`, it means your `squad.config.ts` or `.squad/config.json` contains an absolute path like `C:\Users\me\squad\` or `/Users/me/squad/`. This breaks portability. + +**Fix:** Make the path relative to your project root: +```json +{ + "teamRoot": ".squad" +} +``` + +For linked teams (dual-root mode), use a relative path: +```json +{ + "teamRoot": "../team-repo/.squad" +} +``` + +See [FAQ: squad doctor complains about absolute path for teamRoot](../guide/faq.md#squad-doctor-complains-about-absolute-path-for-teamroot) for details. + --- ## Version Management diff --git a/docs/src/content/docs/scenarios/aspire-dashboard.md b/docs/src/content/docs/scenarios/aspire-dashboard.md index bbee1ec78..fa4cd5eb6 100644 --- a/docs/src/content/docs/scenarios/aspire-dashboard.md +++ b/docs/src/content/docs/scenarios/aspire-dashboard.md @@ -2,6 +2,7 @@ > ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases. +> 📌 **Squad CLI only** — The Aspire dashboard integration requires the Squad CLI (`squad aspire`). It is not available when using GitHub Copilot CLI directly. Only Squad CLI commands emit OpenTelemetry data to the dashboard. **Try this:** ``` diff --git a/package.json b/package.json index 7cfc13420..6d21561ba 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@bradygaster/squad", - "version": "0.8.25", + "version": "0.8.25.2", "private": true, "description": "Squad — Programmable multi-agent runtime for GitHub Copilot, built on @github/copilot-sdk", "type": "module", diff --git a/packages/squad-cli/package.json b/packages/squad-cli/package.json index 752984d19..6d7613310 100644 --- a/packages/squad-cli/package.json +++ b/packages/squad-cli/package.json @@ -1,6 +1,6 @@ { "name": "@bradygaster/squad-cli", - "version": "0.8.25", + "version": "0.8.25.2", "description": "Squad CLI — Command-line interface for the Squad multi-agent runtime", "type": "module", "bin": { diff --git a/packages/squad-cli/templates/skills/agent-collaboration/SKILL.md b/packages/squad-cli/templates/skills/agent-collaboration/SKILL.md new file mode 100644 index 000000000..054463cf8 --- /dev/null +++ b/packages/squad-cli/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 diff --git a/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md b/packages/squad-cli/templates/skills/architectural-proposals/SKILL.md new file mode 100644 index 000000000..46d7b5053 --- /dev/null +++ b/packages/squad-cli/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) diff --git a/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md b/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md new file mode 100644 index 000000000..61c07d73e --- /dev/null +++ b/packages/squad-cli/templates/skills/ci-validation-gates/SKILL.md @@ -0,0 +1,84 @@ +--- +name: "ci-validation-gates" +description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" +domain: "ci-cd" +confidence: "high" +source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident" +--- + +## Context + +CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here. + +## Patterns + +### Semver Validation Gate +Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them. + +```yaml +- name: Validate semver + run: | + VERSION="${{ github.event.release.tag_name }}" + VERSION="${VERSION#v}" + if ! npx semver "$VERSION" > /dev/null 2>&1; then + echo "❌ Invalid semver: $VERSION" + echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid." + exit 1 + fi + echo "✅ Valid semver: $VERSION" +``` + +### NPM Token Type Verification +NPM_TOKEN MUST be an Automation token, not a User token with 2FA: +- User tokens require OTP — CI can't provide it → EOTP error +- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation +- Verify before first publish in any workflow + +### Retry Logic for npm Registry Propagation +npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable. +- Propagation: typically 5-30s, up to 2min in rare cases +- All verify steps: 5 attempts, 15-second intervals +- Log each attempt: "Attempt 1/5: Checking package..." +- Exit loop on success, fail after max attempts + +```yaml +- name: Verify package (with retry) + run: | + MAX_ATTEMPTS=5 + WAIT_SECONDS=15 + for attempt in $(seq 1 $MAX_ATTEMPTS); do + echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..." + if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then + echo "✅ Package verified" + exit 0 + fi + [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS + done + echo "❌ Failed to verify after $MAX_ATTEMPTS attempts" + exit 1 +``` + +### Draft Release Detection +Draft releases don't emit `release: published` event. Workflows MUST: +- Trigger on `release: published` (NOT `created`) +- If using workflow_dispatch: verify release is published via GitHub API before proceeding + +### Build Script Protection +Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions. + +## Known Failure Modes (v0.8.22 Incident) + +| # | What Happened | Root Cause | Prevention | +|---|---------------|-----------|------------| +| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish | +| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only | +| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals | +| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases | +| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 | + +## Anti-Patterns +- ❌ Publishing without semver validation gate +- ❌ Single-shot verification without retry +- ❌ Hard-coded secrets in workflows +- ❌ Silent CI failures — every error needs actionable output with remediation +- ❌ Assuming npm publish is instantly queryable diff --git a/packages/squad-cli/templates/skills/cli-wiring/SKILL.md b/packages/squad-cli/templates/skills/cli-wiring/SKILL.md new file mode 100644 index 000000000..03f7bf55f --- /dev/null +++ b/packages/squad-cli/templates/skills/cli-wiring/SKILL.md @@ -0,0 +1,47 @@ +# Skill: CLI Command Wiring + +**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. + +## Checklist — Adding a New CLI Command + +1. **Create command file** in `packages/squad-cli/src/cli/commands/.ts` + - Export a `run(cwd, options)` async function (or class with static methods for utility modules) + +2. **Add routing block** in `packages/squad-cli/src/cli-entry.ts` inside `main()`: + ```ts + if (cmd === '') { + const { run } = await import('./cli/commands/.js'); + // parse args, call function + await run(process.cwd(), options); + return; + } + ``` + +3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`): + ```ts + console.log(` ${BOLD}${RESET} `); + console.log(` Usage: [flags]`); + ``` + +4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3. + +## Wiring Patterns by Command Type + +| Type | Example | How to wire | +|------|---------|-------------| +| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` | +| Placeholder command | `loop`, `hire` | Inline in cli-entry.ts, prints pending message | +| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) | +| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias | + +## Common Import Pattern + +```ts +import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js'; +``` + +Use dynamic `await import()` for command modules to keep startup fast (lazy loading). + +## History + +- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, hire were already present. diff --git a/packages/squad-cli/templates/skills/client-compatibility/SKILL.md b/packages/squad-cli/templates/skills/client-compatibility/SKILL.md new file mode 100644 index 000000000..da3e94609 --- /dev/null +++ b/packages/squad-cli/templates/skills/client-compatibility/SKILL.md @@ -0,0 +1,89 @@ +--- +name: "client-compatibility" +description: "Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +Squad runs on multiple Copilot surfaces (CLI, VS Code, JetBrains, GitHub.com). The coordinator must detect its platform and adapt spawning behavior accordingly. Different tools are available on different platforms, requiring conditional logic for agent spawning, SQL usage, and response timing. + +## Patterns + +### 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. + +## Examples + +**Example 1: CLI parallel spawn** +```typescript +// Coordinator detects task tool available → CLI mode +task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... }) +task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... }) +// Later: read_agent for both +``` + +**Example 2: VS Code parallel spawn** +```typescript +// Coordinator detects runSubagent available → VS Code mode +runSubagent({ prompt: "...Fenster charter + task..." }) +runSubagent({ prompt: "...Hockney charter + task..." }) +runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group +// Results return automatically, no read_agent +``` + +**Example 3: Fallback mode** +```typescript +// Neither task nor runSubagent available → work inline +// Coordinator executes the task directly without spawning +``` + +## Anti-Patterns + +- ❌ Using SQL tool in cross-platform workflows (breaks on VS Code/JetBrains/GitHub.com) +- ❌ Attempting per-spawn model selection on VS Code (Phase 1 — only session model works) +- ❌ Fire-and-forget Scribe on VS Code (must batch as last subagent) +- ❌ Showing launch table on VS Code (results already inline) +- ❌ Apologizing or explaining platform limitations to the user +- ❌ Using `task` when only `runSubagent` is available +- ❌ Dropping prompt structure (charter/identity/task) on non-CLI platforms diff --git a/packages/squad-cli/templates/skills/git-workflow/SKILL.md b/packages/squad-cli/templates/skills/git-workflow/SKILL.md new file mode 100644 index 000000000..bfa0b8596 --- /dev/null +++ b/packages/squad-cli/templates/skills/git-workflow/SKILL.md @@ -0,0 +1,204 @@ +--- +name: "git-workflow" +description: "Squad branching model: dev-first workflow with insiders preview channel" +domain: "version-control" +confidence: "high" +source: "team-decision" +--- + +## Context + +Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.** + +| Branch | Purpose | Publishes | +|--------|---------|-----------| +| `main` | Released, tagged, in-npm code only | `npm publish` on tag | +| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge | +| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync | + +## Branch Naming Convention + +Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}` + +Examples: +- `squad/195-fix-version-stamp-bug` +- `squad/42-add-profile-api` + +## Workflow for Issue Work + +1. **Branch from dev:** + ```bash + git checkout dev + git pull origin dev + git checkout -b squad/{issue-number}-{slug} + ``` + +2. **Mark issue in-progress:** + ```bash + gh issue edit {number} --add-label "status:in-progress" + ``` + +3. **Create draft PR targeting dev:** + ```bash + gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft + ``` + +4. **Do the work.** Make changes, write tests, commit with issue reference. + +5. **Push and mark ready:** + ```bash + git push -u origin squad/{issue-number}-{slug} + gh pr ready + ``` + +6. **After merge to dev:** + ```bash + git checkout dev + git pull origin dev + git branch -d squad/{issue-number}-{slug} + git push origin --delete squad/{issue-number}-{slug} + ``` + +## Parallel Multi-Issue Work (Worktrees) + +When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead. + +### When to Use Worktrees vs Sequential + +| Scenario | Strategy | +|----------|----------| +| Single issue | Standard workflow above — no worktree needed | +| 2+ simultaneous issues in same repo | Worktrees — one per issue | +| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) | + +### Setup + +From the main clone (must be on dev or any branch): + +```bash +# Ensure dev is current +git fetch origin dev + +# Create a worktree per issue — siblings to the main clone +git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev +git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev +``` + +**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`). + +Each worktree: +- Has its own working directory and index +- Is on its own `squad/{issue-number}-{slug}` branch from dev +- Shares the same `.git` object store (disk-efficient) + +### Per-Worktree Agent Workflow + +Each agent operates inside its worktree exactly like the single-issue workflow: + +```bash +cd ../squad-195 + +# Work normally — commits, tests, pushes +git add -A && git commit -m "fix: stamp bug (#195)" +git push -u origin squad/195-fix-stamp-bug + +# Create PR targeting dev +gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft +``` + +All PRs target `dev` independently. Agents never interfere with each other's filesystem. + +### .squad/ State in Worktrees + +The `.squad/` directory exists in each worktree as a copy. This is safe because: +- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs) +- Each agent appends to its own section; union merge reconciles on PR merge to dev +- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only + +### Cleanup After Merge + +After a worktree's PR is merged to dev: + +```bash +# From the main clone +git worktree remove ../squad-195 +git worktree prune # clean stale metadata +git branch -d squad/195-fix-stamp-bug +git push origin --delete squad/195-fix-stamp-bug +``` + +If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state. + +--- + +## Multi-Repo Downstream Scenarios + +When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad): + +### Setup + +Clone downstream repos as siblings to the main repo: + +``` +~/work/ + squad-pr/ # main repo + squad-sdk/ # downstream dependency + user-app/ # consumer project +``` + +Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use `squad/{issue-number}-{slug}`. + +### Coordinated PRs + +- Create PRs in each repo independently +- Link them in PR descriptions: + ``` + Closes #42 + + **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature) + ``` +- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli) + +### Local Linking for Testing + +Before pushing, verify cross-repo changes work together: + +```bash +# Node.js / npm +cd ../squad-sdk && npm link +cd ../squad-pr && npm link squad-sdk + +# Go +# Use replace directive in go.mod: +# replace github.com/org/squad-sdk => ../squad-sdk + +# Python +cd ../squad-sdk && pip install -e . +``` + +**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs. + +### Worktrees + Multi-Repo + +These compose naturally. You can have: +- Multiple worktrees in the main repo (parallel issues) +- Separate clones for downstream repos +- Each combination operates independently + +--- + +## Anti-Patterns + +- ❌ Branching from main (branch from dev) +- ❌ PR targeting main directly (target dev) +- ❌ Non-conforming branch names (must be squad/{number}-{slug}) +- ❌ Committing directly to main or dev (use PRs) +- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead) +- ❌ Using worktrees for cross-repo work (use separate clones) +- ❌ Leaving stale worktrees after PR merge (clean up immediately) + +## Promotion Pipeline + +- dev → insiders: Automated sync on green build +- dev → main: Manual merge when ready for stable release, then tag +- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent diff --git a/packages/squad-cli/templates/skills/history-hygiene/SKILL.md b/packages/squad-cli/templates/skills/history-hygiene/SKILL.md new file mode 100644 index 000000000..453a03b4e --- /dev/null +++ b/packages/squad-cli/templates/skills/history-hygiene/SKILL.md @@ -0,0 +1,36 @@ +--- +name: history-hygiene +description: Record final outcomes to history.md, not intermediate requests or reversed decisions +domain: documentation, team-collaboration +confidence: high +source: earned (Kobayashi v0.6.0 incident, team intervention) +--- + +## Context + +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake. + +## Patterns + +- **Record the final outcome**, not the initial request. +- **Wait for confirmation** before writing to history — don't log intermediate states. +- **If a decision reverses**, update the entry immediately — don't leave stale data. +- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. + +## Examples + +✓ **Correct:** +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" +- "Reverted to Node 18 per Brady's explicit request on 2024-01-15" + +✗ **Incorrect:** +- "Brady directed v0.6.0" (when later reversed) +- Recording what was *requested* instead of what *actually happened* +- Logging entries before outcome is confirmed + +## Anti-Patterns + +- Writing intermediate or "for now" states to disk +- Attributing decisions without confirming final direction +- Treating history like a draft — history is the source of truth +- Assuming readers will cross-reference or verify; they won't diff --git a/packages/squad-cli/templates/skills/init-mode/SKILL.md b/packages/squad-cli/templates/skills/init-mode/SKILL.md new file mode 100644 index 000000000..4dce6628c --- /dev/null +++ b/packages/squad-cli/templates/skills/init-mode/SKILL.md @@ -0,0 +1,102 @@ +--- +name: "init-mode" +description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)" +domain: "orchestration" +confidence: "high" +source: "extracted" +tools: + - name: "ask_user" + description: "Confirm team roster with selectable menu" + when: "Phase 1 proposal — requires explicit user confirmation" +--- + +## Context + +Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2). + +## Patterns + +### Phase 1: Propose the Team + +No team exists yet. Propose one — but **DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.** +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): + - Determine team size (typically 4–5 + Scribe). + - Determine assignment shape from the user's project description. + - Derive resonance signals from the session and repo context. + - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available. + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ {CastName1} — Lead Scope, decisions, code review +⚛️ {CastName2} — Frontend Dev React, UI, components +🔧 {CastName3} — Backend Dev APIs, database, services +🧪 {CastName4} — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu: + - **question:** *"Look right?"* + - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +### Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms. + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +``` +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow + - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow + - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section + - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment + - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately. + +## Examples + +**Example flow:** +1. Coordinator detects no team.md → Init Mode +2. Runs `git config user.name` → "Brady" +3. Asks: *"Hey Brady, what are you building?"* +4. User: *"TypeScript CLI tool with GitHub API integration"* +5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe +6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph +7. Uses `ask_user` with choices → user selects "Yes, hire this team" +8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents +9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"* + +## Anti-Patterns + +- ❌ Creating files before user confirms Phase 1 +- ❌ Mixing agents from different universes in the same cast +- ❌ Skipping the `ask_user` tool and assuming confirmation +- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role" +- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) +- ❌ Forgetting to initialize `.squad/casting/` state files +- ❌ Reading or storing `git config user.email` (PII violation) diff --git a/packages/squad-cli/templates/skills/model-selection/SKILL.md b/packages/squad-cli/templates/skills/model-selection/SKILL.md new file mode 100644 index 000000000..9b66ae298 --- /dev/null +++ b/packages/squad-cli/templates/skills/model-selection/SKILL.md @@ -0,0 +1,143 @@ +--- +name: "model-selection" +description: "Per-agent model selection with 4-layer hierarchy and fallback chains" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +Before spawning an agent, the coordinator determines which model to use. This skill codifies the 4-layer hierarchy, role-to-model mappings, task complexity adjustments, and fallback chains. Applies to all agent spawns in Team Mode. + +## Patterns + +### 4-Layer Hierarchy + +Check these layers in order — first match wins: + +**Layer 1 — User Override:** Did the user specify a model? ("use opus", "save costs", "use gpt-5.2-codex for this"). If yes, use that model. Session-wide directives ("always use haiku") persist until 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.5` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | 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.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | +| Tester / QA | `claude-sonnet-4.5` | 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.5` | 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.2-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 + +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.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (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" +description: "{emoji} {Name}: {brief task summary}" +prompt: | + ... +``` + +Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, 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 + +When spawning, include the model in your acknowledgment: + +``` +🔧 Fenster (claude-sonnet-4.5) — 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 + +**Premium:** `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5` +**Standard:** `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview` +**Fast/Cheap:** `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` + +## Examples + +**Example 1: Backend dev writing API endpoints** +- Role: Backend Dev +- Task: "implement REST endpoints for user management" +- Layer 3 decision: writing code → `claude-sonnet-4.5` (standard tier) +- Spawn: `🔧 Fenster (claude-sonnet-4.5) — implementing user API endpoints` + +**Example 2: User override** +- User says: "use haiku for everything this session" +- Layer 1 overrides all other layers +- All spawns use `claude-haiku-4.5` regardless of role or task + +**Example 3: Complex refactor** +- Role: Backend Dev +- Task: "refactor 15 auth-related files to use new token system" +- Layer 3 base: `claude-sonnet-4.5` +- Task complexity: heavy multi-file refactor → switch to `gpt-5.2-codex` +- Spawn: `🔧 Fenster (gpt-5.2-codex · code specialist) — refactoring auth to new token system` + +**Example 4: Scribe logging** +- Role: Scribe +- Task: "log session to decisions.md" +- Layer 3: NOT writing code → `claude-haiku-4.5` +- Role mapping: Scribe always haiku, never bump +- Spawn: `📋 Scribe (claude-haiku-4.5 · fast) — logging session` + +## Anti-Patterns + +- ❌ Falling back UP in tier (fast task landing on premium model) +- ❌ Telling the user about fallback attempts ("Opus failed, trying Sonnet") +- ❌ Bumping Scribe or mechanical ops agents to higher tiers +- ❌ Using premium models for documentation or planning tasks +- ❌ Applying multiple complexity adjustments (cascading bumps) +- ❌ Forgetting to include model in spawn acknowledgment +- ❌ Downgrading vision-required tasks from opus diff --git a/packages/squad-cli/templates/skills/release-process/SKILL.md b/packages/squad-cli/templates/skills/release-process/SKILL.md new file mode 100644 index 000000000..12d644538 --- /dev/null +++ b/packages/squad-cli/templates/skills/release-process/SKILL.md @@ -0,0 +1,423 @@ +--- +name: "release-process" +description: "Step-by-step release checklist for Squad — prevents v0.8.22-style disasters" +domain: "release-management" +confidence: "high" +source: "team-decision" +--- + +## Context + +This is the **definitive release runbook** for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken `latest` dist-tag). + +**Rule:** No agent releases Squad without following this checklist. No exceptions. No improvisation. + +--- + +## Pre-Release Validation + +Before starting ANY release work, validate the following: + +### 1. Version Number Validation + +**Rule:** Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them. + +```bash +# Check version is valid semver +node -p "require('semver').valid('0.8.22')" +# Output: '0.8.22' = valid +# Output: null = INVALID, STOP + +# For prerelease versions +node -p "require('semver').valid('0.8.23-preview.1')" +# Output: '0.8.23-preview.1' = valid +``` + +**If `semver.valid()` returns `null`:** STOP. Fix the version. Do NOT proceed. + +### 2. NPM_TOKEN Verification + +**Rule:** NPM_TOKEN must be an **Automation token** (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors. + +```bash +# Check token type (requires npm CLI authenticated) +npm token list +``` + +Look for: +- ✅ `read-write` tokens with NO 2FA requirement = Automation token (correct) +- ❌ Tokens requiring OTP = User token (WRONG, will fail in CI) + +**How to create an Automation token:** +1. Go to npmjs.com → Settings → Access Tokens +2. Click "Generate New Token" +3. Select **"Automation"** (NOT "Publish") +4. Copy token and save as GitHub secret: `NPM_TOKEN` + +**If using a User token:** STOP. Create an Automation token first. + +### 3. Branch and Tag State + +**Rule:** Release from `main` branch. Ensure clean state, no uncommitted changes, latest from origin. + +```bash +# Ensure on main and clean +git checkout main +git pull origin main +git status # Should show: "nothing to commit, working tree clean" + +# Check tag doesn't already exist +git tag -l "v0.8.22" +# Output should be EMPTY. If tag exists, release already done or collision. +``` + +**If tag exists:** STOP. Either release was already done, or there's a collision. Investigate before proceeding. + +### 4. Disable bump-build.mjs + +**Rule:** `bump-build.mjs` is for dev builds ONLY. It must NOT run during release builds (it increments build numbers, creating 4-part versions). + +```bash +# Set env var to skip bump-build.mjs +export SKIP_BUILD_BUMP=1 + +# Verify it's set +echo $SKIP_BUILD_BUMP +# Output: 1 +``` + +**For Windows PowerShell:** +```powershell +$env:SKIP_BUILD_BUMP = "1" +``` + +**If not set:** `bump-build.mjs` will run and mutate versions. This causes disasters (see v0.8.22). + +--- + +## Release Workflow + +### Step 1: Version Bump + +Update version in all 3 package.json files (root + both workspaces) in lockstep. + +```bash +# Set target version (no 'v' prefix) +VERSION="0.8.22" + +# Validate it's valid semver BEFORE proceeding +node -p "require('semver').valid('$VERSION')" +# Must output the version string, NOT null + +# Update all 3 package.json files +npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version + +# Verify all 3 match +grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json +# All 3 should show: "version": "0.8.22" +``` + +**Checkpoint:** All 3 package.json files have identical versions. Run `semver.valid()` one more time to be sure. + +### Step 2: Commit and Tag + +```bash +# Commit version bump +git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json +git commit -m "chore: bump version to $VERSION + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" + +# Create tag (with 'v' prefix) +git tag -a "v$VERSION" -m "Release v$VERSION" + +# Push commit and tag +git push origin main +git push origin "v$VERSION" +``` + +**Checkpoint:** Tag created and pushed. Verify with `git tag -l "v$VERSION"`. + +### Step 3: Create GitHub Release + +**CRITICAL:** Release must be **published**, NOT draft. Draft releases don't trigger `publish.yml` workflow. + +```bash +# Create GitHub Release (NOT draft) +gh release create "v$VERSION" \ + --title "v$VERSION" \ + --notes "Release notes go here" \ + --latest + +# Verify release is PUBLISHED (not draft) +gh release view "v$VERSION" +# Output should NOT contain "(draft)" +``` + +**If output contains `(draft)`:** STOP. Delete the release and recreate without `--draft` flag. + +```bash +# If you accidentally created a draft, fix it: +gh release edit "v$VERSION" --draft=false +``` + +**Checkpoint:** Release is published (NOT draft). The `release: published` event fired and triggered `publish.yml`. + +### Step 4: Monitor Workflow + +The `publish.yml` workflow should start automatically within 10 seconds of release creation. + +```bash +# Watch workflow runs +gh run list --workflow=publish.yml --limit 1 + +# Get detailed status +gh run view --log +``` + +**Expected flow:** +1. `publish-sdk` job runs → publishes `@bradygaster/squad-sdk` +2. Verify step runs with retry loop (up to 5 attempts, 15s interval) to confirm SDK on npm registry +3. `publish-cli` job runs → publishes `@bradygaster/squad-cli` +4. Verify step runs with retry loop to confirm CLI on npm registry + +**If workflow fails:** Check the logs. Common issues: +- EOTP error = wrong NPM_TOKEN type (use Automation token) +- Verify step timeout = npm propagation delay (retry loop should handle this, but propagation can take up to 2 minutes in rare cases) +- Version mismatch = package.json version doesn't match tag + +**Checkpoint:** Both jobs succeeded. Workflow shows green checkmarks. + +### Step 5: Verify npm Publication + +Manually verify both packages are on npm with correct `latest` dist-tag. + +```bash +# Check SDK +npm view @bradygaster/squad-sdk version +# Output: 0.8.22 + +npm dist-tag ls @bradygaster/squad-sdk +# Output should show: latest: 0.8.22 + +# Check CLI +npm view @bradygaster/squad-cli version +# Output: 0.8.22 + +npm dist-tag ls @bradygaster/squad-cli +# Output should show: latest: 0.8.22 +``` + +**If versions don't match:** Something went wrong. Check workflow logs. DO NOT proceed with GitHub Release announcement until npm is correct. + +**Checkpoint:** Both packages show correct version. `latest` dist-tags point to the new version. + +### Step 6: Test Installation + +Verify packages can be installed from npm (real-world smoke test). + +```bash +# Create temp directory +mkdir /tmp/squad-release-test && cd /tmp/squad-release-test + +# Test SDK installation +npm init -y +npm install @bradygaster/squad-sdk +node -p "require('@bradygaster/squad-sdk/package.json').version" +# Output: 0.8.22 + +# Test CLI installation +npm install -g @bradygaster/squad-cli +squad --version +# Output: 0.8.22 + +# Cleanup +cd - +rm -rf /tmp/squad-release-test +``` + +**If installation fails:** npm registry issue or package metadata corruption. DO NOT announce release until this works. + +**Checkpoint:** Both packages install cleanly. Versions match. + +### Step 7: Sync dev to Next Preview + +After main release, sync dev to the next preview version. + +```bash +# Checkout dev +git checkout dev +git pull origin dev + +# Bump to next preview version (e.g., 0.8.23-preview.1) +NEXT_VERSION="0.8.23-preview.1" + +# Validate semver +node -p "require('semver').valid('$NEXT_VERSION')" +# Must output the version string, NOT null + +# Update all 3 package.json files +npm version $NEXT_VERSION --workspaces --include-workspace-root --no-git-tag-version + +# Commit +git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json +git commit -m "chore: bump dev to $NEXT_VERSION + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" + +# Push +git push origin dev +``` + +**Checkpoint:** dev branch now shows next preview version. Future dev builds will publish to `@preview` dist-tag. + +--- + +## Manual Publish (Fallback) + +If `publish.yml` workflow fails or needs to be bypassed, use `workflow_dispatch` to manually trigger publish. + +```bash +# Trigger manual publish +gh workflow run publish.yml -f version="0.8.22" + +# Monitor the run +gh run watch +``` + +**Rule:** Only use this if automated publish failed. Always investigate why automation failed and fix it for next release. + +--- + +## Rollback Procedure + +If a release is broken and needs to be rolled back: + +### 1. Unpublish from npm (Nuclear Option) + +**WARNING:** npm unpublish is time-limited (24 hours) and leaves the version slot burned. Only use if version is critically broken. + +```bash +# Unpublish (requires npm owner privileges) +npm unpublish @bradygaster/squad-sdk@0.8.22 +npm unpublish @bradygaster/squad-cli@0.8.22 +``` + +### 2. Deprecate on npm (Preferred) + +**Preferred approach:** Mark version as deprecated, publish a hotfix. + +```bash +# Deprecate broken version +npm deprecate @bradygaster/squad-sdk@0.8.22 "Broken release, use 0.8.22.1 instead" +npm deprecate @bradygaster/squad-cli@0.8.22 "Broken release, use 0.8.22.1 instead" + +# Publish hotfix version +# (Follow this runbook with version 0.8.22.1) +``` + +### 3. Delete GitHub Release and Tag + +```bash +# Delete GitHub Release +gh release delete "v0.8.22" --yes + +# Delete tag locally and remotely +git tag -d "v0.8.22" +git push origin --delete "v0.8.22" +``` + +### 4. Revert Commit on main + +```bash +# Revert version bump commit +git checkout main +git revert HEAD +git push origin main +``` + +**Checkpoint:** Tag and release deleted. main branch reverted. npm packages deprecated or unpublished. + +--- + +## Common Failure Modes + +### EOTP Error (npm OTP Required) + +**Symptom:** Workflow fails with `EOTP` error. +**Root cause:** NPM_TOKEN is a User token with 2FA enabled. CI can't provide OTP. +**Fix:** Replace NPM_TOKEN with an Automation token (no 2FA). See "NPM_TOKEN Verification" above. + +### Verify Step 404 (npm Propagation Delay) + +**Symptom:** Verify step fails with 404 even though publish succeeded. +**Root cause:** npm registry propagation delay (5-30 seconds). +**Fix:** Verify step now has retry loop (5 attempts, 15s interval). Should auto-resolve. If not, wait 2 minutes and re-run workflow. + +### Version Mismatch (package.json ≠ tag) + +**Symptom:** Verify step fails with "Package version (X) does not match target version (Y)". +**Root cause:** package.json version doesn't match the tag version. +**Fix:** Ensure all 3 package.json files were updated in Step 1. Re-run `npm version` if needed. + +### 4-Part Version Mangled by npm + +**Symptom:** Published version on npm doesn't match package.json (e.g., 0.8.21.4 became 0.8.2-1.4). +**Root cause:** 4-part versions are NOT valid semver. npm's parser misinterprets them. +**Fix:** NEVER use 4-part versions. Only 3-part (0.8.22) or prerelease (0.8.23-preview.1). Run `semver.valid()` before ANY commit. + +### Draft Release Didn't Trigger Workflow + +**Symptom:** Release created but `publish.yml` never ran. +**Root cause:** Release was created as a draft. Draft releases don't emit `release: published` event. +**Fix:** Edit release and change to published: `gh release edit "v$VERSION" --draft=false`. Workflow should trigger immediately. + +--- + +## Validation Checklist + +Before starting ANY release, confirm: + +- [ ] Version is valid semver: `node -p "require('semver').valid('VERSION')"` returns the version string (NOT null) +- [ ] NPM_TOKEN is an Automation token (no 2FA): `npm token list` shows `read-write` without OTP requirement +- [ ] Branch is clean: `git status` shows "nothing to commit, working tree clean" +- [ ] Tag doesn't exist: `git tag -l "vVERSION"` returns empty +- [ ] `SKIP_BUILD_BUMP=1` is set: `echo $SKIP_BUILD_BUMP` returns `1` + +Before creating GitHub Release: + +- [ ] All 3 package.json files have matching versions: `grep '"version"' package.json packages/*/package.json` +- [ ] Commit is pushed: `git log origin/main..main` returns empty +- [ ] Tag is pushed: `git ls-remote --tags origin vVERSION` returns the tag SHA + +After GitHub Release: + +- [ ] Release is published (NOT draft): `gh release view "vVERSION"` output doesn't contain "(draft)" +- [ ] Workflow is running: `gh run list --workflow=publish.yml --limit 1` shows "in_progress" + +After workflow completes: + +- [ ] Both jobs succeeded: Workflow shows green checkmarks +- [ ] SDK on npm: `npm view @bradygaster/squad-sdk version` returns correct version +- [ ] CLI on npm: `npm view @bradygaster/squad-cli version` returns correct version +- [ ] `latest` tags correct: `npm dist-tag ls @bradygaster/squad-sdk` shows `latest: VERSION` +- [ ] Packages install: `npm install @bradygaster/squad-cli` succeeds + +After dev sync: + +- [ ] dev branch has next preview version: `git show dev:package.json | grep version` shows next preview + +--- + +## Post-Mortem Reference + +This skill was created after the v0.8.22 release disaster. Full retrospective: `.squad/decisions/inbox/keaton-v0822-retrospective.md` + +**Key learnings:** +1. No release without a runbook = improvisation = disaster +2. Semver validation is mandatory — 4-part versions break npm +3. NPM_TOKEN type matters — User tokens with 2FA fail in CI +4. Draft releases are a footgun — they don't trigger automation +5. Retry logic is essential — npm propagation takes time + +**Never again.** diff --git a/packages/squad-cli/templates/skills/reskill/SKILL.md b/packages/squad-cli/templates/skills/reskill/SKILL.md new file mode 100644 index 000000000..946de0e0b --- /dev/null +++ b/packages/squad-cli/templates/skills/reskill/SKILL.md @@ -0,0 +1,92 @@ +--- +name: "reskill" +description: "Team-wide charter and history optimization through skill extraction" +domain: "team-optimization" +confidence: "high" +source: "manual — Brady directive to reduce per-agent context overhead" +--- + +## Context + +When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills. + +This is a periodic maintenance activity. Run whenever charter/history bloat is suspected. + +## Process + +### Step 1: Audit +Read all agent charters and histories. Measure byte sizes. Identify: + +- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template) +- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns) +- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills + +### Step 2: Extract +For each identified pattern: +1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md` +2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns) +3. Set confidence: low (first observation), medium (2+ agents), high (team-wide) + +### Step 3: Trim +**Charters** — target ≤1.5KB per agent: +- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it) +- Remove Voice section (tagline blockquote at top of charter already captures it) +- Trim Model section to single line: `Preferred: {model}` +- Remove "When I'm unsure" boilerplate from Boundaries +- Remove domain knowledge now covered by a skill — add skill reference comment if helpful +- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only) + +**Histories** — target ≤8KB per agent: +- Apply history-hygiene skill to any history >12KB +- Promote recurring patterns (3+ occurrences across agents) to skills +- Summarize old entries into `## Core Context` section +- Remove session-specific metadata (dates, branch names, requester names) + +### Step 4: Report +Output a savings table: + +| Agent | Charter Before | Charter After | History Before | History After | Saved | +|-------|---------------|---------------|----------------|---------------|-------| + +Include totals and percentage reduction. + +## Patterns + +### Minimal Charter Template (target format after reskill) + +``` +# {Name} — {Role} + +> {Tagline — one sentence capturing voice and philosophy} + +## Identity +- **Name:** {Name} +- **Role:** {Role} +- **Expertise:** {comma-separated list} + +## What I Own +- {bullet list of owned artifacts/domains} + +## How I Work +- {unique patterns and principles — NOT boilerplate} + +## Boundaries +**I handle:** {domain list} +**I don't handle:** {explicit exclusions} + +## Model +Preferred: {model} +``` + +### Skill Extraction Threshold +- **1 charter** → leave in charter (unique to that agent) +- **2 charters** → consider extracting if >500 bytes of overlap +- **3+ charters** → always extract to a shared skill + +## Anti-Patterns +- Don't delete unique per-agent identity or domain-specific knowledge +- Don't create skills for content only one agent uses +- Don't merge unrelated patterns into a single mega-skill +- Don't remove Model preference line (coordinator needs it for model selection) +- Don't touch `.squad/decisions.md` during reskill +- Don't remove the tagline blockquote — it's the charter's soul in one line diff --git a/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md b/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md new file mode 100644 index 000000000..5d589105c --- /dev/null +++ b/packages/squad-cli/templates/skills/reviewer-protocol/SKILL.md @@ -0,0 +1,79 @@ +--- +name: "reviewer-protocol" +description: "Reviewer rejection workflow and strict lockout semantics" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review. + +## Patterns + +### Reviewer Rejection Protocol + +When a team member has a **Reviewer** role: + +- Reviewers may **approve** or **reject** work from other agents. +- On **rejection**, the Reviewer may choose ONE of: + 1. **Reassign:** Require a *different* agent to do the revision (not the original author). + 2. **Escalate:** Require a *new* agent be spawned with specific expertise. +- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise. +- If the Reviewer approves, work proceeds normally. + +### Strict Lockout Semantics + +When an artifact is **rejected** by a Reviewer: + +1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions. +2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate). +3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent. +4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced. +5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts. +6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise. +7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author. + +## Examples + +**Example 1: Reassign after rejection** +1. Fenster writes authentication module +2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this." +3. Coordinator: Fenster is now locked out of this artifact +4. Coordinator spawns Verbal to revise the authentication module +5. Verbal produces v2 +6. Hockney reviews v2 → approves +7. Lockout clears for next artifact + +**Example 2: Escalate for expertise** +1. Edie writes TypeScript config +2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Edie is now locked out +4. Coordinator spawns new agent (or existing TS expert) to revise +5. New agent produces v2 +6. Keaton reviews v2 + +**Example 3: Deadlock handling** +1. Fenster writes module → rejected +2. Verbal revises → rejected +3. Hockney revises → rejected +4. All 3 eligible agents are now locked out +5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" + +**Example 4: Reviewer accidentally names original author** +1. Fenster writes module → rejected +2. Hockney says: "Fenster should fix the error handling" +3. Coordinator: "Fenster is locked out as the original author. Please name a different agent." +4. Hockney: "Verbal, then" +5. Coordinator spawns Verbal + +## Anti-Patterns + +- ❌ Allowing the original author to self-revise after rejection +- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision +- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user) +- ❌ Applying lockout across unrelated artifacts (scope is per-artifact) +- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent) +- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle) +- ❌ Skipping verification that the revision agent is not the original author diff --git a/packages/squad-cli/templates/skills/secret-handling/SKILL.md b/packages/squad-cli/templates/skills/secret-handling/SKILL.md new file mode 100644 index 000000000..b0576f879 --- /dev/null +++ b/packages/squad-cli/templates/skills/secret-handling/SKILL.md @@ -0,0 +1,200 @@ +--- +name: secret-handling +description: Never read .env files or write secrets to .squad/ committed files +domain: security, file-operations, team-collaboration +confidence: high +source: earned (issue #267 — credential leak incident) +--- + +## Context + +Spawned agents have read access to the entire repository, including `.env` files containing live credentials. If an agent reads secrets and writes them to `.squad/` files (decisions, logs, history), Scribe auto-commits them to git, exposing them in remote history. This skill codifies absolute prohibitions and safe alternatives. + +## Patterns + +### Prohibited File Reads + +**NEVER read these files:** +- `.env` (production secrets) +- `.env.local` (local dev secrets) +- `.env.production` (production environment) +- `.env.development` (development environment) +- `.env.staging` (staging environment) +- `.env.test` (test environment with real credentials) +- Any file matching `.env.*` UNLESS explicitly allowed (see below) + +**Allowed alternatives:** +- `.env.example` (safe — contains placeholder values, no real secrets) +- `.env.sample` (safe — documentation template) +- `.env.template` (safe — schema/structure reference) + +**If you need config info:** +1. **Ask the user directly** — "What's the database connection string?" +2. **Read `.env.example`** — shows structure without exposing secrets +3. **Read documentation** — check `README.md`, `docs/`, config guides + +**NEVER assume you can "just peek at .env to understand the schema."** Use `.env.example` or ask. + +### Prohibited Output Patterns + +**NEVER write these to `.squad/` files:** + +| Pattern Type | Examples | Regex Pattern (for scanning) | +|--------------|----------|-------------------------------| +| API Keys | `OPENAI_API_KEY=sk-proj-...`, `GITHUB_TOKEN=ghp_...` | `[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+` | +| Passwords | `DB_PASSWORD=super_secret_123`, `password: "..."` | `(?:PASSWORD|PASS|PWD)[:=]\s*["']?[^\s"']+` | +| Connection Strings | `postgres://user:pass@host:5432/db`, `Server=...;Password=...` | `(?:postgres|mysql|mongodb)://[^@]+@|(?:Server|Host)=.*(?:Password|Pwd)=` | +| JWT Tokens | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` | `eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` | +| Private Keys | `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` | `-----BEGIN [A-Z ]+PRIVATE KEY-----` | +| AWS Credentials | `AKIA...`, `aws_secret_access_key=...` | `AKIA[0-9A-Z]{16}|aws_secret_access_key=[^\s]+` | +| Email Addresses | `user@example.com` (PII violation per team decision) | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | + +**What to write instead:** +- Placeholder values: `DATABASE_URL=` +- Redacted references: `API key configured (see .env.example)` +- Architecture notes: "App uses JWT auth — token stored in session" +- Schema documentation: "Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)" + +### Scribe Pre-Commit Validation + +**Before committing `.squad/` changes, Scribe MUST:** + +1. **Scan all staged files** for secret patterns (use regex table above) +2. **Check for prohibited file names** (don't commit `.env` even if manually staged) +3. **If secrets detected:** + - STOP the commit (do NOT proceed) + - Remove the file from staging: `git reset HEAD ` + - Report to user: + ``` + 🚨 SECRET DETECTED — commit blocked + + File: .squad/decisions/inbox/river-db-config.md + Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod + + This file contains credentials and MUST NOT be committed. + Please remove the secret, replace with placeholder, and try again. + ``` + - Exit with error (never silently skip) + +4. **If no secrets detected:** + - Proceed with commit as normal + +**Implementation note for Scribe:** +- Run validation AFTER staging files, BEFORE calling `git commit` +- Use PowerShell `Select-String` or `git diff --cached` to scan staged content +- Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior + +### Remediation — If a Secret Was Already Committed + +**If you discover a secret in git history:** + +1. **STOP immediately** — do not make more commits +2. **Alert the user:** + ``` + 🚨 CREDENTIAL LEAK DETECTED + + A secret was found in git history: + Commit: abc1234 + File: .squad/decisions/inbox/agent-config.md + Pattern: API_KEY=sk-proj-... + + This requires immediate remediation: + 1. Revoke the exposed credential (regenerate API key, rotate password) + 2. Remove from git history (git filter-repo or BFG) + 3. Force-push the cleaned history + + Do NOT proceed with new work until this is resolved. + ``` +3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools +4. **Wait for user confirmation** before resuming work + +## Examples + +### ✓ Correct: Reading Config Schema + +**Agent needs to know what environment variables are required:** + +``` +Agent: "What environment variables does this app need?" +→ Reads `.env.example`: + OPENAI_API_KEY=sk-... + DATABASE_URL=postgres://user:pass@localhost:5432/db + REDIS_URL=redis://localhost:6379 + +→ Writes to .squad/decisions/inbox/river-env-setup.md: + "App requires three environment variables: + - OPENAI_API_KEY (OpenAI API key, format: sk-...) + - DATABASE_URL (Postgres connection string) + - REDIS_URL (Redis connection string) + See .env.example for full schema." +``` + +### ✗ Incorrect: Reading Live Credentials + +**Agent needs to know database schema:** + +``` +Agent: (reads .env) + DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb + +→ Writes to .squad/decisions/inbox/river-db-schema.md: + "Database connection: postgres://admin:super_secret_pw@prod.example.com:5432/appdb" + +🚨 VIOLATION: Live credential written to committed file +``` + +**Correct approach:** +``` +Agent: (reads .env.example OR asks user) +User: "It's a Postgres database, schema is in migrations/" + +→ Writes to .squad/decisions/inbox/river-db-schema.md: + "Database: Postgres (connection configured in .env). Schema defined in db/migrations/." +``` + +### ✓ Correct: Scribe Pre-Commit Validation + +**Scribe is about to commit:** + +```powershell +# Stage files +git add .squad/ + +# Scan staged content for secrets +$stagedContent = git diff --cached +$secretPatterns = @( + '[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+', + '(?:PASSWORD|PASS|PWD)[:=]\s*["'']?[^\s"'']+', + 'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+' +) + +$detected = $false +foreach ($pattern in $secretPatterns) { + if ($stagedContent -match $pattern) { + $detected = $true + Write-Host "🚨 SECRET DETECTED: $($matches[0])" + break + } +} + +if ($detected) { + # Remove from staging, report, exit + git reset HEAD .squad/ + Write-Error "Commit blocked — secret detected in staged files" + exit 1 +} + +# Safe to commit +git commit -F $msgFile +``` + +## Anti-Patterns + +- ❌ Reading `.env` "just to check the schema" — use `.env.example` instead +- ❌ Writing "sanitized" connection strings that still contain credentials +- ❌ Assuming "it's just a dev environment" makes secrets safe to commit +- ❌ Committing first, scanning later — validation MUST happen before commit +- ❌ Silently skipping secret detection — fail loud, never silent +- ❌ Trusting agents to "know better" — enforce at multiple layers (prompt, hook, architecture) +- ❌ Writing secrets to "temporary" files in `.squad/` — Scribe commits ALL `.squad/` changes +- ❌ Extracting "just the host" from a connection string — still leaks infrastructure topology diff --git a/packages/squad-sdk/package.json b/packages/squad-sdk/package.json index 7ded30607..c4ac69aac 100644 --- a/packages/squad-sdk/package.json +++ b/packages/squad-sdk/package.json @@ -1,6 +1,6 @@ { "name": "@bradygaster/squad-sdk", - "version": "0.8.25", + "version": "0.8.25.2", "description": "Squad SDK — Programmable multi-agent runtime for GitHub Copilot", "type": "module", "main": "./dist/index.js", diff --git a/packages/squad-sdk/templates/skills/agent-collaboration/SKILL.md b/packages/squad-sdk/templates/skills/agent-collaboration/SKILL.md new file mode 100644 index 000000000..054463cf8 --- /dev/null +++ b/packages/squad-sdk/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 diff --git a/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md b/packages/squad-sdk/templates/skills/architectural-proposals/SKILL.md new file mode 100644 index 000000000..46d7b5053 --- /dev/null +++ b/packages/squad-sdk/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) diff --git a/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md b/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md new file mode 100644 index 000000000..61c07d73e --- /dev/null +++ b/packages/squad-sdk/templates/skills/ci-validation-gates/SKILL.md @@ -0,0 +1,84 @@ +--- +name: "ci-validation-gates" +description: "Defensive CI/CD patterns: semver validation, token checks, retry logic, draft detection — earned from v0.8.22" +domain: "ci-cd" +confidence: "high" +source: "extracted from Drucker and Trejo charters — earned knowledge from v0.8.22 release incident" +--- + +## Context + +CI workflows must be defensive. These patterns were learned from the v0.8.22 release disaster where invalid semver, wrong token types, missing retry logic, and draft releases caused a multi-hour outage. Both Drucker (CI/CD) and Trejo (Release Manager) carried this knowledge in their charters — now centralized here. + +## Patterns + +### Semver Validation Gate +Every publish workflow MUST validate version format before `npm publish`. 4-part versions (e.g., 0.8.21.4) are NOT valid semver — npm mangles them. + +```yaml +- name: Validate semver + run: | + VERSION="${{ github.event.release.tag_name }}" + VERSION="${VERSION#v}" + if ! npx semver "$VERSION" > /dev/null 2>&1; then + echo "❌ Invalid semver: $VERSION" + echo "Only 3-part versions (X.Y.Z) or prerelease (X.Y.Z-tag.N) are valid." + exit 1 + fi + echo "✅ Valid semver: $VERSION" +``` + +### NPM Token Type Verification +NPM_TOKEN MUST be an Automation token, not a User token with 2FA: +- User tokens require OTP — CI can't provide it → EOTP error +- Create Automation tokens at npmjs.com → Settings → Access Tokens → Automation +- Verify before first publish in any workflow + +### Retry Logic for npm Registry Propagation +npm registry uses eventual consistency. After `npm publish` succeeds, the package may not be immediately queryable. +- Propagation: typically 5-30s, up to 2min in rare cases +- All verify steps: 5 attempts, 15-second intervals +- Log each attempt: "Attempt 1/5: Checking package..." +- Exit loop on success, fail after max attempts + +```yaml +- name: Verify package (with retry) + run: | + MAX_ATTEMPTS=5 + WAIT_SECONDS=15 + for attempt in $(seq 1 $MAX_ATTEMPTS); do + echo "Attempt $attempt/$MAX_ATTEMPTS: Checking $PACKAGE@$VERSION..." + if npm view "$PACKAGE@$VERSION" version > /dev/null 2>&1; then + echo "✅ Package verified" + exit 0 + fi + [ $attempt -lt $MAX_ATTEMPTS ] && sleep $WAIT_SECONDS + done + echo "❌ Failed to verify after $MAX_ATTEMPTS attempts" + exit 1 +``` + +### Draft Release Detection +Draft releases don't emit `release: published` event. Workflows MUST: +- Trigger on `release: published` (NOT `created`) +- If using workflow_dispatch: verify release is published via GitHub API before proceeding + +### Build Script Protection +Set `SKIP_BUILD_BUMP=1` (or `$env:SKIP_BUILD_BUMP = "1"` on Windows) before ANY release build. bump-build.mjs is for dev builds ONLY — it silently mutates versions. + +## Known Failure Modes (v0.8.22 Incident) + +| # | What Happened | Root Cause | Prevention | +|---|---------------|-----------|------------| +| 1 | 4-part version published, npm mangled it | No semver validation gate | `npx semver` check before every publish | +| 2 | CI failed 5+ times with EOTP | User token with 2FA | Automation token only | +| 3 | Verify returned false 404 | No retry logic for propagation | 5 attempts, 15s intervals | +| 4 | Workflow never triggered | Draft release doesn't emit event | Never create draft releases | +| 5 | Version mutated during release | bump-build.mjs ran in release | SKIP_BUILD_BUMP=1 | + +## Anti-Patterns +- ❌ Publishing without semver validation gate +- ❌ Single-shot verification without retry +- ❌ Hard-coded secrets in workflows +- ❌ Silent CI failures — every error needs actionable output with remediation +- ❌ Assuming npm publish is instantly queryable diff --git a/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md b/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md new file mode 100644 index 000000000..03f7bf55f --- /dev/null +++ b/packages/squad-sdk/templates/skills/cli-wiring/SKILL.md @@ -0,0 +1,47 @@ +# Skill: CLI Command Wiring + +**Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`. + +## Checklist — Adding a New CLI Command + +1. **Create command file** in `packages/squad-cli/src/cli/commands/.ts` + - Export a `run(cwd, options)` async function (or class with static methods for utility modules) + +2. **Add routing block** in `packages/squad-cli/src/cli-entry.ts` inside `main()`: + ```ts + if (cmd === '') { + const { run } = await import('./cli/commands/.js'); + // parse args, call function + await run(process.cwd(), options); + return; + } + ``` + +3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`): + ```ts + console.log(` ${BOLD}${RESET} `); + console.log(` Usage: [flags]`); + ``` + +4. **Verify both exist** — the recurring bug is doing step 1 but missing steps 2-3. + +## Wiring Patterns by Command Type + +| Type | Example | How to wire | +|------|---------|-------------| +| Standard command | `export.ts`, `build.ts` | `run*()` function, parse flags from `args` | +| Placeholder command | `loop`, `hire` | Inline in cli-entry.ts, prints pending message | +| Utility/check module | `rc-tunnel.ts`, `copilot-bridge.ts` | Wire as diagnostic check (e.g., `isDevtunnelAvailable()`) | +| Subcommand of another | `init-remote.ts` | Already used inside parent + standalone alias | + +## Common Import Pattern + +```ts +import { BOLD, RESET, DIM, RED, GREEN, YELLOW } from './cli/core/output.js'; +``` + +Use dynamic `await import()` for command modules to keep startup fast (lazy loading). + +## History + +- **#237 / PR #244:** 4 commands wired (rc, copilot-bridge, init-remote, rc-tunnel). aspire, link, loop, hire were already present. diff --git a/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md b/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md new file mode 100644 index 000000000..da3e94609 --- /dev/null +++ b/packages/squad-sdk/templates/skills/client-compatibility/SKILL.md @@ -0,0 +1,89 @@ +--- +name: "client-compatibility" +description: "Platform detection and adaptive spawning for CLI vs VS Code vs other surfaces" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +Squad runs on multiple Copilot surfaces (CLI, VS Code, JetBrains, GitHub.com). The coordinator must detect its platform and adapt spawning behavior accordingly. Different tools are available on different platforms, requiring conditional logic for agent spawning, SQL usage, and response timing. + +## Patterns + +### 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. + +## Examples + +**Example 1: CLI parallel spawn** +```typescript +// Coordinator detects task tool available → CLI mode +task({ agent_type: "general-purpose", mode: "background", model: "claude-sonnet-4.5", ... }) +task({ agent_type: "general-purpose", mode: "background", model: "claude-haiku-4.5", ... }) +// Later: read_agent for both +``` + +**Example 2: VS Code parallel spawn** +```typescript +// Coordinator detects runSubagent available → VS Code mode +runSubagent({ prompt: "...Fenster charter + task..." }) +runSubagent({ prompt: "...Hockney charter + task..." }) +runSubagent({ prompt: "...Scribe charter + task..." }) // Last in group +// Results return automatically, no read_agent +``` + +**Example 3: Fallback mode** +```typescript +// Neither task nor runSubagent available → work inline +// Coordinator executes the task directly without spawning +``` + +## Anti-Patterns + +- ❌ Using SQL tool in cross-platform workflows (breaks on VS Code/JetBrains/GitHub.com) +- ❌ Attempting per-spawn model selection on VS Code (Phase 1 — only session model works) +- ❌ Fire-and-forget Scribe on VS Code (must batch as last subagent) +- ❌ Showing launch table on VS Code (results already inline) +- ❌ Apologizing or explaining platform limitations to the user +- ❌ Using `task` when only `runSubagent` is available +- ❌ Dropping prompt structure (charter/identity/task) on non-CLI platforms diff --git a/packages/squad-sdk/templates/skills/git-workflow/SKILL.md b/packages/squad-sdk/templates/skills/git-workflow/SKILL.md new file mode 100644 index 000000000..bfa0b8596 --- /dev/null +++ b/packages/squad-sdk/templates/skills/git-workflow/SKILL.md @@ -0,0 +1,204 @@ +--- +name: "git-workflow" +description: "Squad branching model: dev-first workflow with insiders preview channel" +domain: "version-control" +confidence: "high" +source: "team-decision" +--- + +## Context + +Squad uses a three-branch model. **All feature work starts from `dev`, not `main`.** + +| Branch | Purpose | Publishes | +|--------|---------|-----------| +| `main` | Released, tagged, in-npm code only | `npm publish` on tag | +| `dev` | Integration branch — all feature work lands here | `npm publish --tag preview` on merge | +| `insiders` | Early-access channel — synced from dev | `npm publish --tag insiders` on sync | + +## Branch Naming Convention + +Issue branches MUST use: `squad/{issue-number}-{kebab-case-slug}` + +Examples: +- `squad/195-fix-version-stamp-bug` +- `squad/42-add-profile-api` + +## Workflow for Issue Work + +1. **Branch from dev:** + ```bash + git checkout dev + git pull origin dev + git checkout -b squad/{issue-number}-{slug} + ``` + +2. **Mark issue in-progress:** + ```bash + gh issue edit {number} --add-label "status:in-progress" + ``` + +3. **Create draft PR targeting dev:** + ```bash + gh pr create --base dev --title "{description}" --body "Closes #{issue-number}" --draft + ``` + +4. **Do the work.** Make changes, write tests, commit with issue reference. + +5. **Push and mark ready:** + ```bash + git push -u origin squad/{issue-number}-{slug} + gh pr ready + ``` + +6. **After merge to dev:** + ```bash + git checkout dev + git pull origin dev + git branch -d squad/{issue-number}-{slug} + git push origin --delete squad/{issue-number}-{slug} + ``` + +## Parallel Multi-Issue Work (Worktrees) + +When the coordinator routes multiple issues simultaneously (e.g., "fix bugs X, Y, and Z"), use `git worktree` to give each agent an isolated working directory. No filesystem collisions, no branch-switching overhead. + +### When to Use Worktrees vs Sequential + +| Scenario | Strategy | +|----------|----------| +| Single issue | Standard workflow above — no worktree needed | +| 2+ simultaneous issues in same repo | Worktrees — one per issue | +| Work spanning multiple repos | Separate clones as siblings (see Multi-Repo below) | + +### Setup + +From the main clone (must be on dev or any branch): + +```bash +# Ensure dev is current +git fetch origin dev + +# Create a worktree per issue — siblings to the main clone +git worktree add ../squad-195 -b squad/195-fix-stamp-bug origin/dev +git worktree add ../squad-193 -b squad/193-refactor-loader origin/dev +``` + +**Naming convention:** `../{repo-name}-{issue-number}` (e.g., `../squad-195`, `../squad-pr-42`). + +Each worktree: +- Has its own working directory and index +- Is on its own `squad/{issue-number}-{slug}` branch from dev +- Shares the same `.git` object store (disk-efficient) + +### Per-Worktree Agent Workflow + +Each agent operates inside its worktree exactly like the single-issue workflow: + +```bash +cd ../squad-195 + +# Work normally — commits, tests, pushes +git add -A && git commit -m "fix: stamp bug (#195)" +git push -u origin squad/195-fix-stamp-bug + +# Create PR targeting dev +gh pr create --base dev --title "fix: stamp bug" --body "Closes #195" --draft +``` + +All PRs target `dev` independently. Agents never interfere with each other's filesystem. + +### .squad/ State in Worktrees + +The `.squad/` directory exists in each worktree as a copy. This is safe because: +- `.gitattributes` declares `merge=union` on append-only files (history.md, decisions.md, logs) +- Each agent appends to its own section; union merge reconciles on PR merge to dev +- **Rule:** Never rewrite or reorder `.squad/` files in a worktree — append only + +### Cleanup After Merge + +After a worktree's PR is merged to dev: + +```bash +# From the main clone +git worktree remove ../squad-195 +git worktree prune # clean stale metadata +git branch -d squad/195-fix-stamp-bug +git push origin --delete squad/195-fix-stamp-bug +``` + +If a worktree was deleted manually (rm -rf), `git worktree prune` recovers the state. + +--- + +## Multi-Repo Downstream Scenarios + +When work spans multiple repositories (e.g., squad-cli changes need squad-sdk changes, or a user's app depends on squad): + +### Setup + +Clone downstream repos as siblings to the main repo: + +``` +~/work/ + squad-pr/ # main repo + squad-sdk/ # downstream dependency + user-app/ # consumer project +``` + +Each repo gets its own issue branch following its own naming convention. If the downstream repo also uses Squad conventions, use `squad/{issue-number}-{slug}`. + +### Coordinated PRs + +- Create PRs in each repo independently +- Link them in PR descriptions: + ``` + Closes #42 + + **Depends on:** squad-sdk PR #17 (squad-sdk changes required for this feature) + ``` +- Merge order: dependencies first (e.g., squad-sdk), then dependents (e.g., squad-cli) + +### Local Linking for Testing + +Before pushing, verify cross-repo changes work together: + +```bash +# Node.js / npm +cd ../squad-sdk && npm link +cd ../squad-pr && npm link squad-sdk + +# Go +# Use replace directive in go.mod: +# replace github.com/org/squad-sdk => ../squad-sdk + +# Python +cd ../squad-sdk && pip install -e . +``` + +**Important:** Remove local links before committing. `npm link` and `go replace` are dev-only — CI must use published packages or PR-specific refs. + +### Worktrees + Multi-Repo + +These compose naturally. You can have: +- Multiple worktrees in the main repo (parallel issues) +- Separate clones for downstream repos +- Each combination operates independently + +--- + +## Anti-Patterns + +- ❌ Branching from main (branch from dev) +- ❌ PR targeting main directly (target dev) +- ❌ Non-conforming branch names (must be squad/{number}-{slug}) +- ❌ Committing directly to main or dev (use PRs) +- ❌ Switching branches in the main clone while worktrees are active (use worktrees instead) +- ❌ Using worktrees for cross-repo work (use separate clones) +- ❌ Leaving stale worktrees after PR merge (clean up immediately) + +## Promotion Pipeline + +- dev → insiders: Automated sync on green build +- dev → main: Manual merge when ready for stable release, then tag +- Hotfixes: Branch from main as `hotfix/{slug}`, PR to dev, cherry-pick to main if urgent diff --git a/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md b/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md new file mode 100644 index 000000000..453a03b4e --- /dev/null +++ b/packages/squad-sdk/templates/skills/history-hygiene/SKILL.md @@ -0,0 +1,36 @@ +--- +name: history-hygiene +description: Record final outcomes to history.md, not intermediate requests or reversed decisions +domain: documentation, team-collaboration +confidence: high +source: earned (Kobayashi v0.6.0 incident, team intervention) +--- + +## Context + +History files (.md files tracking decisions, spawns, outcomes) are read cold by future agents. Stale or incorrect entries poison decision-making downstream. The Kobayashi incident proved this: history said "Brady decided v0.6.0" when Brady had reversed that to v0.8.17. Future spawns read the wrong truth and repeated the mistake. + +## Patterns + +- **Record the final outcome**, not the initial request. +- **Wait for confirmation** before writing to history — don't log intermediate states. +- **If a decision reverses**, update the entry immediately — don't leave stale data. +- **One read = one truth.** A future agent should never need to cross-reference other files to understand what actually happened. + +## Examples + +✓ **Correct:** +- "Migration target: v0.8.17 (initially discussed as v0.6.0, corrected by Brady)" +- "Reverted to Node 18 per Brady's explicit request on 2024-01-15" + +✗ **Incorrect:** +- "Brady directed v0.6.0" (when later reversed) +- Recording what was *requested* instead of what *actually happened* +- Logging entries before outcome is confirmed + +## Anti-Patterns + +- Writing intermediate or "for now" states to disk +- Attributing decisions without confirming final direction +- Treating history like a draft — history is the source of truth +- Assuming readers will cross-reference or verify; they won't diff --git a/packages/squad-sdk/templates/skills/init-mode/SKILL.md b/packages/squad-sdk/templates/skills/init-mode/SKILL.md new file mode 100644 index 000000000..4dce6628c --- /dev/null +++ b/packages/squad-sdk/templates/skills/init-mode/SKILL.md @@ -0,0 +1,102 @@ +--- +name: "init-mode" +description: "Team initialization flow (Phase 1 proposal + Phase 2 creation)" +domain: "orchestration" +confidence: "high" +source: "extracted" +tools: + - name: "ask_user" + description: "Confirm team roster with selectable menu" + when: "Phase 1 proposal — requires explicit user confirmation" +--- + +## Context + +Init Mode activates when `.squad/team.md` does not exist, or exists but has zero roster entries under `## Members`. The coordinator proposes a team (Phase 1), waits for user confirmation, then creates the team structure (Phase 2). + +## Patterns + +### Phase 1: Propose the Team + +No team exists yet. Propose one — but **DO NOT create any files until the user confirms.** + +1. **Identify the user.** Run `git config user.name` to learn who you're working with. Use their name in conversation (e.g., *"Hey Brady, what are you building?"*). Store their name (NOT email) in `team.md` under Project Context. **Never read or store `git config user.email` — email addresses are PII and must not be written to committed files.** +2. Ask: *"What are you building? (language, stack, what it does)"* +3. **Cast the team.** Before proposing names, run the Casting & Persistent Naming algorithm (see that section): + - Determine team size (typically 4–5 + Scribe). + - Determine assignment shape from the user's project description. + - Derive resonance signals from the session and repo context. + - Select a universe. If the universe is custom, allocate character names from that universe based on the related list found in the `.squad/templates/casting/` directory. Prefer custom universes when available. + - Scribe is always "Scribe" — exempt from casting. + - Ralph is always "Ralph" — exempt from casting. +4. Propose the team with their cast names. Example (names will vary per cast): + +``` +🏗️ {CastName1} — Lead Scope, decisions, code review +⚛️ {CastName2} — Frontend Dev React, UI, components +🔧 {CastName3} — Backend Dev APIs, database, services +🧪 {CastName4} — Tester Tests, quality, edge cases +📋 Scribe — (silent) Memory, decisions, session logs +🔄 Ralph — (monitor) Work queue, backlog, keep-alive +``` + +5. Use the `ask_user` tool to confirm the roster. Provide choices so the user sees a selectable menu: + - **question:** *"Look right?"* + - **choices:** `["Yes, hire this team", "Add someone", "Change a role"]` + +**⚠️ STOP. Your response ENDS here. Do NOT proceed to Phase 2. Do NOT create any files or directories. Wait for the user's reply.** + +### Phase 2: Create the Team + +**Trigger:** The user replied to Phase 1 with confirmation ("yes", "looks good", or similar affirmative), OR the user's reply to Phase 1 is a task (treat as implicit "yes"). + +> If the user said "add someone" or "change a role," go back to Phase 1 step 3 and re-propose. Do NOT enter Phase 2 until the user confirms. + +6. Create the `.squad/` directory structure (see `.squad/templates/` for format guides or use the standard structure: team.md, routing.md, ceremonies.md, decisions.md, decisions/inbox/, casting/, agents/, orchestration-log/, skills/, log/). + +**Casting state initialization:** Copy `.squad/templates/casting-policy.json` to `.squad/casting/policy.json` (or create from defaults). Create `registry.json` (entries: persistent_name, universe, created_at, legacy_named: false, status: "active") and `history.json` (first assignment snapshot with unique assignment_id). + +**Seeding:** Each agent's `history.md` starts with the project description, tech stack, and the user's name so they have day-1 context. Agent folder names are the cast name in lowercase (e.g., `.squad/agents/ripley/`). The Scribe's charter includes maintaining `decisions.md` and cross-agent context sharing. + +**Team.md structure:** `team.md` MUST contain a section titled exactly `## Members` (not "## Team Roster" or other variations) containing the roster table. This header is hard-coded in GitHub workflows (`squad-heartbeat.yml`, `squad-issue-assign.yml`, `squad-triage.yml`, `sync-squad-labels.yml`) for label automation. If the header is missing or titled differently, label routing breaks. + +**Merge driver for append-only files:** Create or update `.gitattributes` at the repo root to enable conflict-free merging of `.squad/` state across branches: +``` +.squad/decisions.md merge=union +.squad/agents/*/history.md merge=union +.squad/log/** merge=union +.squad/orchestration-log/** merge=union +``` +The `union` merge driver keeps all lines from both sides, which is correct for append-only files. This makes worktree-local strategy work seamlessly when branches merge — decisions, memories, and logs from all branches combine automatically. + +7. Say: *"✅ Team hired. Try: '{FirstCastName}, set up the project structure'"* + +8. **Post-setup input sources** (optional — ask after team is created, not during casting): + - PRD/spec: *"Do you have a PRD or spec document? (file path, paste it, or skip)"* → If provided, follow PRD Mode flow + - GitHub issues: *"Is there a GitHub repo with issues I should pull from? (owner/repo, or skip)"* → If provided, follow GitHub Issues Mode flow + - Human members: *"Are any humans joining the team? (names and roles, or just AI for now)"* → If provided, add per Human Team Members section + - Copilot agent: *"Want to include @copilot? It can pick up issues autonomously. (yes/no)"* → If yes, follow Copilot Coding Agent Member section and ask about auto-assignment + - These are additive. Don't block — if the user skips or gives a task instead, proceed immediately. + +## Examples + +**Example flow:** +1. Coordinator detects no team.md → Init Mode +2. Runs `git config user.name` → "Brady" +3. Asks: *"Hey Brady, what are you building?"* +4. User: *"TypeScript CLI tool with GitHub API integration"* +5. Coordinator runs casting algorithm → selects "The Usual Suspects" universe +6. Proposes: Keaton (Lead), Verbal (Prompt), Fenster (Backend), Hockney (Tester), Scribe, Ralph +7. Uses `ask_user` with choices → user selects "Yes, hire this team" +8. Coordinator creates `.squad/` structure, initializes casting state, seeds agents +9. Says: *"✅ Team hired. Try: 'Keaton, set up the project structure'"* + +## Anti-Patterns + +- ❌ Creating files before user confirms Phase 1 +- ❌ Mixing agents from different universes in the same cast +- ❌ Skipping the `ask_user` tool and assuming confirmation +- ❌ Proceeding to Phase 2 when user said "add someone" or "change a role" +- ❌ Using `## Team Roster` instead of `## Members` as the header (breaks GitHub workflows) +- ❌ Forgetting to initialize `.squad/casting/` state files +- ❌ Reading or storing `git config user.email` (PII violation) diff --git a/packages/squad-sdk/templates/skills/model-selection/SKILL.md b/packages/squad-sdk/templates/skills/model-selection/SKILL.md new file mode 100644 index 000000000..9b66ae298 --- /dev/null +++ b/packages/squad-sdk/templates/skills/model-selection/SKILL.md @@ -0,0 +1,143 @@ +--- +name: "model-selection" +description: "Per-agent model selection with 4-layer hierarchy and fallback chains" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +Before spawning an agent, the coordinator determines which model to use. This skill codifies the 4-layer hierarchy, role-to-model mappings, task complexity adjustments, and fallback chains. Applies to all agent spawns in Team Mode. + +## Patterns + +### 4-Layer Hierarchy + +Check these layers in order — first match wins: + +**Layer 1 — User Override:** Did the user specify a model? ("use opus", "save costs", "use gpt-5.2-codex for this"). If yes, use that model. Session-wide directives ("always use haiku") persist until 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.5` | Standard | Quality and accuracy matter for code. Use standard tier. | +| Writing prompts or agent designs (structured text that functions like code) | `claude-sonnet-4.5` | 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.5` | Writes code — quality first | Heavy code gen → `gpt-5.2-codex` | +| Tester / QA | `claude-sonnet-4.5` | 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.5` | 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.2-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 + +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.6-fast → claude-opus-4.5 → claude-sonnet-4.5 → (omit model param) +Standard: claude-sonnet-4.5 → gpt-5.2-codex → claude-sonnet-4 → gpt-5.2 → (omit model param) +Fast: claude-haiku-4.5 → gpt-5.1-codex-mini → gpt-4.1 → gpt-5-mini → (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" +description: "{emoji} {Name}: {brief task summary}" +prompt: | + ... +``` + +Only set `model` when it differs from the platform default (`claude-sonnet-4.5`). If the resolved model IS `claude-sonnet-4.5`, 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 + +When spawning, include the model in your acknowledgment: + +``` +🔧 Fenster (claude-sonnet-4.5) — 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 + +**Premium:** `claude-opus-4.6`, `claude-opus-4.6-fast`, `claude-opus-4.5` +**Standard:** `claude-sonnet-4.5`, `claude-sonnet-4`, `gpt-5.2-codex`, `gpt-5.2`, `gpt-5.1-codex-max`, `gpt-5.1-codex`, `gpt-5.1`, `gpt-5`, `gemini-3-pro-preview` +**Fast/Cheap:** `claude-haiku-4.5`, `gpt-5.1-codex-mini`, `gpt-5-mini`, `gpt-4.1` + +## Examples + +**Example 1: Backend dev writing API endpoints** +- Role: Backend Dev +- Task: "implement REST endpoints for user management" +- Layer 3 decision: writing code → `claude-sonnet-4.5` (standard tier) +- Spawn: `🔧 Fenster (claude-sonnet-4.5) — implementing user API endpoints` + +**Example 2: User override** +- User says: "use haiku for everything this session" +- Layer 1 overrides all other layers +- All spawns use `claude-haiku-4.5` regardless of role or task + +**Example 3: Complex refactor** +- Role: Backend Dev +- Task: "refactor 15 auth-related files to use new token system" +- Layer 3 base: `claude-sonnet-4.5` +- Task complexity: heavy multi-file refactor → switch to `gpt-5.2-codex` +- Spawn: `🔧 Fenster (gpt-5.2-codex · code specialist) — refactoring auth to new token system` + +**Example 4: Scribe logging** +- Role: Scribe +- Task: "log session to decisions.md" +- Layer 3: NOT writing code → `claude-haiku-4.5` +- Role mapping: Scribe always haiku, never bump +- Spawn: `📋 Scribe (claude-haiku-4.5 · fast) — logging session` + +## Anti-Patterns + +- ❌ Falling back UP in tier (fast task landing on premium model) +- ❌ Telling the user about fallback attempts ("Opus failed, trying Sonnet") +- ❌ Bumping Scribe or mechanical ops agents to higher tiers +- ❌ Using premium models for documentation or planning tasks +- ❌ Applying multiple complexity adjustments (cascading bumps) +- ❌ Forgetting to include model in spawn acknowledgment +- ❌ Downgrading vision-required tasks from opus diff --git a/packages/squad-sdk/templates/skills/release-process/SKILL.md b/packages/squad-sdk/templates/skills/release-process/SKILL.md new file mode 100644 index 000000000..12d644538 --- /dev/null +++ b/packages/squad-sdk/templates/skills/release-process/SKILL.md @@ -0,0 +1,423 @@ +--- +name: "release-process" +description: "Step-by-step release checklist for Squad — prevents v0.8.22-style disasters" +domain: "release-management" +confidence: "high" +source: "team-decision" +--- + +## Context + +This is the **definitive release runbook** for Squad. Born from the v0.8.22 release disaster (4-part semver mangled by npm, draft release never triggered publish, wrong NPM_TOKEN type, 6+ hours of broken `latest` dist-tag). + +**Rule:** No agent releases Squad without following this checklist. No exceptions. No improvisation. + +--- + +## Pre-Release Validation + +Before starting ANY release work, validate the following: + +### 1. Version Number Validation + +**Rule:** Only 3-part semver (major.minor.patch) or prerelease (major.minor.patch-tag.N) are valid. 4-part versions (0.8.21.4) are NOT valid semver and npm will mangle them. + +```bash +# Check version is valid semver +node -p "require('semver').valid('0.8.22')" +# Output: '0.8.22' = valid +# Output: null = INVALID, STOP + +# For prerelease versions +node -p "require('semver').valid('0.8.23-preview.1')" +# Output: '0.8.23-preview.1' = valid +``` + +**If `semver.valid()` returns `null`:** STOP. Fix the version. Do NOT proceed. + +### 2. NPM_TOKEN Verification + +**Rule:** NPM_TOKEN must be an **Automation token** (no 2FA required). User tokens with 2FA will fail in CI with EOTP errors. + +```bash +# Check token type (requires npm CLI authenticated) +npm token list +``` + +Look for: +- ✅ `read-write` tokens with NO 2FA requirement = Automation token (correct) +- ❌ Tokens requiring OTP = User token (WRONG, will fail in CI) + +**How to create an Automation token:** +1. Go to npmjs.com → Settings → Access Tokens +2. Click "Generate New Token" +3. Select **"Automation"** (NOT "Publish") +4. Copy token and save as GitHub secret: `NPM_TOKEN` + +**If using a User token:** STOP. Create an Automation token first. + +### 3. Branch and Tag State + +**Rule:** Release from `main` branch. Ensure clean state, no uncommitted changes, latest from origin. + +```bash +# Ensure on main and clean +git checkout main +git pull origin main +git status # Should show: "nothing to commit, working tree clean" + +# Check tag doesn't already exist +git tag -l "v0.8.22" +# Output should be EMPTY. If tag exists, release already done or collision. +``` + +**If tag exists:** STOP. Either release was already done, or there's a collision. Investigate before proceeding. + +### 4. Disable bump-build.mjs + +**Rule:** `bump-build.mjs` is for dev builds ONLY. It must NOT run during release builds (it increments build numbers, creating 4-part versions). + +```bash +# Set env var to skip bump-build.mjs +export SKIP_BUILD_BUMP=1 + +# Verify it's set +echo $SKIP_BUILD_BUMP +# Output: 1 +``` + +**For Windows PowerShell:** +```powershell +$env:SKIP_BUILD_BUMP = "1" +``` + +**If not set:** `bump-build.mjs` will run and mutate versions. This causes disasters (see v0.8.22). + +--- + +## Release Workflow + +### Step 1: Version Bump + +Update version in all 3 package.json files (root + both workspaces) in lockstep. + +```bash +# Set target version (no 'v' prefix) +VERSION="0.8.22" + +# Validate it's valid semver BEFORE proceeding +node -p "require('semver').valid('$VERSION')" +# Must output the version string, NOT null + +# Update all 3 package.json files +npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version + +# Verify all 3 match +grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json +# All 3 should show: "version": "0.8.22" +``` + +**Checkpoint:** All 3 package.json files have identical versions. Run `semver.valid()` one more time to be sure. + +### Step 2: Commit and Tag + +```bash +# Commit version bump +git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json +git commit -m "chore: bump version to $VERSION + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" + +# Create tag (with 'v' prefix) +git tag -a "v$VERSION" -m "Release v$VERSION" + +# Push commit and tag +git push origin main +git push origin "v$VERSION" +``` + +**Checkpoint:** Tag created and pushed. Verify with `git tag -l "v$VERSION"`. + +### Step 3: Create GitHub Release + +**CRITICAL:** Release must be **published**, NOT draft. Draft releases don't trigger `publish.yml` workflow. + +```bash +# Create GitHub Release (NOT draft) +gh release create "v$VERSION" \ + --title "v$VERSION" \ + --notes "Release notes go here" \ + --latest + +# Verify release is PUBLISHED (not draft) +gh release view "v$VERSION" +# Output should NOT contain "(draft)" +``` + +**If output contains `(draft)`:** STOP. Delete the release and recreate without `--draft` flag. + +```bash +# If you accidentally created a draft, fix it: +gh release edit "v$VERSION" --draft=false +``` + +**Checkpoint:** Release is published (NOT draft). The `release: published` event fired and triggered `publish.yml`. + +### Step 4: Monitor Workflow + +The `publish.yml` workflow should start automatically within 10 seconds of release creation. + +```bash +# Watch workflow runs +gh run list --workflow=publish.yml --limit 1 + +# Get detailed status +gh run view --log +``` + +**Expected flow:** +1. `publish-sdk` job runs → publishes `@bradygaster/squad-sdk` +2. Verify step runs with retry loop (up to 5 attempts, 15s interval) to confirm SDK on npm registry +3. `publish-cli` job runs → publishes `@bradygaster/squad-cli` +4. Verify step runs with retry loop to confirm CLI on npm registry + +**If workflow fails:** Check the logs. Common issues: +- EOTP error = wrong NPM_TOKEN type (use Automation token) +- Verify step timeout = npm propagation delay (retry loop should handle this, but propagation can take up to 2 minutes in rare cases) +- Version mismatch = package.json version doesn't match tag + +**Checkpoint:** Both jobs succeeded. Workflow shows green checkmarks. + +### Step 5: Verify npm Publication + +Manually verify both packages are on npm with correct `latest` dist-tag. + +```bash +# Check SDK +npm view @bradygaster/squad-sdk version +# Output: 0.8.22 + +npm dist-tag ls @bradygaster/squad-sdk +# Output should show: latest: 0.8.22 + +# Check CLI +npm view @bradygaster/squad-cli version +# Output: 0.8.22 + +npm dist-tag ls @bradygaster/squad-cli +# Output should show: latest: 0.8.22 +``` + +**If versions don't match:** Something went wrong. Check workflow logs. DO NOT proceed with GitHub Release announcement until npm is correct. + +**Checkpoint:** Both packages show correct version. `latest` dist-tags point to the new version. + +### Step 6: Test Installation + +Verify packages can be installed from npm (real-world smoke test). + +```bash +# Create temp directory +mkdir /tmp/squad-release-test && cd /tmp/squad-release-test + +# Test SDK installation +npm init -y +npm install @bradygaster/squad-sdk +node -p "require('@bradygaster/squad-sdk/package.json').version" +# Output: 0.8.22 + +# Test CLI installation +npm install -g @bradygaster/squad-cli +squad --version +# Output: 0.8.22 + +# Cleanup +cd - +rm -rf /tmp/squad-release-test +``` + +**If installation fails:** npm registry issue or package metadata corruption. DO NOT announce release until this works. + +**Checkpoint:** Both packages install cleanly. Versions match. + +### Step 7: Sync dev to Next Preview + +After main release, sync dev to the next preview version. + +```bash +# Checkout dev +git checkout dev +git pull origin dev + +# Bump to next preview version (e.g., 0.8.23-preview.1) +NEXT_VERSION="0.8.23-preview.1" + +# Validate semver +node -p "require('semver').valid('$NEXT_VERSION')" +# Must output the version string, NOT null + +# Update all 3 package.json files +npm version $NEXT_VERSION --workspaces --include-workspace-root --no-git-tag-version + +# Commit +git add package.json packages/squad-sdk/package.json packages/squad-cli/package.json +git commit -m "chore: bump dev to $NEXT_VERSION + +Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>" + +# Push +git push origin dev +``` + +**Checkpoint:** dev branch now shows next preview version. Future dev builds will publish to `@preview` dist-tag. + +--- + +## Manual Publish (Fallback) + +If `publish.yml` workflow fails or needs to be bypassed, use `workflow_dispatch` to manually trigger publish. + +```bash +# Trigger manual publish +gh workflow run publish.yml -f version="0.8.22" + +# Monitor the run +gh run watch +``` + +**Rule:** Only use this if automated publish failed. Always investigate why automation failed and fix it for next release. + +--- + +## Rollback Procedure + +If a release is broken and needs to be rolled back: + +### 1. Unpublish from npm (Nuclear Option) + +**WARNING:** npm unpublish is time-limited (24 hours) and leaves the version slot burned. Only use if version is critically broken. + +```bash +# Unpublish (requires npm owner privileges) +npm unpublish @bradygaster/squad-sdk@0.8.22 +npm unpublish @bradygaster/squad-cli@0.8.22 +``` + +### 2. Deprecate on npm (Preferred) + +**Preferred approach:** Mark version as deprecated, publish a hotfix. + +```bash +# Deprecate broken version +npm deprecate @bradygaster/squad-sdk@0.8.22 "Broken release, use 0.8.22.1 instead" +npm deprecate @bradygaster/squad-cli@0.8.22 "Broken release, use 0.8.22.1 instead" + +# Publish hotfix version +# (Follow this runbook with version 0.8.22.1) +``` + +### 3. Delete GitHub Release and Tag + +```bash +# Delete GitHub Release +gh release delete "v0.8.22" --yes + +# Delete tag locally and remotely +git tag -d "v0.8.22" +git push origin --delete "v0.8.22" +``` + +### 4. Revert Commit on main + +```bash +# Revert version bump commit +git checkout main +git revert HEAD +git push origin main +``` + +**Checkpoint:** Tag and release deleted. main branch reverted. npm packages deprecated or unpublished. + +--- + +## Common Failure Modes + +### EOTP Error (npm OTP Required) + +**Symptom:** Workflow fails with `EOTP` error. +**Root cause:** NPM_TOKEN is a User token with 2FA enabled. CI can't provide OTP. +**Fix:** Replace NPM_TOKEN with an Automation token (no 2FA). See "NPM_TOKEN Verification" above. + +### Verify Step 404 (npm Propagation Delay) + +**Symptom:** Verify step fails with 404 even though publish succeeded. +**Root cause:** npm registry propagation delay (5-30 seconds). +**Fix:** Verify step now has retry loop (5 attempts, 15s interval). Should auto-resolve. If not, wait 2 minutes and re-run workflow. + +### Version Mismatch (package.json ≠ tag) + +**Symptom:** Verify step fails with "Package version (X) does not match target version (Y)". +**Root cause:** package.json version doesn't match the tag version. +**Fix:** Ensure all 3 package.json files were updated in Step 1. Re-run `npm version` if needed. + +### 4-Part Version Mangled by npm + +**Symptom:** Published version on npm doesn't match package.json (e.g., 0.8.21.4 became 0.8.2-1.4). +**Root cause:** 4-part versions are NOT valid semver. npm's parser misinterprets them. +**Fix:** NEVER use 4-part versions. Only 3-part (0.8.22) or prerelease (0.8.23-preview.1). Run `semver.valid()` before ANY commit. + +### Draft Release Didn't Trigger Workflow + +**Symptom:** Release created but `publish.yml` never ran. +**Root cause:** Release was created as a draft. Draft releases don't emit `release: published` event. +**Fix:** Edit release and change to published: `gh release edit "v$VERSION" --draft=false`. Workflow should trigger immediately. + +--- + +## Validation Checklist + +Before starting ANY release, confirm: + +- [ ] Version is valid semver: `node -p "require('semver').valid('VERSION')"` returns the version string (NOT null) +- [ ] NPM_TOKEN is an Automation token (no 2FA): `npm token list` shows `read-write` without OTP requirement +- [ ] Branch is clean: `git status` shows "nothing to commit, working tree clean" +- [ ] Tag doesn't exist: `git tag -l "vVERSION"` returns empty +- [ ] `SKIP_BUILD_BUMP=1` is set: `echo $SKIP_BUILD_BUMP` returns `1` + +Before creating GitHub Release: + +- [ ] All 3 package.json files have matching versions: `grep '"version"' package.json packages/*/package.json` +- [ ] Commit is pushed: `git log origin/main..main` returns empty +- [ ] Tag is pushed: `git ls-remote --tags origin vVERSION` returns the tag SHA + +After GitHub Release: + +- [ ] Release is published (NOT draft): `gh release view "vVERSION"` output doesn't contain "(draft)" +- [ ] Workflow is running: `gh run list --workflow=publish.yml --limit 1` shows "in_progress" + +After workflow completes: + +- [ ] Both jobs succeeded: Workflow shows green checkmarks +- [ ] SDK on npm: `npm view @bradygaster/squad-sdk version` returns correct version +- [ ] CLI on npm: `npm view @bradygaster/squad-cli version` returns correct version +- [ ] `latest` tags correct: `npm dist-tag ls @bradygaster/squad-sdk` shows `latest: VERSION` +- [ ] Packages install: `npm install @bradygaster/squad-cli` succeeds + +After dev sync: + +- [ ] dev branch has next preview version: `git show dev:package.json | grep version` shows next preview + +--- + +## Post-Mortem Reference + +This skill was created after the v0.8.22 release disaster. Full retrospective: `.squad/decisions/inbox/keaton-v0822-retrospective.md` + +**Key learnings:** +1. No release without a runbook = improvisation = disaster +2. Semver validation is mandatory — 4-part versions break npm +3. NPM_TOKEN type matters — User tokens with 2FA fail in CI +4. Draft releases are a footgun — they don't trigger automation +5. Retry logic is essential — npm propagation takes time + +**Never again.** diff --git a/packages/squad-sdk/templates/skills/reskill/SKILL.md b/packages/squad-sdk/templates/skills/reskill/SKILL.md new file mode 100644 index 000000000..946de0e0b --- /dev/null +++ b/packages/squad-sdk/templates/skills/reskill/SKILL.md @@ -0,0 +1,92 @@ +--- +name: "reskill" +description: "Team-wide charter and history optimization through skill extraction" +domain: "team-optimization" +confidence: "high" +source: "manual — Brady directive to reduce per-agent context overhead" +--- + +## Context + +When the coordinator hears "team, reskill" (or similar: "optimize context", "slim down charters"), trigger a team-wide optimization pass. The goal: reduce per-agent context consumption by extracting shared patterns from charters and histories into reusable skills. + +This is a periodic maintenance activity. Run whenever charter/history bloat is suspected. + +## Process + +### Step 1: Audit +Read all agent charters and histories. Measure byte sizes. Identify: + +- **Boilerplate** — sections repeated across ≥3 charters with <10% variation (collaboration, model, boundaries template) +- **Shared knowledge** — domain knowledge duplicated in 2+ charters (incident postmortems, technical patterns) +- **Mature learnings** — history entries appearing 3+ times across agents that should be promoted to skills + +### Step 2: Extract +For each identified pattern: +1. Create or update a skill at `.squad/skills/{skill-name}/SKILL.md` +2. Follow the skill template format (frontmatter + Context + Patterns + Examples + Anti-Patterns) +3. Set confidence: low (first observation), medium (2+ agents), high (team-wide) + +### Step 3: Trim +**Charters** — target ≤1.5KB per agent: +- Remove Collaboration section entirely (spawn prompt + agent-collaboration skill covers it) +- Remove Voice section (tagline blockquote at top of charter already captures it) +- Trim Model section to single line: `Preferred: {model}` +- Remove "When I'm unsure" boilerplate from Boundaries +- Remove domain knowledge now covered by a skill — add skill reference comment if helpful +- Keep: Identity, What I Own, unique How I Work patterns, Boundaries (domain list only) + +**Histories** — target ≤8KB per agent: +- Apply history-hygiene skill to any history >12KB +- Promote recurring patterns (3+ occurrences across agents) to skills +- Summarize old entries into `## Core Context` section +- Remove session-specific metadata (dates, branch names, requester names) + +### Step 4: Report +Output a savings table: + +| Agent | Charter Before | Charter After | History Before | History After | Saved | +|-------|---------------|---------------|----------------|---------------|-------| + +Include totals and percentage reduction. + +## Patterns + +### Minimal Charter Template (target format after reskill) + +``` +# {Name} — {Role} + +> {Tagline — one sentence capturing voice and philosophy} + +## Identity +- **Name:** {Name} +- **Role:** {Role} +- **Expertise:** {comma-separated list} + +## What I Own +- {bullet list of owned artifacts/domains} + +## How I Work +- {unique patterns and principles — NOT boilerplate} + +## Boundaries +**I handle:** {domain list} +**I don't handle:** {explicit exclusions} + +## Model +Preferred: {model} +``` + +### Skill Extraction Threshold +- **1 charter** → leave in charter (unique to that agent) +- **2 charters** → consider extracting if >500 bytes of overlap +- **3+ charters** → always extract to a shared skill + +## Anti-Patterns +- Don't delete unique per-agent identity or domain-specific knowledge +- Don't create skills for content only one agent uses +- Don't merge unrelated patterns into a single mega-skill +- Don't remove Model preference line (coordinator needs it for model selection) +- Don't touch `.squad/decisions.md` during reskill +- Don't remove the tagline blockquote — it's the charter's soul in one line diff --git a/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md b/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md new file mode 100644 index 000000000..5d589105c --- /dev/null +++ b/packages/squad-sdk/templates/skills/reviewer-protocol/SKILL.md @@ -0,0 +1,79 @@ +--- +name: "reviewer-protocol" +description: "Reviewer rejection workflow and strict lockout semantics" +domain: "orchestration" +confidence: "high" +source: "extracted" +--- + +## Context + +When a team member has a **Reviewer** role (e.g., Tester, Code Reviewer, Lead), they may approve or reject work from other agents. On rejection, the coordinator enforces strict lockout rules to ensure the original author does NOT self-revise. This prevents defensive feedback loops and ensures independent review. + +## Patterns + +### Reviewer Rejection Protocol + +When a team member has a **Reviewer** role: + +- Reviewers may **approve** or **reject** work from other agents. +- On **rejection**, the Reviewer may choose ONE of: + 1. **Reassign:** Require a *different* agent to do the revision (not the original author). + 2. **Escalate:** Require a *new* agent be spawned with specific expertise. +- The Coordinator MUST enforce this. If the Reviewer says "someone else should fix this," the original agent does NOT get to self-revise. +- If the Reviewer approves, work proceeds normally. + +### Strict Lockout Semantics + +When an artifact is **rejected** by a Reviewer: + +1. **The original author is locked out.** They may NOT produce the next version of that artifact. No exceptions. +2. **A different agent MUST own the revision.** The Coordinator selects the revision author based on the Reviewer's recommendation (reassign or escalate). +3. **The Coordinator enforces this mechanically.** Before spawning a revision agent, the Coordinator MUST verify that the selected agent is NOT the original author. If the Reviewer names the original author as the fix agent, the Coordinator MUST refuse and ask the Reviewer to name a different agent. +4. **The locked-out author may NOT contribute to the revision** in any form — not as a co-author, advisor, or pair. The revision must be independently produced. +5. **Lockout scope:** The lockout applies to the specific artifact that was rejected. The original author may still work on other unrelated artifacts. +6. **Lockout duration:** The lockout persists for that revision cycle. If the revision is also rejected, the same rule applies again — the revision author is now also locked out, and a third agent must revise. +7. **Deadlock handling:** If all eligible agents have been locked out of an artifact, the Coordinator MUST escalate to the user rather than re-admitting a locked-out author. + +## Examples + +**Example 1: Reassign after rejection** +1. Fenster writes authentication module +2. Hockney (Tester) reviews → rejects: "Error handling is missing. Verbal should fix this." +3. Coordinator: Fenster is now locked out of this artifact +4. Coordinator spawns Verbal to revise the authentication module +5. Verbal produces v2 +6. Hockney reviews v2 → approves +7. Lockout clears for next artifact + +**Example 2: Escalate for expertise** +1. Edie writes TypeScript config +2. Keaton (Lead) reviews → rejects: "Need someone with deeper TS knowledge. Escalate." +3. Coordinator: Edie is now locked out +4. Coordinator spawns new agent (or existing TS expert) to revise +5. New agent produces v2 +6. Keaton reviews v2 + +**Example 3: Deadlock handling** +1. Fenster writes module → rejected +2. Verbal revises → rejected +3. Hockney revises → rejected +4. All 3 eligible agents are now locked out +5. Coordinator: "All eligible agents have been locked out. Escalating to user: [artifact details]" + +**Example 4: Reviewer accidentally names original author** +1. Fenster writes module → rejected +2. Hockney says: "Fenster should fix the error handling" +3. Coordinator: "Fenster is locked out as the original author. Please name a different agent." +4. Hockney: "Verbal, then" +5. Coordinator spawns Verbal + +## Anti-Patterns + +- ❌ Allowing the original author to self-revise after rejection +- ❌ Treating the locked-out author as an "advisor" or "co-author" on the revision +- ❌ Re-admitting a locked-out author when deadlock occurs (must escalate to user) +- ❌ Applying lockout across unrelated artifacts (scope is per-artifact) +- ❌ Accepting the Reviewer's assignment when they name the original author (must refuse and ask for a different agent) +- ❌ Clearing lockout before the revision is approved (lockout persists through revision cycle) +- ❌ Skipping verification that the revision agent is not the original author diff --git a/packages/squad-sdk/templates/skills/secret-handling/SKILL.md b/packages/squad-sdk/templates/skills/secret-handling/SKILL.md new file mode 100644 index 000000000..b0576f879 --- /dev/null +++ b/packages/squad-sdk/templates/skills/secret-handling/SKILL.md @@ -0,0 +1,200 @@ +--- +name: secret-handling +description: Never read .env files or write secrets to .squad/ committed files +domain: security, file-operations, team-collaboration +confidence: high +source: earned (issue #267 — credential leak incident) +--- + +## Context + +Spawned agents have read access to the entire repository, including `.env` files containing live credentials. If an agent reads secrets and writes them to `.squad/` files (decisions, logs, history), Scribe auto-commits them to git, exposing them in remote history. This skill codifies absolute prohibitions and safe alternatives. + +## Patterns + +### Prohibited File Reads + +**NEVER read these files:** +- `.env` (production secrets) +- `.env.local` (local dev secrets) +- `.env.production` (production environment) +- `.env.development` (development environment) +- `.env.staging` (staging environment) +- `.env.test` (test environment with real credentials) +- Any file matching `.env.*` UNLESS explicitly allowed (see below) + +**Allowed alternatives:** +- `.env.example` (safe — contains placeholder values, no real secrets) +- `.env.sample` (safe — documentation template) +- `.env.template` (safe — schema/structure reference) + +**If you need config info:** +1. **Ask the user directly** — "What's the database connection string?" +2. **Read `.env.example`** — shows structure without exposing secrets +3. **Read documentation** — check `README.md`, `docs/`, config guides + +**NEVER assume you can "just peek at .env to understand the schema."** Use `.env.example` or ask. + +### Prohibited Output Patterns + +**NEVER write these to `.squad/` files:** + +| Pattern Type | Examples | Regex Pattern (for scanning) | +|--------------|----------|-------------------------------| +| API Keys | `OPENAI_API_KEY=sk-proj-...`, `GITHUB_TOKEN=ghp_...` | `[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+` | +| Passwords | `DB_PASSWORD=super_secret_123`, `password: "..."` | `(?:PASSWORD|PASS|PWD)[:=]\s*["']?[^\s"']+` | +| Connection Strings | `postgres://user:pass@host:5432/db`, `Server=...;Password=...` | `(?:postgres|mysql|mongodb)://[^@]+@|(?:Server|Host)=.*(?:Password|Pwd)=` | +| JWT Tokens | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` | `eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+` | +| Private Keys | `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` | `-----BEGIN [A-Z ]+PRIVATE KEY-----` | +| AWS Credentials | `AKIA...`, `aws_secret_access_key=...` | `AKIA[0-9A-Z]{16}|aws_secret_access_key=[^\s]+` | +| Email Addresses | `user@example.com` (PII violation per team decision) | `[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}` | + +**What to write instead:** +- Placeholder values: `DATABASE_URL=` +- Redacted references: `API key configured (see .env.example)` +- Architecture notes: "App uses JWT auth — token stored in session" +- Schema documentation: "Requires OPENAI_API_KEY, GITHUB_TOKEN (see .env.example for format)" + +### Scribe Pre-Commit Validation + +**Before committing `.squad/` changes, Scribe MUST:** + +1. **Scan all staged files** for secret patterns (use regex table above) +2. **Check for prohibited file names** (don't commit `.env` even if manually staged) +3. **If secrets detected:** + - STOP the commit (do NOT proceed) + - Remove the file from staging: `git reset HEAD ` + - Report to user: + ``` + 🚨 SECRET DETECTED — commit blocked + + File: .squad/decisions/inbox/river-db-config.md + Pattern: DATABASE_URL=postgres://user:password@localhost:5432/prod + + This file contains credentials and MUST NOT be committed. + Please remove the secret, replace with placeholder, and try again. + ``` + - Exit with error (never silently skip) + +4. **If no secrets detected:** + - Proceed with commit as normal + +**Implementation note for Scribe:** +- Run validation AFTER staging files, BEFORE calling `git commit` +- Use PowerShell `Select-String` or `git diff --cached` to scan staged content +- Fail loud — secret leaks are unacceptable, blocking the commit is correct behavior + +### Remediation — If a Secret Was Already Committed + +**If you discover a secret in git history:** + +1. **STOP immediately** — do not make more commits +2. **Alert the user:** + ``` + 🚨 CREDENTIAL LEAK DETECTED + + A secret was found in git history: + Commit: abc1234 + File: .squad/decisions/inbox/agent-config.md + Pattern: API_KEY=sk-proj-... + + This requires immediate remediation: + 1. Revoke the exposed credential (regenerate API key, rotate password) + 2. Remove from git history (git filter-repo or BFG) + 3. Force-push the cleaned history + + Do NOT proceed with new work until this is resolved. + ``` +3. **Do NOT attempt to fix it yourself** — secret removal requires specialized tools +4. **Wait for user confirmation** before resuming work + +## Examples + +### ✓ Correct: Reading Config Schema + +**Agent needs to know what environment variables are required:** + +``` +Agent: "What environment variables does this app need?" +→ Reads `.env.example`: + OPENAI_API_KEY=sk-... + DATABASE_URL=postgres://user:pass@localhost:5432/db + REDIS_URL=redis://localhost:6379 + +→ Writes to .squad/decisions/inbox/river-env-setup.md: + "App requires three environment variables: + - OPENAI_API_KEY (OpenAI API key, format: sk-...) + - DATABASE_URL (Postgres connection string) + - REDIS_URL (Redis connection string) + See .env.example for full schema." +``` + +### ✗ Incorrect: Reading Live Credentials + +**Agent needs to know database schema:** + +``` +Agent: (reads .env) + DATABASE_URL=postgres://admin:super_secret_pw@prod.example.com:5432/appdb + +→ Writes to .squad/decisions/inbox/river-db-schema.md: + "Database connection: postgres://admin:super_secret_pw@prod.example.com:5432/appdb" + +🚨 VIOLATION: Live credential written to committed file +``` + +**Correct approach:** +``` +Agent: (reads .env.example OR asks user) +User: "It's a Postgres database, schema is in migrations/" + +→ Writes to .squad/decisions/inbox/river-db-schema.md: + "Database: Postgres (connection configured in .env). Schema defined in db/migrations/." +``` + +### ✓ Correct: Scribe Pre-Commit Validation + +**Scribe is about to commit:** + +```powershell +# Stage files +git add .squad/ + +# Scan staged content for secrets +$stagedContent = git diff --cached +$secretPatterns = @( + '[A-Z_]+(?:KEY|TOKEN|SECRET)=[^\s]+', + '(?:PASSWORD|PASS|PWD)[:=]\s*["'']?[^\s"'']+', + 'eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+' +) + +$detected = $false +foreach ($pattern in $secretPatterns) { + if ($stagedContent -match $pattern) { + $detected = $true + Write-Host "🚨 SECRET DETECTED: $($matches[0])" + break + } +} + +if ($detected) { + # Remove from staging, report, exit + git reset HEAD .squad/ + Write-Error "Commit blocked — secret detected in staged files" + exit 1 +} + +# Safe to commit +git commit -F $msgFile +``` + +## Anti-Patterns + +- ❌ Reading `.env` "just to check the schema" — use `.env.example` instead +- ❌ Writing "sanitized" connection strings that still contain credentials +- ❌ Assuming "it's just a dev environment" makes secrets safe to commit +- ❌ Committing first, scanning later — validation MUST happen before commit +- ❌ Silently skipping secret detection — fail loud, never silent +- ❌ Trusting agents to "know better" — enforce at multiple layers (prompt, hook, architecture) +- ❌ Writing secrets to "temporary" files in `.squad/` — Scribe commits ALL `.squad/` changes +- ❌ Extracting "just the host" from a connection string — still leaks infrastructure topology diff --git a/packages/squad-sdk/templates/skills/squad-conventions/SKILL.md b/packages/squad-sdk/templates/skills/squad-conventions/SKILL.md new file mode 100644 index 000000000..72eca68ed --- /dev/null +++ b/packages/squad-sdk/templates/skills/squad-conventions/SKILL.md @@ -0,0 +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`). diff --git a/test/docs-build.test.ts b/test/docs-build.test.ts index 2ff110dca..8fee82f68 100644 --- a/test/docs-build.test.ts +++ b/test/docs-build.test.ts @@ -17,7 +17,7 @@ const DIST_DIR = join(DOCS_DIR, 'dist'); // Expected content directories in src/content/docs/ const EXPECTED_GET_STARTED = ['installation', 'first-session']; -const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell']; +const EXPECTED_GUIDES = ['tips-and-tricks', 'sample-prompts', 'personal-squad', 'contributing', 'contributors', 'shell', 'faq']; const EXPECTED_REFERENCE = ['cli', 'sdk', 'config', 'api-reference', 'integration', 'tools-and-hooks'];