CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

release-process

Operate Squad's automated insider, preview, and stable release channels safely

Quality

74%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./.copilot/skills/release-process/SKILL.md
SKILL.md
Quality
Evals
Security

Squad Release Process

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

ReleaseTriggerRequired versionResult
InsiderManual squad-insider-publish.yml dispatch from devGenerated X.Y.Z-insider.NGitHub prerelease, npm insider, standalone archives, Homebrew, WinGet
PreviewManual squad-release.yml dispatch from devX.Y.Z-preview.NGitHub prerelease, npm preview, standalone archives, Homebrew, WinGet
StableManual squad-promote.yml dispatch from devX.Y.ZSanitized promotion PR or legacy main push, then GitHub stable release, npm latest, standalone archives, Homebrew, WinGet

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. Activation installs the latest stable GitHub Release; insider-tag promotion also remains 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

When a validated sanitized promotion branch already exists in the upstream repository, a human may instead have github-actions[bot] open the protected main PR:

gh workflow run squad-promote.yml --ref dev \
  -f dry_run=false \
  -f promotion_branch=chore/promote-X.Y.Z

The workflow revalidates the branch, builds it, runs the release-gate tests, and opens the PR with GITHUB_TOKEN. GitHub may hold the resulting pull_request workflow runs for maintainer approval; a maintainer with write access must approve those runs, approve the PR, and merge it. The human merge pushes main, which starts squad-release.yml normally.

Without promotion_branch, the legacy path 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.

Repository

bradygaster/squad

Path

.copilot/skills/release-process/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.