implement-workflow

name

implement-workflow

description

Execute a cold implementation session from an externally authored plan, handoff, task-register entry, or build prompt. Enforce slice arming, consultation, blocking user-chat HALTs, test-first commit order, repository gates, one worktree/branch/PR, cold-review handoff, and stop-without-merge. Use when the user asks to implement or execute a plan written elsewhere. Do not use to author plans or resolve builder HALTs (`delegate`), review completed PRs (`review-workflow`), or apply a review punch list (`fix-workflow`).

Executing a plan written by someone else

An architect writes the plan. You execute it. A human merges it. You and the author never share a context window, so when the plan underdetermines the work you cannot ask them — you stop and ask the human who can rule.

What is enforced, and what is judgement

Most of this workflow's failure modes are things a model talks itself out of at 2am with a warm context. Those are enforced mechanically. The rest is genuinely judgement, and no amount of bold text makes it otherwise.

Two enforcement tiers, and the difference matters: the hook fires on every Bash call whether you remember it or not; the scripts enforce their verdict only when you run them — the phase gates below say when, and skipping the run is the one bypass the machinery can't catch.

Invariant	Enforced by	Tier	You cannot bypass it by
Never merge; never push to the default branch	hooks/guard.py (PreToolUse, denies the call)	hook	deciding it's fine this once
Never commit on the default branch (worktree-scoped: covers the armed worktree; merge/push blocks are repo-wide)	hooks/guard.py	hook	committing "just this once" from the slice
Never review your own PR	hooks/guard.py denies gh pr review	hook	approving "just to unblock"
Test lands with or before its implementation	scripts/check_commit_order.py (exit 1)	script	asserting you did TDD
Working tree clean, no whitespace damage, repo gates green	scripts/verify_pr_ready.py (exit 1)	script	running a different command
Gate commands are the repo's own	verify_pr_ready.py exits 2 when unknown	script	inventing one you like better
The PR is reviewable by a cold session	scripts/make_review_prompt.py exits 2 when the body lacks what/evidence/gates/deviations	script	promising to explain it in chat

The guard is inert until scripts/slice_start.py arms it, and it arms only the worktree you're in. Nothing changes in any other project.

What stays judgement: when to consult, when a fork is a HALT, and what counts as exercising the code live. The phases tell you how to decide; they cannot decide for you.

Phases

Run in order. Each ends in a gate that either exits 0 or tells you what to fix. phases/ holds the detail — read the file when you enter the phase, not before.

#	Phase	Gate
0	phases/00-ingest.md — read the plan; extract the return contract	The plan's fence and "done" definition are quoted in your notes
1	phases/01-orient.md — read the chain, open every seam. No edits	scripts/slice_start.py --slice <slug> --plan <path> --gates ... → exit 0 (arms the guard)
2	phases/02-consult.md — advisor before you design	An advisor (or fallback) response exists in the transcript
3	phases/03-halt.md — ambiguity → ask the user in chat, then close it at its source	A ruling exists, and it is written back into the governing doc
4	phases/04-tdd.md — red (captured) → green → refactor	scripts/check_commit_order.py → exit 0
5	phases/05-gates.md — repo gates + exercise the change live	scripts/verify_pr_ready.py → exit 0
6	phases/06-pr.md — one PR whose body is the durable record	gh pr create succeeds; scripts/checkpoint.py --sync-pr <n>
7	phases/07-stop.md — hand off to a cold reviewer, report the URL, stop	scripts/make_review_prompt.py --pr <n> → exit 0; scripts/slice_end.py --pr <n>

Phase 3 fires whenever an ambiguity appears, not only after phase 2.

You never review your own work. A builder cannot see what it cannot see about itself: its suite is green because it wrote the tests, and the paths it forgot to test are exactly the paths its tests don't cover. Phase 7 generates a self-contained prompt for a separate, cold session running the review-workflow skill. The guard denies gh pr review so this cannot be quietly skipped.

Because that session starts with none of your context — and because your own context may be cleared mid-slice — the PR body is the only durable store. checkpoint.py folds phase-by-phase progress into it; make_review_prompt.py refuses to emit a handoff until the body can stand alone.

