/release

name: release
description: |
  Create a release from dev branch. Generates changelog entries from commits,
  bumps version, and creates a PR to main.

  TRIGGERS - Use this skill when user says:
  - "/release" - create a patch release (default)
  - "/release minor" - create a minor release
  - "/release major" - create a major release
  - "make a release", "cut a release", "ship it", "release to main"

Release Skill

Creates a release by comparing dev to main, generating changelog entries from commits, bumping the version, and creating a PR. After the tag is pushed and the release workflow finishes building binaries, updates the Homebrew formula with the real SHA256 values from the published `checksums.txt`, syncs the `coleam00/homebrew-archon` tap, and verifies the end-to-end install path via `/test-release`.

> **⚠️ CRITICAL — Homebrew formula SHAs cannot be known until after the release workflow builds binaries.** > > The `version` field in `homebrew/archon.rb` and the `sha256` fields must be updated **atomically**. Never update one without the other. > > The correct sequence is: > 1. Tag is pushed → release workflow fires → binaries built → `checksums.txt` uploaded > 2. Fetch `checksums.txt` from the published release > 3. Parse the SHA256 per platform > 4. Update `homebrew/archon.rb` with the new version AND the new SHAs in a single commit > 5. Sync to the `coleam00/homebrew-archon/Formula/archon.rb` tap repo > > Updating the formula's `version` field without also updating the `sha256` values creates a stale, misleading formula that looks valid but produces checksum mismatches on install. This has happened before (v0.3.0: version updated to 0.3.0 but SHAs were still from v0.2.13). Always do both or neither.

Process

Step 1: Validate State

# Must be on dev branch with clean working tree
git checkout dev
git pull origin dev --no-rebase
git status --porcelain  # must be empty
git fetch origin main

If not on dev or working tree is dirty, abort with a clear message.

**Then check that dev actually contains main.** Anything committed directly to main — a docs typo fix, a hotfix, the previous release's formula commit — stays stranded there until someone merges it back. The release PR would then propose *reverting* it, and the next release inherits the drift.

if git merge-base --is-ancestor origin/main origin/dev; then
  echo "dev contains main — OK"
else
  echo "DRIFT: commits exist on main that dev does not have:"
  git log origin/dev..origin/main --oneline
  echo ""
  echo "Resync before releasing:"
  echo "  git checkout dev && git pull origin main --no-rebase && git push origin dev"
  exit 1
fi

Observed on the 0.7.1 release: `ae704a73 Update docs.mdx (#2155)` had been committed straight to main after 0.7.0 and never merged back. Someone had noticed the *content* gap and hand-forward-ported it via a separate PR (#2403), so dev had the change but not the commit — and `main` was still not an ancestor of `dev`. Resolve this before Step 2; do not carry it into the release PR.

Step 1.5: Pre-flight compiled-binary smoke test (MANDATORY before any other step)

> **Why this is first**: releases have ended up with zero working binaries because a module-init crash or bundler bug only surfaces in `bun build --compile` output, not in `bun run`. CI catches it — but only AFTER the tag is pushed and a GitHub Release is created. By then the damage (empty release, broken `releases/latest`, broken `install.sh`) is already live. Failing here, before any user-visible change, keeps the blast radius at "no release was cut."

Run locally on the native target. This takes ~15-30s and is cheaper than discovering the problem after tag+release.

# Guard: only run this for Node/Bun projects with a CLI entry point + build-binaries script.
if [ -f scripts/build-binaries.sh ] && [ -f packages/cli/src/cli.ts ]; then
  TMP_BINARY=$(mktemp)
  trap "rm -f $TMP_BINARY" EXIT

  # Compile for the native target only (not full cross-compile — that's CI's job).
  # Match the real release flags so any bundler quirk reproduces locally.
  bun build \
    --compile \
    --minify \
    --target=bun \
    --outfile="$TMP_BINARY" \
    packages/cli/src/cli.ts

  # Smoke test: the binary must start and exit 0 on a safe, non-interactive command.
  # Use `--help` (NOT `version`). The `version` command's compiled-binary code
  # path depends on BUNDLED_IS_BINARY=true, which is set by scripts/build-binaries.sh
  # — but we're doing a bare `bun build --compile` here to keep the smoke fast,
  # so BUNDLED_IS_BINARY is still `false`. That sends `version` down the dev
  # branch of version.ts which tries to read package.json from a path that only
  # exists in node_modules, producing a false-positive ENOENT. `--help` has no
  # such dev/binary branch and exercises the same module-init graph we're
  # actually testing. Must NOT touch network, database, or require env vars.
  if ! "$TMP_BINARY" --help > /tmp/archon-preflight.log 2>&1; then
    echo "ERROR: compiled binary crashed at startup"
    cat /tmp/archon-preflight.log
    echo ""
    echo "This usually means a dependency has a module-init-time side effect that"
    echo "fails in a compiled binary context (readFileSync of a path that only"
    echo "exists in node_modules, etc.). Fix before cutting the release — do NOT"
    echo "proceed to version bump."
    exit 1
  fi

  # Also grep for known crash markers that exit 0 but print a fatal error
  # (some module-init errors are caught by top-level try/catch but still log).
  if grep -qE "Expected CommonJS module|TypeError:|ReferenceError:|SyntaxError:" /tmp/archon-preflight.log; then
    echo "ERROR: compiled binary emitted a runtime error despite exit 0"
    cat /tmp/archon-preflight.log
    exit 1
  fi

  echo "Pre-flight binary smoke: PASSED"
fi

If this fails, **abort the release entirely** — do not bump version, do not modify CHANGELOG, do not create a PR. Surface the err