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

```bash
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.

```bash
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:

```bash
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 a