release

name	release
description	Prepare code for release (version bumps, changelog, README updates) and create an annotated tag to trigger the GoReleaser workflow.

Your job is to guide the user through a full release for this project. A release includes preparing the code (version bumps, README documentation, changelog), creating an annotated git tag with a v prefix (e.g. v1.5.0), pushing it to trigger the GoReleaser GitHub Actions workflow, setting release notes, and linking the GHCR Docker image.

Rules

• Always create an annotated tag (git tag -a), never a lightweight tag.
• Tag format is vMAJOR.MINOR.PATCH following Semantic Versioning.
• The changelog MUST follow Keep a Changelog 1.1.0 format.
• Valid changelog categories: Added, Changed, Deprecated, Removed, Fixed, Security.
• All version strings MUST be updated before committing. There are three locations (listed in Reference). Run version tests after bumping to catch drift.
• README.md MUST document any user-facing changes — new config fields, CLI flags, behavior changes, exit codes.
• DO NOT push to master until the user confirms.
• DO NOT push the tag until the user confirms.
• DO NOT skip asking the user for the version number, tag annotation message, and changelog review.

Steps

1. Gather context

   • Check the current branch and ensure it is clean (git status).
   • List existing tags (git tag --sort=-v:refname) to determine the next version.
   • Collect the commit log since the last tag (or all commits if this is the first release).

2. Ask the user

   • What version number to use.
   • What the annotated tag message should say.
   • Whether the auto-generated changelog looks correct or needs edits.

3. Categorize commits into Keep a Changelog sections:

   • Added — new features and capabilities.
   • Changed — changes to existing functionality.
   • Deprecated — features marked for removal.
   • Removed — features that were removed.
   • Fixed — bug fixes.
   • Security — vulnerability fixes.
   • Exclude commits prefixed with docs:, test:, ci:, or merge commits.

4. Bump version strings

   • Update all three version locations listed in the Reference section.
   • Run go test ./cmd/ -run TestVersion -count=1 to verify the bump is consistent.

5. Update README.md

   • Explore new feature implementations (via subagents if available) to understand config fields, flags, defaults, and behavior before writing documentation.
   • For each user-facing change, update the relevant README sections: Features list, Run Flags table, Agent Configuration example TOML, and add new sections as needed.
   • Add or update the Exit Codes table if new exit codes were introduced.
   • Do NOT guess at config fields or flag names — read the actual implementation first.

6. Update CHANGELOG.md

   • Prepend the new release section under the # Changelog header.
   • Add a reference link at the bottom of the file using the Keep a Changelog format:
     • First release: [1.0.0]: https://github.com/jrswab/axe/releases/tag/v1.0.0
     • Subsequent releases: [1.1.0]: https://github.com/jrswab/axe/compare/v1.0.0...v1.1.0

7. Commit and push prep changes

   • Stage all modified files and commit with message: Update changelog and version for vX.Y.Z
   • Push to master only after the user confirms.

8. Verify

   • Run go build . to confirm the binary compiles.
   • Run go test ./cmd/ -run TestVersion -count=1 at minimum.
   • Confirm tests pass before proceeding to tag creation.

9. Ask user to confirm tag creation

   • Show the tag name, annotation message, and commit hash.
   • Wait for explicit confirmation before creating the tag.

10. Create the annotated tag on the prep commit.

11. Push the tag to origin only after the user confirms. The v* tag push triggers the GoReleaser workflow which builds binaries and creates the GitHub release.

12. Set release notes via gh

    • Extract the new version's section from CHANGELOG.md — everything between the ## [X.Y.Z] heading and the next ## heading, excluding the heading itself and trailing blank lines.
    • Append a Docker section to the extracted notes:

      ## Docker
      
      ```bash
      docker pull ghcr.io/jrswab/axe:X.Y.Z
      ```
      
      See the [GHCR package page](https://github.com/jrswab/axe/pkgs/container/axe) for all available tags.
      

    • Write the combined content (changelog section + Docker section) to a temporary file.
    • Poll gh release view vX.Y.Z every 10 seconds (up to 120 seconds) until the GoReleaser workflow creates the release.
    • Run gh release edit vX.Y.Z --notes-file <tmp-file> to set the release description.
    • Clean up the temporary file.
    • This is the authoritative source for release notes — do NOT rely on the workflow's awk extraction.

Reference

Project Files

• GoReleaser config: .goreleaser.yml (auto-changelog is disabled)
• Release workflow: .github/workflows/release.yml (builds binaries and Docker image; do NOT rely on it for release notes)
• Changelog: CHANGELOG.md

Version Strings (all three must match)

• cmd/root.go — const Version (source of truth)
• internal/mcpclient/mcpclient.go — hardcoded Version: in mcp.NewClient call
• cmd/version_test.go — test assertions for the version string

GHCR Image

• Package page: https://github.com/jrswab/axe/pkgs/container/axe
• Pull command: docker pull ghcr.io/jrswab/axe:<version>
• Tags generated per release: X.Y.Z, X.Y, X, latest (on default branch)