build-loop moves a complex coding task through assess, plan, execute, and review, with a gate between each phase
Every run records its changes, decisions, and preferences to a build-loop-memory file, so the next one starts from what the last one learned rather than from scratch. build-loop runs on Claude Code, Codex, and any AGENTS.md-aware tool, one repo at a time. The flow diagram below maps build-loop as verified on June 24, 2026.
build-loop learns from every run
Every run ends by writing down what it learned. The next run reads that before it plans, so it starts from the last run's evidence instead of a blank slate.
Three things land in the build-loop-memory file: the decisions a run made and why, the lessons from what failed, and your standing preferences. A fresh session reads them first, so you stop repeating context the last session already had.
Every run also emits a Learn line that feeds a per-phase escape-rate control chart. The chart tracks where defects slip past a gate, phase by phase, and adapts how much the next run samples rather than checking everything at a fixed rate. Checking concentrates where failures actually escape.
Four phases run on every task
Assess, plan, execute, and review carry the loop. Iterate is not a fifth step forward, it is the path back into review when a check fails. Closeout and learn run at the end, not on every pass. Five gates sit across the whole thing: plan acceptance blocks before any implementer runs, commit audit fires on every qualifying commit, Validate sends a failure back to iterate, and the last two, the production push and the promotion of anything experimental, require a human.
Interactive
Open the flow diagram
The four core phases left to right, plus iterate, closeout, and learn. Click a phase for its sub-steps, and any step, gate, or subagent for detail.
The build-loop, end to end
The four core phases left to right, input to output, plus iterate, closeout, and learn. Click a phase to expand its sub-steps; click any phase, step, gate, agent chip, or role for detail.
Per session, real SessionStart hooks (retrieval, memory, architecture) also fire — they live in the data's hooks, not as a role.
- user goal / prompt
- repo + git state
- build-loop memory
Reads the live repo, past build-loop memory, and docs, then writes intent, goal, pass/fail acceptance probes, and the trigger flags (such as risk-surface and UI) that later phases read.
MECE partition plus dependency order.
N implementers edit their own files in parallel under a single-writer commit protocol.
Seven sub-steps A-G.
Phase 5 is a LOOP, not a forward stage: on a Review failure it escalates a stuck cascade by failure count, applies a fix, and loops BACK to Review (up to 5 classic / 25 autonomous).
Runs by default.
Always emits a ## Learn line.
- committed, validated change
- ## Learn outcome + drafts
Clarity enables autonomy
build-loop holds a North Star for the repo and propagates it to every subagent, so an agent can decide how to execute without waiting on approval for each micro-decision. These are the principles it enforces on every build.
Every agent knows your intent.
- Define the North Star first. State the core user value, key jobs, users, and non-goals before agents build.
- Propagate intent, not just tasks. Every subagent receives purpose, user impact, authority boundaries, anti-patterns, and a user-centered definition of done.
- Delegate decisions within explicit boundaries. Agents decide how to execute, but escalate when their approach violates the North Star or creates unjustified complexity.
Every build stays simple, honest, and easy to change.
- Make UI earn its place. Every visible element must help a meaningful user goal; avoid dead controls, orphaned options, and competing primary actions.
- Default to simplicity and progressive disclosure. Keep advanced features secondary unless they clearly serve a primary, frequent task.
- Protect truth and task flow. Never present mock, stale, or approximate data as live; primary tasks should remain reachable in one or two steps.
- Build for scalability without rigidity. Prefer modular, composable structures; allow short-term fixes only when user-safe and paired with explicit debt tracking.
SHIPS decides what ships.
- Gate acceptance with SHIPS: Singular focus, Honest information, Intuitive navigation, Purposeful elements, and Scalable structure.
Reach for build-loop when being wrong is expensive
The trigger is the cost of being wrong, not the size of the task.
- multi-file changes
- anything that adds or removes an endpoint
- anything crossing an architectural boundary
- a bug you can screenshot
- one-line edits
- typos and renames
- status checks
- questions you just want answered