versioning

name	versioning
description	Version bumping, changelog generation, release automation, and tool detection for multi-file projects: SemVer strategy, tool-agnostic detection logic, flag mapping for common versioning tools, breaking change guidelines for textual/config ecosystems. Triggers: bumping versions, generating changelogs, configuring release automation, choosing a versioning tool, defining breaking changes in a non-library project.
allowed-tools	["Read","Bash","Grep","Glob"]
compatibility	Claude Code

Versioning

Domain knowledge for version management, changelog generation, and release automation across versioning tools and project types.

Satellite files (loaded on-demand):

• references/commitizen.md -- Commitizen config reference, version_files patterns, PEP 440 pre-release workflow, common flags, GitHub Actions integration

Tool Detection

Detect the active versioning tool from project configuration files. Check in priority order (first match wins):

Config Signal	Tool	Bump Command
[tool.commitizen] in pyproject.toml	Commitizen	cz bump
[tool.semantic_release] in pyproject.toml	python-semantic-release	semantic-release version
[tool.bumpversion] in pyproject.toml	bump-my-version	bump-my-version bump
.release-please-manifest.json	Release Please	PR-based (different flow)
knope.toml	Knope	knope release
package.json with semantic-release dep	semantic-release (JS)	npx semantic-release

Detection procedure:

1. Read pyproject.toml -- check for [tool.commitizen], [tool.semantic_release], [tool.bumpversion] sections
2. Check for .release-please-manifest.json at the project root
3. Check for knope.toml at the project root
4. Check package.json for semantic-release in devDependencies or dependencies
5. If no tool detected, report to the user and suggest configuring one

Flag Mapping

Map user intent to tool-specific CLI flags. The /release command uses this table to translate intent into the correct invocation.

Intent	Commitizen	python-semantic-release	bump-my-version	Knope	semantic-release (JS)
auto	cz bump --changelog	semantic-release version	N/A (requires explicit part)	knope release	npx semantic-release
patch	cz bump --increment PATCH --changelog	semantic-release version --patch	bump-my-version bump patch	N/A	N/A
minor	cz bump --increment MINOR --changelog	semantic-release version --minor	bump-my-version bump minor	N/A	N/A
major	cz bump --increment MAJOR --changelog	semantic-release version --major	bump-my-version bump major	N/A	N/A

Notes:

• Release Please uses a PR-based flow -- there is no direct bump command. Merging the release PR triggers the version bump.
• Knope and semantic-release (JS) auto-detect the bump type from commit history. Explicit increment overrides are not supported.
• All tools except bump-my-version support auto-detection from conventional commits.

Breaking Change Guidelines

For textual and configuration projects (Markdown skills, agent prompts, rules, commands, hooks, plugin manifests), "breaking" requires an explicit definition since there is no compiled API to analyze.

MAJOR (breaking)

• Skill or agent renamed or removed (breaks activation by name)
• Command renamed or removed (breaks /<command> invocation)
• Rule file renamed or removed (breaks rules/ symlink paths)
• MCP server API changed (breaks hook integrations and client callers)
• plugin.json structural change (breaks marketplace install or plugin cache resolution)

MINOR (feature)

• New skill, agent, command, or rule added
• New reference file added to an existing skill
• New MCP server tool or resource
• Enhanced prompt or instruction that adds capability without changing existing behavior
• New hook event handler

PATCH (fix)

• Bug fix in hooks, scripts, or MCP server code
• Typo or documentation correction
• Prompt refinement that preserves existing behavior
• Dependency update in Python subprojects

Ambiguous Cases

When a change spans multiple categories, use the highest applicable level. When in doubt between MINOR and MAJOR, ask: "Would a user who pinned the previous version encounter breakage if they upgrade?" If yes, it is MAJOR.

Gotchas

• Commitizen version_files uses substring matching. The :version suffix in a version_files entry means "find the substring version on a line and replace the version string on that line." This works for both TOML (version = "1.0.0") and JSON ("version": "1.0.0"). However, if a file has multiple lines containing the word version with version-like strings, Commitizen may update the wrong one. Ensure each target file has an unambiguous version field.

• major_version_zero = true changes bump semantics. When enabled, feat commits produce MINOR bumps instead of MAJOR, and breaking-change commits (a feat with a trailing bang, or a BREAKING CHANGE footer) produce MINOR instead of MAJOR. This keeps the project in the 0.x range during early development. Disable it (or remove the setting) when ready to release 1.0.0.

• Commitizen requires a baseline tag. The first cz bump fails if no tag matching tag_format exists in git history. Bootstrap with a manual tag (git tag -a v0.0.1 -m "Bootstrap") before running any bump commands.

• --dry-run does not check version_files accessibility. A cz bump --dry-run can succeed even if a version_files target path is wrong or the file is missing. The error only surfaces during an actual bump. Validate paths manually after configuration changes.

Version Strategy Patterns

Single-Version Monorepo

All components share one version. A single bump updates every version file. Best for projects where components are always deployed together (e.g., a plugin ecosystem).

Independent Versioning

Each component maintains its own version and changelog. Best for projects where components are published independently (e.g., a library collection).

Choosing a Strategy

• If users install the project as a unit, use single-version
• If users install individual components, use independent versioning
• If in doubt, start with single-version -- splitting later is easier than merging

Plugin Marketplace Publishing

When a project ships as a Claude Code plugin via an external marketplace manifest — a separate repo with .claude-plugin/marketplace.json pointing at the plugin's source — the marketplace version field is read by Claude Code as a cache key. Keep it equal to the plugin's released version: bump it in lockstep when the plugin tags a new release.

The simplest workflow is to make .claude-plugin/plugin.json a version_files target so cz bump rewrites it atomically alongside pyproject.toml. After tagging and pushing, update the external marketplace manifest to advertise the same version. Avoid keeping the marketplace manifest at a different version than the plugin's pyproject.toml — divergence breaks the cache-key contract.

Integration with Other Skills

• CI/CD -- release workflow design, GitHub Actions for automated bumps
• Python Project Management -- pyproject.toml configuration for tool sections