Release

Release Pipeline

Orchestrate end-to-end releases with pre-flight validation, version bumping, PR creation, merge, and GitHub release — all in one flow.

When to Use

• User says "release", "ship it", "cut a release", or similar
• User wants to publish a new version to GitHub/npm/PyPI
• User is ready to merge dev to main and tag a release

Prerequisites

• Must be on dev branch (or have dev up to date)
• All feature work merged to dev via PRs
• Working tree clean (no uncommitted changes)

Arguments

Dry-Run Mode

When --dry-run or -n is passed, execute only Step 1 (version detection), then display a preview of every remaining step and exit. No mutations occur.

Risk Level: HIGH (modifies git history, creates PRs, publishes releases)

Dry-Run Output

After detecting the current and next version, display:

┌─────────────────────────────────────────────────────────────┐
│ /release --dry-run                                          │
├─────────────────────────────────────────────────────────────┤
│ Current version: v2.17.0                                    │
│ Next version:    v2.18.0 (minor — feat: commits detected)   │
├─────────────────────────────────────────────────────────────┤
│ Actions that WOULD be taken:                                │
│                                                             │
│  1. ✓ /craft:check --for release (full CI mirror)            │
│  2. ✓ Run pre-release-check.sh v2.18.0 (metadata)           │
│  3. ✓ Bump version in plugin.json, CLAUDE.md                │
│  3b. ✓ /craft:docs:update --post-merge (semantic doc sync)  │
│  3b.5 ✓ docs-staleness-check.sh --non-interactive (gate)   │
│  4. ✓ Commit: "chore: bump version to v2.18.0 for release"  │
│  5. ✓ Push to dev                                           │
│  6. ✓ Create PR: dev → main                                 │
│  6.5 ✓ CI monitoring (poll → diagnose → fix → retry)        │
│  7. ✓ Merge PR (--merge, NO --delete-branch)                │
│  8. ✓ Create GitHub release v2.18.0 on main                 │
│  9. ✓ mkdocs build --strict && mkdocs gh-deploy              │
│ 10. ✓ Update Homebrew tap (formula or cask)                 │
│      (10b if Tauri: build → upload → SHA256 → cask → tap)   │
│      (10b verify_caveats.py — advisory caveats gate)         │
│      (10c post_install_check.py — advisory structural gate)  │
│      (10d aggregator-sync.yml CI action — BLOCKING on unmerged PR)  │
│ 11. ✓ Sync dev with main                                    │
│ 12. ✓ Verify CI on main                                     │
│ 13. ✓ Verify downstream (docs, brew, badges, cask)          │
│ 13.5 ✓ Post-release sweep (Tier 2+ drift detection)        │
├─────────────────────────────────────────────────────────────┤
│ ⚠ Risk: HIGH — modifies git history, creates PRs            │
│ ⚠ No changes were made. Run without --dry-run to execute.   │
└─────────────────────────────────────────────────────────────┘

Dry-Run Guarantees

• No commits, tags, or pushes
• No PRs created or merged
• No GitHub releases published
• No docs deployed
• Exit code 0

Autonomous Mode (--autonomous)

When --autonomous or --auto is passed, the release pipeline runs without user interaction:

Full detail — safety checks, version-detection script, admin-override warning, error-recovery box, and flag combinations — is in references/autonomous-mode.md.

Release Pipeline

Execute these steps in order. Stop and report if any step fails. Full command-level detail for Steps 1–9 and 11–12 is in references/pipeline-steps.md.

Step 1: Determine Version

Detect current version from plugin.json / package.json / git describe. Analyze commits to suggest patch / minor / major bump. Ask user to confirm (skipped in autonomous mode).

Step 2: Pre-Flight Checks

2a /craft:check --for release — full CI mirror (tests, lint, security, docs, 90% coverage). 2b ./scripts/pre-release-check.sh <version> — release metadata consistency (craft projects). 2c claude plugin validate . — marketplace validation (if marketplace.json exists). Both must pass before proceeding. See pipeline-steps.md for fix guidance.

Step 3: Version Bump

