@bradygaster/squad-sdk 0.9.0 → 0.9.1

package/templates/skills/session-recovery/SKILL.md

@@ -1,155 +1,155 @@
----
-name: "session-recovery"
-description: "Find and resume interrupted Copilot CLI sessions using session_store queries"
-domain: "workflow-recovery"
-confidence: "high"
-source: "earned"
-tools:
-  - name: "sql"
-    description: "Query session_store database for past session history"
-    when: "Always — session_store is the source of truth for session history"
----
-
-## Context
-
-Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized.
-
-Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work.
-
-## Patterns
-
-### 1. Find Recent Sessions
-
-Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped:
-
-```sql
-SELECT
-  s.id,
-  s.summary,
-  s.cwd,
-  s.branch,
-  s.updated_at,
-  (SELECT title FROM checkpoints
-   WHERE session_id = s.id
-   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
-FROM sessions s
-WHERE s.updated_at >= datetime('now', '-24 hours')
-ORDER BY s.updated_at DESC;
-```
-
-### 2. Filter Out Automated Sessions
-
-Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them:
-
-```sql
-SELECT s.id, s.summary, s.cwd, s.updated_at,
-  (SELECT title FROM checkpoints
-   WHERE session_id = s.id
-   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
-FROM sessions s
-WHERE s.updated_at >= datetime('now', '-24 hours')
-  AND s.id NOT IN (
-    SELECT DISTINCT t.session_id FROM turns t
-    WHERE t.turn_index = 0
-      AND (LOWER(t.user_message) LIKE '%keep-alive%'
-           OR LOWER(t.user_message) LIKE '%heartbeat%')
-  )
-ORDER BY s.updated_at DESC;
-```
-
-### 3. Search by Topic (FTS5)
-
-Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic:
-
-```sql
-SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at
-FROM search_index si
-JOIN sessions s ON si.session_id = s.id
-WHERE search_index MATCH 'auth OR login OR token OR JWT'
-  AND s.updated_at >= datetime('now', '-48 hours')
-ORDER BY s.updated_at DESC
-LIMIT 10;
-```
-
-### 4. Search by Working Directory
-
-```sql
-SELECT s.id, s.summary, s.updated_at,
-  (SELECT title FROM checkpoints
-   WHERE session_id = s.id
-   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
-FROM sessions s
-WHERE s.cwd LIKE '%my-project%'
-  AND s.updated_at >= datetime('now', '-48 hours')
-ORDER BY s.updated_at DESC;
-```
-
-### 5. Get Full Session Context Before Resuming
-
-Before resuming, inspect what the session was doing:
-
-```sql
--- Conversation turns
-SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp
-FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index;
-
--- Checkpoint progress
-SELECT checkpoint_number, title, overview
-FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number;
-
--- Files touched
-SELECT file_path, tool_name
-FROM session_files WHERE session_id = 'SESSION_ID';
-
--- Linked PRs/issues/commits
-SELECT ref_type, ref_value
-FROM session_refs WHERE session_id = 'SESSION_ID';
-```
-
-### 6. Detect Orphaned Issue Work
-
-Find sessions that were working on issues but may not have completed:
-
-```sql
-SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at,
-  sr.ref_type, sr.ref_value
-FROM sessions s
-JOIN session_refs sr ON s.id = sr.session_id
-WHERE sr.ref_type = 'issue'
-  AND s.updated_at >= datetime('now', '-48 hours')
-ORDER BY s.updated_at DESC;
-```
-
-Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session.
-
-### 7. Resume a Session
-
-Once you have the session ID:
-
-```bash
-# Resume directly
-copilot --resume SESSION_ID
-```
-
-## Examples
-
-**Recovering from a crash during PR creation:**
-1. Query recent sessions filtered by branch name
-2. Find the session that was working on the PR
-3. Check its last checkpoint — was the code committed? Was the PR created?
-4. Resume or manually complete the remaining steps
-
-**Finding yesterday's work on a feature:**
-1. Use FTS5 search with feature keywords
-2. Filter to the relevant working directory
-3. Review checkpoint progress to see how far the session got
-4. Resume if work remains, or start fresh with the context
-
-## Anti-Patterns
-
-- ❌ Searching by partial session IDs — always use full UUIDs
-- ❌ Resuming sessions that completed successfully — they have no pending work
-- ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes
-- ❌ Skipping the automated-session filter — high-volume automated sessions will flood results
-- ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms
-- ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped
+---
+name: "session-recovery"
+description: "Find and resume interrupted Copilot CLI sessions using session_store queries"
+domain: "workflow-recovery"
+confidence: "high"
+source: "earned"
+tools:
+  - name: "sql"
+    description: "Query session_store database for past session history"
+    when: "Always — session_store is the source of truth for session history"
+---
+
+## Context
+
+Squad agents run in Copilot CLI sessions that can be interrupted — terminal crashes, network drops, machine restarts, or accidental window closes. When this happens, in-progress work may be left in a partially-completed state: branches with uncommitted changes, issues marked in-progress with no active agent, or checkpoints that were never finalized.
+
+Copilot CLI stores session history in a SQLite database called `session_store` (read-only, accessed via the `sql` tool with `database: "session_store"`). This skill teaches agents how to query that store to detect interrupted sessions and resume work.
+
+## Patterns
+
+### 1. Find Recent Sessions
+
+Query the `sessions` table filtered by time window. Include the last checkpoint to understand where the session stopped:
+
+```sql
+SELECT
+  s.id,
+  s.summary,
+  s.cwd,
+  s.branch,
+  s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.updated_at >= datetime('now', '-24 hours')
+ORDER BY s.updated_at DESC;
+```
+
+### 2. Filter Out Automated Sessions
+
+Automated agents (monitors, keep-alive, heartbeat) create high-volume sessions that obscure human-initiated work. Exclude them:
+
+```sql
+SELECT s.id, s.summary, s.cwd, s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.updated_at >= datetime('now', '-24 hours')
+  AND s.id NOT IN (
+    SELECT DISTINCT t.session_id FROM turns t
+    WHERE t.turn_index = 0
+      AND (LOWER(t.user_message) LIKE '%keep-alive%'
+           OR LOWER(t.user_message) LIKE '%heartbeat%')
+  )
+ORDER BY s.updated_at DESC;
+```
+
+### 3. Search by Topic (FTS5)
+
+Use the `search_index` FTS5 table for keyword search. Expand queries with synonyms since this is keyword-based, not semantic:
+
+```sql
+SELECT DISTINCT s.id, s.summary, s.cwd, s.updated_at
+FROM search_index si
+JOIN sessions s ON si.session_id = s.id
+WHERE search_index MATCH 'auth OR login OR token OR JWT'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC
+LIMIT 10;
+```
+
+### 4. Search by Working Directory
+
+```sql
+SELECT s.id, s.summary, s.updated_at,
+  (SELECT title FROM checkpoints
+   WHERE session_id = s.id
+   ORDER BY checkpoint_number DESC LIMIT 1) AS last_checkpoint
+FROM sessions s
+WHERE s.cwd LIKE '%my-project%'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC;
+```
+
+### 5. Get Full Session Context Before Resuming
+
+Before resuming, inspect what the session was doing:
+
+```sql
+-- Conversation turns
+SELECT turn_index, substr(user_message, 1, 200) AS ask, timestamp
+FROM turns WHERE session_id = 'SESSION_ID' ORDER BY turn_index;
+
+-- Checkpoint progress
+SELECT checkpoint_number, title, overview
+FROM checkpoints WHERE session_id = 'SESSION_ID' ORDER BY checkpoint_number;
+
+-- Files touched
+SELECT file_path, tool_name
+FROM session_files WHERE session_id = 'SESSION_ID';
+
+-- Linked PRs/issues/commits
+SELECT ref_type, ref_value
+FROM session_refs WHERE session_id = 'SESSION_ID';
+```
+
+### 6. Detect Orphaned Issue Work
+
+Find sessions that were working on issues but may not have completed:
+
+```sql
+SELECT DISTINCT s.id, s.branch, s.summary, s.updated_at,
+  sr.ref_type, sr.ref_value
+FROM sessions s
+JOIN session_refs sr ON s.id = sr.session_id
+WHERE sr.ref_type = 'issue'
+  AND s.updated_at >= datetime('now', '-48 hours')
+ORDER BY s.updated_at DESC;
+```
+
+Cross-reference with `gh issue list --label "status:in-progress"` to find issues that are marked in-progress but have no active session.
+
+### 7. Resume a Session
+
+Once you have the session ID:
+
+```bash
+# Resume directly
+copilot --resume SESSION_ID
+```
+
+## Examples
+
+**Recovering from a crash during PR creation:**
+1. Query recent sessions filtered by branch name
+2. Find the session that was working on the PR
+3. Check its last checkpoint — was the code committed? Was the PR created?
+4. Resume or manually complete the remaining steps
+
+**Finding yesterday's work on a feature:**
+1. Use FTS5 search with feature keywords
+2. Filter to the relevant working directory
+3. Review checkpoint progress to see how far the session got
+4. Resume if work remains, or start fresh with the context
+
+## Anti-Patterns
+
+- ❌ Searching by partial session IDs — always use full UUIDs
+- ❌ Resuming sessions that completed successfully — they have no pending work
+- ❌ Using `MATCH` with special characters without escaping — wrap paths in double quotes
+- ❌ Skipping the automated-session filter — high-volume automated sessions will flood results
+- ❌ Assuming FTS5 is semantic search — it's keyword-based; always expand queries with synonyms
+- ❌ Ignoring checkpoint data — checkpoints show exactly where the session stopped

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

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

