@bradygaster/squad-sdk 0.8.24 → 0.9.0

package/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=<set in .env>`
+- 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 <file>`
+   - 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

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

@@ -0,0 +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

package/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`).

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

@@ -0,0 +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

package/templates/skills/windows-compatibility/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: "windows-compatibility"
+description: "Cross-platform path handling and command patterns"
+domain: "platform"
+confidence: "high"
+source: "earned (multiple Windows-specific bugs: colons in filenames, git -C failures, path separators)"
+---
+
+## Context
+
+Squad runs on Windows, macOS, and Linux. Several bugs have been traced to platform-specific assumptions: ISO timestamps with colons (illegal on Windows), `git -C` with Windows paths (unreliable), forward-slash paths in Node.js on Windows.
+
+## Patterns
+
+### Filenames & Timestamps
+- **Never use colons in filenames:** ISO 8601 format `2026-03-15T05:30:00Z` is illegal on Windows
+- **Use `safeTimestamp()` utility:** Replaces colons with hyphens → `2026-03-15T05-30-00Z`
+- **Centralize formatting:** Don't inline `.toISOString().replace(/:/g, '-')` — use the utility
+
+### Git Commands
+- **Never use `git -C {path}`:** Unreliable with Windows paths (backslashes, spaces, drive letters)
+- **Always `cd` first:** Change directory, then run git commands
+- **Check for changes before commit:** `git diff --cached --quiet` (exit 0 = no changes)
+
+### Commit Messages
+- **Never embed newlines in `-m` flag:** Backtick-n (`\n`) fails silently in PowerShell
+- **Use temp file + `-F` flag:** Write message to file, commit with `git commit -F $msgFile`
+
+### Paths
+- **Never assume CWD is repo root:** Always use `TEAM ROOT` from spawn prompt or run `git rev-parse --show-toplevel`
+- **Use path.join() or path.resolve():** Don't manually concatenate with `/` or `\`
+
+## Examples
+
+✓ **Correct:**
+```javascript
+// Timestamp utility
+const safeTimestamp = () => new Date().toISOString().replace(/:/g, '-').split('.')[0] + 'Z';
+
+// Git workflow (PowerShell)
+cd $teamRoot
+git add .squad/
+if ($LASTEXITCODE -eq 0) {
+  $msg = @"
+docs(ai-team): session log
+
+Changes:
+- Added decisions
+"@
+  $msgFile = [System.IO.Path]::GetTempFileName()
+  Set-Content -Path $msgFile -Value $msg -Encoding utf8
+  git commit -F $msgFile
+  Remove-Item $msgFile
+}
+```
+
+✗ **Incorrect:**
+```javascript
+// Colon in filename
+const logPath = `.squad/log/${new Date().toISOString()}.md`; // ILLEGAL on Windows
+
+// git -C with Windows path
+exec('git -C C:\\src\\squad add .squad/'); // UNRELIABLE
+
+// Inline newlines in commit message
+exec('git commit -m "First line\nSecond line"'); // FAILS silently in PowerShell
+```
+
+## Anti-Patterns
+
+- Testing only on one platform (bugs ship to other platforms)
+- Assuming Unix-style paths work everywhere
+- Using `git -C` because it "looks cleaner" (it doesn't work)
+- Skipping `git diff --cached --quiet` check (creates empty commits)