Every Phase Gate in /develop Wants an Artifact, Not a Sentence

/develop is a 456-line skill. It starts an orchestrator, the team lead, which handles implementation rounds between human decision points. The rule is that an agent saying it is finished is not enough to move a run forward. A phase change needs evidence that can be checked: a test command with its output, a diff stat, a file check, or a recorded human decision. The skill states the rule in one sentence, and it applies to the human as well: “A user utterance in conversation never flips a status.”

This post walks through the nine phases, what unlocks each one, and where the human makes the decisions.

The map is a list of preconditions

The table summarizes the main phases; the sections below follow a run through them.

The diagram highlights GO and commit; needs confirmation, review decisions and closure questions also require the human.

A file decides where you are, the model decides how heavy

The lead’s first action on every invocation is a file check. If .claude/runs/<feature>/PLAN.md exists on the branch, it reads the current phase of its own stack and continues from there. A different engineer, a new session, the next day: same run, same phase. When a new session resumes at go or later, it first re-verifies the key facts the sealed design depends on. If a fact is broken, the run goes back to an amendment, “never silent continuation”. This rule exists because I once pressed /clear by accident and lost the run’s progress.

If there is no run folder, the lead decides how heavy the run should be. The human is not asked. The quick signals are listed in the skill; a small single-project change with no contract change and a fully stated intent takes the quick path: a brief scope confirmation, a small set of dispatches and verification instead of the full apparatus. If there is any doubt, the lead asks one question and takes the full path. The same small change ran under the full apparatus with 40 dispatches, then under quick mode with 8. The previous version of this workflow died partly because a ten-line change ran the same track as a full feature. This is the fix, and it is the model’s judgment, not a flag the human sets.

Quick mode also has written exits back to the full path, such as a reviewer reporting a critical finding or an agent editing outside the scope it announced. The conditions are in the skill text; the agent does not decide them case by case.

Before GO, the interview seals premises into PLAN.md

The full path settles scope and design in this phase, so routine implementation can proceed after GO without repeated questions. Questions come in batches. Answers are recorded verbatim. A reply is not a decision: only explicit decision words close a question, and the rest are asked again in the next round. These are the four questions from the LDAP run, translated from the log:

1. Is the scope a “sign in with LDAP” entry on the login page, or does it include a standalone LDAP settings page (domain, connection settings)?
2. When LDAP authentication fails or the service is unreachable, fall back to local credentials or block the login?
3. There is no LDAP folder under docs/features/. Should this run create one (for example ldap-auth) to record the criteria for this feature?
4. Do the existing login-page e2e tests cover the selectors and routes you are about to change? If so, add LDAP-branch cases in this run?

Questions 3 and 4 are possible because the lead had already looked at the repo. The rule behind them: a question the codebase can answer is never sent to the human. The lead dispatches a research read instead. The lead matches the request against the feature index and opens each affected spec. Factual premises are checked against the codebase before they are written into the design, because spec text and codebase convention have disagreed before without anyone noticing. Every new abstraction needs at least one existing precedent of the same shape in the repo; if none is found, it is reported as a design red flag. Before the design is sealed, a research read maps the impact across every project in scope. Work items are written from that map, “never from guesswork”.

The result is PLAN.md. It records the decisions in the human’s exact words with the date, the cross-stack contract, and per stack an approval line and a work-item table in which every row carries its evidence. Developers read this file too, not just the orchestrator.

Then planned. The lead repeats the design, the work items and the explicit not-doing list in plain language, checks that every instruction from the interview appears in one of those three lists, and asks for go. This authorizes implementation. The human’s words go into the approval line with the date. Coder dispatch waits for that approval.

After GO, the lead dispatches and never reads the code

What the human provides for this phase is fixed in advance: the roles (coder, tester, reviewer, syncer and a few more), their tools, and the project knowledge each role reads. How many agents, how many rounds, what runs in parallel: the skill says “dispatch shape is your judgment call”, and I do not check.

Two constraints make that acceptable. First, roles have separate responsibilities. Each agent loads its own role file: the coder handles production code, the tester handles tests, and the reviewer reports findings for a coder to fix. The diagram shows that division of work; it does not mean each role’s files are inaccessible to the others. Second, the lead follows the same discipline: “never Read source files or full diffs yourself”. Facts come from a research dispatch, and any file:line shown to the human is relayed from an agent’s summary. The retro of one run counted the lead’s source reads: zero.

Evidence enters at fixed points. After every parallel coder round, one verifier runs the tests in scope, using commands from the project’s config file, and repeats build checks when multiple coders’ changes need checking together. The transcript is the evidence. Before a work item is marked done, the lead compares git diff --stat with the files the coder announced; an unannounced change blocks the flip. When all coder rounds have converged and the verifier is green, a fixed sequence closes the phase: review, fixes, a UI preview offer where applicable, one explicit question to the human whether the change solves what they asked for, and only then the tester. Test work stays with the tester; scoped test updates can also accompany earlier implementation rounds.

