AWS’s AI-DLC project has a rule for coding agents that sounds too obvious to break: write a plan, get it approved, and only then write code. For a while the rule lived where most agent rules live, in the instructions.

Then a field report came in. The agent had written the code first, and then produced a plan beside the finished code, describing what it had just built. The instructions were clear, and they lost. The maintainers left a note about it in the source of their fix, with a phrase I keep coming back to: the report showed “prose losing that contest” [1].

Here is the same request, run once with the rule in the prompt and once with the rule enforced:

A coding agent follows a process only as far as something outside the model enforces it. Everything else is a request.

That sentence is the whole post. The rest is about how AI-DLC turns requests into guarantees with a state machine and a handful of hooks, why the same trick matters for AI code review, and how Anthropic, GitHub, OpenAI and Google approach the same problem. It’s a companion to Assume Your Agent Will Misbehave, which used the same kind of check to stop dangerous actions; here the target is actions taken out of order.

A note on the figures: orange always means instructions the model may ignore, violet the state machine, blue code that can refuse, and green you.

• 1. A state machine beside the model
• 2. Hooks: where requests become guarantees
• 3. The same lesson, applied to code review
• 4. How the others approach it
• 5. What a state machine can’t give you
• 6. Where this leaves us
• Cite this post
• References

1. A state machine beside the model

The simplest way to picture AI-DLC is a contractor and a project manager. Claude is the contractor: it does all the actual work. The engine is the project manager with a clipboard. It never touches the work. It only knows where the job stands and what comes next.

Concretely, the engine is a command-line program that lives in your project, and Claude calls it the way it would call git. Every step of the workflow goes through the same exchange. Watch one stage go round:

Claude asks aidlc engine orchestrate next. The engine reads a state file and replies with exactly one move: run this stage, ask the person this question, or stop. Claude does that one thing and reports back with orchestrate report, and the engine, and only the engine, updates the record. Asking twice returns the same answer, so a confused agent can’t skip ahead by asking again [2].

The division of labour is deliberate. The skill file says the engine “owns all between-stage routing” [2], while Claude owns the quality of the work inside each step. Routing is the part a model gets wrong when its context is crowded or it’s overconfident, so it’s the part taken away from the model.

Around this loop sits a full software lifecycle: 5 phases, 33 stages, 14 agents (two of them dedicated reviewers) and 11 workflow profiles, so after setup a bug fix runs 6 stages while an enterprise feature runs all 30 [1][3]. It installs into seven coding agents, among them Claude Code, Codex CLI, Cursor and GitHub Copilot. AWS open-sourced it in November 2025; version 2.11.3 shipped on November 4, 2026 [4][5].

There is an obvious hole, though. Claude is only told to call the engine.

2. Hooks: where requests become guarantees

Claude Code lets you register hooks, scripts that run at fixed moments in a session: before a tool call, after one, when you send a message, when the agent tries to stop. A hook that runs before a tool call can veto it by exiting with code 2 [1]. That veto is the piece that doesn’t depend on the model’s cooperation.

AI-DLC wires a hook into nearly every one of those moments, and every hook consults the same engine [6]. The result is three layers, each with a different job:

Only the hook layer can stop a tool call outright. Diagram by the author from AI-DLC's settings and skill files [2][6]; simplified.

The maintainers sum up the design in one line: determinism “in tools and hooks, knowledge in agents, judgement with humans” [1]. I think that’s the right split, and it generalises well beyond this project.

The hook that started it all is the plan-approval guard. While code is being generated, every write to your project has to clear three checks: a plan exists, a person approved it in a real message of their own, and the plan on disk is byte-for-byte the one they approved [1]. Try to slip past it:

Two details deserve honesty. The byte-for-byte recheck is the default only in the Enterprise profile; elsewhere an edited plan is logged and accepted rather than re-asked [3][7]. And there is an off switch for when the guard misfires, but flipping it leaves a GUARD_DISABLED entry in the audit trail [1]. You can turn the guardrail off; you can’t do it quietly.

3. The same lesson, applied to code review

Code review is where this stops being an AWS curiosity. Anthropic launched Code Review for Claude Code in March 2026 and now runs it on nearly every internal pull request. Before, 16% of their PRs got substantive review comments; with it, 54% do [8]. Several agents hunt for bugs in parallel, a verification step filters out false positives, the confirmed issues are ranked by severity, and fewer than 1% of findings are marked incorrect [9].

Review turns out to have exactly the same weakness as planning. AI-DLC’s source records two more cases where a written rule lost, each followed by a hook that now enforces it [10][11]:

Each story is recorded in the header comment of the hook that fixed it [1][10][11].

The second row is my favourite, because it’s such a human failure. The agent did the helpful thing, and in doing so destroyed the evidence that the work had been checked.

OpenAI’s Codex plugin for Claude Code reaches the same idea from another direction. Claude writes the code and Codex reviews it, read-only. Turn on the optional review gate and a Stop hook runs that review whenever Claude tries to finish, refusing to let it stop while issues remain [12]. In effect: you are not done until a different model agrees.

