@bradygaster/squad-sdk 0.8.25 → 0.9.1

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

@@ -0,0 +1,57 @@
+# Personal Squad — Skill Document
+
+## What is a Personal Squad?
+
+A personal squad is a user-level collection of AI agents that travel with you across projects. Unlike project agents (defined in a project's `.squad/` directory), personal agents live in your global config directory and are automatically discovered when you start a squad session.
+
+## Directory Structure
+
+```
+~/.config/squad/personal-squad/    # Linux/macOS
+%APPDATA%/squad/personal-squad/    # Windows
+├── agents/
+│   ├── {agent-name}/
+│   │   ├── charter.md
+│   │   └── history.md
+│   └── ...
+└── config.json                    # Optional: personal squad config
+```
+
+## How It Works
+
+1. **Ambient Discovery:** When Squad starts a session, it checks for a personal squad directory
+2. **Merge:** Personal agents are merged into the session cast alongside project agents
+3. **Ghost Protocol:** Personal agents can read project state but not write to it
+4. **Kill Switch:** Set `SQUAD_NO_PERSONAL=1` to disable ambient discovery
+
+## Commands
+
+- `squad personal init` — Bootstrap a personal squad directory
+- `squad personal list` — List your personal agents
+- `squad personal add {name} --role {role}` — Add a personal agent
+- `squad personal remove {name}` — Remove a personal agent
+- `squad cast` — Show the current session cast (project + personal)
+
+## Ghost Protocol
+
+See `templates/ghost-protocol.md` for the full rules. Key points:
+- Personal agents advise; project agents execute
+- No writes to project `.squad/` state
+- Transparent origin tagging in logs
+- Project agents take precedence on conflicts
+
+## Configuration
+
+Optional `config.json` in the personal squad directory:
+```json
+{
+  "defaultModel": "auto",
+  "ghostProtocol": true,
+  "agents": {}
+}
+```
+
+## Environment Variables
+
+- `SQUAD_NO_PERSONAL` — Set to any value to disable personal squad discovery
+- `SQUAD_PERSONAL_DIR` — Override the default personal squad directory path

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

@@ -1,56 +1,56 @@
----
-name: "project-conventions"
-description: "Core conventions and patterns for this codebase"
-domain: "project-conventions"
-confidence: "medium"
-source: "template"
----
-
-## Context
-
-> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality.
-
-## Patterns
-
-### [Pattern Name]
-
-Describe a key convention or practice used in this codebase. Be specific about what to do and why.
-
-### Error Handling
-
-<!-- Example: How does your project handle errors? -->
-<!-- - Use try/catch with specific error types? -->
-<!-- - Log to a specific service? -->
-<!-- - Return error objects vs throwing? -->
-
-### Testing
-
-<!-- Example: What test framework? Where do tests live? How to run them? -->
-<!-- - Test framework: Jest/Vitest/node:test/etc. -->
-<!-- - Test location: test/, __tests__/, *.test.ts, etc. -->
-<!-- - Run command: npm test, etc. -->
-
-### Code Style
-
-<!-- Example: Linting, formatting, naming conventions -->
-<!-- - Linter: ESLint config? -->
-<!-- - Formatter: Prettier? -->
-<!-- - Naming: camelCase, snake_case, etc.? -->
-
-### File Structure
-
-<!-- Example: How is the project organized? -->
-<!-- - src/ — Source code -->
-<!-- - test/ — Tests -->
-<!-- - docs/ — Documentation -->
-
-## Examples
-
-```
-// Add code examples that demonstrate your conventions
-```
-
-## Anti-Patterns
-
-<!-- List things to avoid in this codebase -->
-- **[Anti-pattern]** — Explanation of what not to do and why.
+---
+name: "project-conventions"
+description: "Core conventions and patterns for this codebase"
+domain: "project-conventions"
+confidence: "medium"
+source: "template"
+---
+
+## Context
+
+> **This is a starter template.** Replace the placeholder patterns below with your actual project conventions. Skills train agents on codebase-specific practices — accurate documentation here improves agent output quality.
+
+## Patterns
+
+### [Pattern Name]
+
+Describe a key convention or practice used in this codebase. Be specific about what to do and why.
+
+### Error Handling
+
+<!-- Example: How does your project handle errors? -->
+<!-- - Use try/catch with specific error types? -->
+<!-- - Log to a specific service? -->
+<!-- - Return error objects vs throwing? -->
+
+### Testing
+
+<!-- Example: What test framework? Where do tests live? How to run them? -->
+<!-- - Test framework: Jest/Vitest/node:test/etc. -->
+<!-- - Test location: test/, __tests__/, *.test.ts, etc. -->
+<!-- - Run command: npm test, etc. -->
+
+### Code Style
+
+<!-- Example: Linting, formatting, naming conventions -->
+<!-- - Linter: ESLint config? -->
+<!-- - Formatter: Prettier? -->
+<!-- - Naming: camelCase, snake_case, etc.? -->
+
+### File Structure
+
+<!-- Example: How is the project organized? -->
+<!-- - src/ — Source code -->
+<!-- - test/ — Tests -->
+<!-- - docs/ — Documentation -->
+
+## Examples
+
+```
+// Add code examples that demonstrate your conventions
+```
+
+## Anti-Patterns
+
+<!-- List things to avoid in this codebase -->
+- **[Anti-pattern]** — Explanation of what not to do and why.

package/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.**

package/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