checksums.txt

coleam00/homebrew-archon

/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.

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."

undefined

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.

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.

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 this fails, **abort the release entirely** — do not bump version, do not modify CHANGELOG, do not create a PR. Surface the error to the user, point at the failing output, and stop. Recovery is: fix the bundler / dependency issue on a feature branch, merge to dev, re-run `/release`.

**Common failure modes this catches:**
- Bun `--bytecode` flag producing broken bytecode for the current module graph
- A dependency (e.g. an SDK) reading `package.json` or other files at module top level via paths that resolve fine in `node_modules/` but not next to a compiled binary
- Circular imports that break under minification but work under plain `bun run`
- A newly added package that ships CJS with an unusual wrapper shape

1. Check for

   pyproject.toml

   — Python project, version in

   version = "x.y.z"

2. Check for

   package.json

   — Node/Bun project, version in

   "version": "x.y.z"

3. Check for

   Cargo.toml

   — Rust project, version in

   version = "x.y.z"

4. Check for

   go.mod

   — Go project (version from git tags only, no file to bump)

• No argument or

  patch

  (default):

  0.1.0 -> 0.1.1

• minor

  :

  0.1.3 -> 0.2.0

• major

  :

  0.3.5 -> 1.0.0

git diff main..dev

• Added — new features, new files, new capabilities
• Changed — modifications to existing behavior
• Fixed — bug fixes
• Removed — deleted features or code

