bradygaster · May 1, 2026 · Apr 25, 2026
@@ -1,3 +1,11 @@
+---
+name: "cli-wiring"
+description: "Checklist and patterns for wiring new CLI commands into cli-entry.ts"
+domain: "cli"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: CLI Command Wiring
 
 **Bug class:** Commands implemented in `packages/squad-cli/src/cli/commands/` but never routed in `cli-entry.ts`.

@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state

@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  

@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.

@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?

@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring

@@ -1,3 +1,11 @@
+---
+name: "release-process"
+description: "Pre-release validation, npm publish procedures, and post-publish verification"
+domain: "release"
+confidence: "high"
+source: "earned"
+---
+
 # Release Process
 
 > Earned knowledge from the v0.9.0→v0.9.1 and v0.9.4 incidents. Every agent involved in releases MUST read this before starting release work.

@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  

@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.

@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state

@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?

@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring

@@ -1,6 +1,15 @@
+---
+name: "release-process"
+description: "Pre-release validation, npm publish procedures, and post-publish verification"
+domain: "release"
+confidence: "high"
+source: "earned"
+---
+
 # Release Process
 
-> Earned knowledge from the v0.9.0→v0.9.1 incident. Every agent involved in releases MUST read this before starting release work.
+> Earned knowledge from the v0.9.0→v0.9.1 and v0.9.4 incidents. Every agent involved in releases MUST read this before starting release work.
+> See also: `.copilot/skills/release-process/SKILL.md` for the Copilot-facing runbook.
 
 ## SCOPE
 
@@ -17,7 +26,7 @@
 
 ## Confidence: high
 
