القائمة
Pre-release validation, npm publish procedures, and post-publish verification
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
استنادا إلى تصنيف SOC المهني
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/bradygaster/squad --skill release-processيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
| 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 . The release pipeline flows: dev → preview → main → GitHub Release → npm publish. Brady (project owner) triggers releases — the coordinator does NOT.
@bradygaster/squad-clidev and main Share Ancestry BEFORE Starting Any Release-Prep WorkSource: 2026-08-13 orphaned-history incident, PR #1699.
dev's history was silently reset on 2026-07-13 (a dependabot bump became a brand-new root commit with zero shared history withmain). Nothing in normal release-prep work (version bump, CHANGELOG entry, changeset consolidation, CI) surfaces this —devbuilds and tests green the whole time because none of it touchesmain's history. The break is invisible until the very last step: opening thedev→mainpromotion PR, which GitHub then reports as flatly unmergeable, withgit merge-treerefusing outright and no reviewable diff.
Before touching version numbers or the CHANGELOG, run:
git merge-base upstream/dev upstream/main
If this returns a commit SHA (exit 0), proceed normally. If it returns nothing (exit 1), STOP. The promotion PR will be unmergeable no matter how clean dev's own release content is — fix ancestry first via a separate chore: restore shared ancestry PR (merge main into dev with --allow-unrelated-histories; do not rebase if dev has a non_fast_forward ruleset, since rebase requires a force-push and rewrites every commit under every open PR). See .squad/decisions/inbox/data-restore-dev-main-ancestry.md for the full worked example and the diff-based verification technique used to prove a dev-wins conflict resolution was safe.
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 |
dev and main silently drift to unrelated histories (2026-08-13) | dev → main promotion PR is flatly unmergeable, no reviewable diff | Run git merge-base upstream/dev upstream/main BEFORE starting release-prep; see Rule 0 above |
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)