Two examples from real runs. A form field was validated on blur, and the spec said on every keystroke. The reviewer found it before hand-off, the lead sent a coder to fix it, and the human was on a coffee break and did not need to know. In the LDAP run, the tester wrote a test that passed, then reported that the test proved nothing, because it had been copied from the code it was supposed to test. A green result would have passed the gate. The tester sent the sentence to the human instead. In both cases, a separate review of the work caught something the implementation had missed.

Failure has a limit, and the limit is written down: a verifier that keeps failing freezes the run and shows the raw error output to the human. Everything below the limit is decided by the lead and logged in one line. Escalation to the human during the run “has exactly three triggers”: a cross-stack contract change, an ambiguity that changes the decided design, or an irreversible operation. These are in addition to the scheduled review, preview and needs questions.

dev-done: two reviewers, three buckets, one table

Review during development is local to one round. At dev-done the whole run is reviewed again from start to end, by two tracks running in parallel. /code-review reads the full diff, including tests, for generic bugs and simplification. Domain reviewers read for business logic and contract correctness. When two stacks changed production code, at least one pass has to read both sides of the contract, because field names, casing and failure-mode interaction are invisible to a reviewer that sees one project. We keep the two tracks separate so each review has a clear focus.

A finding needs a citation. A verdict without file:line is treated as speculation and “cannot flip a decision”. The heaviest findings get one more dispatch whose only job is to rebut them; a finding counts only when the rebuttal fails. Decisions the human already made in this run are passed to the reviewers as parameters, and a finding that matches one is dropped at triage, so a rejected suggestion does not come back every round. The findings that remain go into three buckets:

• Bugs and criticals with evidence inside the approved scope: fixed without asking, logged as a deviation. Out-of-scope fixes need approval.
• Violations of a written project rule: fixed without asking, because the rule already records the team’s decision.
• Judgment calls: “NEVER auto-applied”. They go into the suggestion table, one row each.

The citation rule is what settles disputes between reviewers. One reviewer reported that an error code was not defined in any config file. Another reviewer ran one search and found it defined twice in one of them. The search ended the argument, because a report without a citation cannot move anything on its own.

The suggestion table is shown in full in the conversation, not only written to the file, because a decision the human cannot see without opening a file is not a gate. Zero-impact rows default to rejected and are still shown, so the human sees every candidate and can change any default. The human can accept the proposed decisions as a batch or review them individually. Adopted rows get a scoped fix round and a scoped re-check rather than repeating /code-review. The phase becomes reviewed only when no row is left open. This is the split phase: the AI fixes what has a rule behind it, and the human decides what does not.

The exit runs the suite and docs, then closes with human decisions

The full test suite runs at most once per run, after all fixes are in, in the same parallel round as the docs writers; tests and docs touch different files. Each project’s config file defines its suite, and a project that skips is reported as a skip and not as a pass. A green full run that already happened after the last code change counts as evidence; it is cited, not repeated.

Docs are written from the as-built record (work-item evidence, deviations, hand-off), “never from the frozen plan”. They have two audiences: a plain-language summary for people who will not read the code, and the decisions the next agent cannot infer from the code. I have been that next reader, trying to understand why I wrote something a month earlier.

Before commit, the lead confirms whether all stacks are done, offers frontend E2E checks where relevant, and handles the remaining delivery choices. Retro is a separate question; if accepted, its report travels with the commit. The final stack also decides whether to keep the run folder. Those choices come before the commit question.

The commit question is always last and is a plain yes or no. If the human inserts a step (“run review first”), that answers the step, not the gate; the commit question is asked again afterwards. Only an explicit yes invokes /commit, with the test evidence passed along.

What it costs

The skill is 456 lines, and its reference files add 298 more. That is process text, the same kind that killed the two earlier versions of this workflow, and it stays alive only because the retro is allowed to delete from it. A full run takes from half an hour to several hours. The human types less: the interview, go, needs confirmation, review and delivery decisions. The human reads more: everything the agents hand back. The gates are meant to make that reading manageable by requiring evidence for completion claims.

It does not believe anyone who says "done".
Itself included.

The backend has a cleanup script. Its job is to remove the containers a test run leaves behind. For almost two months, every test report contained the same line: cleaned up automatically by hook. The script had never run once. The report described what should happen, not what had been seen to happen. A self-check finally caught the difference, and the line was deleted. That gap, between a description of work and evidence of work, is the only thing this whole apparatus exists to close.