| 1 | # Release Process |
| 2 | |
| 3 | > Earned knowledge from the v0.9.0→v0.9.1 incident. Every agent involved in releases MUST read this before starting release work. |
| 4 | |
| 5 | ## SCOPE |
| 6 | |
| 7 | ✅ THIS SKILL PRODUCES: |
| 8 | - Pre-release validation checks that prevent broken publishes |
| 9 | - Correct npm publish commands (never workspace-scoped) |
| 10 | - Fallback procedures when CI workflows fail |
| 11 | - Post-publish verification steps |
| 12 | |
| 13 | ❌ THIS SKILL DOES NOT PRODUCE: |
| 14 | - Feature implementation or test code |
| 15 | - Architecture decisions |
| 16 | - Documentation content |
| 17 | |
| 18 | ## Confidence: high |
| 19 | |
| 20 | Established through the v0.9.1 incident (8-hour recovery). Every rule below is battle-tested. |
| 21 | |
| 22 | ## Context |
| 23 | |
| 24 | Squad publishes two npm packages: `@bradygaster/squad-sdk` and `@bradygaster/squad-cli`. The release pipeline flows: dev → preview → main → GitHub Release → npm publish. Brady (project owner) triggers releases — the coordinator does NOT. |
| 25 | |
| 26 | ## Rules (Non-Negotiable) |
| 27 | |
| 28 | ### 1. Coordinator Does NOT Publish |
| 29 | |
| 30 | The coordinator routes work and manages agents. It does NOT run `npm publish`, trigger release workflows, or make release decisions. Brady owns the release trigger. If an agent or the coordinator is asked to publish, escalate to Brady. |
| 31 | |
| 32 | ### 2. Pre-Publish Dependency Validation |
| 33 | |
| 34 | Before ANY release is tagged, scan every `packages/*/package.json` for: |
| 35 | - `file:` references (workspace leak — the v0.9.0 root cause) |
| 36 | - `link:` references |
| 37 | - Absolute paths in dependency values |
| 38 | - Non-semver version strings |
| 39 | |
| 40 | **Command:** |
| 41 | ```bash |
| 42 | grep -r '"file:\|"link:\|"/' packages/*/package.json |
| 43 | ``` |
| 44 | If anything matches, STOP. Do not proceed. Fix the reference first. |
| 45 | |
| 46 | ### 3. Never Use `npm -w` for Publishing |
| 47 | |
| 48 | `npm -w packages/squad-sdk publish` hangs silently when 2FA is enabled. Always `cd` into the package directory: |
| 49 | |
| 50 | ```bash |
| 51 | cd packages/squad-sdk && npm publish --access public |
| 52 | cd packages/squad-cli && npm publish --access public |
| 53 | ``` |
| 54 | |
| 55 | ### 4. Fallback Protocol |
| 56 | |
| 57 | If `workflow_dispatch` or the publish workflow fails: |
| 58 | 1. Try once more (ONE retry, not four) |
| 59 | 2. If it fails again → local publish immediately |
| 60 | 3. Do NOT attempt GitHub UI file operations to fix workflow indexing |
| 61 | 4. GitHub has a ~15min workflow cache TTL after file renames/deletes — waiting helps, retrying doesn't |
| 62 | |
| 63 | ### 5. Post-Publish Smoke Test |
| 64 | |
| 65 | After every publish, verify in a clean shell: |
| 66 | ```bash |
| 67 | npm install -g @bradygaster/squad-cli@latest |
| 68 | squad --version # should match published version |
| 69 | squad doctor # should pass in a test repo |
| 70 | ``` |
| 71 | |
| 72 | If the smoke test fails, rollback immediately. |
| 73 | |
| 74 | ### 6. npm Token Must Be Automation Type |
| 75 | |
| 76 | NPM_TOKEN in CI must be an Automation token (not a user token with 2FA prompts). User tokens with `auth-and-writes` 2FA cause silent hangs in non-interactive environments. |
| 77 | |
| 78 | ### 7. No Draft GitHub Releases |
| 79 | |
| 80 | Never create draft GitHub Releases. The `release: published` event only fires when a release is published — drafts don't trigger the npm publish workflow. |
| 81 | |
| 82 | ### 8. Version Format |
| 83 | |
| 84 | Semantic versioning only: `MAJOR.MINOR.PATCH` (e.g., `0.9.1`). Four-part versions like `0.8.21.4` are NOT valid semver and will break npm publish. |
| 85 | |
| 86 | ### 9. SKIP_BUILD_BUMP=1 in CI |
| 87 | |
| 88 | Set this environment variable in all CI build steps to prevent the build script from mutating versions during CI runs. |
| 89 | |
| 90 | ## Release Checklist (Quick Reference) |
| 91 | |
| 92 | ``` |
| 93 | □ All tests passing on dev |
| 94 | □ No file:/link: references in packages/*/package.json |
| 95 | □ CHANGELOG.md updated |
| 96 | □ Version bumps committed (node -e script) |
| 97 | □ npm auth verified (Automation token) |
| 98 | □ No draft GitHub Releases pending |
| 99 | □ Local build + test: npm run build && npx vitest run |
| 100 | □ Push dev → CI green |
| 101 | □ Promote dev → preview (squad-promote workflow) |
| 102 | □ Preview CI green (squad-preview validates) |
| 103 | □ Promote preview → main |
| 104 | □ squad-release auto-creates GitHub Release |
| 105 | □ squad-npm-publish auto-triggers |
| 106 | □ Monitor publish workflow |
| 107 | □ Post-publish smoke test |
| 108 | ``` |
| 109 | |
| 110 | ## Known Gotchas |
| 111 | |
| 112 | | Gotcha | Impact | Mitigation | |
| 113 | |--------|--------|------------| |
| 114 | | npm workspaces rewrite `"*"` → `"file:../path"` | Broken global installs | Preflight scan in CI (squad-npm-publish.yml) | |
| 115 | | GitHub Actions workflow cache (~15min TTL) | 422 on workflow_dispatch after file renames | Wait 15min or use local publish fallback | |
| 116 | | `npm -w publish` hangs with 2FA | Silent hang, no error | Never use `-w` for publish | |
| 117 | | Draft GitHub Releases | npm publish workflow doesn't trigger | Never create drafts | |
| 118 | | User npm tokens with 2FA | EOTP errors in CI | Use Automation token type | |
| 119 | |
| 120 | ## CI Gate: Workspace Publish Policy |
| 121 | |
| 122 | The `publish-policy` job in `squad-ci.yml` scans all workflow files for bare `npm publish` commands that are missing `-w`/`--workspace` flags. Any workflow that attempts a non-workspace-scoped publish will fail CI. This prevents accidental root-level publishes that would push the wrong `package.json` to npm. |
| 123 | |
| 124 | See `.github/workflows/squad-ci.yml` → `publish-policy` job for implementation details. |
| 125 | |
| 126 | ## Related |
| 127 | |
| 128 | - Issues: #556–#564 (release:next) |
| 129 | - Retro: `.squad/decisions/inbox/surgeon-v091-retrospective.md` |
| 130 | - CI audit: `.squad/decisions/inbox/booster-ci-audit.md` |
| 131 | - Playbook: `PUBLISH-README.md` (repo root) |