Cut Release

---
name: cut-release
description: Cut a new agnostic-ai release end to end. Use when the user wants to ship a new version (tag + GitHub Release).
---

# cut-release

Cuts a new release of agnostic-ai. The release commit carries the version,
exact changelog, and one public release briefing. GoReleaser publishes
artifacts and the GitHub Release once the tag is pushed. Pages publishes the
briefing from the same commit on `main`.

## When to run

The user asks to release, tag, ship, or cut a new version.

## Steps

1. Confirm working tree clean and on `main`. `git pull --ff-only`.
2. `make ci-local`. Not `make preflight`. Check its own exit code, never through a pipe, and refuse to proceed on any failure.

   `preflight` covers formatting, lint (including govet), and Go tests. A
   release also needs race tests, the WASM build, schema drift, spec lint, shell
   tests, and both editor extensions. `ci-local` runs those checks.

   The JetBrains plugin runs only when `editors/jetbrains/` changed since
   `origin/main`; `FORCE_JETBRAINS=1` runs it anyway. `SKIP_JETBRAINS=1`
   exists for machines without Java or access to the Gradle distribution. If
   you use it, say so in the release report: that job was not gated locally.

   `ci-local` tests on this machine's OS alone. Step 8 checks the exact
   release commit across all three OSes. The plugin version-bump job is
   PR-only; if the plugin changed since the last release, confirm that its
   PR check passed.
3. Decide next version per semver, reading the commit types since the last
   tag (`git log --oneline <last-tag>..HEAD`), since the changelog groups by
   scope rather than by kind:
   - patch: bug fixes only
   - minor: additive features
   - major: breaking changes
4. Update `CHANGELOG.md`: drop empty `### ` and `#### ` headings from `## [Unreleased]`, then move the remaining lines into a new dated `## vX.Y.Z - YYYY-MM-DD` section (no brackets). The released section must never carry a heading with no entries. Reset `## [Unreleased]` to empty.

   Curate the section first with the layout, entry rules, and length check in
   `.agnostic-ai/agents/changelog-curator.md`. Condensing keeps every `#NNN`.
   A path, flag, or case it drops must already be on the docs page or in the
   PR; if it is not, add it to the docs, not back to the bullet.

   Then run `scripts/signals-shipped.sh`. It sets `shipped-date` in
   `scripts/target-audit/signals.tsv` to the release date on every signal
   whose issue the new section cites, and never moves a date already set.
   Read the rows it names: a line that only mentions the issue, without
   delivering support, does not ship the signal, so clear that date.
5. Bump `version` in `cmd/agnostic-ai/main.go`, `extra.version` in
   `docs/site/config.toml`, and both pins in the root `agnostic-ai.yaml`:
   exact `requires: "X.Y.Z"` and the `$schema` URL's `vX.Y.Z` tag. Keep
   them in the release commit. `make site-test` fails when these values
   disagree with the latest dated changelog section.
6. Immediately before the release commit, create exactly one
   `docs/site/content/updates/YYYY-MM-DD-vX.Y.Z.md` release briefing. Read and
   follow [references/release-briefing.md](references/release-briefing.md).
   Explain how to upgrade from the previous release, name the main shipped
   value with a few useful examples, and select consequential target changes. Keep
   agnostic-ai support separate from upstream availability. Run
   `make site-build site-test`.
7. Confirm the version file, site version, project config pins, dated
   changelog section, briefing, and any `signals.tsv` change are all staged
   for the same commit. Commit `chore(release): vX.Y.Z`, GPG-signed.
8. Push `main` and wait for the CI run on that exact commit. Confirm Linux,
   macOS, Windows, and every other job that ran passed. If no run starts,
   dispatch `gh workflow run ci.yml --ref main` and wait for that run.
9. Tag the green commit with `git tag -s vX.Y.Z -m "vX.Y.Z"`, then push the
   tag with `git push origin vX.Y.Z`.
10. Watch the `Release` workflow for the tag and the `Pages` workflow for the
    release commit on `main`. If either fails, fix the root cause. Do not delete
    and retag without clear reason. If the automatic Pages run is absent, use
    its documented `workflow_dispatch` path on `main`, then watch that run.

## Conventions

- Release notes pipeline reads the latest dated section from `CHANGELOG.md`. Never skip step 4.
- A release briefing is release material, not a follow-up docs change. It must
  be created after the changelog is finalized and included in the tagged
  release commit.
- The briefing orders breaking behavior, default changes, removals, and
  deprecations before additions. It never presents upstream news as shipped
  agnostic-ai support.
- Cover every substantial feature and migration. A fixed bullet count must
  never hide a change a reader needs to use the release.
- Tag format `vX.Y.Z` (lowercase `v`). GoReleaser matches this prefix.
- Commit message follows Conventional Commits. Never mention AI in the message.