bump-plugin-version

Bump Plugin Version

Automate version bumps across the Agent Alchemy ecosystem. Scans 5 version locations per plugin, detects drift, applies consistent updates, adds a CHANGELOG entry, and creates a conventional commit.

CRITICAL: Complete ALL 6 phases. The workflow is not complete until Phase 6: Commit is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

Critical Rules

AskUserQuestion is MANDATORY

IMPORTANT: You MUST use the AskUserQuestion tool for ALL questions to the user. Never ask questions through regular text output.

• Plugin selection -> AskUserQuestion
• Bump level selection -> AskUserQuestion
• Drift resolution -> AskUserQuestion
• Confirmation prompts -> AskUserQuestion

Text output should only be used for:

• Displaying progress updates between phases
• Presenting inventory tables and drift reports
• Phase transition markers

If you need the user to make a choice or provide input, use AskUserQuestion.

NEVER do this (asking via text output):

Which plugins would you like to bump?
1. core-tools
2. dev-tools

ALWAYS do this (using AskUserQuestion tool):

AskUserQuestion:
  questions:
    - header: "Plugins"
      question: "Which plugins would you like to bump?"
      options:
        - label: "core-tools (0.1.1)"
          description: "Current version: 0.1.1"
        - label: "dev-tools (0.1.1)"
          description: "Current version: 0.1.1"
      multiSelect: true

Plan Mode Behavior

CRITICAL: This skill performs an interactive version bump workflow, NOT an implementation plan. When invoked during Claude Code's plan mode:

• DO NOT create an implementation plan for how to build the bumper
• DO NOT defer the version bump to an "execution phase"
• DO proceed with the full workflow immediately
• DO make file edits as normal

Phase Overview

Execute these phases in order, completing ALL of them:

1. Discovery — Read marketplace.json, build plugin inventory with current versions
2. Drift Check — Scan all 5 version locations for inconsistencies
3. Selection — Choose plugins and bump level, compute new versions
4. Bump — Edit all 5 version locations per plugin
5. Changelog — Add entries under ## [Unreleased] in CHANGELOG.md
6. Commit — Stage modified files and create a conventional commit

Phase 1: Discovery

Goal: Read the marketplace registry and build a complete plugin inventory.

Step 1: Parse Arguments

Parse $ARGUMENTS for:

• --plugin <group,...> — Comma-separated list of plugin groups to bump (e.g., --plugin core-tools,dev-tools). Default: prompt for selection in Phase 3.
• --level patch|minor|major — Bump level. Default: prompt for selection in Phase 3.
• --dry-run — Show what would change without modifying files. Default: false.

Set variables:

• PLUGIN_FILTER from --plugin value (default: null = prompt in Phase 3)
• BUMP_LEVEL from --level value (default: null = prompt in Phase 3)
• DRY_RUN from --dry-run flag (default: false)

Step 2: Load Marketplace Registry

Read the marketplace registry:

Read: ${CLAUDE_PLUGIN_ROOT}/../../.claude-plugin/marketplace.json

Build a plugin map from the plugins array:

{
  group_name -> {
    marketplace_name: "agent-alchemy-{group}",
    version: "x.y.z",
    source_dir: "{group}"
  }
}

The group_name is derived from the source field by stripping the leading ./.

Step 3: Display Inventory

Display the current plugin inventory:

[Phase 1/6] Plugin Inventory

| Plugin | Marketplace Name | Current Version |
|--------|-----------------|-----------------|
| core-tools | agent-alchemy-core-tools | 0.1.1 |
| dev-tools | agent-alchemy-dev-tools | 0.1.1 |
| sdd-tools | agent-alchemy-sdd-tools | 0.1.2 |
| tdd-tools | agent-alchemy-tdd-tools | 0.1.0 |
| git-tools | agent-alchemy-git-tools | 0.1.0 |
| plugin-tools | agent-alchemy-plugin-tools | 0.1.0 |

Phase 2: Drift Check

Goal: Scan all 5 version locations and detect inconsistencies against marketplace.json (the source of truth).

Version Locations

For each plugin, versions appear in up to 5 locations:

| # | File | Description | |---|------|-------------| | 1 | claude/.claude-plugin/marketplace.json | Source of truth — JSON "version" field | | 2 | CLAUDE.md (root) | Plugin Inventory table — \| {group} \| ... \| {version} \| | | 3 | docs/index.md | Project Status table — \| {Display Name} \| {version} \| {status} \| | | 4 | docs/plugins/index.md | At a Glance table — \| [{Name}](...) \| ... \| {version} \| | | 5 | docs/plugins/{group}.md | Per-plugin doc file — format varies (see Per-Plugin Formats below) |

Per-Plugin Doc Formats (Location 5)

Each plugin doc uses a different version format. When scanning, look within the first 15 lines:

| Plugin | Format | Example | |--------|--------|---------| | core-tools | Parenthetical in prose + vertical table | Core Tools (v0.1.1) provides... and \| Version \| 0.1.1 \| | | dev-tools | Bold metadata line | Version: 0.1.1 \| Skills: ... | | sdd-tools | Bold metadata with plugin name | Plugin: ... \| Version: 0.1.2 \| ... | | tdd-tools | Backtick-wrapped parenthetical | ` (v0.1.0) in prose | | git-tools | Bold metadata line | Version: 0.1.0 \| Skills: ... | | plugin-tools | Bold metadata with plugin name | Plugin: ... \| Version: 0.1.0 \| ...` |

Step 1: Scan All Locations

For each plugin in the inventory:

1. Location 2 (CLAUDE.md): Read the Plugin Inventory table. Find the row matching the plugin group name. Extract the version from the last column.

1. Location 3 (docs/index.md): Read the Project Status table. Find the row matching the plugin's display name. Extract the version. Note: not all plugins may be listed here — skip silently if absent.

1. Location 4 (docs/plugins/index.md): Read the At a Glance table. Find the row matching the plugin name. Extract the version from the Version column.

1. Location 5 (docs/plugins/{group}.md): Read the first 15 lines. Search for the version string using the format described in Per-Plugin Formats above.

Compare each found version against the marketplace.json version (Location 1). Record any mismatches.

Step 2: Present Drift Report

[Phase 2/6] Version Drift Check

✓ No drift detected — all locations consistent.

Or if drift is found:

[Phase 2/6] Version Drift Check

| Plugin | Location | Expected | Found |
|--------|----------|----------|-------|
| core-tools | docs/plugins/core-tools.md | 0.1.1 | 0.1.0 |
| dev-tools | CLAUDE.md | 0.1.1 | 0.1.0 |

Step 3: Resolve Drift (if any)

If drift was detected, present resolution options via AskUserQuestion:

AskUserQuestion:
  questions:
    - header: "Drift"
      question: "Version drift detected in N locations. How should we proceed?"
      options:
        - label: "Fix drift first"
          description: "Update drifted locations to match marketplace.json before bumping"
        - label: "Ignore and bump"
          description: "Proceed with version bump — drifted locations will be overwritten with new version"
        - label: "Abort"
          description: "Stop the workflow to investigate manually"
      multiSelect: false

If Fix drift first: Use Edit to update each drifted location to match marketplace.json, then continue to Phase 3.

If Ignore and bump: Continue to Phase 3. The bump will overwrite with the new version anyway.

If Abort: Display the drift details and exit.

Phase 3: Selection

Goal: Determine which plugins to bump and the bump level. Compute new versions.

Step 1: Select Plugins

If PLUGIN_FILTER was provided via --plugin, use those plugins. Validate each against the inventory — warn and skip any that don't exist.

Otherwise, present a multi-select via AskUserQuestion listing al