Claude Release Workflow

A set of Claude Code skills and hooks for shipping code safely. It splits "ship it" into an iterate stage and a release stage, codifies the pre-release review loop, and puts a hook in front of git push so a release always goes through the skill instead of an ad-hoc push.

The idea is a small, repeatable path from a feature branch to a verified production deploy:

1. pr-checkpoint: snapshot in-progress work as a GitHub PR and rebuild your local Docker container so you can test the feature branch on localhost. Does not merge, does not touch prod. Optionally runs the review loop as advisory reports.
2. review-round: the codified three-reviewer loop. Author per-agent adversarial prompts aimed at the riskiest spots, launch the review agents in parallel, reproduce every finding by execution before fixing, prove each fix with a non-vacuous regression test, and post the PR verdict comment that release reads.
3. release: the single ship-it verb. Auto-detects PR mode (merge open PRs targeting main) or trunk mode (commit straight to main), updates the README and project notes, pushes to every remote, verifies the auto-deploy landed on the right commit, and rebuilds local Docker so localhost matches prod. Refuses to merge a PR whose review-round verdict at the current head is CRITICALS-OPEN.

A block-git-push-main.sh PreToolUse hook backs this up: it deterministically blocks any raw git push to main / master and points you at /release. It is the safety net for when the model forgets the workflow.

The flow

Source: docs/release-flow.drawio (editable in draw.io).

Why two verbs

/pr-checkpoint is the iterate stage. You run it as many times as you like while building a feature: it opens or updates a PR and gives you a running local container to test against, but it never merges or deploys, and does not touch your release docs (that would be premature).

/release is the hard gate. It is the one place that merges, updates docs, pushes, and deploys, all as one atomic action. Because the docs update and the deploy verification are part of the same step, you cannot ship code and forget to write down what changed.

The skills

• pr-checkpoint: commit staged work, push the feature branch, open a draft PR with a structured body, optionally run the advisory review loop, and rebuild local Docker. Refuses to push to main or commit secrets, and (via the shared preflight) refuses to push AI-assistant harness files to a repo you do not own.
• review-round: the pre-release review loop (also the engine behind the pr-checkpoint step-6 review, in advisory checkpoint mode). Scopes the diff, authors adversarial per-agent prompts, launches the review agents in parallel, reproduces findings by execution, verifies suggested fixes against the authoritative gate, proves each fix with a mutation- or contrast-checked regression test, and posts a Review-round verdict: <CLEAN|CRITICALS-OPEN> @ <sha> comment. release reads that marker and refuses a CRITICALS-OPEN head.
• release: detects the release shape (PR / trunk / nothing to do), merges or commits, runs an optional project pre-push gate, updates README + project notes, pushes to all remotes, verifies the deploy landed on the correct commit, and rebuilds local Docker. Refuses to merge a PR whose review-round verdict at the current head is CRITICALS-OPEN (a missing or stale-SHA verdict is not a blocker).

Shared protocols the skills reference (in _shared/):

• release-docs.md: how the README and project notes get updated at ship time, plus the secrets / staging guardrails.
• local-docker-rebuild.md: detect and rebuild the repo's local container; skips silently when the project does not use Docker.
• harness-files-protection.md: a preflight that keeps AI-assistant working files (CLAUDE.md, MEMORY.md, .claude/, and so on) out of any repo you do not own personally.
• codex-delegation.md and codex_delegate.py: the codex-reviewer, a second model family (OpenAI, through the headless Codex CLI) that reviews the same diff as the Claude agents. The runner keeps Codex read-only, fails loud when it cannot run, and checks that the answer is about the commits it was asked to review. delegation_contract.py, process_group.py, review_result_v1.schema.json and model_profiles.json (an example) are its helpers. See "Codex review" below.

The hooks (in hooks/):

• block-git-push-main.sh: PreToolUse hook on the Bash tool that blocks git push to main / master, with two documented bypasses for the rare direct-push case. It is a thin delegator to block-git-push-main.py, which decides from a quote-aware parse of the command (_bash_command_parse.py) rather than from a substring match. The parse matters in both directions: a substring match blocks a quoted grep pattern, a heredoc that writes a script containing a push line, and prose that ends one word after "push", while it lets bash -c "git push origin main" and git push origin HEAD:refs/heads/main straight through.
• test-integrity-check.py: PostToolUse hook (advisory) that catches DEAD tests (defined after a custom if __name__ == "__main__" runner, so they never bind) and UNREGISTERED tests (missing from a hand-maintained call list). Both read as green from the outside; this hook flags them deterministically via AST. It also runs standalone as test-integrity-check.py --file <path> for a one-shot audit. _bash_write_targets.py is its helper: it lets the Bash matcher see files written by shell redirection or tee, which normal Write/Edit hooks miss.

Install

On Windows: install Git for Windows, so Claude Code runs these scripts in Git Bash. Where a command here says python3 and your PC has only python, use python. In WSL, follow the Linux steps.

This is the beginning of the README. Read the rest at the original. Read the full README ↗