release-prep

Version Bump Strategy

Change type	Bump	Examples
Breaking change	major	Agent behavior removed, skill renamed, install path changed
New agent, skill, or command	minor	New agent file, new /devteam:* command, new workflow
Bug fix, typo, clarification, doc sync	patch	Broken script fixed, wording corrected, link updated

Rule: when in doubt, prefer patch over minor. Prefer minor over major.

Pre-Release Checklist

Run through every item before creating the tag.

1. Tests and Linting

bash helpers/agent-lint.sh
bash helpers/orphan-skill-scan.sh

Both must exit 0 with no ACTION REQUIRED lines.

2. CHANGELOG

• CHANGELOG.md has an entry for this version under ## [vX.Y.Z] - YYYY-MM-DD
• Entry lists all changes grouped by type: Added / Changed / Fixed / Removed
• No unreleased items left in the ## [Unreleased] section

3. Docs Sync

• README.md and README.pt-BR.md are in sync
• docs/agents.md matches the agents currently in agents/
• CLAUDE.md command table reflects all commands in commands/

4. No Debug Artifacts

grep -r "console\.log\|TODO:\|FIXME:\|HACK:\|XXX:" agents/ skills/ commands/ --include="*.md" -l

Output must be empty (or all matches are intentional and documented).

Git Tag and Push

# Confirm the version
git log --oneline -5

# Create annotated tag
git tag -a vX.Y.Z -m "Release vX.Y.Z"

# Push tag
git push origin vX.Y.Z

Do not force-push tags. If a tag was created in error, see Rollback below.

Post-Release Steps

1. GitHub Release: go to Releases → Draft a new release → select the tag → paste the CHANGELOG entry as the body.
2. Notify stakeholders: post in the team channel with a summary of what changed and a link to the release notes.
3. Update docs/reports/_index.md if the release changes the fingerprint baseline.

Rollback Strategy

Delete a bad tag (before others have pulled it)

git tag -d vX.Y.Z
git push origin :refs/tags/vX.Y.Z

Hotfix after a bad release

git checkout -b hotfix/vX.Y.Z+1 vX.Y.Z
# apply fix
git tag -a vX.Y.Z+1 -m "Hotfix release vX.Y.Z+1"
git push origin hotfix/vX.Y.Z+1 vX.Y.Z+1

Open a PR from hotfix/vX.Y.Z+1 into main. Do not skip review.