Phase-Gate

Plan it, build it, review it, ship it — for one person and an AI assistant.

v0.1.0 — pre-1.0, in real-world use. Interfaces and file layout can still change between releases; see CHANGELOG.md.

Teams get independent review from a second engineer. Phase-Gate gives you the same thing from a second AI model reading your work in a fresh conversation. It installs as Claude Code commands, so you'll need Claude Code and a git repo to use it.

New to this and just deciding whether it's worth adopting? Read docs/methodology-explainer.pdf instead. No commands in it.

Features

• Every change gets sized first, so a typo fix doesn't get the same process as a rewrite.
• The plan is reviewed before code exists, by a model that didn't write it.
• The finished code is checked against that plan, by another one that didn't build it.
• A new conversation starts with no memory of the last one. In a long session, a hook nudges you once you're past 50% of the context window. A handoff note passes what matters to the next conversation, so it picks up where you left off instead of starting from zero.
• Take all of it or one piece. Nine components work standalone, with nothing to adapt.

Requirements

You need three things installed:

• Claude Code
• git
• Python 3

Two commands have their own hard requirement — not optional if you use them, with no fallback if it's missing:

• /implement-queue (builds several approved plans in parallel — skip this if you don't use it) needs Claude Code's Workflow tool with worktree support. Check /config to confirm it's on — there's no fallback without it.
• /review-pr (reviews a GitHub pull request — skip this if you don't use it) needs the gh CLI, authenticated. Install it from cli.github.com, then run gh auth login. It also needs Claude Code's own code-review and security-review skills.

The installer itself is a model reading and reasoning about your repo, not a script, so run /phase-gate-install with Sonnet-class reasoning or better — check /model if you're not sure what you're currently on.

Reviews cost real model time. Anything above a one-line fix spends at least one extra agent run, and usually two — the design review and the QA check are separate passes, and most changes get both. Tier 1 can also switch the whole session to a stronger, more expensive model for the design pass. There's no spend cap, so watch your usage for the first few sessions.

Quick Start

Two ways in — paste one message, or type a few terminal commands yourself. Either one ends at the same installer.

Prefer not to open a terminal first? Start Claude Code in the repo you want Phase-Gate in, and paste this:

I want to install Phase-Gate (https://github.com/Michuru/phase-gate) into this project without
typing terminal commands myself first. Please do the following, stopping to confirm with me at
each checkpoint — don't skip ahead:

1. Confirm you're running on Sonnet-class reasoning or better (check /model if unsure). If not,
   tell me and stop here.
2. Tell me the resolved root of the project you're about to act in, and confirm this is where I
   want Phase-Gate installed.
3. Show me the exact clone URL (https://github.com/Michuru/phase-gate.git) and a destination
   folder outside this project — a sibling directory next to this project, never a temp folder
   that gets cleaned up — and wait for my yes before cloning.
4. Clone it there and confirm it succeeded.
5. Show me the exact folder you're about to copy (the clone's installer/phase-gate-install folder,
   into this project's .claude/skills/phase-gate-install) and wait for my yes before copying.
6. Copy it in, then stop.
7. Tell me the installer skill is ready, that a skill copied mid-session isn't reliably usable in
   that same session, and that I need to start a brand-new Claude Code session in this repo and
   run /phase-gate-install <the path you cloned to> myself there — don't run it yourself. Also
   remind me that once the installer has actually written .githooks/ (only if I picked apply mode
   with hooks selected), I still need to run `git config core.hooksPath .githooks` myself.

This clones the repo and copies the installer skill in for you, then hands off — a skill copied mid-session isn't reliably usable in that same session (tested directly, not assumed), so actually running the installer always happens in a second, genuinely fresh session, the same way the terminal path below reaches it after its own copy step.

Worth knowing before you paste it: unlike typing the clone command yourself, here the URL comes from this README, not from you choosing it. That's not a new risk — the installer's own Step 0 still asks you to confirm the remote it actually cloned before reading anything further — but it's a real difference worth naming rather than pretending the two paths are identical.

Prefer the terminal? Four steps: clone and copy from a terminal, run the installer inside Claude Code, then one more terminal command to finish.

1. Clone this repo anywhere. It doesn't need to live near your project. In a terminal:

git clone <this-repo's-clone-url> /path/to/phase-gate

2. Still in a terminal, cd into the repo you want Phase-Gate in, then copy the installer there:

# macOS and Linux
mkdir -p .claude/skills && cp -r /path/to/phase-gate/installer/phase-gate-install .claude/skills/

# Windows
New-Item -ItemType Directory -Force .claude\skills | Out-Null
Copy-Item -Recurse C:\path\to\phase-gate\installer\phase-gate-install .claude\skills\

3. In that same terminal, still in your project repo, start Claude Code:

claude

Then run the installer as a Claude Code command:

/phase-gate-install /path/to/phase-gate

It asks which mode you want, then lists every component with a verdict for your repo. In apply mode it shows one file's before-and-after at a time and waits for a yes on each. Nothing is written until you give it.

4. Back in a terminal, point git at the hooks it installed. This one is yours to run; the installer doesn't touch your git config.

git config core.hooksPath .githooks

Confirm it worked. .claude/phase-gate-install/receipt.json lists every file the installer actually wrote — open it to see exactly what landed. To confirm Claude Code picked the skills up, start a fresh session in your project and run /initiate (the same fresh session either path above already had you start in): if it reads your new BACKLOG.md and names what to work on next, rather than giving a generic reply, the install is live.

Trying it without changing anything

Once you're running /phase-gate-install — step 3 above, or your own fresh session after the paste path — answer recommend-only at the mode question. It writes two files under .claude/phase-gate-install/ recording what it would propose, and nothing else anywhere.

To try a single standalone component instead, open its folder, copy the one file, and paste its settings snippet. No installer involved. For example, block-dangerous-commands: copy standalone/hooks/block-dangerous-commands/block-dangerous-commands.py into your repo, then merge settings.fragment.json from that same folder into your .claude/settings.json.

What happens without asking

Not because any of this is risky to run — it's that Phase-Gate acts on your repo in ways worth knowing up front rather than discovering later.

Phase-Gate commits without asking you first. This is deliberate, so finished work leaves a clean history without you approving each commit, and the installer confirms it separately from everything else. You can decline it.

• Commits when a work item is finished and verified, one commit per item.
• Commits just before a large or risky rewrite, as a checkpoint you can return to.
• Commits when wrapping up a session, so finished work doesn't sit uncommitted.
• Never pushes without asking. Every push, every time.

The installer itself never writes to your CLAUDE.md — day-to-day work does, constantly (see "What it puts in your repo" below). A pre-push hook scans outgoing commits for credentials.

Usage

You drive this with slash commands, one per stage. Each stage hands the work to the next, and those hand-offs are where the reviews happen, because the model receiving the work is never the one that did it.

Starting and ending a session

/initiate is where every session begins: it reads where things stand and tells you what to work on.

Command	What it does
/initiate	Opens a session by reading where things stand, then names what to do next
/handoff	Writes down in-progress work; run it again at the start of a fresh session to resume from it
/end-task	Closes a session out: commit, sync docs, or write a handoff

One change, start to finish

This is the order you'd type these in, and it loops: /ship closes one item and points back at /backlog for the next.

Step	Command	What happens
Track	/backlog	Lists open work. Pick an item, or add a new one
Design	/spec	Writes a short plan. You approve it before any code exists
Build	/build	Implements the approved plan, task by task
Check	/verify	A separate reviewer checks the result against that plan
Ship	/ship	Commits, archives the item, and lists what's still open

How a change gets sized

/spec figures out the tier before it starts writing the plan, so both the tier and the plan itself can still be refined before any of it reaches /build.

Tier	The change	What it gets
1	A new tool, or rewriting how an existing one works	Fuller plan, automatic review from a different model, option of a second
2	Several files or new UI, no existing pattern to copy	Short plan, automatic review
3	Several files or new UI, copying a pattern already working here	Short plan, no review
4	One spot in one file	One-sentence plan

Also included

These cover real, common needs: parallel builds, onboarding an existing project, and reviewing someone else's pull request.

Command	What it does
/execution-gate	Decide, per task, whether the AI does it directly, delegates it, or needs you
/implement-queue	Build several approved plans at once, each in its own copy of the repo
/adopt	One-time inventory for adding this to a project that already has code
/consolidate-docs	Keep your always-loaded rules file from growing unbounded
/periodic-audit	Check whether tests cover a tool's branches, and whether an old bug is back
/review-pr	Review a GitHub pull request and post the findings

Two more skills ship but aren't listed above because they're not commands you run directly: /commit and /wrap-up-session are internal redirects to /end-task's own depth modes, kept for backward compatibility (see docs/WORKFLOW.md).

Four subagents run behind these commands, each in its own fresh conversation: code-reviewer (the independent check in /verify) and periodic-audit-coverage/periodic-audit-structural (the two halves of /periodic-audit) do review work; docs-writer (mechanical documentation updates) doesn't review anything, it transcribes.

One more piece is opt-in and invisible unless you configure it: local-delegate lets /build try a free local-model draft (via a local model runtime such as Ollama) on an eligible task before spending a turn on your main model, gated by your own already-written tests. Ships off — see process/local-delegate/README.md if you want to turn it on.

What it puts in your repo

Phase-Gate keeps its records as four plain markdown files in your own repo, not in a database or a service, and you can rename any of them: your CLAUDE.md rules doc (which the installer merges into rather than overwrites, and which day-to-day work keeps current — see below); open work in one file; finished work in a second, once it ships; and a fourth file that logs process mistakes — not bugs in your code, but times the process itself went wrong, a wrong assumption or a "done" that wasn't actually checked, so a future session doesn't have to rediscover it the hard way. A fifth thing, a folder rather than a file, holds design plans.

The installer creates whichever of these don't exist yet, one confirmation at a time. Where your CLAUDE.md rules and Phase-Gate's disagree, it shows you the conflict and leaves the decision to you. After that, the installer itself never touches CLAUDE.md again — normal work does, constantly: a durable lesson gets written into it, a stale rule gets pruned, a design's task list gets recorded. That's how the rules doc and mistakes log stay current, not a one-time install-day write.

The complete list of everything the installer can write is in installer/phase-gate-install/SKILL.md. A full install (everything, not a cherry-picked subset) looks roughly like this in your repo — a selective install only gets the pieces you chose:

your-project/
├── CLAUDE.md                       ← merged into, never overwritten
├── BACKLOG.md
├── BACKLOG_ARCHIVE.md
├── MISTAKES.md
├── Design Docs/
├── .githooks/                      ← pre-commit, pre-push, secret scanning
├── .claude/
│   ├── settings.json                ← hooks/statusLine merged in
│   ├── skills/                      ← one folder per command you chose
│   │   ├── initiate/
│   │   ├── backlog/
│   │   ├── spec/
│   │   └── ...
│   └── phase-gate-install/
│       ├── variables.json           ← your settings; edit and re-run to apply
│       └── receipt.json             ← every file this installer actually wrote
└── docs/                            ← Phase-Gate's own reference docs, copied in
    ├── methodology.md
    ├── WORKFLOW.md
    └── PORTING.md

Standalone components

Each works alone. Most are one file: copy it, paste its settings snippet, done. doc-review is a skill with its own references/ and scripts/ subdirectories and no settings snippet at all — copy its whole folder into .claude/skills/doc-review/ instead.

Component	What it does
block-dangerous-commands	Refuses a short list of catastrophic shell commands outright
hooks-health-check	Says at session start when your git hooks have come unwired
schedule-wakeup-guard	Blocks ScheduleWakeup unless a real /loop is actually live
context-usage-nudge	Warns as a conversation fills up, so you can hand off in time
update-notification	Mentions when Phase-Gate has new commits. Never fetches or applies anything
periodic-audit-threshold-check	Flags when a tool is due for an audit. Needs /periodic-audit
statusline	Context usage, session cost, and elapsed time in your status bar
ai-check	Scores text for signs an AI wrote it
humanize	Rewrites text to read less that way
doc-review	Reviews a document for clarity, checks its claims against the files it cites, and scans it for repeated words and machine-sounding phrasing

Updating

In a terminal, git pull the clone. Then, in Claude Code, run /phase-gate-install /path/to/phase-gate again. It compares against what it wrote last time and shows you a plan. Nothing you've edited is overwritten without a diff first.

Settings live at .claude/phase-gate-install/variables.json in your repo. Edit a value there and the next run reads your edit instead of asking again. docs/PORTING.md explains what each one does.

Uninstalling

Run /phase-gate-uninstall inside Claude Code, in the repo you installed into. It reads your own install receipt, shows you the full removal plan (skipping anything you've hand-edited since install) before touching anything, and never touches core.hooksPath automatically — it only reports the current value, since phase-gate never set that itself.

If your receipt is gone or predates this skill, .claude/phase-gate-install/receipt.json (if it still exists) lists every path phase-gate ever wrote — remove those by hand, along with any matching entries under .claude/settings.json's hooks/statusLine keys.

Documentation

Document	What it covers
docs/methodology-explainer.pdf	The idea in plain language, no commands
docs/methodology.md	The full process reference
docs/WORKFLOW.md	How the commands connect
docs/PORTING.md	Every configurable setting
CHANGELOG.md	Release history. Pre-1.0

Licence

MIT, under LICENSE. ai-check and humanize came from elsewhere and keep their own licence; see their folders. The idea of distributing small single-purpose hooks individually rather than as one config comes from claude-code-templates (MIT, Daniel Ávila).