releasing

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

| Context | Path | |---------|------| | User wants to release a version, provides a project directory | Path 1: Standard release — run the full pipeline below | | Urgent fix with small changes | Path 2: Hotfix release — run the abbreviated pipeline (see Hotfix Releases) | | Project needs version infrastructure for the first time | Path 3: Version setup — read references/version-infrastructure.md § Version Setup |

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:

| Check | What to Look For | Severity | |-------|-----------------|----------| | Contradictions | File A says "supports 5 platforms", file B says "supports 4 platforms" | Critical | | Redundancy | Two SKILL.md files with large duplicated sections | Warning | | Over-engineering | Complex abstraction for a simple feature, unnecessary indirection layers | Warning | | Missing registrations | New skill added but not in bootstrap routing, AGENTS.md, or README tables | Critical | | Stale references | Renamed skill but old name still used in prose | Critical |

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:

| Change Type | Version Bump | Example | |-------------|-------------|---------| | Breaking changes to skill behavior or structure | Major (X.0.0) | Renamed skills, changed workflow chain | | New skills, new platform support, significant improvements | Minor (0.X.0) | Added a skill, added Gemini support | | Bug fixes, description improvements, doc updates | Patch (0.0.X) | Fixed description, updated README | | Testing a major release before stabilizing | Pre-release (X.Y.Z-beta.N) | 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 page has release notes and notifies watchers:

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

Generate CHANGELOG-EXCERPT.md from the current version's CHANGELOG.md section (the ## [X.Y.Z] block written in Step 6). Delete the excerpt file after gh release create succeeds. If gh CLI is unavailable, instruct the user to create the release manually from the GitHub web UI at https://github.com/<owner>/<repo>/releases/new?tag=v<version>.

Platform-specific publishing:

| Platform | Command | |----------|---------| | Claude Code | claude plugin publish (if marketplace-ready) | | Cursor | Submit through Cursor plugin marketplace | | Codex | Users pull from git — GitHub Release is sufficient | | OpenCode | Users pull from git — GitHub Release is sufficient | | Gemini CLI | Users install from git URL — GitHub Release is sufficient |

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

| Mistake | Fix | |---------|-----| | Releasing with uncommitted changes | Always verify git status is clean before starting the pipeline | | Releasing without running audit | Always run full pipeline — "it's just a small change" is how drift happens | | Skipping documentation consistency check | bundles-forge audit-docs catches skill list drift, broken cross-refs, README desync | | Not reviewing changes for coherence | Read the full diff since last tag — contradictions and missing registrations are invisible to automated checks | | Forgetting to tag the release | Tags are how git-based platforms identify versions | | Only pushing a tag without creating a GitHub Release | Tags appear on /tags but not /releases — use gh release create to publish release notes and notify watchers | | Bumping version before fixing issues | Fix first, bump second — avoid releasing a known-broken version | | Skipping CHANGELOG update | Users need to know what changed, especially for breaking changes | | Not re-verifying after fixes | Changes to fix issues can introduce new drift | | Forgetting marketplace.json entry | plugins.0.version field needs tracking too | | Manual editing without bump command | Always use bundles-forge bump-version — it runs audit after | | Releasing from non-main branch without awareness | Not blocked, but should be an explicit decision |

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