package/templates/skills/test-discipline/SKILL.md

@@ -1,37 +1,37 @@
----
-name: "test-discipline"
-description: "Update tests when changing APIs — no exceptions"
-domain: "quality"
-confidence: "high"
-source: "earned (Fenster/Hockney incident, test assertion sync violations)"
----
-
-## Context
-
-When APIs or public interfaces change, tests must be updated in the same commit. When test assertions reference file counts or expected arrays, they must be kept in sync with disk reality. Stale tests block CI for other contributors.
-
-## Patterns
-
-- **API changes → test updates (same commit):** If you change a function signature, public interface, or exported API, update the corresponding tests before committing
-- **Test assertions → disk reality:** When test files contain expected counts (e.g., `EXPECTED_FEATURES`, `EXPECTED_SCENARIOS`), they must match the actual files on disk
-- **Add files → update assertions:** When adding docs pages, features, or any counted resource, update the test assertion array in the same commit
-- **CI failures → check assertions first:** Before debugging complex failures, verify test assertion arrays match filesystem state
-
-## Examples
-
-✓ **Correct:**
-- Changed auth API signature → updated auth.test.ts in same commit
-- Added `distributed-mesh.md` to features/ → added `'distributed-mesh'` to EXPECTED_FEATURES array
-- Deleted two scenario files → removed entries from EXPECTED_SCENARIOS
-
-✗ **Incorrect:**
-- Changed spawn parameters → committed without updating casting.test.ts (CI breaks for next person)
-- Added `built-in-roles.md` → left EXPECTED_FEATURES at old count (PR blocked)
-- Test says "expected 7 files" but disk has 25 (assertion staleness)
-
-## Anti-Patterns
-
-- Committing API changes without test updates ("I'll fix tests later")
-- Treating test assertion arrays as static (they evolve with content)
-- Assuming CI passing means coverage is correct (stale assertions can pass while being wrong)
-- Leaving gaps for other agents to discover
+---
+name: "test-discipline"
+description: "Update tests when changing APIs — no exceptions"
+domain: "quality"
+confidence: "high"
+source: "earned (Fenster/Hockney incident, test assertion sync violations)"
+---
+
+## Context
+
+When APIs or public interfaces change, tests must be updated in the same commit. When test assertions reference file counts or expected arrays, they must be kept in sync with disk reality. Stale tests block CI for other contributors.
+
+## Patterns
+
+- **API changes → test updates (same commit):** If you change a function signature, public interface, or exported API, update the corresponding tests before committing
+- **Test assertions → disk reality:** When test files contain expected counts (e.g., `EXPECTED_FEATURES`, `EXPECTED_SCENARIOS`), they must match the actual files on disk
+- **Add files → update assertions:** When adding docs pages, features, or any counted resource, update the test assertion array in the same commit
+- **CI failures → check assertions first:** Before debugging complex failures, verify test assertion arrays match filesystem state
+
+## Examples
+
+✓ **Correct:**
+- Changed auth API signature → updated auth.test.ts in same commit
+- Added `distributed-mesh.md` to features/ → added `'distributed-mesh'` to EXPECTED_FEATURES array
+- Deleted two scenario files → removed entries from EXPECTED_SCENARIOS
+
+✗ **Incorrect:**
+- Changed spawn parameters → committed without updating casting.test.ts (CI breaks for next person)
+- Added `built-in-roles.md` → left EXPECTED_FEATURES at old count (PR blocked)
+- Test says "expected 7 files" but disk has 25 (assertion staleness)
+
+## Anti-Patterns
+
+- Committing API changes without test updates ("I'll fix tests later")
+- Treating test assertion arrays as static (they evolve with content)
+- Assuming CI passing means coverage is correct (stale assertions can pass while being wrong)
+- Leaving gaps for other agents to discover