./scripts/bump-version.sh <version>   # craft projects: updates 13 files atomically
./scripts/bump-version.sh --verify    # confirm consistency

For Python / Node / R projects, update manifest files manually.

Step 3b: Semantic Doc Updates

/craft:docs:update --post-merge

Updates CHANGELOG.md, VERSION-HISTORY.md, README.md, docs/index.md, docs/REFCARD.md, mkdocs.yml, commands/hub.md, and docs/commands/hub.md with release-specific content. Full table of what to update is in pipeline-steps.md.

Step 3b.5: Staleness Gate

./scripts/docs-staleness-check.sh --non-interactive

RED findings block; YELLOW findings warn but allow proceed. Fix any RED before Step 4. Run ./scripts/docs-staleness-check.sh --fix to auto-resolve mechanical staleness.

Step 4: Commit & Push

git add <changed-files>
git commit -m "chore: bump version to v<version> for release"
git push

Never use git add -A or git add . for release commits.

Step 5: Create Release PR

gh pr create --base main --head dev \
  --title "Release: v<version> — <title>" \
  --body "<release-notes>"

Avoid literal destructive git command strings in the PR body (branch guard scans them).

Step 6: Monitor CI on PR (MANDATORY)

Poll gh run list --branch dev every 30s until success or failure. Fix failures before merging. Full polling script and escalation path in pipeline-steps.md.

Step 6.5: CI Monitoring (NEW in v2.22.0)

bash scripts/ci-monitor.sh <pr-number> — polls, auto-fixes safe categories (version_mismatch, lint_failure, changelog_format), asks before risky ones. Configuration via .claude/release-config.json. Full category table and output format in pipeline-steps.md.

Step 7: Merge Release PR

gh pr merge <number> --merge

NEVER use --delete-branch — dev must not be deleted. Use --admin only after user confirmation if branch protection blocks. Autonomous mode: auto-uses --admin, logs a WARNING.

Step 8: Create GitHub Release

git pull origin main
gh release create v<version> --target main \
  --title "v<version> — <title>" \
  --notes "<release-notes>"

Include highlights, grouped changes, test count, and changelog comparison link.

Step 9: Post-Release (if applicable)

If docs site exists (mkdocs.yml, _quarto.yml, or docs/):

mkdocs build --strict && mkdocs gh-deploy  # or /craft:site:deploy

mkdocs build --strict fails on broken links and Jinja errors. Fix before deploying — a broken deploy is harder to roll back than a local build failure.

Step 10: Update Homebrew Tap (if applicable)

If the project has a Homebrew formula or cask in the data-wise/tap, update it with the new version. Detects formula vs. cask from .craft/homebrew.json → Tauri → git remote → basename fallback. Full detection script, Step 10a (formula update), and Step 10b (Tauri cask pipeline) are in references/homebrew.md.

Step 11: Sync Dev with Main

git checkout dev && git pull origin main
git push  # sync origin/dev

Step 12: Verify CI on Main (MANDATORY)

Poll gh run list --branch main after merge. Fix immediately if CI fails — the tag points to broken code. Full polling commands in pipeline-steps.md.

Step 13: Verify Downstream Workflows (MANDATORY)

Verify docs deploy, homebrew-release workflow, live site version, formula content, CI badge, and (if 10b ran) cask SHA256. Full scripts for 13a–13f are in references/downstream-verification.md.

Live-site version check (run after docs deploy):

curl -s https://data-wise.github.io/craft/ | grep -o 'version-[0-9]\+\.[0-9]\+\.[0-9]\+' | head -1 | sed 's/^version-/v/'

