PR Version Bump

Phase 1: CONTEXT

Establish the working context.

Steps

1. Verify not on main branch:

   git branch --show-current
   

   If on main or master, STOP with: "Switch to a feature branch first. Version bumps should not be done directly on main."

2. Identify base branch:

   git merge-base main HEAD
   

   This is the point where the current branch diverged from main.

3. Detect mode from user input:

   • Empty / "prepare" / "bump" → Prepare mode
   • "finalize" / "verify" / "check" → Finalize mode

4. Report context:

   Branch: feature/my-feature
   Base: main (diverged at abc1234)
   Mode: Prepare
   

STOP: If on main branch

Phase 2: DISCOVER

Scan the repository for version infrastructure.

Steps

1. Read pattern reference: Read {PLUGIN_ROOT}/lib/patterns/version-discovery.md for the detection algorithm.

2. Scan for version files in priority order:

   • package.yaml → look for version: field
   • package.json → look for "version": field
   • pyproject.toml → look for version = field
   • .claude-plugin/plugin.json → look for "version": field
   • Cargo.toml, setup.cfg, VERSION

3. Scan for changelog:

   • CHANGELOG.md, CHANGES.md, HISTORY.md
   • Detect format (Keep a Changelog, conventional, other)

4. Extract semver rules from:

   • CLAUDE.md → look for ## Versioning section
   • RELEASING.md → look for semantic versioning guidance
   • CONTRIBUTING.md → look for versioning section

5. Detect release automation:

   • scripts/release.sh
   • .github/workflows/release.yaml
   • Makefile or Justfile release targets

6. Check for additional version files that should stay in sync:

   • If package.yaml has version, also check .claude-plugin/plugin.json
   • Flag any mismatches

STOP: Present discovery summary for confirmation

## Version Infrastructure

| Component | Found | Details |
|-----------|-------|---------|
| Version file | package.yaml | v3.0.0 |
| Changelog | CHANGELOG.md | Keep a Changelog format |
| Semver rules | CLAUDE.md | 5 rules extracted |
| Release script | scripts/release.sh | Tag-based release |
| Additional version files | .claude-plugin/plugin.json | v3.0.0 (in sync) |

Phase 3: ANALYZE

Examine all changes since branching from main.

Steps

1. Read pattern reference: Read {PLUGIN_ROOT}/lib/patterns/change-classification.md for the classification algorithm.

2. Collect commit history:

   git log main..HEAD --oneline --no-merges
   

3. Collect diff summary:

   git diff main...HEAD --stat
   git diff main...HEAD --name-status
   

4. Classify changes using the pipeline from change-classification.md:

   • Apply repository-specific rules (from Phase 2) first
   • Parse conventional commit prefixes
   • Apply file-level heuristics as fallback
   • Apply blueprint-lib-specific heuristics if type YAML files changed

5. Build evidence table:

   Evidence	Source	Bump Signal
   ...	...	...

STOP: Present change analysis summary

Phase 4: RECOMMEND

Map classified changes to a semver recommendation.

Steps

1. Determine bump level:

   • Take the highest signal from the evidence table
   • MAJOR > MINOR > PATCH

2. Calculate new version:

   • Current: X.Y.Z (from Phase 2)
   • MAJOR → X+1.0.0
   • MINOR → X.Y+1.0
   • PATCH → X.Y.Z+1

3. Present recommendation:

   ## Recommendation: MINOR bump
   
   Current: 3.0.0 → Recommended: 3.1.0
   
   ### Evidence
   | Evidence | Source | Signal |
   |----------|--------|--------|
   | New consequence type `foo` added | consequences.yaml diff | MINOR |
   | feat: Add foo consequence | commit abc1234 | MINOR |
   
   ### Reasoning
   New type added with no breaking changes. All existing types unchanged.
   

4. Offer override:

   • "Accept MINOR (3.1.0)"
   • "Override to MAJOR (4.0.0)"
   • "Override to PATCH (3.0.1)"
   • "Skip version bump"

STOP: Wait for user to select bump level

Phase 5: EXECUTE

Apply the version bump and draft changelog.

Only runs in Prepare mode. In Finalize mode, skip to Phase 6.

Steps

1. Update version file(s):

   • Update the primary version file (e.g., package.yaml)
   • Update any additional version files found in Phase 2 (e.g., .claude-plugin/plugin.json)

2. Draft changelog entry:

   • Use the format detected in Phase 2
   • Place new entry after the changelog header, before existing entries
   • Include today's date
   • Categorize changes using Keep a Changelog sections:
     • ### Added - New features
     • ### Changed - Changes to existing functionality
     • ### Fixed - Bug fixes
     • ### Removed - Removed features
     • ### BREAKING CHANGES - For MAJOR bumps

3. Present draft for review: Show the exact changes that will be made to each file.

4. After user confirms, commit:

   git add <version-files> <changelog>
   git commit -m "chore: Prepare release vX.Y.Z"
   

5. Push branch to remote:

   git push -u origin <branch-name>
   

6. Create pull request: Reference {SKILL_ROOT}/resources/pull-requests.md for gh pr create syntax.

   gh pr create --title "Release vX.Y.Z" --body "$(cat <<'EOF'
   ## Summary
   
   Version bump: A.B.C → X.Y.Z (MAJOR|MINOR|PATCH)
   
   ### Changelog
   
   <paste changelog entry from step 2>
   
   ---
   Prepared by `/pr-version-bump`
   EOF
   )"
   

   Capture and store the PR URL from the output.

STOP: Confirm before making file mutations

Phase 6: REPORT

Summarize what was done and offer next steps.

Prepare Mode Report

## Version Bump Complete

- Version: 3.0.0 → 3.1.0
- Files updated: package.yaml, .claude-plugin/plugin.json
- Changelog: CHANGELOG.md updated with [3.1.0] entry
- Commit: abc1234 "chore: Prepare release v3.1.0"
- PR: https://github.com/hiivmind/hiivmind-blueprint-lib/pull/XX

### Next Steps

1. Review the PR and get approval
2. Merge the PR -- GitHub Actions will automatically create a tagged release

Finalize Mode Report

In Finalize mode, Phase 6 checks instead of executes:

1. Check version bumped:

   • Compare version in HEAD vs main
   • PASS if version is higher, FAIL if unchanged

2. Check changelog updated:

   • Look for an entry matching the new version number
   • PASS if found with content, FAIL if missing

3. Report results:

   ## Pre-Merge Verification
   
   | Check | Status | Details |
   |-------|--------|---------|
   | Version bumped | PASS | 3.0.0 → 3.1.0 |
   | Changelog entry | PASS | [3.1.0] - 2026-02-07 with 3 items |
   | Version files in sync | PASS | package.yaml and plugin.json both 3.1.0 |
   
   Ready to merge.
   

   Or if checks fail:

   ## Pre-Merge Verification
   
   | Check | Status | Details |
   |-------|--------|---------|
   | Version bumped | FAIL | Still 3.0.0 - no bump detected |
   | Changelog entry | FAIL | No [3.1.0] entry found |
   
   Run `/pr-version-bump prepare` to fix.
   

Error Handling