---
title: "Release Checklist"
description: "Sequential release gate validating build success, test suite, security checks, type checking, manifest counts consistency, and changelog presence. Each step reports pass/fail with remediation guidance. Manages version bumping, staging, and pre-push confirmation. Use when preparing a release."
---

<span className="badge badge-gray">Reference</span> <span className="badge badge-yellow">medium</span>

> **Auto-activated** — this skill loads automatically when Claude detects matching context.

<ContextualSkillSidebar slug="release-checklist" />


# Release Checklist

Sequential release gate for OrchestKit. Each step reports `[PASS]` or `[FAIL]`. Stop on first failure, suggest a fix, then continue after user confirmation.

Load details: `Read("$\{CLAUDE_SKILL_DIR\}/references/release-flow.md")` for why the order matters and hotfix guidance.

> **CC ≥ 2.1.118 (M122):** Pre-release gate now includes `claude plugin tag &lt;version&gt; --dry-run` to validate the manifest hierarchy. Add to the gate sequence after manifest count checks. See `src/skills/chain-patterns/references/plugin-tag.md`.

## Quick Reference

| Category | Rules | Impact | When to Use |
|----------|-------|--------|-------------|
| [Pre-Release Gates](#pre-release-gates) | 2 | CRITICAL | Before every release commit |
| [Release Commit](#release-commit) | 2 | HIGH | Staging, committing, tagging, pushing |

**Total: 4 rules across 2 categories**

## Quick Start

```bash
# Run all pre-release gates in order (stop on first failure)
npm run build && npm test && npm run test:security && npm run typecheck
bash src/skills/validate-counts/scripts/validate-counts.sh
git diff  # review before staging
```

## Pre-Release Gates

Must all pass before writing any release commit. See `rules/gate-build-and-test.md` and `rules/gate-counts-and-diff.md`.

| Step | Command | Rule File |
|------|---------|-----------|
| 1. Build | `npm run build` | `rules/gate-build-and-test.md` |
| 2. Tests | `npm test` | `rules/gate-build-and-test.md` |
| 3. Security | `npm run test:security` | `rules/gate-build-and-test.md` |
| 4. TypeScript | `npm run typecheck` | `rules/gate-build-and-test.md` |
| 5. Validate counts | `/validate-counts` | `rules/gate-counts-and-diff.md` |
| 6. Diff review | `git diff` | `rules/gate-counts-and-diff.md` |

## Release Commit

Steps after all gates pass. See `rules/commit-staging.md` and `rules/commit-tag-push.md`.

| Step | Action | Rule File |
|------|--------|-----------|
| 7. Changelog | Entry exists in `CHANGELOG.md` | `rules/commit-staging.md` |
| 8. Version bump | `package.json` + `CLAUDE.md` both updated | `rules/commit-staging.md` |
| 9. Stage files | `git add &lt;specific files&gt;` — never `-A` | `rules/commit-staging.md` |
| 10. Commit | `release: vX.Y.Z` conventional format | `rules/commit-tag-push.md` |
| 11. Tag | `git tag vX.Y.Z` | `rules/commit-tag-push.md` |
| 12. Push | Run `scripts/pre-push-confirm.sh` — confirm first | `rules/commit-tag-push.md` |

## Related Skills

- `validate-counts` — Count consistency check (step 5 of this checklist)
- `audit-skills` — Broader skill quality audit (run before major releases)
- `checkpoint-resume` — Rate-limit-resilient pipelines for long release sessions

## Common Mistakes

1. Running `npm test` before `npm run build` — tests run against stale dist
2. Using `git add -A` — accidentally stages secrets or unrelated in-progress work
3. Forgetting to bump `CLAUDE.md` version alongside `package.json`
4. Pushing without explicit user confirmation — irreversible on shared remotes
5. Skipping security tests — non-negotiable, even for patch releases


---

## Rules (4)

### Stage release files carefully to avoid accidentally committing secrets or debug artifacts — HIGH


## Release Staging Rules

### Version Consistency

Before staging, verify both version locations match the release version:

```bash
# Check package.json version
grep '"version"' package.json

# Check CLAUDE.md version line
grep 'Current' CLAUDE.md
```

Both must show the same version (e.g., `6.0.21`). If either is missing or wrong, update before staging.

Also check `CHANGELOG.md` has an entry for this version with a date and summary.

### Staging — Never `git add -A`

**Incorrect:**
```bash
git add -A          # Stages everything including secrets, temp files, unrelated changes
git add .           # Same problem — too broad
```

**Correct:**
```bash
git add src/hooks/src/my-changed-hook.ts \
        src/hooks/dist/ \
        plugins/ \
        CHANGELOG.md \
        package.json \
        CLAUDE.md \
        manifests/
```

### Expected Files to Stage for a Release

| File/Dir | Why |
|----------|-----|
| `src/` changed files | Source of the actual change |
| `src/hooks/dist/` | Compiled TypeScript |
| `plugins/` | Generated by `npm run build` |
| `manifests/` | If counts changed |
| `CHANGELOG.md` | Release entry |
| `package.json` | Version bump |
| `CLAUDE.md` | Version bump |

**Key rules:**
- Always `git add &lt;specific files&gt;` — name every file explicitly
- Never stage `.env`, `*.secret`, or anything not listed in the diff review
- Version in `package.json` and `CLAUDE.md` must match before staging


### Format release commits, tags, and pushes correctly for CI changelog and semver automation — HIGH


## Release Commit, Tag, and Push

### Commit Format

**Incorrect:**
```bash
git commit -m "version bump"       # Not conventional format
git commit -m "Release 6.0.21"    # Missing type prefix
git commit -m "release v6.0.21"   # Inconsistent — v prefix in message but not tag
```

**Correct:**
```bash
git commit -m "$(cat <<'EOF'
release: v6.0.21

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
EOF
)"
```

- Type: `release`
- No scope needed
- Include Co-Authored-By when working with Claude

### Tag

```bash
git tag v6.0.21
```

- Tag must exactly match `"version"` in `package.json` with a `v` prefix
- Use annotated tags for public releases: `git tag -a v6.0.21 -m "Release v6.0.21"`

### Push — Confirm With User First

**Always ask the user before running:**

```bash
git push --follow-tags
```

This pushes commits AND the version tag. On a shared remote this is effectively irreversible.

**Script available:** Run `scripts/pre-push-confirm.sh` to show the user a summary of what will be pushed and prompt for explicit confirmation before executing the push.

**Key rules:**
- Use `release:` type, not `chore:` or `version:` for release commits
- Tag with `v` prefix matching `package.json` version exactly
- NEVER push without explicit user confirmation — even if user said "go ahead" earlier in the conversation


### Pass build and test gates before release to prevent shipping broken artifacts — CRITICAL


## Build and Test Gates

All four checks must pass in order. Stop on first failure and suggest a fix before continuing.

### 1. Build

```bash
npm run build
```

- Pass: `plugins/` is populated, no errors printed
- Fail: check edits in `src/`, re-run. If interrupted mid-build, `plugins/` is left empty — re-run before retrying

### 2. Full Test Suite

```bash
npm test
```

- Pass: all test suites green
- Fail: fix failing tests; do not proceed

### 3. Security Tests

```bash
npm run test:security
```

**MUST pass. No exceptions.** Security failures block the release unconditionally.

### 4. TypeScript

```bash
npm run typecheck
```

- Pass: zero type errors in hooks TypeScript
- Fail: fix errors in `src/hooks/src/` then rebuild with `cd src/hooks && npm run build`

**Incorrect:**

```bash
# Running tests before building — tests validate stale plugins/
npm test
npm run build
```

**Correct:**

```bash
# Build first, then test against fresh output
npm run build
npm test
npm run test:security
npm run typecheck
```

**Key rules:**
- Run in order: build → test → security → typecheck
- Any single failure stops the checklist
- Do not skip security tests under any circumstance
- A failed build leaves `plugins/` empty — re-run `npm run build` before retrying count validation


### Validate counts and review diffs before release to catch manifest errors and stale edits — HIGH


## Count Validation and Diff Review

### Validate Counts

Run `/validate-counts` — verifies that hook/skill/agent counts in `manifests/ork.json` match actual files.

- Pass: counts consistent in `ork`
- Fail: update manifests or re-run `npm run build`, then retry

### Diff Review

```bash
git diff
```

Scan the full diff before staging anything. Verify:

**Correct:**
```
src/hooks/src/my-hook.ts          ← intended source edit
src/hooks/dist/hooks.mjs          ← regenerated dist
plugins/ork/hooks/dist/hooks.mjs  ← regenerated plugin dist
CHANGELOG.md                      ← new entry
package.json                      ← version bump
CLAUDE.md                         ← version bump
```

**Incorrect:**
```
src/hooks/src/my-hook.ts          ← whitespace-only edit (no-op)
.env                              ← secret accidentally staged
plugins/ork/something.md          ← direct edit to plugins/ (forbidden)
```

**Key rules:**
- No edits directly to `plugins/` — it is generated; changes there indicate an accidental direct edit
- No secrets, credentials, or `.env` files in the diff
- No no-op whitespace-only edits — revert them before committing
- `plugins/` dist files are expected if `npm run build` was run



---

## References (1)

### Release Flow

# Release Flow Overview

## What Constitutes a Release

A release is a version-tagged commit pushed to the remote `main` branch. It triggers:
- Automated changelog parsing (reads `CHANGELOG.md`)
- GitHub Release creation (if CI is configured)
- Plugin distribution (consumers pull the tagged version)

Every release must be reproducible: another developer should be able to check out the tag and get a working, tested plugin set.

## Why the Checklist Order Matters

```
Build → Test → Security → Typecheck → Validate Counts → Changelog/Version → Diff → Stage → Commit → Tag → Push
```

Each step depends on the previous:
- Tests are meaningless if run against a stale build
- Count validation reads `plugins/` — must build first
- Diff review happens after version bumps so the bump is included in what you stage
- Tag is created after commit so it points to the right SHA
- Push is last and irreversible — everything else must be confirmed first

## Plugin Consistency

OrchestKit ships as a single plugin:

| Plugin | Skills | Agents | Description |
|--------|--------|--------|-------------|
| `ork` | 69 | 38 | Full toolkit |

The `/validate-counts` step catches drift between `src/` and `manifests/ork.json`.

## Hotfix vs. Normal Release

For a hotfix (urgent patch from `main`):
1. Branch from the release tag: `git checkout -b hotfix/vX.Y.Z vX.Y.Z`
2. Apply the fix, run the full checklist
3. Bump patch version only
4. Merge back to `main` and `dev`

The checklist steps are identical — never skip them for hotfixes.

## Common Release Failures

| Symptom | Cause | Fix |
|---------|-------|-----|
| Count mismatch | Added skill/hook but didn't update manifest | Edit manifest, re-build |
| `plugins/` empty | Build interrupted or not run | `npm run build` |
| Security test fails | New hook introduced vulnerable pattern | Fix hook, do not bypass |
| Version mismatch | Bumped `package.json` but forgot `CLAUDE.md` | Update `CLAUDE.md` |
| Tag already exists | Ran `git tag` twice | `git tag -d vX.Y.Z` then re-tag |

