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.

See references/release-flow.md for why the order matters and hotfix guidance.

Quick Reference

Total: 4 rules across 2 categories

Quick Start

# 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.

Release Commit

Steps after all gates pass. See rules/commit-staging.md and 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:

# 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:

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

Correct:

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

Key rules:

• Always git add <specific files> — 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:

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:

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

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:

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

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

npm test

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

3. Security Tests

npm run test:security

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

4. TypeScript

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:

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

Correct:

# 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 match actual files across all three plugins.

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

Diff Review

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

Three-Plugin Consistency

OrchestKit ships three plugins from one source:

All three must have consistent counts in their manifests. The /validate-counts step catches drift between src/ and manifests/.

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