export default repo-release

name	repo-release
description	Prepare a plugin release with version bumping, CHANGELOG validation, and comprehensive consistency checks. Use when: (1) a plugin release is requested, (2) after completing a set of changes worth releasing, (3) before creating a git tag for a version, (4) when preparing to publish to marketplace, (5) after major feature additions or bug fixes, (6) when coordinating multi-plugin releases

Repo Release

Orchestrate a plugin release as a coherent publication event where changelog documentation, version metadata, and validation checks form an integrity chain that ensures users receive well-documented, consistent releases.

Instructions

1. Verify CHANGELOG documents the release. Read plugins/{plugin}/CHANGELOG.md to confirm the target version appears in the required format ## [X.Y.Z] - YYYY-MM-DD followed by change descriptions—the presence of documented changes establishes what users will understand about this release, while their absence signals that the release story remains untold. When the entry is missing, guide the user by diagnosing whether no CHANGELOG exists (create one with release notes), only an Unreleased section exists (move those changes to a versioned section), or the target version is absent (add the versioned section with change descriptions that explain what this release delivers).

2. Determine version increment through explicit specification, declared bump type, or CHANGELOG inference. Accept explicit version from the user if provided directly, or ask for bump type when they know the change scope, or infer from CHANGELOG content by scanning for keywords where "breaking change" or "remove" signal major, "add" or "new" signal minor, and "fix" or "patch" signal patch—these three paths converge on the semantic version increment that matches the nature of changes. Use .claude/scripts/bump-version.sh --plugin {plugin} --bump {type} to calculate the new version from current state, establishing the version number that will propagate through all metadata files.

3. Bump plugin version as the authoritative declaration. Update plugins/{plugin}/.claude-plugin/plugin.json with the new version using .claude/scripts/bump-version.sh --plugin {plugin} --bump {type} --apply and report the transition from old to new version—this file serves as the single source of truth that other metadata files will sync to, creating a release version that flows consistently through the entire publication chain.

4. Sync marketplace metadata to match the authoritative version. Update the corresponding entry in .claude-plugin/marketplace.json to reflect the new version so the marketplace presents the same version that users will actually install when they add the plugin—alignment between display and installation reality prevents the confusion that arises when version numbers diverge across metadata files.

5. Validate release integrity through comprehensive preflight checks. Invoke repo-preflight to verify consistency across versions, skill counts, changelogs, and skill references, then report all preflight results and proceed only when validation passes—validation before release preserves user trust by ensuring the published state is coherent, while releasing a broken state creates support burden that outweighs the value of shipping quickly.

6. Report release readiness with complete publication context. Summarize the version bump showing old and new versions, list files modified during release preparation, confirm CHANGELOG has proper entry documenting the changes, and provide commit message suggestion following conventional commit format—these elements together create a coherent picture of what will be committed, why the release is ready, and what users can expect from this version.

7. Create annotated release tags after changes reach origin. Once the release commit is pushed to origin, create annotated git tags for each released plugin using the format {plugin}-v{version} and push tags to origin with git push origin --tags—tags provide stable reference points for users installing specific versions, enable GitHub releases, and create a permanent historical record in the repository that marks when each version was released.

Workflow Steps

Step 1: CHANGELOG Validation

Read plugins/{plugin}/CHANGELOG.md and verify it contains an entry for the target version.

Required format:

## [X.Y.Z] - YYYY-MM-DD

- Change description
- Another change

Conditions requiring CHANGELOG updates:

• No CHANGELOG.md exists → Guide to create CHANGELOG.md with release notes
• Only ## [Unreleased] section → Guide to move changes from Unreleased to versioned section
• Target version missing → Guide to add ## [{version}] section with changes

Halt the release workflow if CHANGELOG is incomplete, providing guidance to document changes before proceeding.

Step 2: Version Determination

Three approaches:

Explicit version:

User: "Release thinkies as 2.0.0"
→ Use 2.0.0 directly

Bump type:

User: "Prepare a minor release for software"
→ Read current: 1.1.2
→ Apply minor bump: 1.2.0

Inferred from CHANGELOG:

Scan Unreleased section for keywords:
- "breaking change", "remove", "incompatible" → major
- "add", "new", "feature" → minor
- "fix", "patch", "bug" → patch

Use .claude/scripts/bump-version.sh for calculation:

.claude/scripts/bump-version.sh --plugin {plugin} --bump {type}

Step 3: Version Bumping

Apply the version change:

.claude/scripts/bump-version.sh --plugin {plugin} --bump {type} --apply

This updates plugins/{plugin}/.claude-plugin/plugin.json.

Report: "Bumped {plugin} version: {old} → {new}"

Step 4: Marketplace Sync