Resolve the project's specifics first — never carry them over

This skill is stack-agnostic; the plan is not.

What	Where
Gate commands (build/test/lint)	CONTRIBUTING.md, CLAUDE.md, .github/workflows/*
The governing doc chain, and which doc wins a conflict	CLAUDE.md, the plan's own read order
The register/spec this slice implements + its out-of-scope fence	named in the plan
Worktree/branch/commit conventions	CONTRIBUTING.md, git log

Pin the gates once per repo in .implement/config.json ({"gates": ["...", "..."]}) or pass them to slice_start.py. The commands the repo names are the gates. verify_pr_ready.py refuses to run rather than guess, because an unknown gate is not a passed gate.

Authority, when advice conflicts

Tier	Source	Weight
1	advisor tool (sees your whole transcript)	Primary
2	A peer LLM, packaged self-contained (e.g. spec-driven-collaboration) — the fallback when advisor is unavailable	Advisory
3	A ruling from the plan's author or the human owner	Binding

Authority is a property of the source, not of how persuasive the answer sounds. When a tier-2 opinion contradicts a tier-3 ruling, surface the conflict; do not silently switch. Being close to the code is not authority either.

When to stop and ask

Situation	Action
The answer is in a file you haven't opened	Open it. Research, not a HALT
A conventional default exists for a decision the plan already scoped	Decide, say so, proceed
Two readings, same artifact	Decide. It doesn't matter
Two readings, different artifacts	HALT
The plan names an artifact, field, or output that does not exist in the code	HALT
Plan contradicts spec, or spec contradicts code	HALT
SDK/endpoint/path needed by an acceptance criterion is unavailable	HALT. Never weaken a test to route around it

Inventing an output is never a default

The trap has a specific shape, and it is the one builders actually fall into. A clause says "record a reason in whatever artifact the limiter writes" — and the limiter writes no artifact. The word "whatever" reads like delegated latitude, so you pick an in-memory list, or a log file, or a JSON sidecar, and ship it behind a green suite you wrote yourself.

It isn't latitude. If satisfying a clause requires creating a file, field, table, endpoint, or record shape the plan never named, that is a design decision, not a default. The reader of that clause and the writer of it did not have the same object in mind. In the real slice this rule comes from, the owner's ruling was "no standalone artifact — put the marker on the things that already exist." A builder that guessed would have shipped output the register never asked for.

Two tells, both mechanical:

• The clause references something (the artifact, the log, the response) that a grep shows does not exist.
• Your candidate readings would produce different files on disk, or different public shapes.

Either tell → HALT. Consulting an advisor does not substitute: it can bless a reading, but it cannot know which one the plan's author meant.

HALTing on something you could have looked up teaches the human your questions aren't load-bearing, and the next real HALT gets waved through. See phases/03-halt.md for the payload shape.

Two facts that cost real time when forgotten

A red gate is a claim, not a fact. Root-cause a failure before believing its message. Error handlers routinely assert causes they never established — a real one: git diff --check HEAD~1 HEAD on a shallow clone printed fatal: ambiguous argument 'HEAD~1', and a || echo '::error::whitespace errors' wrapper relabelled it as a whitespace failure. It false-failed every merge for weeks. There was never any whitespace.

A green signal proves nothing about a thing whose job is to say no. When the change is a check, guard, validator, or fallback, feed it bad input and watch it fail. Passing on good input is what the broken version did too.

Files

• hooks/guard.py — PreToolUse guard (merge / default-branch / self-review / bare --force), shared with fix-workflow. Matches by token position, not substring, so gh pr comment --body "…git merge…" is allowed and bash -c 'git merge' is not. hooks/test_guard.py self-tests it (52 cases, incl. that git merge-base and gh pr comment are not blocked).
• hooks/settings-snippet.json — registration for ~/.codex/hooks.json.
• scripts/ — slice_start · checkpoint · check_commit_order · verify_pr_ready · make_review_prompt · slice_end · common.
• references/worked-examples.md — four real slices: a ruling that added the edge cases, a bug caught before it reached a PR, a HALT closed in the register, a CI gate that never ran.
• references/pr-body-template.md — the evidence table; use the repo's own template if it has one.