Plugin Versioning¶

How versioning works in the VisiTrans Claude Toolkit, including version bumps, changelogs, session-start notifications, and finalize gate enforcement.

How it works¶

Each plugin has its own independent semantic version (semver). The single source of truth for all plugin versions is plugins/registry.json.

{
  "plugins": {
    "core-standards": { "version": "3.1.0", ... },
    "finance": { "version": "0.1.0", ... },
    "ims": { "version": "1.0.0", ... }
  }
}

Each plugin also declares its version in .claude-plugin/plugin.json. Both files must always agree.

Semantic versioning rules¶

Bump	When	Example
MAJOR	Breaking changes (renamed skills, removed commands, changed behavior)	2.0.0 → 3.0.0
MINOR	New features, new skills/agents, non-breaking enhancements	3.0.0 → 3.1.0
PATCH	Bug fixes, typo corrections, minor adjustments	3.1.0 → 3.1.1

Session-start notifications¶

When a user starts a new Claude Code session, the toolkit compares plugin versions against the user's last-seen state (stored in ~/.claude/plugin-versions/). If versions have changed, a notification is displayed:

## Plugin Updates

**core-standards** 3.0.0 → 3.1.0 MINOR
  - Extract IMS agents and skills into independent ims plugin

This is powered by scripts/check-plugin-versions.sh and scripts/session-start.sh.

For contributors: how to bump versions¶

When you change plugin code (skills, agents, scripts, commands), follow these steps before merging:

1. Determine the bump type¶

Did you rename, remove, or change the behavior of existing skills/commands? → MAJOR
Did you add new skills, agents, or features? → MINOR
Did you fix bugs or make small corrections? → PATCH

2. Update `plugins/registry.json`¶

Change the version for the affected plugin:

"core-standards": {
  "version": "3.2.0",
  ...
}

3. Update `plugin.json`¶

Update the version in plugins/{name}/.claude-plugin/plugin.json to match:

{
  "version": "3.2.0",
  ...
}

4. Add a changelog entry¶

Add a new section to plugins/{name}/CHANGELOG.md:

## [3.2.0] - 2026-02-25

### Added
- Finalize gate version enforcement (SPEC-023)
- New check-finalize-versions.sh script

### Changed
- /vt-c-5-finalize now includes version gate check

Use these subsection headers as needed: - ### Added — new features - ### Changed — changes to existing features - ### Fixed — bug fixes - ### Breaking — breaking changes (triggers a warning if bump is not MAJOR) - ### Removed — removed features

What the finalize gate checks¶

The /vt-c-5-finalize skill runs a version gate check (Step 0c) before other finalization checks. It verifies:

Version bump exists — If plugin code files changed compared to main, the version in registry.json must be different from main's version.
Changelog entry exists — A ## [x.y.z] section matching the new version must exist in the plugin's CHANGELOG.md.
Version sync — The version in plugin.json must match registry.json.
Breaking change consistency — If the changelog contains ### Breaking but the version bump is MINOR or PATCH, a warning is displayed (non-blocking).

What does NOT require a version bump¶

Changes to specs/ (spec/plan/task files)
Changes to docs/ (project documentation)
Changes to root files (README.md, CLAUDE.md, etc.)
Changes to .design-state.yaml or gate files
Changes only to plugins/registry.json itself

Troubleshooting finalize gate failures¶

Error	Fix
"Version bump required. Current: X, Main: X"	Bump the version in `plugins/registry.json`
"CHANGELOG.md missing ## [x.y.z] section"	Add a changelog entry for the new version
"Version mismatch. registry.json: X, plugin.json: Y"	Update `plugin.json` to match `registry.json`
"Breaking changes detected but version bump is MINOR"	Consider changing to a MAJOR bump, or proceed if intentional
"Not found in plugins/registry.json"	Add the plugin to `plugins/registry.json`