-Established through the v0.9.1 incident (8-hour recovery). Every rule below is battle-tested.
+Established through the v0.9.1 incident (8-hour recovery) and reinforced by the v0.9.4 release delay (PRs #1042, #1043, #1044). Every rule below is battle-tested.
 
 ## Context
 
@@ -92,8 +101,9 @@ Set this environment variable in all CI build steps to prevent the build script
 ```
 □ All tests passing on dev
 □ No file:/link: references in packages/*/package.json
-□ CHANGELOG.md updated
-□ Version bumps committed (node -e script)
+□ Root package.json version matches sub-packages (v0.9.4 lesson — PR #1043)
+□ CHANGELOG.md has ## [$VERSION] section (not just [Unreleased]) (v0.9.4 lesson — PR #1042)
+□ Version bumps committed: npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
 □ npm auth verified (Automation token)
 □ No draft GitHub Releases pending
 □ Local build + test: npm run build && npx vitest run
@@ -102,7 +112,8 @@ Set this environment variable in all CI build steps to prevent the build script
 □ Preview CI green (squad-preview validates)
 □ Promote preview → main
 □ squad-release auto-creates GitHub Release
-□ squad-npm-publish auto-triggers
+□ squad-npm-publish auto-triggers (⚠️ may be BLOCKED — see GITHUB_TOKEN limitation below)
+□ If publish didn't trigger: gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
 □ Monitor publish workflow
 □ Post-publish smoke test
 ```
@@ -116,6 +127,79 @@ Set this environment variable in all CI build steps to prevent the build script
 | `npm -w publish` hangs with 2FA | Silent hang, no error | Never use `-w` for publish |
 | Draft GitHub Releases | npm publish workflow doesn't trigger | Never create drafts |
 | User npm tokens with 2FA | EOTP errors in CI | Use Automation token type |
+| Root package.json version drift (v0.9.4) | squad-release.yml fails CHANGELOG check | Always bump all 3 package.json files together (PR #1043) |
+| CHANGELOG.md missing `## [$VERSION]` (v0.9.4) | squad-release.yml exits with error | Convert `[Unreleased]` → `[$VERSION] - YYYY-MM-DD` before promoting to main (PR #1042) |
+| GITHUB_TOKEN can't trigger downstream workflows (v0.9.4) | squad-npm-publish.yml never fires | Manual `gh workflow run` or use PAT/GitHub App token (see below) |
+| Lockfile integrity check rejects workspace packages (v0.9.4) | False failures in squad-npm-publish.yml | Only validate packages resolved from npm registry (`startsWith('https://')`) (PR #1044) |
+| `prebuild` version bump breaks workspace linking (v0.9.4) | Local builds fail after bump-build.mjs runs | `git checkout -- package.json packages/*/package.json` then fresh install |
+
+## v0.9.4 Incident Learnings
+
+> Source: v0.9.4 release session. PRs #1042, #1043, #1044.
+
+### Root Package.json Version Must Match Sub-Packages
+
+`squad-release.yml` reads version from ROOT `package.json` (lines 31-35):
+```bash
+VERSION=$(node -e "console.log(require('./package.json').version)")
+if ! grep -q "## \[$VERSION\]" CHANGELOG.md; then
+  echo "::error::Version $VERSION not found in CHANGELOG.md"
+  exit 1
+fi
+```
+If root package.json is behind (e.g., 0.9.1 while sub-packages are 0.9.4), the release workflow FAILS. This was the root cause of the v0.9.4 release delay — PR #1043 fixed it.
+
+**Rule:** When bumping versions, ALWAYS bump all 3 package.json files together:
+```bash
+npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
+```
+
+### CHANGELOG.md Must Have Version Entry
+
+`squad-release.yml` validates that `CHANGELOG.md` contains `## [$VERSION]`. If the version section is still `[Unreleased]` and no `[$VERSION]` section exists, the release workflow exits with error. PR #1042 fixed this for v0.9.4.
+
+**Rule:** Before promoting to main, convert `[Unreleased]` to `[$VERSION] - YYYY-MM-DD` in CHANGELOG.md and add a fresh `[Unreleased]` section above it.
+
+### GITHUB_TOKEN Event Propagation Limitation (CRITICAL)
+
+When `squad-release.yml` creates a GitHub Release using the default `GITHUB_TOKEN`, the `release: published` event does NOT trigger `squad-npm-publish.yml`. This is a GitHub security feature to prevent infinite workflow loops.
+
+**Workaround:** After the release workflow succeeds and creates the tag + GitHub Release, manually trigger the publish workflow:
+```bash
+gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+IMPORTANT: Use `--ref main` to ensure the workflow runs against the main branch (where the release artifacts exist).
+
+**Permanent fix (TODO):** Use a PAT or GitHub App token in `squad-release.yml` instead of `GITHUB_TOKEN`.
+
+### Lockfile Integrity — Workspace Package Handling
+
+The lockfile stability check in `squad-npm-publish.yml` (line 82) filters packages for integrity hashes. Workspace packages resolve to bare relative paths (e.g., `packages/squad-sdk`), NOT `file:` URLs. The check must filter for registry-resolved packages only (`startsWith('https://')`). PR #1044 fixed this.
+
+### Prebuild Version Bump Breaks Local Workspace Resolution
+
+`scripts/bump-build.mjs` runs during `npm run prebuild` and bumps versions like `0.9.4` → `0.9.4-build.1`. This breaks workspace linking because CLI depends on exact `"@bradygaster/squad-sdk": "0.9.4"` but SDK becomes `0.9.4-build.1`.
+
+**Fix for local dev:**
+```bash
+git checkout -- package.json packages/*/package.json
+rm -rf node_modules packages/*/node_modules
+npm install
+npm run build
+```
+
+### The Full Promotion Chain (v0.9.4 Documented)
+
+```
+dev → preview → main (via squad-promote.yml)
+main push → squad-release.yml validates CHANGELOG, creates tag + GitHub Release
+release published → squad-npm-publish.yml (⚠️ BLOCKED by GITHUB_TOKEN limitation)
+manual workaround → gh workflow run squad-npm-publish.yml --ref main -f version=X.Y.Z
+```
+
+### npm Publish Workflow Dispatch Target
+
+When using `workflow_dispatch` to trigger `squad-npm-publish.yml`, the default ref is the repo's default branch (`dev`). Always specify `--ref main` explicitly to ensure the workflow runs against the branch with the release tag and latest workflow fixes.
 
 ## CI Gate: Workspace Publish Policy
 
@@ -126,6 +210,8 @@ See `.github/workflows/squad-ci.yml` → `publish-policy` job for implementation
 ## Related
 
 - Issues: #556–#564 (release:next)
+- v0.9.4 fixes: PR #1042 (CHANGELOG), PR #1043 (root package.json), PR #1044 (lockfile integrity)
 - Retro: `.squad/decisions/inbox/surgeon-v091-retrospective.md`
 - CI audit: `.squad/decisions/inbox/booster-ci-audit.md`
+- Copilot-level skill: `.copilot/skills/release-process/SKILL.md`
 - Playbook: `PUBLISH-README.md` (repo root)
@@ -1,3 +1,11 @@
+---
+name: "cross-machine-coordination"
+description: "Enables squad agents on different machines to share work via git-based task queuing"
+domain: "orchestration"
+confidence: "medium"
+source: "manual"
+---
+
 # Skill: Cross-Machine Coordination Pattern
 
 **Skill ID:** `cross-machine-coordination`  

@@ -1,3 +1,11 @@
+---
+name: "model-selection"
+description: "Determines which LLM model to use for each agent spawn"
+domain: "orchestration"
+confidence: "medium"
+source: "extracted"
+---
+
 # Model Selection
 
 > Determines which LLM model to use for each agent spawn.

@@ -1,3 +1,11 @@
+---
+name: "nap"
+description: "Context hygiene — compress, prune, archive .squad/ state"
+domain: "maintenance"
+confidence: "medium"
+source: "extracted"
+---
+
 # Skill: nap
 
 > Context hygiene — compress, prune, archive .squad/ state

@@ -1,3 +1,11 @@
+---
+name: "personal-squad"
+description: "User-level AI agents that travel with you across projects"
+domain: "configuration"
+confidence: "medium"
+source: "manual"
+---
+
 # Personal Squad — Skill Document
 
 ## What is a Personal Squad?

@@ -1,3 +1,11 @@
+---
+name: "ralph-two-pass-scan"
+description: "Cuts GitHub API calls by separating lightweight list scanning from full hydration"
+domain: "work-monitoring"
+confidence: "high"
+source: "extracted"
+---
+
 # Skill: Ralph — Two-Pass Issue Scanning
 **Confidence:** high
 **Domain:** work-monitoring