why AI coding agents need hard stage boundaries

Every structured Claude Code workflow defines stages: scope the story, design the solution, architect the decomposition, implement, review, release. Most practitioners nod at this and then implement it loosely — stages as mental labels rather than enforced contracts. That gap is where the expensive failures happen.

Two failure modes are worth separating, because they happen at different levels and require different fixes. The first is a wrong transition: the workflow advances from one stage to the next before the exit criteria are met. The second is wrong work within a stage: an agent operating in stage N does work that belongs to stage N+1. Both waste tokens, corrupt the artifact record, and strand work that then has to be redone. But they're triggered differently and caught at different points in the system.

failure mode 1: the stage that advances itself

Automatic stage advancement sounds convenient. If the design agent finishes its output, why not automatically kick off architecture? If architecture completes, why not start implementation?

The reason is that "finished" and "approved" are different states. An agent can produce a complete design artifact — one that parses correctly, meets the structural requirements, covers all the user story's acceptance criteria — and still be wrong. Wrong because the visual treatment doesn't match the existing interface. Wrong because the agent made an assumption about a constraint that the developer knows is false. Wrong because the solution is technically correct but misses the intent of the feature.

A gate that advances automatically on completion skips the human check that catches these mismatches. By the time implementation runs on a bad design, correcting the mistake means reverting multiple files across potentially several agents' work — not a one-line fix.

The fix is simple in principle: a stage may not advance until a human approves the current stage's output. No exception for "looks done." The approval is the gate; completion is a precondition for surfacing the gate, not a substitute for it.

failure mode 2: an agent doing out-of-stage work

The second failure mode is subtler. An agent operating within a permitted stage — say, the design stage — starts doing work that belongs to a different stage. The most common version: a design agent that writes code. Not because it was asked to, but because the boundary between "designing a component" and "speccing it in implementable terms" blurs for a code-native model, and without an explicit constraint, the agent takes the path that feels complete.

The consequences are different from wrong transitions. The code produced during the design stage is:

• Unreviewed — it bypassed the architecture stage (where parallelization is decided) and the review stage (where specialist agents check it)
• Contextually wrong — the design agent doesn't have the implementation brief that constrains which files can change, what interfaces are expected, or what's running in parallel
• Confusingly placed — it's committed or recorded as a design artifact, not as implementation output, which breaks the traceability from design approval to implementation diff

The key insight is that the constraint has to live in the agent's prompt, not just in the orchestration layer. Catching a wrong transition at the state machine level is sufficient for failure mode 1. Catching wrong intra-stage work requires the agent itself to understand and apply the stage contract.

why these failures are expensive

Both failure modes compound in multi-agent workflows. If a design stage produces an artifact that advances automatically, and three parallel implementation agents start on it, you have three partial implementations that may now conflict when the design correction arrives. The token cost scales with the number of parallel agents running on bad input. The coordination cost — resolving three agents' work against a revised design — is worse.

The intra-stage failure compounds differently. Code written during the design stage doesn't appear in the implementation diff that reviewers check. It may not appear in the worktree that the review stage operates on. It's orphaned from the review gate. If it's committed as part of the design artifact and then implementation adds more code on top of it, the review stage is reviewing an incomplete picture.

Neither failure is catastrophic in a single small task. In a workflow running five or six parallel agents on a feature of real complexity, either failure can strand the entire task.

what enforced stages look like in practice

Enforcement happens at two levels and you need both:

Transition enforcement is the gating mechanism: an explicit human approval step before any stage advance. This can be implemented in a terminal workflow with a simple loop that waits for a "y" before advancing, but the discipline erodes quickly under time pressure. The gate has to be the default path, not an opt-in you remember to apply when you're careful.

Intra-stage enforcement is prompt-level: each agent operating in a stage needs to know, explicitly, what work is and isn't within its mandate. A design agent's system prompt should state that it produces wireframes and interface contracts; it does not write implementation code. An architecture agent produces a decomposition document; it does not start editing files. A review agent produces structured output against the implementation diff; it does not modify the code it's reviewing.

The spec-driven approach — defining these contracts in structured specification documents that agents read before acting — helps with the intra-stage problem, because the spec itself encodes what each stage produces and what the next stage expects as input. An agent that reads its operating brief before acting is less likely to wander out of scope than one that's operating from a generic system prompt.

For teams running parallel Claude Code agents, both enforcement mechanisms become more important as the number of agents increases. The failure surface is proportional to the degree of parallelism — each agent is a surface where a transition can advance prematurely or where out-of-stage work can be silently injected into the artifact stream.

what defract does with stage contracts

defract enforces stage contracts at both levels as a native property of the lifecycle, not a convention you configure. Transitions require explicit approval before advancing — the gate is enforced at the application layer, not tracked in someone's head. Each stage's agent set operates with prompts that define the stage contract explicitly, including what work is out of scope. The 0.9.4 transition enforcement fix and the 0.9.5 designer constraint were shipped as correctness fixes, not features — the stage contract is the property the product guarantees.

If you're running Claude Code tasks today and want to see what a fully gated lifecycle looks like in practice, it's a free download.