Prepare Release

Automate the full release workflow: create a release/* branch, bump version files, draft changelog, commit, push, and open a PR targeting main.

Path Convention

{PLUGIN_ROOT} = Plugin root directory (where .claude-plugin/plugin.json lives)

When this skill references files like {PLUGIN_ROOT}/lib/patterns/version-discovery.md, read from the plugin root, not relative to this skill folder.

Scope

Relationship to pr-version-bump

This skill reuses the same version analysis logic (Phases 2-4 of pr-version-bump) but adds release branch creation and enforces the release/* branching convention required by RELEASING.md.

Phase 1: CONTEXT

Establish the working context and validate preconditions.

Steps

1. Check for dirty working tree:

   git status --porcelain
   

   If output is non-empty, STOP with: "You have uncommitted changes. Commit or stash them before preparing a release."

2. Get current branch:

   git branch --show-current
   

3. Check if already on a release branch:

   • If current branch matches release/*: note this — skip Phase 3 (branch creation)
   • Otherwise: will create a new release branch in Phase 3

4. Ensure main is up to date:

   git fetch origin main
   

5. Identify merge base:

   git merge-base origin/main HEAD
   

6. Report context:

   Branch: feature/simplify_bootstrap
   Base: origin/main (diverged at abc1234)
   Action: Will create release branch
   

STOP: If working tree is dirty

Phase 2: VERSION

Determine the target version for this release.

If explicit version provided

If the user passed a version argument (e.g., /prepare-release 4.0.0):

• Validate it is valid semver (X.Y.Z)
• Strip leading v if present
• Skip to Phase 2 confirmation
• No change analysis needed

If no explicit version (auto-detect)

Reuse the analysis logic from pr-version-bump:

1. Read pattern references:

   • {PLUGIN_ROOT}/lib/patterns/version-discovery.md
   • {PLUGIN_ROOT}/lib/patterns/change-classification.md

2. Discover version infrastructure (pr-version-bump Phase 2):

   • Scan for version files: package.yaml, .claude-plugin/plugin.json
   • Extract current version
   • Detect changelog format

3. Analyze changes (pr-version-bump Phase 3):

   git log origin/main..HEAD --oneline --no-merges
   git diff origin/main...HEAD --stat
   git diff origin/main...HEAD --name-status
   

   • Classify changes using change-classification.md
   • Build evidence table

4. Recommend version (pr-version-bump Phase 4):

   • Determine bump level (MAJOR > MINOR > PATCH)
   • Calculate new version

STOP: Present version recommendation and wait for confirmation

## Version Recommendation

Current: 3.1.0 → Recommended: 3.2.0 (MINOR)

### Evidence
| Evidence | Source | Signal |
|----------|--------|--------|
| New workflow added | workflows/ diff | MINOR |

Accept 3.2.0, override, or cancel?

Offer choices:

• "Accept MINOR (3.2.0)" (or whatever was recommended)
• "Override to MAJOR (4.0.0)"
• "Override to PATCH (3.1.1)"
• "Cancel"

Phase 3: BRANCH

Create the release branch. Skip this phase if already on a release/* branch.

Steps

1. Create release branch from current HEAD:

   git checkout -b release/vX.Y.Z
   

2. Push with tracking:

   git push -u origin release/vX.Y.Z
   

3. Confirm:

   Created and pushed branch: release/vX.Y.Z
   

Phase 4: BUMP

Update version files and changelog, then commit.

Steps

1. Update version file(s):

   • package.yaml: update version: field
   • .claude-plugin/plugin.json: update "version": field
   • Any other version files discovered in Phase 2

2. Draft changelog entry:

   • Use Keep a Changelog format (matching existing CHANGELOG.md)
   • Place new entry after the header, before existing entries
   • Include today's date
   • Categorize changes:
     • ### 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 to each file.

STOP: Confirm before making file mutations

4. After user confirms, commit:

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

5. Push:

   git push
   

Phase 5: PR

Create a pull request targeting main.

Steps

1. Create PR:

   gh pr create --base main --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 Phase 4>
   
   ---
   Prepared by `/prepare-release`
   EOF
   )"
   

2. Capture PR URL from output.

Phase 6: REPORT

Summarize the release preparation.

## Release Prepared

- Branch: release/vX.Y.Z
- Version: A.B.C → X.Y.Z
- Files updated: package.yaml, .claude-plugin/plugin.json, CHANGELOG.md
- Commit: abc1234 "chore: Prepare release vX.Y.Z"
- 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
3. After merge, configure "Validate PR Source Branch" as a required status check on main (first time only)

Error Handling