/releasing

name: releasing
description: "Use when releasing a bundle-plugin, bumping versions, fixing version drift across manifests, setting up version sync infrastructure, updating CHANGELOG, publishing to marketplaces, or checking release readiness"
allowed-tools: Bash(bundles-forge bump-version *) Bash(bundles-forge audit-plugin *) Bash(bundles-forge audit-docs *)

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,