• Write entries as a human would — clear, concise, user-facing language
• Do NOT just copy commit messages verbatim — rewrite them into proper changelog entries
• Group related commits into single entries where it makes sense
• Include PR numbers in parentheses when available:

  (#12)

• Each entry should start with a noun or gerund describing WHAT changed
• Skip internal-only changes (CI tweaks, typo fixes) unless they affect behavior
• One blank line between sections

1. Version file — update version to new value:

   • package.json

     : update

     "version": "x.y.z"

   • pyproject.toml

     : update

     version = "x.y.z"

   • Cargo.toml

     : update

     version = "x.y.z"

2. Workspace version sync (monorepo only):
   • If

     scripts/sync-versions.sh

     exists, run

     bash scripts/sync-versions.sh

     to sync all

     packages/*/package.json

     versions to match the root version.
3. Lockfile refresh (stack-dependent):

   • package.json

     +

     bun.lock

     : run

     bun install

   • package.json

     +

     package-lock.json

     : run

     npm install --package-lock-only

   • pyproject.toml

     +

     uv.lock

     : run

     uv lock --quiet

   • Cargo.toml

     : run

     cargo update --workspace

4. CHANGELOG.md

   — prepend new version section:

undefined

• Entry one (#PR)
• Entry two (#PR)

• Entry one (#PR)

• Entry one (#PR)

Move any content under `[Unreleased]` into the new version section. Leave `[Unreleased]` header with nothing under it.

1. The detected stack and version file
2. The version bump (old -> new)
3. The full changelog section that will be added
4. The list of commits being included

Note: The

update-homebrew

CI job in

.github/workflows/release.yml

runs automatically after the release job and handles the formula update + push to dev (part of Step 10). Step 11 (tap sync to

coleam00/homebrew-archon

) is always manual. Check the Actions tab before running Step 10 manually.

.github/workflows/release.yml

echo "Waiting for release workflow to finish uploading binaries..."
WORKFLOW_FAILED=0
for i in {1..30}; do
  ASSET_COUNT=$(gh release view "vx.y.z" --repo coleam00/Archon --json assets --jq '.assets | length')
  # Expect 7 assets: 5 binaries (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64.exe) + archon-web.tar.gz + checksums.txt
  if [ "$ASSET_COUNT" -ge 7 ]; then
    echo "All $ASSET_COUNT assets uploaded"
    break
  fi

  # Short-circuit: if the release workflow itself has failed, stop waiting.
  # Hanging for 15 min when CI already crashed just delays the recovery path.
  WORKFLOW_STATUS=$(gh run list --workflow release.yml --event push --limit 1 --json conclusion,status --jq '.[0] | "\(.status)|\(.conclusion)"')
  if [[ "$WORKFLOW_STATUS" == "completed|failure" ]]; then
    echo "Release workflow FAILED — no point waiting longer"
    WORKFLOW_FAILED=1
    break
  fi

  echo "  Assets so far: $ASSET_COUNT/7 — waiting 30s (attempt $i/30)..."
  sleep 30
done

if [ "$WORKFLOW_FAILED" -eq 1 ] || [ "$ASSET_COUNT" -lt 7 ]; then
  # Triage: rerun once in case it's transient, then check again.
  RUN_ID=$(gh run list --workflow release.yml --event push --limit 1 --json databaseId --jq '.[0].databaseId')
  echo "Release workflow failed on run $RUN_ID. Rerunning failed jobs once to confirm..."
  gh run rerun "$RUN_ID" --failed
  gh run watch "$RUN_ID" --exit-status --interval 30 || true

  # Re-check asset count + run status after rerun.
  ASSET_COUNT=$(gh release view "vx.y.z" --repo coleam00/Archon --json assets --jq '.assets | length')
  if [ "$ASSET_COUNT" -ge 7 ]; then
    echo "Rerun succeeded — all assets now present"
  else
    echo ""
    echo "===== DETERMINISTIC CI FAILURE ====="
    echo "The release workflow failed on two consecutive runs. This is NOT a flake."
    echo "The tag and release exist but have no (or incomplete) assets."
    echo ""
    echo "install.sh and similar 'releases/latest' paths are now 404-ing."
    echo "Proceeding with Homebrew/tap sync would publish a formula pointing at"
    echo "missing or inconsistent binaries."
    echo ""
    echo "Jump to the 'Recovery: deterministic release CI failure' section at the"
    echo "bottom of this skill and execute it. Do NOT continue past this point."
    exit 1
  fi
fi

TMP_DIR=$(mktemp -d)
gh release download "vx.y.z" --repo coleam00/Archon --pattern "checksums.txt" --dir "$TMP_DIR"

DARWIN_ARM64_SHA=$(awk '/archon-darwin-arm64$/ {print $1}' "$TMP_DIR/checksums.txt")
DARWIN_X64_SHA=$(awk '/archon-darwin-x64$/ {print $1}' "$TMP_DIR/checksums.txt")
LINUX_ARM64_SHA=$(awk '/archon-linux-arm64$/ {print $1}' "$TMP_DIR/checksums.txt")
LINUX_X64_SHA=$(awk '/archon-linux-x64$/ {print $1}' "$TMP_DIR/checksums.txt")

test-release

/test-release brew x.y.z

• Install via

  brew tap coleam00/archon && brew install coleam00/archon/archon

• Verify the binary reports the correct version and

  Build: binary

• Verify bundled workflows load
• Verify the SDK spawn path works (a minimal assist workflow)
• Verify the env-leak gate is active (if shipped in this release)
• Uninstall cleanly
• Produce a PASS/FAIL report

/test-release brew

x.y.z+1

test-release

/test-release curl-mac x.y.z

install.sh

/test-release curl-vps x.y.z <vps-target>

gh run list --workflow release.yml --limit 2 --json databaseId,conclusion
gh run view <RUN_ID> --log-failed

• Bundler/bytecode bug — Bun

  --bytecode

  produces invalid output for the current module graph. Symptom:

  TypeError: Expected CommonJS module to have a function wrapper

  at binary startup. Historically caused by a new dependency's CJS/ESM shape interacting with

  --bytecode

  — dropping the flag or lazy-importing the offending module has been the fix.
• Module-init crash — a dependency does

  readFileSync('package.json')

  or similar at module top level via a path that exists in

  node_modules/

  but not next to a compiled binary. Symptom: every binary subcommand crashes immediately; error typically mentions a missing file adjacent to

  process.execPath

  . Fix by lazy-importing the dependency behind the code path that actually uses it.
• Smoke-test timeout on Windows — not actually a bug in the code; the Windows runner is slow. Rerun once; if it recurs, bump the test timeout.

vx.y.z

vx.y.(z+1)

• Tag immutability:

  vx.y.z

  is already recorded in git history and release cache
• Semver clarity: users and tooling should see a new version number when the bits change
• Audit trail: "v0.3.7 was cut but had no shipped binaries; v0.3.8 is the first release with <fix>" is cleaner than rewriting v0.3.7

1. Cut a fix branch off dev, implement the fix, PR to dev, merge.
2. Re-run

   /release

   (it will bump to the next patch — e.g.

   0.3.8

   — automatically).
3. Step 1.5's pre-flight smoke will catch the same bug locally if the fix didn't actually fix it. Iterate until it passes before tagging.

• First release with working compiled binaries after vx.y.z's <bug>. vx.y.z was tagged but its binary smoke test failed deterministically (see RUN_ID in CI history). The tag is preserved for history; this release (vx.y.(z+1)) is the first with shipped binaries.

  install.sh

  and Homebrew were never updated to vx.y.z, so users were not exposed to the broken state.

undefined

• Do not force-push or rewrite the tag. Once a tag exists, it's a public promise of that SHA. Deleting and re-creating to a different SHA is tag-spoofing and breaks any downstream that cached the original.
• Do not skip this recovery path to "just push more binaries to the broken release". The release exists with a specific commit SHA; uploading binaries built from a newer SHA creates binary/source drift that is hard to diagnose later.
• Do not update the Homebrew formula before v0.3.(z+1) is fully shipped. The formula should always point at a version with all 7 assets uploaded and

  /test-release brew

  passing.

• NEVER force push
• NEVER skip Step 1.5 (pre-flight compiled-binary smoke). If the stack is a Bun/Node project with a build-binaries script, the

  bun build --compile

  smoke test runs before version bump, PR, or tag. Skipping it means every bundler regression or module-init crash only surfaces after the tag is pushed — by which point

  releases/latest

  is already 404-ing for every user. The ~30s cost is paid to keep the failure mode local.
• If Step 1.5 fails, abort the release and fix the underlying issue on a feature branch. Do not "just skip it" and hope CI doesn't repro the problem.
• NEVER skip the review step — always show the changelog before committing
• NEVER include "Co-Authored-By: Claude" or any AI attribution in the commit
• NEVER add emoji to changelog entries unless the user asks
• If the user says "ship it" without specifying bump type, default to patch
• The commit message is just

  Release x.y.z

  — clean and simple
• NEVER update

  homebrew/archon.rb

  version field without also updating the

  sha256

  values. They must move together atomically. The correct SHAs only exist after the release workflow finishes building binaries — see Step 10. Updating the version field alone produces a stale formula that looks valid but causes checksum mismatches on install.
• NEVER skip Step 11 (tap sync). The

  coleam00/Archon/homebrew/archon.rb

  file is only a template; users install from

  coleam00/homebrew-archon/Formula/archon.rb

  . If you update one without the other, users get stale or wrong data.
• NEVER announce a release that failed

  /test-release brew

  . A release that installs but crashes on first invocation is worse than no release — it burns user trust. If the release verification fails, cut a hotfix before telling anyone the release exists.