Update .claude-plugin/marketplace.json to match:

jq --arg plugin "{plugin}" --arg version "{new-version}" \
  '(.plugins[] | select(.name == $plugin) | .version) = $version' \
  .claude-plugin/marketplace.json

Step 5: Preflight Validation

Invoke repo-preflight skill for comprehensive checks:

• Version consistency (should pass after sync)
• Skill count accuracy
• CHANGELOG existence (should pass)

If preflight reports critical issues, halt release and guide to fixes.

Step 6: Release Readiness Report

Provide structured summary:

Release Readiness Report
========================

Plugin: {plugin}
Version: {old} → {new}
Bump type: {major/minor/patch}

Files modified:
✓ plugins/{plugin}/.claude-plugin/plugin.json
✓ .claude-plugin/marketplace.json

CHANGELOG verified:
✓ Version {new} documented with changes

Preflight results:
✓ All consistency checks passed

Status: Ready to commit and release

Suggested commit message:
chore(release): bump {plugin} to v{new}

After commit and push, create release tag:
git tag -a {plugin}-v{new} -m "Release {plugin} v{new}"
git push origin --tags

Release notes from CHANGELOG:
- [change 1]
- [change 2]

Step 7: Create Release Tags

After commit and push, create annotated tags for released plugins:

git tag -a {plugin}-v{version} -m "Release {plugin} v{version}"

For example:

git tag -a thinkies-v1.4.1 -m "Release thinkies v1.4.1"
git tag -a software-v1.1.1 -m "Release software v1.1.1"

Push tags to origin:

git push origin --tags

Tag naming convention: {plugin}-v{version} allows filtering tags by plugin (e.g., git tag -l "thinkies-v*") and clearly associates each tag with its plugin.

When to tag: Create tags only after the release commit is pushed to ensure the tag points to a commit that exists on the remote, which prevents orphaned tags if the push fails or is rejected.

Examples

Example: Minor release with CHANGELOG ready

User: "Prepare a release for thinkies"

Process: Read plugins/thinkies/CHANGELOG.md, find ## [Unreleased] with 3 new skills added. Ask: "I see 3 new skills in Unreleased. Should I create a minor release (recommended for new skills), a major release, or move Unreleased to a specific version?"

User: "Minor release"

Process continues: Check that Unreleased has content → Not versioned yet. Response: "Please update CHANGELOG.md by moving the Unreleased changes to a versioned section like:

## [1.4.0] - 2024-11-25

- Add decision-option-tradeoffs skill
- Add synthesis-connect-dots skill
- Add exploration-wonder skill

Then I can proceed with the release."

User updates CHANGELOG

Process continues: CHANGELOG has [1.4.0] section → Pass. Bump: 1.3.0 → 1.4.0. Sync marketplace.json. Run preflight → all pass. Report readiness.

Output:

Release Readiness Report
========================

Plugin: thinkies
Version: 1.3.0 → 1.4.0
Bump type: minor

Files modified:
✓ plugins/thinkies/.claude-plugin/plugin.json
✓ .claude-plugin/marketplace.json

CHANGELOG verified:
✓ Version 1.4.0 documented

Preflight results:
✓ All checks passed

Status: ✓ Ready to commit

Suggested commit message:
chore(release): bump thinkies to v1.4.0

Release notes:
- Add decision-option-tradeoffs skill
- Add synthesis-connect-dots skill
- Add exploration-wonder skill

Example: Halted release due to missing CHANGELOG

User: "Release software plugin version 1.2.0"

Process: Check plugins/software/CHANGELOG.md. No section for 1.2.0 found. Halt release.

Output:

Release Halted
==============

CHANGELOG.md missing entry for version 1.2.0

Required action:
Add a section to plugins/software/CHANGELOG.md:

## [1.2.0] - 2024-11-25

- [Describe what changed]
- [Describe what changed]

Once documented, retry the release.

Example: Patch release with auto-inference

User: "Patch release for expression—fixed a typo in epistemic-clarity skill"

Process: Check CHANGELOG has [0.1.1] section documenting the fix → Pass. Infer patch from user's "fixed" language. Bump: 0.1.0 → 0.1.1. Sync marketplace. Run preflight. Report readiness.

Output:

Release Readiness Report
========================

Plugin: expression
Version: 0.1.0 → 0.1.1
Bump type: patch (inferred from fix)

Files modified:
✓ plugins/expression/.claude-plugin/plugin.json
✓ .claude-plugin/marketplace.json

CHANGELOG verified:
✓ Version 0.1.1 documented

Preflight results:
✓ All checks passed

Status: ✓ Ready to commit

Suggested commit message:
chore(release): bump expression to v0.1.1

Release notes:
- Fix typo in epistemic-clarity skill instructions