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 schema, script usage, version setup for new projects), read references/version-infrastructure.md. For distribution strategy options, read references/distribution-strategy.md.

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

Entry Detection

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 (or /plugin validate in a session) to verify plugin.json schema, skill/agent/command frontmatter, and hooks/hooks.json validity. Skip this step on other platforms — the inspector agent covers equivalent structural checks.

Full audit: Invoke bundles-forge:auditing (preferred — includes qualitative assessment via auditor subagent with 10-category scoring). Fallback: bundles-forge audit-plugin <target-dir> (automated checks only, no qualitative scoring).

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 for quality issues.

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 to identify the scope of changes.

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 output from Step 1 as a guide for what needs updating. After making fixes, re-run bundles-forge audit-docs to confirm all documentation is consistent.

Step 4: Local Testing

Before bumping the version, invoke bundles-forge:testing to verify the plugin works correctly in a real installation scenario:

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:

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 descripti