semver-setup

name	semver-setup
description	Interactive setup wizard for semantic versioning enforcement. Creates or updates .claude-plugin/semver.json with version files, trigger strategy, and enforcement rules. Run this command to configure SemVer for your project. Keywords: setup semver, configure versioning, version config, semver setup, version bump config.

Semver Setup

Configure semantic versioning enforcement for this project.

Steps

1. Detect existing config and version files

Check for existing configuration:

• Read .claude-plugin/semver.json if present (use as defaults for all questions)
• Auto-detect common version files in the project root: package.json, pyproject.toml, Cargo.toml, .claude-plugin/plugin.json, version.txt
• For monorepos: also scan one level deep (e.g., packages/*/package.json)

Show the user what was found.

2. Ask: which version files to track

Use AskUserQuestion with multiSelect: true. List detected files with descriptions:

• package.json — npm/Node.js projects
• pyproject.toml — Python projects (field: project.version or tool.poetry.version)
• Cargo.toml — Rust projects (field: package.version)
• .claude-plugin/plugin.json — Claude Code plugins (field: version)
• Other: ask user to enter path manually

For each selected file, ask:

• Field path (dot notation for nested) — default by file type: version for JSON, project.version for pyproject.toml, package.version for Cargo.toml
• Format — json / toml / yaml / text (auto-detected from extension if possible)

3. Ask: trigger strategy

Use AskUserQuestion (single select):

• auto — Claude evaluates each change and decides. New feature → MINOR, bug fix → PATCH, breaking change → MAJOR, docs/config only → skip. (Recommended)
• always — Every commit with source file changes must include a version bump. No exceptions. Good for strict release workflows.

4. Ask: enforcement level

Use AskUserQuestion (single select):

• ask — Warn and ask for confirmation before proceeding without a bump. (Default)
• deny — Block commit/push/PR until a version bump is staged.
• allow — No enforcement. Only session rules, no hook blocking.

5. Ask: base branch

Use AskUserQuestion (single select):

• main (Default)
• master
• develop
• Other (user enters custom name)

6. Ask: exclude patterns

Show default patterns and let user customize:

Default exclusions (files that never require a version bump):

README.md, CHANGELOG.md, LICENSE, .gitignore, *.md, docs/**, .claude/**, .claude-plugin/**

Use AskUserQuestion — ask if user wants to add or remove any patterns.

7. Write config

Write .claude-plugin/semver.json with all chosen settings:

{
  "versionFiles": [
    { "path": "package.json", "field": "version", "format": "json" }
  ],
  "triggerStrategy": "auto",
  "baseBranch": "main",
  "enforcement": {
    "missingBump": "ask"
  },
  "commitFormat": "chore: bump version to {version}",
  "excludePatterns": ["README.md", "CHANGELOG.md", "LICENSE", ".gitignore", "*.md", "docs/**", ".claude/**", ".claude-plugin/**"]
}

Create .claude-plugin/ directory if it doesn't exist.

8. Show confirmation

Display:

• Path written: .claude-plugin/semver.json
• Summary of settings (version files, strategy, enforcement, base branch)
• Next steps:

Next steps:
1. git add .claude-plugin/semver.json && git commit -m "chore: add semver config"
2. Push to share enforcement rules with your team
3. Run /semver:guide for the full SemVer 2.0.0 reference