| name | tagging-a-new-release |
| description | Guides the release tagging workflow for this project. Invoke when the user asks to tag, release, cut a release, bump the version, or publish a new version. Determines the next semver version, presents it for user approval, then tags and pushes. |
Tagging a New Release
This project uses semantic versioning (semver) and GoReleaser. Releases are triggered by pushing a Git tag — CI handles the build, binary compilation, and Homebrew tap update automatically. Do not run GoReleaser locally.
Workflow
1. Pre-flight checks
Verify the environment is ready for a release. Do not proceed until all checks pass.
git branch --show-current
git status --porcelain
git fetch origin
git status -uno
If the working tree is dirty, commit or stash first. If the branch is behind the remote, pull before proceeding.
2. Determine the current version
git fetch --tags origin
git tag --sort=-v:refname
Do not pipe through head or other commands — the sandbox silently swallows pipe failures, producing empty output with no error. Run git tag alone and read the output directly.
Identify the latest tag. This is the baseline for the next version.
3. Analyze changes and build a changelog
git log <latest-tag>..HEAD --oneline
Group the commits into a changelog summary for the user:
- Features: new capabilities, commands, integrations
- Fixes: bug fixes, crash fixes, correctness improvements
- Internal: refactoring, docs, CI changes, dependency updates
Then classify the overall change scope to determine the version bump:
| Change type | Version bump | Examples |
|---|
| Breaking / incompatible API changes | Major (X.0.0), or Minor while pre-1.0 | Removed a CLI command, changed config schema incompatibly, renamed a public concept |
| New features, capabilities, or commands | Minor (0.X.0) | Added a new subcommand, new config option, new integration |
| Bug fixes, docs, internal improvements | Patch (0.0.X) | Fixed a crash, corrected a typo, refactored internals with no behavior change |
While the project is pre-1.0, breaking changes bump minor (not major), minor is the "feature release," and patch is the "fix release."
4. Suggest a version — then wait
Present the user with:
- The changelog summary from step 3
- The suggested version with brief reasoning
- The commit that will be tagged (short SHA + first line)
STOP here and wait for the user to confirm or override the version number. Do not proceed to tagging until the user explicitly approves a specific version.
The user decides the version — your suggestion is advisory. If the user picks a different version, use theirs without pushback.
5. Tag and push
Once the user confirms the version, verify the tag does not already exist:
git tag -l v<confirmed-version>
If the tag already exists, tell the user and ask for a different version. Otherwise:
git tag v<confirmed-version>
git push origin v<confirmed-version>
6. Verify the release
The tag push triggers the GitHub Actions release workflow (.github/workflows/release.yml), which runs GoReleaser to build binaries and update the Homebrew tap.
Monitor the workflow until it completes:
gh run list --workflow=release.yml --limit=1
If the run is still in progress, use gh run watch <run-id> to stream logs (get the run ID from the gh run list output).
The release is not finished until the workflow reports success. If it fails, investigate and resolve the issue before telling the user the release is done.
When the workflow succeeds, confirm to the user with:
- The version that was released
- A link to the GitHub release page
- A reminder that
brew upgrade agenc will pick up the new version
