Release

Perform a full release for version $ARGUMENTS.

1. Pre-flight

• Run git status. Working directory must show no changes and stay on main.
• Run git log --oneline -3. Confirm the tip commit matches what you want tagged.
• Check version format: must match vMAJOR.MINOR.PATCH
• Get the previous version tag for use in step 4: git tag --sort=-version:refname | grep "^v" | head -1

2. Update CHANGELOG.md

Read CHANGELOG.md and make these edits:

1. Replace ## [Unreleased] with ## [$ARGUMENTS_NO_V] - YYYY-MM-DD, using today's date. The heading uses the version without the leading v to match the existing convention and to match the link reference added in step 3 (rumdl will report MD053 Unused link/image reference if the two get out of sync).
2. Insert a new empty ## [Unreleased] section before it
3. Add a comparison link at the bottom of the file, before the current top link: [$ARGUMENTS_NO_V]: https://github.com/tbhb/vale-ai-tells/compare/PREV_TAG...$ARGUMENTS where PREV_TAG refers to the tag found in step 1 and ARGUMENTS_NO_V strips the leading v

Writing CHANGELOG entries: Metacommentary uses scope: raw, which bypasses <!-- vale off --> inline suppression. Don't quote literal trigger phrases from that rule (the Let's [verb] patterns) in the CHANGELOG. Paraphrase them instead, as in v1.4.0.

3. Update README.md

The release workflow builds three packages at every tag (ai-tells.zip, ai-tells-commits.zip, ai-tells-experimental.zip). Bump the version in every releases/download/vX.Y.Z/... URL in the README so all package references point at the new tag.

Use grep -n "releases/download" README.md to enumerate every occurrence before editing.

4. Pre-commit checks

Run:

• mise run repotools:lint-yaml: confirm any new YAML files pass
• mise run test-clean: confirm false positives file remains clean

5. Commit

Invoke the commit skill, telling it to stage CHANGELOG.md and README.md and nothing else, and to use chore: release $ARGUMENTS as the subject. That skill owns the COMMIT_AGENTMSG draft, the Assisted-by and Signed-off-by trailers the commit-trailers hook requires, and the gates. A hand-written git commit here fails that hook, since a bare subject carries no trailers.

Keep the body short and trigger-free. The commit-msg hook lints the message with all ai-tells rules, and a release commit has little to explain beyond the version. Never name a flagged phrase or token in it.

6. Publish

Run:

mise run release $ARGUMENTS

This creates the annotated tag (using -a -m), pushes the commit and tag, then waits for the GitHub Actions release workflow to complete. It extracts the CHANGELOG entry and updates the release notes automatically.

7. Verify

Run gh release view $ARGUMENTS to confirm:

• Release notes match the CHANGELOG entry
• The "Full Changelog" comparison link appears and points to the right range
• All three package assets appear in the release: ai-tells.zip, ai-tells-commits.zip, ai-tells-experimental.zip