메뉴
Pre-release validation, npm publish procedures, and post-publish verification
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
{what this skill teaches agents}
{what this skill teaches agents}
{what this skill teaches agents}
{what this skill teaches agents}
Checklist and patterns for wiring new CLI commands into cli-entry.ts
Team initialization flow (Phase 1 proposal + Phase 2 creation)
| name | release-process |
| description | Pre-release validation, npm publish procedures, and post-publish verification |
| domain | release |
| confidence | high |
| source | earned |
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:
.github/skills/release-process/SKILL.mdfor the Copilot-facing runbook.
✅ THIS SKILL PRODUCES:
❌ THIS SKILL DOES NOT PRODUCE:
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.
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.
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.
Before ANY release is tagged, scan every packages/*/package.json for:
file: references (workspace leak — the v0.9.0 root cause)link: referencesCommand:
grep -r '"file:\|"link:\|"/' packages/*/package.json
If anything matches, STOP. Do not proceed. Fix the reference first.
npm -w for Publishingnpm -w packages/squad-sdk publish hangs silently when 2FA is enabled. Always cd into the package directory:
cd packages/squad-sdk && npm publish --access public
cd packages/squad-cli && npm publish --access public
If workflow_dispatch or the publish workflow fails:
After every publish, verify in a clean shell:
npm install -g @bradygaster/squad-cli@latest
squad --version # should match published version
squad doctor # should pass in a test repo
If the smoke test fails, rollback immediately.
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.
Never create draft GitHub Releases. The release: published event only fires when a release is published — drafts don't trigger the npm publish workflow.
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.
Set this environment variable in all CI build steps to prevent the build script from mutating versions during CI runs.
□ All tests passing on dev
□ No file:/link: references in packages/*/package.json
□ 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
□ Push dev → CI green
□ Promote dev → preview (squad-promote workflow)
□ Preview CI green (squad-preview validates)
□ Promote preview → main
□ squad-release auto-creates GitHub Release
□ 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
| Gotcha | Impact | Mitigation |
|---|---|---|
npm workspaces rewrite "*" → "file:../path" | Broken global installs | Preflight scan in CI (squad-npm-publish.yml) |
| GitHub Actions workflow cache (~15min TTL) | 422 on workflow_dispatch after file renames | Wait 15min or use local publish fallback |
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 |
Source: v0.9.4 release session. PRs #1042, #1043, #1044.
squad-release.yml reads version from ROOT package.json (lines 31-35):
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:
npm version $VERSION --workspaces --include-workspace-root --no-git-tag-version
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.
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:
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.
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.
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:
git checkout -- package.json packages/*/package.json
rm -rf node_modules packages/*/node_modules
npm install
npm run build
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
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.
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.
See .github/workflows/squad-ci.yml → publish-policy job for implementation details.
.squad/decisions/inbox/surgeon-v091-retrospective.md.squad/decisions/inbox/booster-ci-audit.md.github/skills/release-process/SKILL.mdPUBLISH-README.md (repo root)