AI-Driven Changelog

Set up a changelog system where AI coding agents write entries under ## [Unreleased] during development, and automation stamps version numbers at release time. No agent ever writes version numbers; the build process handles that.

Setup workflow

1. Detect the build system: Check for Makefile, Justfile, package.json, Cargo.toml, pyproject.toml, go.mod. Note which config files contain a "version" field.

2. Detect the versioning scheme by inspecting (highest confidence first):

   • CHANGELOG.md heading style: ## [YYYY.M.N] headings → CalVer; ## [X.Y.Z] headings or prose mentioning "SemVer" → SemVer
   • Git tags from git tag --list | head: vX.Y.Z → SemVer; YYYY.M.N → CalVer
   • VERSION file with content matching ^[0-9]+\.[0-9]+\.[0-9]+ → SemVer
   • Manifest version field (package.json, Cargo.toml, pyproject.toml) matching X.Y.Z → SemVer

   If signals are absent or contradictory, ask the user. Suggest SemVer for projects with established version history (existing tags, manifest versions, prior changelog entries) and CalVer for greenfield projects where automatic versioning is preferable. Each scheme has trade-offs documented in its reference file.

3. Read the scheme reference that matches the chosen scheme. It contains the build integration recipes, CLAUDE.md snippet, GitHub Actions pattern, and scheme-specific gotchas:

   • CalVer → references/calver.md
   • SemVer → references/semver.md