Learning AI-DLC building a game, part 5: inside a stage

Part 5 of the AI-DLC game series: the eight steps inside one AI-DLC stage, from asking the engine for the next move, loading the rules, asking questions and keeping a diary, to the reviewer, the learnings, the approval and the report, shown with the Domain Design stage of this project

This is part 5 of a series on learning AI-DLC by building a game, World Rift Conflict, in Godot with an AWS backend. Parts 1 to 4 followed the work. This one stops and looks closely at one piece of the method: what happens inside a single stage, from the moment it starts until I approve it.

Parts so far:

The example throughout is the Domain Design stage from part 3: the stage that designed the automated end-to-end checks. Everything quoted comes from its records.

TL;DR

  1. A stage is not a prompt. It is a loop between a deterministic engine, which decides what happens next, and the agent, which does the work inside the step it was given.
  2. Every stage follows the same eight steps: ask, load the rules, do the work (questions, documents, diary), review, check, learn, approve, report.
  3. Two kinds of record come out of it. The documents a person reads, and an audit trail of every question, answer, review and approval.
  4. The engine refuses moves made out of order. That is what makes the loop trustworthy, and it is also where most of my early friction came from.

Who does what

Three parts take part in every stage:

  • The engine (aidlc engine orchestrate) is a small command-line program. It reads the workflow state and the stage graph and returns exactly one next move as JSON. It never writes the documents.
  • The agent (here, Claude Code) runs the engine, does the move it names, and reports the outcome. Inside a stage it takes on the stage's lead role: the architect for Domain Design.
  • The person answers the questions and approves the stage. Nothing moves past a stage without that approval.

1. Ask what to do next

Every move starts with the same command:

aidlc engine orchestrate next

It answers with one directive. For Domain Design it said, among other things:

{
  "kind": "run-stage",
  "stage": "domain-design",
  "lead_agent": "aidlc-architect-agent",
  "mode": "inline",
  "produces": ["components.md", "decisions.md", "traceability.json"],
  "reviewer": "aidlc-architecture-reviewer-agent",
  "review_class": "advisory",
  "next_stage": "Code Generation"
}

The real directive has full paths and more fields. It says who leads, what the stage must produce, what it consumes (the approved requirements, the code knowledge base, the team practices), which checks run on the outputs, and who reviews them. The agent does not decide any of that.

2. Load the rules

Before the work starts, the engine hands over the rules that apply, in parts, each with a receipt:

{
  "kind": "load-steering",
  "stage": "domain-design",
  "part": 1,
  "parts": 2,
  "next": "aidlc engine orchestrate continue e-UQxc3J"
}

The rules come in layers: the organisation defaults, the team practices agreed at Practices Discovery, the project's own rules, and the rules of the phase. A narrower layer can add to a broader one but not contradict it. Only after the last part does the run-stage directive arrive. Running a fresh next in the middle starts the delivery over at part 1, so no stage starts with half its rules.

3. Ask the questions

Most stages ask before they write. The questions go into a file with an [Answer]: line under each, every option explained, and a final X. Other (please specify):

## Q1. What kind of test backend?

A. **One long-lived Amplify sandbox named `e2e`.** ... (Recommended)
B. **A second Amplify Hosting branch, `test`.** ...
C. **A new sandbox for every run, deleted after it.** ...
X. Other (please specify)

[Answer]: A

I chose to be guided, so the agent asked them in batches in chat and wrote my answers back to the file. Before showing each batch it logs the question, and afterwards the answer, so the audit trail holds exactly what I was shown and what I picked:

aidlc engine log decision --stage domain-design --decision "Q1-Q4: ..." --options "Q1:A,B,C,X;..."
aidlc engine log answer --stage domain-design --details 'Q1: A; Q2: A; Q3: A; Q4: A'

The file stays the source of truth. I could have edited it directly, and the engine would have read the same file.

4. Write the documents and keep a diary

Then the lead writes what the stage produces. For Domain Design: a component catalogue with a machine-readable block and a human view, the architecture decision records, and a traceability file mapping every requirement to the component that realizes it.

At the same time the agent keeps a diary for the stage, memory.md, under four headings: Interpretations, Deviations, Tradeoffs, and Open questions. One entry from this stage:

Tradeoffs — The hook presses buttons by emitting signals instead of simulated input, so it works headless; keyboard focus and Enter-to-submit stay untested end to end (ADR-007).

The diary is the only file the agent maintains by hand outside the documents. It matters in step 6.

5. The review

If the stage has a reviewer, the agent records a review request, and the engine opens a slot for exactly one review file. A separate agent, the architecture reviewer, reads the documents and the upstream files, never the diary, and writes its findings into that file with a severity for each. The agent then records the verdict the file states:

aidlc engine log review --stage domain-design --reviewer aidlc-architecture-reviewer-agent --iteration 1 --verdict 'NOT-READY'

Domain Design's review was advisory: one pass, the fixes made afterwards, and the findings shown to me at the approval. Part 4 is about what those reviews found.

6. The checks and the learnings

When the stage asks for approval, small automatic checks called sensors run over its outputs: required sections, upstream coverage, traceability. For Domain Design the traceability check reported two requirement IDs missing from the design. I mapped them before deciding.

Then comes the learnings step. The engine reads the diary and offers its entries as candidates:

aidlc engine learnings surface --slug domain-design

I picked which to keep, and the engine wrote them into the project's rules:

aidlc engine learnings persist --slug domain-design --selections-json <file>

From this stage, one kept rule says Godot tests drive the UI by text and signals, never simulated input. Every later stage read it. That is how a stage's lesson reaches the next one without anyone editing a stage file.

7. The approval

The agent opens the gate, presents a summary of what the stage produced, and asks one question with fixed choices: Approve, Request Changes, and sometimes an option to add a skipped stage. My answer goes back to the engine with my words:

aidlc engine orchestrate report --stage domain-design --result awaiting-approval
aidlc engine orchestrate report --stage domain-design --result approved --user-input 'Approve'

A Request Changes answer is reported too, with my feedback, and the stage loops back inside itself before the gate opens again.

8. Report and move on

The approval report answers with the next step:

{
  "narration": "Progress: 4 of 7 stages done. Next: Code Generation.",
  "kind": "done",
  "workflow_continues": true
}

And the loop starts again with next.

Where the friction is

The engine is strict about order. It refuses moves made too early, and so do hooks that run on every tool call. Three times in this project they stopped the agent:

  • Starting Code Generation work before its plan was approved: "Code generation cannot run mutation-capable shell commands ... code-generation-plan.md is missing or empty."
  • Running a command while the rules were still arriving: "The Code Generation rules are still arriving (part 1 of 2 has been loaded)."
  • Asking for a second review where the stage allows one: "Cannot request review pass 2 ... this stage allows 1 review pass."

Each time the message said what to do instead, and doing that was the fix. It feels slow the first day. After that, it is the reason I trust that a stage marked approved went through every step.

What I would tell myself

  • Read the directive, not the stage file, to know what this run of the stage will do. The scope and settings change it.
  • Keep the diary honest. It is the raw material for the learnings, and the learnings are what make later stages better.
  • When a guard refuses something, do what its message says. Working around one throws away the record it protects.

What is next

Part 6 picks up the work again. Until then, one of these deep dives fills any day without project progress.

Related articles