AO Forge in practice: how we deliver software with AI agents
The problem
A coding agent is fast and capable, but it fails in predictable ways. It drifts out of scope. It invents requirements that nobody asked for. It forgets a constraint that a past incident taught the team. It breaks code that it did not read. And it reports work as finished when nobody has checked it.
Better prompts do not fix these failures, because each failure comes from a missing step in the process. So we built the process. Each failure mode has one structural step in AO Forge that stops it.
What AO Forge is
AO Forge is a set of commands, agents, skills, hooks and shell scripts that installs into Claude Code. It also runs under Codex and Grok, through an adapter and a plugin. It has no server and no database. Everything it produces is a plain file in the project repository, so a reviewer reads the record in the same pull request as the code.
The framework has three parts:
- A delivery pipeline. Commands take one feature through shaping, specification, task planning, implementation, verification and review.
- A project memory. Each repository holds files that tell an agent how the code is organised, which rules it must never break, and which words the project uses.
- A work registry. One shared list holds every idea, spec and incident of a repository, with its state. Each session starts by reading it.
How a feature moves through the pipeline
The pipeline has eight steps. After the human confirms the requirements, the commands start each next step themselves. The run continues to an open pull request with no "shall I continue?" questions.
- Shape. The shaping interview settles the requirements before anyone writes a spec. The agent researches the facts in the code itself, with file and line citations. It asks the human only for decisions, and it gives a recommended answer with each question. It works in rounds and stops only when no open question remains.
- Write the spec. A spec-writer agent turns the agreed requirements into a formal spec.
- Plan the tasks. A task-list agent splits the spec into task groups. Each group cuts one narrow but complete path through every layer that the change needs, so it works on its own the moment it merges. Each group fits in one fresh agent context.
- Verify the plan. A spec-verifier agent compares the spec and the tasks with the requirements. It looks for scope drift, dropped requirements, missed reuse and over-engineering, before any code exists.
- Write failing checks first. The testing gate blocks implementation until the acceptance checks for the spec exist, fail, and are committed. A hook enforces this gate in code, not in a prompt.
- Build. The orchestrator gives each task group to its own implementer agent, with the standards and the expertise domains that the group needs. Groups that write no file in common run in parallel waves. Before it merges a wave, the orchestrator checks that no two groups wrote the same file.
- Verify the build. An implementation-verifier agent runs every test suite and every acceptance check. It drives the real interface in a browser where the change has one. It compares the spec with the code, line by line, and lists each disagreement.
- Explain the change. A walkthrough agent writes a reviewer guide. It tours the diff in the order a reviewer needs, with code excerpts and diagrams, and it states the intent of the spec at each stop.
Each spec has its own git worktree. The developer can work on a second spec, or review a third, while the agents build.
The project memory
An agent that starts with no context explores, and exploration is where mistakes start. AO Forge gives each repository four kinds of memory, and the pipeline gives each agent only the parts its task needs.
Expertise domains are navigation maps of one area of the code, each kept within 300 lines. Beside each map sits an invariants file: the rules that an agent cannot work out from the code, each with the reason and the spec that taught it. One example from the AOne search domain:
The admin search index holds draft pages, so no public site may ever read it. The index updates on every page save, published or not, so a public search would show unpublished work to readers. Live-site search uses a separate index of published pages only.
A new agent that reads this rule does not "simplify" live search into a leak of unpublished work.
Architectural decision records hold the hard-to-reverse choices and the reason behind each one. If a change contradicts a record, the orchestrator stops and asks the human to supersede the record or fix the code.
Standards hold the house rules for code and prose: how to write tests, how to comment, how to handle errors.
A domain glossary gives each concept one agreed name, and lists the words to avoid. Agents and humans then use the same words in specs, code and reviews.
After each build, the framework refreshes the expertise files with what the work taught. The memory improves with each spec.
The walkthrough: a guided review
Agents now write code faster than a human can review it. A large diff in file order gives the reviewer no reading order, no intent and no sign of where the risk is. The walkthrough is the step that makes human review of agent code practical, and in our experience it is the most valuable document the pipeline produces.
Each walkthrough is pinned to one commit, and the pull request description links to it at that commit. It starts with the goal of the spec and the approach the code takes. A "what was rejected" table follows, with the reason for each rejected option. An architecture diagram and a change inventory come next. The inventory lists every changed file, and the framework checks that no file is missing.
The core is the guided tour: a sequence of stops through the diff, in the order that a reviewer needs to understand it. Each stop names the exact files and line ranges, quotes the requirement of the spec that the code satisfies, shows the important code excerpt, and links to the stops it connects to. A "worth noticing" note points at the detail that is easy to miss, such as two copies that must share no data.
The walkthrough describes the code. It does not judge it. When the writer sees a concern, it becomes an item in a review checklist, sorted by consequence and tagged as "verify", "judgement call" or "known gap". Each item says what to check and where. When the code and the spec disagree, the walkthrough says so, and it describes what the code really does.
The Block toolbar walkthrough for AOne has 11 stops over a diff of 74 files. The first checklist item tells the reviewer that the tooltip of a toolbar button must stay readable when the layout labels are switched on. The two values that decide which one shows on top sit in two different files, and the item names both lines and the test that guards them. The first build had exactly that defect: the layout labels covered the tooltip. The final verification found it before review, and the fix went in with a test that fails if the order breaks again.
The reviewer does not have to find the important lines in a large diff. The walkthrough takes them there.
Where the human decides
We removed every yes/no question that carried no decision. The human still owns the decisions that only a human can make, and AO Forge stops for six of them:
- issues that the spec-verifier finds in the plan,
- a disagreement between the spec and the code (the direction gate),
- a conflict with an architectural decision record,
- how to resume a run that was interrupted,
- whether to plan with one model or to compare several models,
- which open ideas a finished spec delivered.
Everything else runs. A pull request is easy to reverse, so the framework does not ask permission to open one. The merge is always a human decision.
A day with AO Forge
Start of session. A hook prints the live work of the repository when a session opens: the specs in progress, the specs in review, the open ideas, and the entry to continue. We name an entry, and the prime command loads exactly the files that entry needs. Nobody has to remember where yesterday stopped.
Ideas as they come. When an improvement occurs to us mid-task, we record it with one command and continue. The idea goes into the work registry, with a note file if it needs detail. When many ideas collect, another command groups them into a few roadmap items.
Shaping. We spend most of our own time here. A typical interview takes a few rounds of questions with recommended answers. Most answers are "accept". The few that we change are where the value of the interview is.
The build. After we confirm the requirements, the pipeline runs. We do other work while the agents build: often we review the walkthrough of the previous spec. For a feature where the approach is not clear, we run the same planning task in parallel lanes with Claude, Codex and Grok, and merge on the evidence.
Review. We open the walkthrough from the pull request and follow its stops through the diff. Then we work through its review checklist. The verification report tells us what the tests did not cover.
Merge and close. After the merge, the cleanup command removes the worktree and closes the work entry. A work entry is only "closed" when its code is merged. Until then it shows as "in review".
Maintenance. At intervals, the code-health command surveys the code for architectural friction. It collects the code smells that finished specs recorded and groups them into small fix batches. Each batch goes through its own branch and pull request.
One spec, end to end
The Text editing spec for AOne added a markdown formatting toolbar to the page editor. Its folder holds the full record: the question tree of the interview, 196 lines of requirements with code citations, the spec, a task plan, an acceptance-check script, a pre-build review, a final verification report, screenshots, and a 382-line walkthrough.
The record shows why the verification step exists. The final report states that every suite passed: 3,036 tests, 0 failures, and 42 of 42 acceptance checks. It then states that a browser probe found two defects that no test covered. One of them: the text area shrank from 192 px to 52 px at the first keystroke. A pipeline that trusts a green test run would have merged those defects. This one reported them, with a "fix now" label, before review.
The same report lists five places where the code and the spec disagree, each with a line reference in both files. And one decision record shows the framework protecting the architecture: the usability brief asked for a WYSIWYG editor, and a decision record rejected it, because it would add a second render path beside the one that publishes the site. The final verification checked the code against that record.
The numbers
AOne, the CMS that publishes this site, is the main proof. From June to September 2026:
- 66 specs went through the pipeline,
- 217 commits merged to the main branch, 82 of them features,
- six expertise domains hold 69 invariants between them,
- the largest single spec, the page editor, changed 122 files across nine task groups.
Across eight of our repositories, the pipeline has produced more than 400 specs, from a CMS and an autonomous delivery platform to two games.
AO Forge is also built with itself. Since the framework moved into its own repository at the end of August 2026, 40 specs have changed it. The framework records its own ideas, specs and incidents in its own work registry.
What we learned
Put each rule in a step, not in a prompt. An instruction in a prompt is a hope. A hook that blocks a commit until the failing tests exist is a fact. Each time an agent skipped a rule, we moved that rule into code.
Separate facts from decisions. An agent can find facts in the code. Only the owner of the product can make decisions. When the interview asks the human only for decisions, it gets shorter and better.
Never trust a green test run on its own. The most useful line in a verification report is the defect that the tests did not find.
Write the record for the reviewer. A reviewer who has the intent, the plan, the deviations and a guided tour of the diff reviews a 7,000-line change properly. Without that record, they approve it.
Record the reason with the rule. An invariant without its reason gets "fixed" by the next agent that does not understand it.
Limits
AO Forge does not replace engineering judgement. It moves that judgement to the places where it has the most effect: the shaping interview, the direction gates and the review. The full pipeline is too heavy for a one-line fix. Small fixes go through a lighter path, such as the bug-diagnosis skill. And the record is only as good as the human who reads it.