Put these together and a few principles fall out. A review only counts for the exact code it saw; change anything afterwards and you need a new one, which is what GitHub’s “dismiss stale pull request approvals” setting enforces for human teams [21]. The reviewer should be separate from the author, whether that means a dedicated agent or a different model altogether. Its reading should be bounded, or it gets slower and more expensive with every file you add. And approval stays with a person. Anthropic is explicit that Code Review won’t approve pull requests: “that’s still a human call” [8]. AI-DLC encodes the same rule in a human-presence check that no scope or Guard Policy can lower; only a machine-wide override switches it off, and AI-DLC says so while it is [13].

4. How the others approach it

AWS isn’t alone in trying to give coding agents a process. Here are four comparable systems from Anthropic, GitHub, OpenAI and Google beside AI-DLC. Press the buttons and see what each does when the agent cuts a corner:

Sources: [1], [14], [8], [15], [12], [16].

What strikes me is how much everyone agrees on. Plan before you code, split the work among specialists, review it, keep the state in files rather than in the model’s head. The real disagreement is about where the rule lives. The labs mostly ship small, composable pieces and trust the model to follow them. AWS ships an entire methodology and backs the rules that matter with code.

That also puts AI-DLC in some tension with the labs’ own advice. Anthropic and OpenAI both say to start with the simplest thing that works [17][18]. AI-DLC does offer light profiles, but the framework underneath is large, and its release notes regularly warn of breaking changes [5]. For a regulated team that needs an audit trail, that’s a fair price. For one developer fixing a bug, it’s a steep one.

5. What a state machine can’t give you

None of this makes the agent fully reliable, and it’s worth being precise about the gaps.

The model still drives the loop. Hooks can refuse a bad action, but they can’t make Claude call the engine in the first place. In autonomous or unattended runs, a Stop hook sends an agent that quits early back to work with “AI-DLC is carrying on” [2]; when you’re at the keyboard, an early stop simply pauses the work until you return. Either way it’s a nudge, not a guarantee. Hooks also only see tool calls, so anything the agent merely says in chat goes unchecked.

The bigger gap is the definition of “done”. A process can be followed perfectly and still ship a bug if the last check never looks at the running software. Here is one bug, borrowed from AI-DLC’s own documentation, against five kinds of check:

AI-DLC is better here than I expected. Its Build and Test stage only counts a browser requirement as met if a real browser ran the check; otherwise it records the result as “Unverified” instead of passing it [19]. Anthropic reached the same conclusion from the other side: left alone, agents tend to declare a feature finished after unit tests, and only end-to-end testing catches what those miss [20].

6. Where this leaves us

The pattern I take from AI-DLC is less about software lifecycles than about where to put trust. Let the model do what models are good at: reading a codebase, asking good questions, writing the code. Take away the decisions where a lapse is costly and easy to rationalise, such as what happens next, whether a plan was really approved, or whether a review still applies. Give those to a program with a memory, and let it say no.

That’s also the most transferable idea for anyone building agents outside software, in domains where an out-of-order step is more than an inconvenience. The instructions can stay as rich as you like. Just don’t let them be the only thing between the agent and a step it shouldn’t take.

Cite this post

@misc{moniruzzaman2026reliableagents,
  author       = {Monir Moniruzzaman},
  title        = {Reliable Coding Agents Through a State Machine: AI-DLC},
  year         = {2026},
  month        = nov,
  howpublished = {\url{https://monirzaman.github.io/reliable-coding-agents-state-machine-ai-dlc/}}
}

References

[1] AWS Labs. awslabs/aidlc-workflows: README and the plan-approval guard, core/hooks/aidlc-plan-approval-guard.ts. Accessed November 7, 2026.

[2] AWS Labs. The /aidlc skill for Claude Code.

[3] AWS Labs. Workflow Profiles and Scopes, Depth, and Test Strategy, AI-DLC user guide.

[4] W. Matos, R. Jain, S. Jog, Raja SP. Open-sourcing adaptive workflows for AI-Driven Development Life Cycle (AI-DLC). AWS DevOps Blog, November 29, 2025.

[5] AWS Labs. AI-DLC changelog, through version 2.11.3 (November 4, 2026).

[6] AWS Labs. Claude Code settings and hooks.

[7] AWS Labs. CLI commands: Guard Policy.

[8] SD Times. Anthropic brings code review into Claude Code. March 9, 2026. See also the Code Review documentation.

[9] Help Net Security. New Claude tool uses AI agents to find bugs in pull requests. March 10, 2026.

[10] AWS Labs. Review-freeze guard, AI-DLC repository.

[11] AWS Labs. Reviewer-scope guard, AI-DLC repository.

[12] OpenAI. Codex plugin for Claude Code (README and hooks/hooks.json). Accessed November 7, 2026.

[13] AWS Labs. Phases and Stages, AI-DLC user guide.

[14] Anthropic. feature-dev plugin, claude-plugins-official repository.

[15] GitHub. github/spec-kit: README, command templates and extension docs. Accessed November 7, 2026.

[16] Google. gemini-cli-extensions/conductor, version 0.3.0. See also InfoQ, January 2026.

[17] E. Schluntz, B. Zhang. Building effective agents. Anthropic, December 2024.

[18] OpenAI. A practical guide to building agents, 2025, as summarised by Maginative.

[19] AWS Labs. Build and Test stage.

[20] Anthropic. Effective harnesses for long-running agents. November 26, 2025.

[21] GitHub Docs. About protected branches: “Dismiss stale pull request approvals when new commits are pushed.”