Gaia Release

GAIA Release

Run a GAIA release end-to-end against the amd/gaia repo. The skill is a phased checklist with hard gates — each phase produces a concrete artifact, then stops and asks for confirmation before doing anything irreversible (opening a PR, pushing a tag, rerunning a CI job, posting an announcement).

The pre-tag verification phase exists because the v0.17.4 release uncovered two release-blocking bugs that merged-PR CI did not catch (squash-merge silently reverting version.py, and the AppImage smoke test's circular pip install amd-gaia==<unpublished> dependency). Do not skip it.

Argument parsing

Accept one argument in any of these shapes:

• 0.17.5 — bare semver
• v0.17.5 — with the v prefix (the actual tag form)
• 0.17.5.1 — hotfix-style four-part version (rare; e.g. v0.15.4.1)
• (no argument) — read __version__ from src/gaia/version.py, then suggest the next-patch bump (e.g. 0.17.4 → propose 0.17.5) and ask the user to confirm or override before continuing.

Normalise to the bare form internally (0.17.5) and the tag form externally (v0.17.5). If the user gives a version that is older than or equal to the current __version__, stop and ask — never silently roll backwards.

Resume detection (run before any phase)

The skill is reinvocation-safe — releases span days, and the user will return mid-flow. Before doing anything else, detect where in the flow we are and skip phases that already landed:

git fetch origin --tags
git checkout main && git pull
NOTES_ON_MAIN=$(git ls-tree -r origin/main --name-only | grep -c "^docs/releases/v<version>\.mdx$" || true)
PR_OPEN=$(gh pr list --repo amd/gaia --search "Release v<version> in:title" --state open --json number --jq '.[0].number' || true)
PR_MERGED=$(gh pr list --repo amd/gaia --search "Release v<version> in:title" --state merged --json number --jq '.[0].number' || true)
TAG_EXISTS=$(git tag --list "v<version>")
RELEASE_EXISTS=$(gh release view "v<version>" --repo amd/gaia --json tagName --jq '.tagName' 2>/dev/null || true)

Resume table:

Always announce the resume decision before continuing: "Detected v<version> state: PR #831 merged, no tag yet. Resuming at Phase 3 (pre-tag verification)."

A PR_OPEN or PR_MERGED state may have been produced by the nightly automation rather than a person: .github/workflows/nightly-patch-release.yml drafts Phase 1-2 on its own when a patch release is due, and stops before merge and tag. Treat that PR exactly like a human-drafted one — review the notes, then resume at the phase the table gives.

Hard rules (do not violate)

These map to CLAUDE.md. Re-read them whenever this skill runs.

• Plain language first, in every artifact — the release notes, PR body, Discord post, and your own between-phase status updates all follow CLAUDE.md → How You Communicate: lead with what a user can now do, layer version numbers, SHAs, and pipeline mechanics underneath. Say each point once — don't restate a highlight in the changelog and again in the announcement.
• No Claude attribution anywhere — not in PR titles, PR bodies, commit messages (no Co-Authored-By: Claude ... trailer), release notes, code comments, or the Discord announcement.
• No silent fallbacks — if a validator fails, a step times out, or a workflow run isn't found, stop with an actionable error. Do not retry blindly. Do not "proceed anyway."
• Release notes are bulleted, plain, and short — see Notes format in Phase 1. Every entry is one bullet, never a prose block; no narrative overview paragraph; no emoji; a hard word budget that is checked, not eyeballed. Sections in order: ## Breaking Changes (only if any), ## What's New, ## Bug Fixes, ## Known Issues (only if any), ## Contributors, ## Full Changelog. Patch releases do not include a pip install block.
• Match the previous release PR body shape exactly — read the most recent merged Release vX.Y.Z PR (e.g. gh pr list --repo amd/gaia --state merged --search "Release v in:title" --limit 3). Open with # GAIA vX.Y.Z Release Notes (no MDX frontmatter in the PR body), end with a Release checklist section. Style drift here costs review cycles.
• The version.py bump and its notes land in the same commit. docs.yml and tests/unit/test_docs_json_release.py both resolve docs/releases/v<version>.mdx and the docs.json navbar label from the declared __version__, so bumping ahead of the notes (the old 0.17.3 → "bump to 0.17.4 for development" pattern) turns every later docs and unit run red, not just the release PR. Never bump on its own.
• Bulletproof commits only — every change made by this skill must satisfy the four criteria in CLAUDE.md (validated, critiqued, scope-clean, no half-finished work) before being committed.
• Pushing tags is irreversible. Always confirm the SHA the tag will point to and the green status of the pre-tag verification run before git push origin v<version>.
• Manual approval gate at the publish step is human-only — Claude cannot click the GitHub environment "approve" button. Surface the run URL and stop.

Phase 1 — Draft release notes (PR-ready)

Goal: produce docs/releases/v<version>.mdx matching house style; update navigation and the UI package.json.

Steps

1. Survey commits since previous tag, then sanity-check the version request against scope.

   PREV=$(git tag --sort=-v:refname | grep -E '^v[0-9]+\.[0-9]+\.[0-9]+' | head -1)
   echo "Previous tag: $PREV"
   git log "$PREV..HEAD" --pretty=format:'%h  %s'
   echo
   echo "Total: $(git log $PREV..HEAD --oneline | wc -l) commits"
   echo "Feat:  $(git log $PREV..HEAD --oneline | grep -cE '^[a-f0-9]+ feat') feat commits"
   echo "Fix:   $(git log $PREV..HEAD --oneline | grep -cE '^[a-f0-9]+ fix')  fix commits"

   Group commits by theme (features, fixes, infra, docs). Extract the PR number from each subject ((#NNN)). For each non-trivial entry, open the linked PR or commit body to get the why — release notes need motivation, not just titles.

   Scope-vs-version sanity check (do not skip): apply this rubric against the requested target version:

   Commit shape	Suggested release shape
   Only fix/docs/chore/ci, no feat	Patch (vX.Y.Z+1) ✓
   1–2 feat commits, small scope	Patch acceptable, mention them as "What's New"
   3+ feat commits, or any commit titled ... vX.Y.Z milestone, default-model swap, breaking change, package layout change	Minor (vX.Y+1.0) — push back
   Removal of a public API, CLI flag deletion, config schema break, version-pin floor raised in a non-additive way	Major (vX+1.0.0) — push back

   If the requested version doesn't match the rubric, stop and surface the mismatch: "You asked for v<requested> (patch). I see N feat commits since <prev> including <one or two examples> — this looks minor-shaped. Continue as patch, or bump to v<suggested>?" Do not silently proceed.

2. Read recent release notes for structure only — frontmatter shape, section headings, PR-link format. Take length and tone from Notes format below, not from the files: v0.21.1 is the model at 267 narrative words, while v0.22.0 (1705) and v0.23.0 (1119) were flagged in review as too much text in too-blocky a form — they are the regression this section exists to prevent.

   Patch releases are short. Minor/major releases carry more bullets and a pip install block — the per-bullet shape is identical, only the count grows.

3. Create docs/releases/v<version>.mdx with this skeleton (adapt to whether it's patch / minor / major):

   ---
   title: "v<version>"
   description: "<one plain line: what shipped. Not a pitch.>"
   ---
   
   # GAIA v<version> Release Notes
   
   <Optional single sentence naming what this release is about. Drop it entirely if
   the bullets already say it — that is the common case. Never a paragraph.>
   
   ## Breaking Changes
   
   - **<what changed>** — <what to do instead>. (PR [#NNN](https://github.com/amd/gaia/pull/NNN))
   
   ## What's New
   
   - **<what the user can now do>** — `<gaia command>`. <At most one more sentence, only
     if the title genuinely needs it.> (PRs [#NNN](https://github.com/amd/gaia/pull/NNN), [#NNN](https://github.com/amd/gaia/pull/NNN))
   
   ## Bug Fixes
   
   - **<what was broken>** — <what now happens>. (PR [#NNN](https://github.com/amd/gaia/pull/NNN))
   
   ## Known Issues
   
   - **<what still does not work>** — <workaround, or "tracked in [#NNN](https://github.com/amd/gaia/issues/NNN)">.
   
   ## Contributors
   
   - [@handle](https://github.com/handle) — <what they contributed>. (PR [#NNN](https://github.com/amd/gaia/pull/NNN))
   
   ## Full Changelog
   
   **N commits** since v<previous>:
   
   - `<sha>` — <subject>
   - ...
   
   Full Changelog: [v<previous>...v<version>](https://github.com/amd/gaia/compare/v<previous>...v<version>)

   Omit ## Breaking Changes and ## Known Issues when empty — no "None" placeholder. Drop the --- rules between sections; the headings already separate them.

   Generate the changelog by introspecting git, and escape it for MDX. Do not hand-transcribe subjects, and do not pipe git log output in raw — a subject containing < or { is valid git and invalid MDX, which fails CI's mintlify validate. v0.22.0 hit this on #1791's subject ("fix Mintlify MDX validation (unescaped '<' breaks the docs check)") — the one commit whose subject describes the bug it causes.

   # Generate the `- `<sha>` — <subject>` lines, escaping the two characters MDX
   # treats as syntax. `\<` and `\{` render as literal `<` / `{` (verified against
   # `mintlify validate`), and shas never contain them, so escaping the whole line
   # is safe. Subjects like "AMD <> SpecificAI" survive correctly.
   git log v<previous>..HEAD --pretty=format:'- `%h` — %s' \
     | sed -e 's/</\\</g' -e 's/{/\\{/g' > /tmp/changelog.txt
   
   # Guard: nothing hazardous may survive.
   grep -nE '(^|[^\\])[<{]' /tmp/changelog.txt && echo "MDX HAZARD — fix before continuing" || echo "changelog MDX-safe"

   Sanity-check the count against git log --oneline | wc -l after writing the file (wc -l under-counts by one when the last line has no trailing newline — v0.22.0 claimed 197 when the real count was 198). The claimed count, the listed lines, and git log must all agree.

   Notes format (apply to every entry — this is the point of the skill). Tone is already governed by CLAUDE.md → How You Communicate — plain language, outcome first, each point made exactly once. Do not restate or soften it here. What is release-notes-specific is the shape:

   • Bullets, not paragraphs. Every entry is one bullet: a bold clause naming what the user can now do, then at most one sentence, then the PR links. No ### prose blocks inside What's New.
   • Say it once. A highlight appears in the bullet list or in the opening sentence, never both. The frontmatter description is not a third copy.
   • Factual, not promotional. State the capability and stop. Banned: emoji, "we're excited to announce", "finally", "blazing(-fast)", "game-changer", "seamless", "powerful", "unlock", "Here's the good stuff", "makes X effortless", "no more crashes", invented benchmarks.
   • Order by what users run. Agents and commands first (gaia hub, gaia email, …); SDK, CI, and refactor work last, or omitted when it has no user-visible effect.
   • Word budget — a cap, not a target. ≤ 350 words for a patch, ≤ 600 for a minor/major, measured from the top down to the first of ## Bug Fixes / ## Known Issues / ## Contributors / ## Full Changelog. Those four are reference lists — their length is set by how many fixes actually shipped, and squeezing them hides work. The cap is on the narrative part, which is what bloats. Over budget means cut entries, not reflow them. Step 8 checks it. (Calibration, same measure: v0.21.1 shipped at 267, v0.22.0 at 1705, v0.23.0 at 1119.)

   Example — one highlight:

   Bad (prose block, promotional, three sentences where one works):

   Triage your inbox from the terminal — gaia email

   Point GAIA at your inbox and it sorts the noise from what needs you: drafts replies to routine mail, flags what's urgent, leaves the rest. Runs locally, so your mail never leaves your machine. Try it: gaia email.

   Good (one bullet, plain, factual):

   • Triage your inbox from the terminal — gaia email sorts mail, drafts replies to routine messages, and flags what needs you. Runs locally. (PR #1234)

4. Update docs/docs.json:

   • Add releases/v<version> to the Releases tab.
   • Bump the navbar label (e.g. v<previous-version> · Lemonade <previous-lemonade> → v<version> · Lemonade <current-lemonade>). Read src/gaia/version.py for the LEMONADE_VERSION constant — it is the source of truth, and the navbar may be drifted from it (Lemonade bumps land outside release PRs).

5. Sync the UI package version.

   node installer/version/bump-ui-version.mjs

   Confirm src/gaia/apps/webui/package.json now reads the new version.

6. Bump the hub component manifests. The terminal hub and Agent UI publish to the Agent Hub R2 catalog on a version tag, and release_components.yml gates the tag against each manifest — R2 paths are immutable, so publishing under a stale version cannot be undone. A mismatch fails the release, by design.

   sed -i '' "s/^version: .*/version: <version>/" \
     hub/components/terminal-hub/gaia-agent.yaml \
     hub/components/agent-ui/gaia-agent.yaml     # GNU sed: drop the ''
   grep -H '^version:' hub/components/*/gaia-agent.yaml   # both must read <version>

   Then bump the terminal hub's min_gaia_version to <version> too. It needs daemon host API v1.1, which no release before this one ships — so the release it publishes alongside is its minimum, and release_components.yml refuses to publish it under an older core. Leave agent-ui's alone: it talks to gaia.ui.server, not the daemon control plane.

   sed -i '' "s/^min_gaia_version: .*/min_gaia_version: \"<version>\"/" \
     hub/components/terminal-hub/gaia-agent.yaml     # GNU sed: drop the ''
   python util/check_component_core_api.py --release-version <version>

   Finally, record what the previous release shipped in RELEASED_DAEMON_API in util/check_component_core_api.py — the guard resolves an already-published version from that table, and a missing row makes it fall back to trusting this tree, which is the drift it exists to catch.

7. Confirm __version__ is correct.

   grep -E '^__version__' src/gaia/version.py

   The post-prior-release bump usually handles this, but a squash-merge can revert it silently. If it's wrong, edit it. If it's right but reverted later (see Phase 3), the validator will catch it.

8. Validate — both checks. Run from the repo's activated venv (source .venv/bin/activate on Linux/macOS, .venv\Scripts\activate on Windows; the bare-python Microsoft Store stub will fail). If you're working from a git worktree without its own venv, run from the parent checkout's venv.

   python util/validate_release_notes.py docs/releases/v<version>.mdx --tag v<version>
   (cd docs && npx -y mintlify@latest validate)   # the docs.yml `validate` job — MUST also pass
   
   # Word budget from *Notes format* — the narrative part only, not the reference lists.
   # Cap: 350 words for a patch, 600 for a minor/major. Over budget means cut entries.
   awk '/^## (Bug Fixes|Known Issues|Contributors|Full Changelog)/{exit} {print}' \
     docs/releases/v<version>.mdx | wc -w

   Both must exit 0. Fix any errors before continuing. If either fails for reasons unrelated to your changes (missing dep, broken import), stop and surface that — do not silently bypass. validate_release_notes.py prints the first failing check (missing/renamed section, absent compare/ link, tag mismatch) — read that line to localise the fix; it has no --verbose flag.

   validate_release_notes.py passing is not sufficient — it is not an MDX parser. CI's validate job additionally runs mintlify validate from docs/, and v0.22.0 failed it after the notes passed the Python validator (see the escaping rule in step 3). Its error is misleading: an unparseable .mdx surfaces as "releases/v<version>" is referenced in the docs.json navigation but the file does not exist — the file exists, it just never parsed. Pre-existing parse errors under docs/plans/ and docs/superpowers/ are reported but non-fatal; leave them alone.

Gate 1 — show the user the draft

Show the diff (git diff --stat plus the new .mdx file inline). Ask: "Approve these release notes and continue to Phase 2 (open PR)?" Wait for explicit yes. Iterate on tone/wording before continuing — much cheaper than fixing on main.

Phase 2 — Open the release PR

Goal: branch, commit, push, open PR, request review.

Steps

1. Branch and commit.

   git checkout -b v<version>-release
   git add docs/releases/v<version>.mdx docs/docs.json src/gaia/version.py \
           src/gaia/apps/webui/package.json src/gaia/apps/webui/package-lock.json \
           hub/components/terminal-hub/gaia-agent.yaml \
           hub/components/agent-ui/gaia-agent.yaml
   git status              # confirm scope-clean — no drive-by edits
   git diff --cached --stat
   git commit -m "Release v<version>"
   git push -u origin v<version>-release

   If git status shows anything outside those five files, stop and ask (bump-ui-version.mjs rewrites package-lock.json too — the prior release commit carries all five). The release PR must be scope-clean.

2. Read the most recent release PR body to match shape.

   gh pr list --repo amd/gaia --state merged --search "Release v in:title" --limit 3 \
     --json number,title,body | jq -r '.[0]'

   Use that as the structural template for this PR body — same opening, same checklist, same section order. Do not invent a new shape.

3. Prepare the PR body file. Build it by stripping the MDX frontmatter from the release notes and appending the Release checklist section copied from the previous release PR.

   # Strip the YAML frontmatter (everything between the first two '---' lines)
   awk '/^---$/{c++; next} c>=2' docs/releases/v<version>.mdx > /tmp/release-body.md
   
   # Append the Release checklist section from the previous release PR
   PREV_PR=$(gh pr list --repo amd/gaia --state merged --search "Release v in:title" --limit 1 --json number --jq '.[0].number')
   gh pr view "$PREV_PR" --repo amd/gaia --json body --jq '.body' \
     | awk '/^## Release checklist/{found=1} found' \
     >> /tmp/release-body.md
   
   # Sanity-check the body before opening the PR
   head -3 /tmp/release-body.md   # should start with "# GAIA v<version> Release Notes"
   tail -10 /tmp/release-body.md  # should end with the checklist

   If the awk pipeline produces an empty file, the previous PR didn't have a ## Release checklist heading — fall back to copying the entire body and editing it manually before continuing.

4. Open the PR. Title: Release v<version>. Body: the file you just built.

   gh pr create --repo amd/gaia \
     --title "Release v<version>" \
     --body-file /tmp/release-body.md \
     --reviewer kovtcharov-amd

   Surface the resulting PR URL.

Gate 2 — wait for merge

Stop. Tell the user: "PR opened at <url>. Waiting for review/merge before pre-tag verification. Re-invoke this skill (or /loop) to continue once merged."

Do not poll, do not auto-merge. Do not push the tag from the un-merged branch.

Phase 3 — Pre-tag verification (the hard-won gate)

Goal: prove the merged commit on main actually builds clean before the tag locks it in. Do not skip this. Two release-blocking bugs in v0.17.4 would have shipped without this step.