@bradygaster/squad-sdk 0.9.0 → 0.9.1

package/templates/skills/ci-validation-gates/SKILL.md

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

package/templates/skills/cli-wiring/SKILL.md

@@ -1,47 +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/<name>.ts`
-   - Export a `run<Name>(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 === '<name>') {
-     const { run<Name> } = await import('./cli/commands/<name>.js');
-     // parse args, call function
-     await run<Name>(process.cwd(), options);
-     return;
-   }
-   ```
-
-3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`):
-   ```ts
-   console.log(`  ${BOLD}<name>${RESET}     <description>`);
-   console.log(`             Usage: <name> [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.
+# 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/<name>.ts`
+   - Export a `run<Name>(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 === '<name>') {
+     const { run<Name> } = await import('./cli/commands/<name>.js');
+     // parse args, call function
+     await run<Name>(process.cwd(), options);
+     return;
+   }
+   ```
+
+3. **Add help text** in the help section of `cli-entry.ts` (search for `Commands:`):
+   ```ts
+   console.log(`  ${BOLD}<name>${RESET}     <description>`);
+   console.log(`             Usage: <name> [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.

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

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