Releasing Bundle-Plugins

Overview

Orchestrate the complete release workflow for a bundle-plugin: verify quality, scan for security risks, check documentation consistency, review change coherence, test locally, bump versions, update documentation, and publish to target platforms.

Core principle: Release is a checkpoint, not a formality. Every release deserves the full pipeline — even "minor" version bumps can introduce drift or break platform installs. Users should complete all agent, skill, and workflow development before invoking this skill.

Skill type: Rigid — follow every step exactly. Releases have no room for improvisation.

For version management infrastructure details (

.version-bump.json

references/version-infrastructure.md

references/distribution-strategy.md

Announce at start: "I'm using the releasing skill to prepare this project for release."

Entry Detection

references/version-infrastructure.md

The Release Pipeline

0. Prerequisites  →  1. Pre-flight Checks  →  2. Address Findings
→  3. Change Review & Doc Sync  →  4. Local Testing
→  5. Version Bump  →  6. Release Notes
→  7. Final Verification  →  8. Publish

Step 0: Prerequisites

Verify all conditions before entering the pipeline. Hard requirements block the pipeline; soft requirements trigger warnings.

Hard requirements (must pass):

• The project is a bundle-plugin (has

  skills/

  directory and

  package.json

  )
• Working tree is clean —

  git status

  shows no uncommitted or unstaged changes. All development work (agents, skills, workflows) must be committed before releasing.
• The user knows the target version number (or wants help deciding)

Soft requirements (warn if missing):

• A recent audit report exists in

  .bundles-forge/audits/

  — if not, releasing runs a full audit in Step 1
• The current branch is

  main

  or

  master

  — if not, warn the user and ask for confirmation before proceeding
• The target version tag does not already exist — run

  git tag -l v<version>

  to verify

git status
git tag -l v<version>
git branch --show-current

If the working tree is dirty, instruct the user to commit all development work first. If the tag already exists, ask the user to choose a different version. If on a non-main branch, warn and ask for confirmation.

Step 1: Pre-flight Checks

Run all automated checks. If any critical issues are found, resolve them before continuing.

bundles-forge bump-version <target-dir> --check
bundles-forge audit-docs <target-dir>

Plugin validation (Claude Code only): If running in a Claude Code environment, run

claude plugin validate

/plugin validate

plugin.json

hooks/hooks.json

Full audit: Invoke

bundles-forge:auditing

bundles-forge audit-plugin <target-dir>

If audit status is FAIL, resolve critical issues before releasing. If security findings are critical, block the release.

Step 2: Address Findings

Present all findings to the user grouped by severity:

• Critical — must fix before release (broken cross-references, missing skills, security issues)
• Warning — recommend fixing, but user decides (documentation drift, missing from tables)
• Info — note for future, don't block release

For fixes, invoke

bundles-forge:optimizing

Step 3: Change Review & Doc Sync

This step requires AI judgment — it cannot be fully automated.

Change coherence review:

Read the diff from the last release tag to HEAD:

git diff $(git describe --tags --abbrev=0)..HEAD --stat
git diff $(git describe --tags --abbrev=0)..HEAD

If no prior tags exist, use

git log --oneline

Review all changed files for:

Present findings as a blocking report using the same Critical/Warning/Info severity model as Step 2. Critical items must be resolved before proceeding.

Documentation update:

After resolving coherence issues, sync project documentation:

1. docs/

   directory — Check each document references accurate skill names, script commands, and architecture descriptions. Fix any outdated content.

2. CLAUDE.md

   — Verify: skill count in Directory Layout, skill names in Lifecycle Flow, scripts in Commands section, agents in Agent Dispatch, platform manifests table.

3. AGENTS.md

   — Verify: Available Skills table matches

   skills/

   directory.

4. README.md

   and

   README.zh.md

   — Verify: Skills table, Agents table, Commands table, code blocks, and file links are consistent between both files and with the project state.

Use

bundles-forge audit-docs

bundles-forge audit-docs

Step 4: Local Testing

Before bumping the version, invoke

bundles-forge:testing

1. Generate a dev-marketplace and install the plugin locally
2. Verify hook smoke tests pass (SessionStart + any custom hooks)
3. Confirm all components (skills, agents) are discoverable
4. Run cross-platform readiness checks for all target platforms

If testing reveals critical issues, resolve them before proceeding to version bump.

For abbreviated hotfix releases, this step may be reduced to hook smoke tests only.

Step 5: Version Bump

Help the user choose the right version increment:

2.0.0-beta.1

2.0.0-rc.1

Pre-release versions follow semver pre-release syntax. The bump script accepts any valid version string — pre-release versions work the same as stable ones across all manifests.

bundles-forge bump-version <target-dir> <new-version>

This updates all declared files and runs an audit to catch any missed files. For the full command reference, read

references/version-infrastructure.md

Step 6: Release Notes

CHANGELOG.md — Add an entry for the new version using Keep a Changelog format:

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

### Added
- New skill: `bundles-forge:authoring` for skill authoring guidance

### Changed
- Improved descriptions for better triggering accuracy

### Fixed
- Version drift in Cursor manifest

CHANGELOG validation — After writing the entry, verify:

• Format follows Keep a Changelog (## [version] - date)
• Version number matches the bumped version
• Date is today's date (YYYY-MM-DD)
• No duplicate version entries exist in the file
• Categories are valid (Added, Changed, Deprecated, Removed, Fixed, Security)

README.md — Update if the release adds/removes skills, changes the workflow, or adds platform support.

Step 7: Final Verification

After all changes, re-run verification to confirm nothing broke:

bundles-forge bump-version <target-dir> --check
bundles-forge bump-version <target-dir> --audit
bundles-forge audit-docs <target-dir>

Step 8: Publish

Git + GitHub Release:

git add -A
git commit -m "release: v<version>"
git tag v<version>
git push origin main --tags

After pushing the tag, create a GitHub Release so the

/releases

gh release create v<version> --title "v<version>" --notes-file CHANGELOG-EXCERPT.md

Generate

CHANGELOG-EXCERPT.md

## [X.Y.Z]

gh release create

gh

https://github.com/<owner>/<repo>/releases/new?tag=v<version>

Platform-specific publishing:

claude plugin publish

Hotfix Releases

For urgent fixes between planned releases:

1. Fix the issue on main (or a hotfix branch)
2. Run abbreviated pipeline: version drift check + security scan + documentation consistency check (skip full audit)
3. Bump patch version
4. Update CHANGELOG with

   ### Fixed

   section
5. Publish

Common Mistakes

git status

bundles-forge audit-docs

/tags

/releases

gh release create

plugins.0.version

bundles-forge bump-version

Inputs

• project-directory

  (required) — bundle-plugin project root with committed skill content ready for release

Outputs

• version-tag

  — git tag (

  v<version>

  ) for the release

• changelog-entry

  — CHANGELOG.md update with categorized changes (Added, Changed, Fixed)

• github-release

  (optional) — GitHub Release with release notes, created via

  gh release create

Integration

Calls:

• bundles-forge:auditing — pre-release quality and security diagnostics
  • Artifact:

    project-directory

    →

    project-directory

    (direct match — releasing passes the project root for audit)
• bundles-forge:testing — pre-release dynamic verification (after audit, before version bump)
  • Artifact:

    project-directory

    →

    project-directory

    (direct match)
• bundles-forge:optimizing — orchestrate fixes for quality findings
  • Artifact:

    project-directory

    →

    audit-report

    (indirect — releasing passes audit findings, optimizing consumes them as

    audit-report

    )

Pairs with:

• bundles-forge:scaffolding — version infrastructure setup and platform sync