bump-plugin-version

What this skill does

# 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):
```yaml
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.

2. **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.

3. **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.

4. **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:

```yaml
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 a