/release-alpha

description: Prepare and execute an alpha release (patch/minor/major)

**Arguments**: `{{arg1}}`

• First word: release type (`patch`, `minor`, `major`)
• If second word is `auto`: skip approval prompts and automatically push `main` and the release tag

Prepare an alpha release following this workflow.

**Inventory check (both auto and interactive modes):** Before running the release script, reconcile the release's notable Added/Changed/Removed capabilities and relevant commits against `docs/FEATURE_INVENTORY.md`, following the root `CLAUDE.md` feature-inventory rule. Update missing, incomplete, or obsolete entries; verify unclear scope against current code. Report the updated sections or a short "No inventory impact" reason. Preserve unrelated pending edits, and do not treat uncommitted or planned work as shipped.

AUTO MODE DETECTION

If `{{arg1}}` contains `auto` (for example `patch auto`), run the full process without stopping for approval: 1. Find the last **successful** alpha release build. 2. Collect all commits since that successful release. 3. Generate two note sets:

• developer changelog notes for `CHANGELOG.md`
• public-facing draft notes for later use with `/promote-public-release`

4. Update `CHANGELOG.md`. 5. Run `./scripts/release.sh [type]`. 6. Push `main` and the new `v*` tag automatically. 7. Monitor the GitHub Actions release build until it completes. 8. On success, show the public draft notes for reference.

Otherwise, follow the interactive workflow below.

MONITOR THE BUILD (auto mode)

After pushing the tag, babysit the run instead of handing it back to the user:

1. Find the run ID for the tag that was just pushed:

   gh run list --limit=5 --json databaseId,headBranch,status,conclusion,event \
     | jq '[.[] | select(.event == "push" and .headBranch == "v[VERSION]")][0]'

2. Watch the run to completion, in **bounded foreground segments** — never one long background watcher. A release build runs 15-30 minutes; a single `gh run watch` exceeds the Bash timeout, gets auto-backgrounded, and is then killed when the turn tears down (GitHub #1355). The grace timer is only armed *after* a turn ends, so a foreground wait is never affected. Repeat this until `status` is `completed`:

   gh run watch [RUN_ID] --exit-status --interval 30

Call it with the Bash tool's own `timeout` set to `480000` (8 minutes) so the segment returns well inside the ceiling rather than auto-backgrounding. On timeout, check where the run stands and issue another segment if it is still going:

   gh run view [RUN_ID] --json status,conclusion -q '.status + " " + (.conclusion // "")'

Do not use `run_in_background` for this, and do not raise the Bash timeout past the ceiling — segmenting is the point. 3. On success, announce that the alpha release shipped and show the public draft notes. 4. On failure:

• Pull failed logs: `gh run view [RUN_ID] --log-failed`
• Diagnose the root cause and fix it on `main`
• Re-run `/release-alpha patch auto`

Do **not** run `/promote-public-release` until the alpha prerelease build is green.

ALPHA RELEASE WORKFLOW

1. **Find the last successful alpha release**:

• Run:

     gh run list --limit=20 --json headBranch,conclusion,displayTitle,event \
       | jq '[.[] | select(.event == "push" and (.headBranch | startswith("v0.")))]'

• Find the most recent tag where `conclusion == "success"`.
• Use commits since that successful tag:

     git log [successful-tag]..HEAD --oneline

2. **Generate release notes**:

• Create two versions:

**A. Developer changelog notes (for `CHANGELOG.md`)**

• **One short line per change. Hard cap: ~150 characters per bullet, single sentence, no sub-bullets.**
• Derive bullets from the commit `--oneline` shortlog, not from full commit message bodies. The body is for the PR; the changelog is for skim-reading.
• Technical language is fine, but do NOT include: root-cause analysis, file paths, function names, line / test counts, "previously X, now Y" before/after pairs, multi-sentence explanations, parenthetical "(closes #N)" trailers unless the issue is the most useful identifier.
• Categorize as `Added`, `Changed`, `Fixed`, `Removed`. Drop sections that have nothing.
• Squash near-duplicate commits (multiple "fix typecheck", multiple follow-ups to the same PR) into a single bullet.
• Skip purely internal noise: typecheck fixes, test-only changes, doc reshuffles, agent-instruction tweaks, lint, formatting, dependency bumps without behavior change. If it doesn't change behavior for any user (end-user or agent author), it doesn't belong in the changelog.

**B. Public release draft notes (for `/promote-public-release`)**

• Only include user-facing changes.
• Use user-friendly, product-facing language.
• Answer "what can I now do?" or "what problem is fixed?"
• Exclude internal refactors, tooling changes, and non-user-visible maintenance.

3. **Update `CHANGELOG.md`**:

• Add the developer notes to `[Unreleased]`.
• Use the standard `###` section headings.
• Only include categories that actually have entries.

4. **Show both versions to the user**:

• Display the developer changelog block.
• Display the public draft notes separately.
• Ask for approval before proceeding.

5. **Execute the alpha release**:

• Run:

     ./scripts/release.sh [type]

• The script will:
• bump `packages/electron/package.json`
• update `pnpm-lock.yaml`
• move `[Unreleased]` into a new versioned section
• create the release commit
• create the annotated `v*` tag

6. **Push `main` and the tag**:

• Push:

     git push origin main
     git push origin v[VERSION]

• Provide the Actions URL:

`https://github.com/nimbalyst/nimbalyst/actions`

7. **Done**:

• Remind the user that the tag pus