Anchor to the version BADGE slug (version-X.Y.Z), not the first bare vX.Y.Z string on the page — docs/index.md accumulates historical "since vX.Y.Z" prose and mkdocs.yml's site_description also embeds a version mention, either of which can render before the real badge in page order and get matched instead. This exact bare-grep bug false-positived scripts/pre-release-check.sh's docs/index.md check for both v4.2.0 and v4.3.0 (fixed in PR #308); .github/workflows/docs.yml and scripts/verify-surfaces.sh use the same anchored pattern.

Must match the just-released version. If stale, wait 60s and retry (GitHub Pages CDN lag); if still wrong after 3 retries, redeploy with mkdocs gh-deploy.

Step 13.4: Doc Coverage Gate (MANDATORY)

bash scripts/doc-coverage-check.sh — blocks on missing REFCARD rows or mkdocs nav entries. Fix with refcard-gen.sh and mkdocs.yml edits. Full guidance in downstream-verification.md.

Step 13.5: Post-Release Sweep (RECOMMENDED)

./scripts/post-release-sweep.sh --fix — catches Tier 2+ version drift not managed by bump-version.sh. Commit any changes. Full tier table in downstream-verification.md.

Step 13.6: Surface Registry Phase

Auto-runs when .claude-plugin/plugin.json is present. Propagates the release across the surface registry and asserts ONE version across every registered surface.

Registry-driven propagation (runs before verify):

1. Aggregator CI action — the aggregator-sync.yml workflow fires on release: published and opens + auto-merges a PR in Data-Wise/claude-plugins. If the PR is not merged within the timeout the action exits 1 (fail-loud: blocking — craft#218 Q2 gate).
2. Advisory pins — brew upgrade craft and claude plugin update craft@local-plugins are emitted as one-time advisory reminders (WARN; not blocking).
3. Cowork surface — a Cowork report is generated and a remind is queued (WARN; manual claude plugin marketplace add; non-blocking).

Pre-ship gate (manual, before release): verify the GitHub App has contents: write and pull-requests: write permissions on Data-Wise/claude-plugins. Without these permissions the aggregator CI action cannot open or merge PRs and will fail at runtime.

Surface matrix:

Verify half (retained from prior behavior): After propagation, scripts/verify-surfaces.sh asserts each BLOCK surface has landed the expected version. Injectable overrides (SURFACES_* env vars) allow surface verification in test/CI without live machine state. Bypass the entire step with --skip-surfaces (e.g. a non-plugin release or deliberate partial publish).

Full implementation — trigger condition, aggregator snippet, BLOCK/WARN table, and absent-leg handling — is in references/downstream-verification.md.

Step 13.7: Prune Version Cache (maintenance)

./scripts/cache-prune.sh (dry-run) then --prune. Keeps current + 2 most recent plugin version dirs. Never blocks release. Detail in downstream-verification.md.

Output Format

Display progress using box-drawing:

┌─────────────────────────────────────────────────────────────┐
│ /release v2.17.0                                            │
├─────────────────────────────────────────────────────────────┤
│ [ 1/13] CI mirror check .................... PASSED          │
│ [ 2/13] Release metadata check ............. PASSED          │
│ [ 3/13] Version bump ....................... DONE             │
│ [ 4/13] Commit and push ................... DONE              │
│ [ 5/13] Release PR created ................. PR #70          │
│ [ 6/13] CI monitoring ..................... GREEN (90s)       │
│ [ 7/13] PR merged .......................... DONE             │
│ [ 8/13] GitHub release ..................... v2.17.0          │
│ [ 9/13] Docs deployed ..................... DONE              │
│ [10/13] Homebrew tap updated .............. DONE              │
│ [11/13] Dev synced ........................ DONE               │
│ [12/13] Verify CI on main ................. PASSED            │
│ [13/13] Downstream verification ........... ALL GREEN         │
├─────────────────────────────────────────────────────────────┤
│ Release URL: https://github.com/.../releases/tag/v2.17.0   │
└─────────────────────────────────────────────────────────────┘

Error Recovery

Step 10b (desktop app) error recovery table is in references/homebrew.md.

Additional Resources

Reference Files

• references/pipeline-steps.md — Full command detail for Steps 1–9 and 11–12
• references/autonomous-mode.md — Autonomous mode safety checks, scripts, and error boxes
• references/homebrew.md — Step 10 complete: formula update, Tauri cask pipeline, error recovery
• references/downstream-verification.md — Steps 13a–13.7: downstream checks, sweep, surfaces
• references/release-checklist.md — Detailed per-project-type checklists and edge cases