Release Process

Squad Release Process

Read .squad/skills/release-process/SKILL.md for the canonical runbook and recovery commands. The operational model is:

There is no staging preview branch. Do not create tags or GitHub Releases manually.

Human release-trigger boundary: use the canonical runbook for exact commands. Agents may prepare, validate, and present commands, but agents must never execute or dispatch any live publication, promotion, or recovery workflow: squad-release.yml, squad-agents-ai-release.yml, squad-insider-publish.yml, squad-promote.yml with dry_run=false, squad-version-promote.yml, squad-npm-publish.yml, or squad-standalone-release.yml. Treat squad-promote.yml --ref dev -f dry_run=true as human-only too: it has actions: write and contents: write, checks out dev with the workflow token, installs dependencies, and runs build and test steps. Do not describe any GitHub Actions release workflow as agent-safe once it has write-capable credentials or a dispatch path. Only a human executes those triggers; human approval alone does not authorize an agent to fire them.

Preconditions

Before either channel:

git fetch origin dev main
git merge-base origin/dev origin/main
grep '"version"' package.json packages/squad-sdk/package.json packages/squad-cli/package.json
node -p "require('./packages/squad-cli/package.json').dependencies['@bradygaster/squad-sdk']"
grep -F "## [$VERSION]" CHANGELOG.md
SKIP_BUILD_BUMP=1 npm run build
npx vitest run

The validation build must not mutate package versions or the lockfile; check git diff -- package.json packages/squad-sdk/package.json packages/squad-cli/package.json package-lock.json afterward and stop if any version-only change appears.

The ancestry command must return a commit, all three versions must match, the CLI SDK dependency floor must be >=VERSION, and the changelog must contain the exact release version.

Required Actions secrets:

• NPM_TOKEN: automation-capable npm publish token.
• HOMEBREW_TAP_TOKEN: classic PAT with public_repo from a collaborator with write access to bradygaster/homebrew-squad.
• WINGET_CREATE_GITHUB_TOKEN: classic PAT with public_repo for tamirdresher/winget-pkgs.

Preview

After a PR sets an immutable prerelease version on dev and CI passes:

Human-only reference command: this live publish workflow must be run by a human. Agents must stop, hand off, and not execute it directly.

VERSION=0.14.0-preview.1
gh workflow run squad-release.yml --ref dev -f confirm_tag="v$VERSION"
gh run watch

The release workflow rejects stable versions on manual dispatch, creates a GitHub prerelease, publishes npm preview, and uploads standalone bundles. It also updates the squad-preview Homebrew cask and bradygaster.Squad.Preview WinGet package. The activation pin and insider-tag promotion remain stable-only.

Insider

Human-only reference command: this live publish workflow must be run by a human. Agents must stop, hand off, and not execute it directly.

gh workflow run squad-insider-publish.yml --ref dev -f dry_run=false
gh run watch

The workflow computes the next X.Y.Z-insider.N version, publishes npm insider, creates the GitHub prerelease and standalone archives, updates squad-insider in Homebrew, and opens or reuses the bradygaster.Squad.Insider WinGet PR.

Stable

After a PR replaces the preview version with X.Y.Z on dev and CI passes:

Human-only validation dispatch: this workflow still checks out dev with repo/workflow credentials and runs build and test logic. Agents must stop and hand off; only a human should fire it.

gh workflow run squad-promote.yml --ref dev -f dry_run=true
gh run watch

Human-only reference command: this live publish workflow must be run by a human. Agents must stop, hand off, and not execute it directly.

gh workflow run squad-promote.yml --ref dev -f dry_run=false
gh run watch

Promotion merges dev directly into main, strips internal team state, validates the release tree, builds it, runs tests, and pushes main. It then explicitly dispatches squad-release.yml because GITHUB_TOKEN pushes do not start another workflow. The release creates the tag and stable GitHub Release and directly invokes npm and standalone publication.

Verify

npm view @bradygaster/squad-sdk dist-tags.preview
npm view @bradygaster/squad-cli dist-tags.preview
npm view @bradygaster/squad-sdk dist-tags.latest
npm view @bradygaster/squad-cli dist-tags.latest
gh release view "v$VERSION"

Use the tag for the channel being released. Verify the GitHub Release contains all six OS/architecture archives and SHA256SUMS.txt. Every release must update its channel-specific Homebrew cask and create or reuse a WinGet PR.

Recovery

Do not recreate or overwrite the tag. Rerun a failed child job, or dispatch the reusable npm/standalone workflow with source_ref=v$VERSION. Use --ref dev for previews and --ref main for stable releases. The canonical runbook contains the exact commands.

After a stable release, prepare the next X.Y.Z-preview.1 version in a normal PR to dev.