release-towit

name	release-towit
description	Use when releasing a new version of to-wit — when the user asks to "cut a release", "release vX.Y.Z", "bump the version", "tag a release", "publish a new version", or "do a release".

Release to-wit

Release a new version of the to-wit CLI: determine version, audit README, update CHANGELOG, commit, tag, and push.

Step 1 — Determine the Version

If the user provided an explicit version (e.g. 0.7.0), use it. Otherwise:

1. Get the current version: git tag --sort=-version:refname | head -1 → strips leading v
2. Ask the user: "What's the release level — major, minor, or patch?" (or accept a literal X.Y.Z)
3. Compute the new version by incrementing the appropriate semver component. Reset lower components to 0.

Tags use a v prefix: v0.7.0.

Step 2 — Audit Help Text and README

2a — Validate towit --help

Run bin/towit help and compare its output against the Usage section of README.md and the actual subcommand implementations in bin/towit and libexec/towit/.

Check for:

• Subcommands or flags present in the implementation but missing from --help
• Subcommands or flags in --help that no longer exist
• Description or default values in --help that contradict the implementation

If any discrepancies are found, stop and fix bin/towit before proceeding. Help text must match the implementation before a release is tagged.

2b — Audit README.md

Read README.md and compare it against the ## [Unreleased] section of CHANGELOG.md plus recent tagged releases.

Check for:

• New subcommands or flags that aren't documented in the Usage section
• Removed or renamed subcommands still listed
• Changed behavior (default scope, flag names, output format) that contradicts the README
• Installation or requirements notes that are out of date
• Usage section out of sync with bin/towit help output

Present a brief audit summary. If nothing is out of date, say so explicitly. If issues are found, propose edits and wait for approval before editing README.md.

Step 3 — Update CHANGELOG.md

1. Read CHANGELOG.md.
2. Confirm there is content under ## [Unreleased]. If it's empty, warn the user before proceeding.
3. Replace ## [Unreleased] with two sections:

## [Unreleased]

## [X.Y.Z] - YYYY-MM-DD

Use today's date. Move all existing Unreleased content under the new version heading. Do not alter the content itself.

Step 4 — Commit

Stage only the files that were changed (README.md if edited, CHANGELOG.md always):

git add CHANGELOG.md README.md   # or just CHANGELOG.md if README was unchanged
git commit -m "chore: release vX.Y.Z"

Show the diff before committing and wait for approval.

Step 5 — Tag and Push

git tag vX.Y.Z
git push origin main
git push origin vX.Y.Z

Confirm each command succeeded. Report the tag name and the commit SHA it points to.

Done

Summarize: version released, tag pushed, any README changes made.