@bradygaster/squad-sdk 0.8.25 → 0.9.0

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

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