Building with AI Agents

Methodology version: 2026-07-24 — if you're using this method as a standard in your organisation, pin this version. See version history.

1. The Idea

A single AI agent asked to build and review its own code will rationalize its own output. This is the same cognitive failure that makes developer self-review unreliable. The fix is structural: separate the builder from the reviewer.

You need two agent records to make this work:

1. An Owner/Builder record — the shared understanding of what needs to be built and where things stand.
2. An Auditor record — the auditor's instructions, evidence review, and dispositions.

Each agent has strict write permissions. The builder writes the Owner/Builder record and the code. The auditor writes the Auditor record. Neither touches the other's record. Those records are the durable coordination layer: material instructions, evidence, decisions, and acceptance belong there.

Direct messages have a different job. They notify the other role that a stable checkpoint or blocker exists. They accelerate the hand-off; they never replace the files as the record of what happened or what must happen next.

Important: role prompts define intent; they are not access control. Use the tool's sandbox or filesystem permissions for the enforcement boundary. A tested pre-write policy hook can add defence in depth, but it is not the sole boundary. The Stop hooks shown later reinforce the role at a checkpoint but do not block file writes.

2. Two Roles, Two Files

The roles are always Builder and Auditor, regardless of which models or products fill them. Model names are implementation choices; the authority split is the method.

Entering a project

When an incoming prompt refers to this methodology, read this complete guide before acting. If the prompt assigns Builder or Auditor, preserve that role. Then read the repository-level instructions and discover the project's operating records by purpose and contents, not by assumed filenames.

1. Locate the record containing Owner direction, authorised packages, Builder status, evidence, and next step.
2. Locate the record containing Auditor instructions, dispositions, corrections, and acceptance.
3. Locate any configured handoff or session summary.
4. Determine the Owner revision, current package, current gate, latest disposition, evidence, and next role-owned hand-off before writing anything.
5. Do not create duplicate records merely because files named plan.md, comments.md, or handoff.md are absent.
6. If multiple candidate records exist, stop BLOCKED and ask the Owner which paths are authoritative.
7. If no operating records exist and the incoming prompt requests setup, ask the Owner where the two records should live; offer the default names below only when they have no preference.
8. If no operating records exist but the incoming prompt assigns Builder or Auditor, remain BLOCKED. Ask the Owner whether this is a new setup and who will initialise the other role's record.
9. Record the Owner-confirmed Owner/Builder, Auditor, product-goal, and optional handoff paths at the top of both operating records. Neither agent changes that map without Owner confirmation.

This guide uses plan.md, comments.md, handoff.md, and GOAL.md as readable default names in examples. They are not required filenames. Preserve an existing project's names and locations. In every instruction and template below, Owner/Builder record, Auditor record, handoff, and product goal document mean the paths discovered during project entry.

The Owner/Builder record

The Owner/Builder record holds the owner's direction and the builder's current package in one durable record. The owner's Now section is an ordered queue of authorised outcomes; only the current package is being executed. The owner controls the priority and decision sections. The builder never edits them. The builder controls the current-package, status, evidence, and next-step sections. The auditor reads this record but never writes it.

# Operating record map
Owner/Builder record: plan.md
Auditor record: comments.md
Handoff: handoff.md
Product goal document: GOAL.md

# Owner direction
Revision: O-17
Goal boundary: deliver O-17.1 and O-17.2 in development.
Stopping condition: both packages are runtime_proven; production remains untouched.

## Now
- O-17.1 Tenant-safe customer export: approved outcome and acceptance evidence.
- O-17.2 Renewal-risk view: approved outcome; execute after O-17.1.

## Next
- Account health scoring. Not yet authorised.

## Later
- CRM replacement exploration.

## Parked
- Automated customer outreach.

## Inbox
- Raw owner ideas and customer observations. Not implementation scope.

## Decisions
- Production remains out of scope until the owner approves it.

## Confirmed business rules
- Tenant identity comes from the authenticated server-side session, never from a client-supplied tenant identifier.
- An administrator may export records only for their authenticated organisation.
- A cross-tenant request returns no records and produces auditable denial evidence.
- Confirmed by Owner in revision O-17.

# Current package (builder)
Package: O-17.1

## Scope
- Tenant-safe customer export.

## Acceptance evidence
- Two-tenant runtime proof and negative-path test.

## Critical path
- Build and test server-bound tenant identity.
- Deploy the accepted change to development.
- Prove permitted export, cross-tenant denial, audit evidence, and cleanup.
- Terminal evidence: the complete development evidence run with test state restored.
- Hard stops: cross-tenant disclosure, production activity, or destructive state change.

## Builder restatement
- Business rule: export is limited to the authenticated organisation.
- Architecture: the service derives tenant identity from the server-side session.
- Boundary: production is excluded; development proof only.
- Contradictions or ambiguity: none remaining.
- Evidence: two administrators, two tenants, permitted and denied paths.

## Understanding status
- UNDERSTANDING_CONFIRMED by auditor against owner revision O-17.

## Status and next step
- Current critical-path gate: development runtime proof.
- Recorded ordinary failures: none.
- Independent evidence still to complete: permitted export, denial evidence, and cleanup.

The Auditor record

The Auditor record is the auditor's durable voice. It records the audit disposition, the evidence reviewed, exact corrections, evidence still required, and how an owner decision changes execution. It also holds the next owner-authorised work package when the auditor has prepared one. It does not invent business decisions.

# Operating record map
Owner/Builder record: plan.md
Auditor record: comments.md
Handoff: handoff.md
Product goal document: GOAL.md

# Understanding disposition
UNDERSTANDING_CONFIRMED

## Alignment evidence
- Builder restatement matches owner revision O-17.
- Business rules, architecture, boundaries, contradictions, and acceptance evidence are explicit.
- Implementation may begin for package O-17.1.

# Audit disposition
FIXES REQUIRED

## Evidence reviewed
- Current package diff and two-tenant dev result.

## Required corrections
- Bind access to server-side tenant identity.
- Add a two-tenant negative-path test.

## Evidence required for acceptance
- Runtime proof with two separate administrator accounts.

## Owner constraints translated into execution
- Production remains out of scope: development proof only.

# Next authorised package
Package: O-17.2

## Scope
- Renewal-risk view from owner revision O-17, Now item O-17.2.

## Owner-confirmed business rules
- Exact expected outcomes, prohibited outcomes, boundaries, and negative cases.

## Exact implementation instructions
- Files, interfaces, sequence, rollback points, and explicit exclusions.

## Access preconditions
- Required capability, environment, owner, approved access mechanism, and verification result.
- No secret values.

## Acceptance evidence
- Commands, runtime proof, negative paths, and screenshots required.

## Critical path
- Ordered gates: implementation, tests, development deployment, complete runtime evidence, cleanup.
- Terminal evidence: permitted and denied paths proven with two administrators and two tenants.
- Hard stops: cross-tenant disclosure, production activity, destructive state change, or false safety evidence.

## Understanding gate
- Builder must restate the package in the Owner/Builder record and send UNDERSTANDING_REVIEW_READY.
- No implementation until the auditor records UNDERSTANDING_CONFIRMED.

The builder must not infer business logic from old code, historical plans, customer comments, or its own judgement. The auditor may challenge a decision and present options, but it cannot make the decision. Nothing enters builder scope until the owner has placed it in Now in the Owner/Builder record. Every package and checkpoint records the owner revision and Now item that authorised it. The auditor rejects a checkpoint if that reference changed or the owner section was edited by an agent.

The builder owns implementation, tests, commits, deployment evidence, and the Owner/Builder record. Before touching code, it restates the package there: business rules, architecture, boundaries, acceptance evidence, ambiguities, and contradictions. It challenges anything that does not cohere. After the auditor records UNDERSTANDING_CONFIRMED, the builder executes one bounded pass along the critical path, keeps its record current, and ends at the named return-channel hand-off.

The auditor is strategically ahead, operationally checkpoint-driven. It turns owner intent into explicit, falsifiable business rules and takes them back to the owner until the product logic is confirmed. It then investigates the existing system, adversarially tests the proposed design, and prepares the next implementation-ready package: dependencies, verified access preconditions, exact files, critical-path sequence, boundaries, rollback points, acceptance criteria, terminal evidence, and hard stops. Before implementation, it walks the builder through that package and checks the builder's restatement. During implementation it reviews stable checkpoints rather than shadowing every edit.

The auditor escalates to the owner when it encounters:

• Business decisions — anything where the right answer depends on business context the auditor can't know.
• High-impact forks — decisions that change the shape of future steps, where getting it wrong is expensive to undo.
• Access and permissions — anything the agents can't resolve themselves.
• Cross-team coordination — anything that involves people or systems outside the project.

The owner decides, the auditor translates the decision into builder instructions.

The auditor tells the builder how to test and what evidence to produce. The builder executes the tests and reports results in the Owner/Builder record. The auditor does not edit implementation code.

Checkpoint protocol

The two configured records are the project's durable operating memory; messages are only the doorbell. The builder updates the Owner/Builder record before sending the auditor a checkpoint. The auditor updates the Auditor record before replying. The messages do not carry the working record, detailed evidence, or instructions.

UNDERSTANDING_REVIEW_READY
Owner revision: O-17
Package: O-17.1
The Owner/Builder record contains my restatement, ambiguities, and contradictions.
No code changed. Ready for alignment review.

UNDERSTANDING_CONFIRMED
Owner revision: O-17
Package: O-17.1
The Auditor record contains the alignment disposition.
Implementation may begin.

CHECKPOINT_READY
Checkpoint: O-17.1-C3
Owner revision: O-17
Package: O-17.1 tenant-safe customer export
Evidence: commit 4f27c1a
Critical-path gate: complete local evidence run.
The Owner/Builder record is current: scope, diff, recorded failures, completed and blocked evidence branches, questions, and intended next step are recorded.
Ready for audit.

AUDIT_COMPLETE
Checkpoint: O-17.1-C3
Evidence reviewed: commit 4f27c1a
The Auditor record is current.
Disposition: ACCEPTED / FIXES REQUIRED.

The Auditor record contains the actual disposition: evidence reviewed, exact corrections, evidence still required, and the translation of any owner decision into execution constraints. Ordinary findings are batched into one response. A verdict without instructions is not an audit.

Keep the message vocabulary small: UNDERSTANDING_REVIEW_READY, UNDERSTANDING_CONFIRMED, PACKAGE_STARTED, MEANINGFUL_MILESTONE, CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, P1_DECISION_NEEDED, and AUDIT_COMPLETE. Each message identifies the owner revision, package, critical-path gate, and relevant checkpoint or evidence reference. Its meaning is still simple: the relevant durable file is current; read it before acting.

The auditor interrupts the builder mid-build only for a production action, credential or secret exposure, cross-tenant leakage, destructive data or migration risk, uncontrolled paid-provider use, or a test that falsely proves safety. Everything else waits for the next stable checkpoint.

Speak to the owner, not to the system

Escalation isn't just when — it's how. The auditor's job is to translate the system's state into something the owner can act on. Two rules cover the rest.

Bottom line first. Every owner-facing update opens with the business-level truth in one plain sentence: what is blocked, where, and what action unblocks it. Implementation detail — repo names, internal codes, stack traces — comes last, if at all. After the one-sentence truth, state the decision the owner needs to make: builder can continue, owner approval required, or outside help needed.

No softening, no gatekeeping. Bad news arrives direct, complete, and early. An auditor that filters bad news to spare the owner is failing the role. If something is broken, expensive to fix, or going to slip, that is sentence one, not sentence five. The owner cannot make decisions on information they do not have.

Generic example.

Wrong: "Builder hit a 500 on POST /sync, traced to the v2 API client. Retries didn't help. Investigating dependencies — possible regression in last week's deploy."

Right: "The publish step is failing because the upstream API is broken. Fix is to patch and redeploy that API — builder is on it now. No owner action needed unless it slips past today."

The first version forces the owner to do the translation work. The second tells the owner what to decide.

The owner briefing

The one-sentence rule above is for a single escalation. For a recurring update — a checkpoint, a status request, a decision point — the auditor uses a fixed four-part shape. It matters most when the owner is supervising several projects at once: nobody holds the full state of four projects in their head, so each update has to let the owner re-enter a project cold in seconds and know exactly what, if anything, to do.

Four parts, always in this order:

• Done — what is finished, in plain business terms. “Done” means the auditor accepted the evidence (the auditor_accepted state), not that the builder said it passed. Add technical detail only where it changes risk, timing, or a decision.
• Left — what remains, one bullet per step, in the order it will happen. Call out anything actively blocking progress.
• Status & risk — one short paragraph: is the project going well, badly, or blocked, and what is the single biggest risk right now.
• Owner tasks — the part the owner reads first. Either “no owner action right now” or the exact action required. Then state how the cycle proceeds: builder continues, auditor awaits evidence, or both pause for a named authority decision.

Live-state briefing

For a fast checkpoint update, use this shorter shape. It tells an owner exactly where the work is without making them reconstruct the workflow from technical detail.

This is not a template for every message — “step 3 done, moving to 4” needs no ceremony. Use the full shape at the moments that carry a decision: at a review checkpoint, after a CI or deploy failure, before handing the next step to the builder, before any deployment decision, and whenever the owner asks “where do we stand?” These are the meaningful boundaries in the checkpoint cycle.

A generic example:

Keep this separate from the handoff summary later in the guide: the handoff is written for the next agent picking up cold; the briefing is written for the human deciding what happens next.

Why this split makes you faster

The role separation isn't just about integrity — it's about using the right capability for the right job. The auditor does the investigation, risk analysis, dependency mapping, and sequencing. The builder receives scoped packages with clear instructions. For well-understood work, that often means a high-reasoning auditor and a faster execution model as builder.

The auditor investigates the next steps, does the thinking, and makes sure the builder just has to build — no research required. This means the builder runs faster, uses fewer tokens, and produces more predictable output. The thinking happened upstream.

Choose the pair for capability and coordination

A same-stack pair can communicate directly and carry checkpoints with less friction. A cross-family pair may reduce the chance that both agents rationalise the same bad pattern in the same way, but it may need a scheduled or manual notification bridge. Different models can still share data, assumptions, and failure modes. The procedural independence comes from the roles, files, authority boundaries, and evidence gates.

Considerations about model performance

Coding benchmarks are useful for identifying capable and cost-efficient candidates, but they mostly measure execution inside defined engineering tasks. This methodology gives the two roles different work. The Auditor handles uncertain business logic, system investigation, architecture, adversarial review, and evidence design. The Builder receives a confirmed, implementation-ready package. Select models for those roles rather than from one overall leaderboard position.

My current OpenAI-stack default is SOL xhigh or Ultra as Auditor and Terra medium as Builder. Terra does not need to rediscover the product logic, but it needs enough understanding to restate the package, challenge contradictions, and implement safely. The shared-understanding gate tests that capability before code is written.

Use the strongest Auditor selectively where mistakes are expensive. Escalate the Builder only when its teach-back, implementation, or evidence fails. The useful efficiency metric is total cost per auditor-accepted, runtime-proven package, including clarification and rework, not API cost per isolated coding attempt.

Who does the thinking: follow the smarter model

The default split — auditor thinks, builder executes — assumes the auditor is the smarter model. If it isn't, flip the thinking to where the capability lives.

Fast builder, heavy auditor. The auditor does all investigation, risk analysis, and sequencing. It translates each upcoming step into precise, executable instructions in the Auditor record with exact file paths, commands, and acceptance criteria. The builder proves that it understands the package, then executes it without repeating the upstream research. This is the fastest path for well-understood work.

You are the Auditor and the thinker. The Builder is a fast execution model and does not own open-ended investigation, research, or design. Use the configured operating-record paths. Do all investigation, risk analysis, dependency mapping, and rollback planning yourself. Before the Builder reaches a step, translate it into precise, executable instructions in the Auditor record: exact file paths, commands, acceptance criteria, and the evidence you require. Require the Builder to restate and challenge the package before code. After shared understanding is confirmed, the Builder executes without repeating the upstream research.

Heavy builder, pragmatic auditor. When the builder is the stronger reasoning model, don't waste it on execution alone. The auditor delegates investigation to the builder between steps and requires the observations in the Owner/Builder record. The builder returns risks, alternatives, and commentary there. The auditor reads those observations alongside the code; the human makes higher-impact decisions with both perspectives in view.

You are the Auditor working with a heavy-reasoning Builder. Use the configured operating-record paths. When you need investigation or research for upcoming steps, delegate it through the Auditor record: ask the Builder to investigate specific open questions between build steps and report observations, risks, and commentary in the Owner/Builder record. Read the Builder's observations alongside the code when reviewing. For high-impact forks, escalate to the human with both your assessment and the Builder's observations attached.

The rule. The owner direction at the top of the Owner/Builder record is the owner's voice. The package, status, evidence, risks, and alternatives below it are the builder's voice. The Auditor record is the auditor's voice. The first record is not just a progress log; together, the two records are the durable operating memory.

This is also a security pattern

This structure addresses three of the most dangerous failure modes in autonomous AI systems: excessive agency (one agent with unchecked write access everywhere), cascading failures (an agent whose output feeds its own next step with no independent check), and accountability gaps (you can't tell which agent decided what went wrong). File-level write boundaries, independent review, and evidence gating before step completion are the same controls you'd apply to any high-stakes autonomous system. See the agent scenario in the AI Security Primer for the full threat model.

3. Plan First, Execute Second

The most important part of this workflow happens before any agent starts building. You create the goal document — but you don't have to write it alone. The agent interviews you.

You sit down with Claude or Codex and talk about what you want to build. The agent asks questions, challenges your assumptions, and helps you think deeper. Together you produce a goal document — a vision written from the future, describing what life looks like after the software is delivered. No implementation details. No stack decisions. Just: what can a user do, and what questions can the system answer?

Write questions, not requirements

"Which contract renewals are coming in the next 6 months, and which are at risk?" implicitly demands a far richer system than "The system shall have a contract renewal dashboard with alerting."

A question tells the builder what the user needs to know and leaves the implementation open. Questions also set the quality bar implicitly: if the system cannot answer the question, it has failed. No interpretation required.

Write at least 20 questions. The depth of your questions drives the depth of the software. If a question only requires one data source to answer, it's too shallow. The best questions require three or more.

The process

1. Interview — The agent interviews you. What are you building? Who is it for? What does the user's day look like after this exists? The agent pushes you to think in capability questions (at least 20) and writes the goal document from the conversation.
2. Confirm business rules — The auditor converts the owner's intent into explicit, falsifiable rules in the Auditor record: required outcomes, prohibited outcomes, boundaries, and negative cases. The owner corrects and confirms them, then records or approves the confirmed rules under a named owner revision in the owner-controlled section of the Owner/Builder record.
3. Access check — At project intake and before each package, the auditor identifies the required repos, environments, services, APIs, databases, credentials, permissions, and test data. The owner confirms availability, and the agents verify that each required access path works. Missing access is resolved or the dependent work leaves the package before any code is written.
4. Investigate and prepare — The auditor investigates the existing system, tests the proposed design against the confirmed rules, looks for contradictions and failure paths, then writes one implementation-ready package in the Auditor record.
5. Run the understanding gate — The auditor walks the builder through the rules, architecture, boundaries, and evidence. The builder restates them in the Owner/Builder record, challenges ambiguity, and identifies contradictions. The auditor records UNDERSTANDING_CONFIRMED in the Auditor record only when all three parties share the same product logic.
6. Coordination setup — Choose direct checkpoint messages when available. Otherwise create the low-frequency hook or scheduled check needed to carry the work forward without making the owner a message bus.
7. Start the authorised package — Only after the understanding gate, the builder executes the next bounded pass along the critical path and the auditor reviews its stable hand-off independently. The owner intervenes only when the auditor escalates an authority decision.

The shared-understanding gate

This gate prevents a technically competent implementation of the wrong product logic. The auditor does not decide what the business rules mean. It makes the rules testable, exposes missing decisions, and takes them back to the owner until the owner confirms the product truth.

The builder then proves that the package was understood. Its restatement in the Owner/Builder record answers five questions: What must the user be able to do? What must never happen? How does the proposed architecture enforce those rules? What remains outside the package? What evidence would falsify a claim of success?

If the builder finds ambiguity or contradiction, implementation remains blocked. The auditor resolves technical contradictions itself and returns business contradictions to the owner. Direct discussion can accelerate the walkthrough, but the builder's restatement and the auditor's release remain in the two durable files.

Why access goes first

Treat access as a precondition. At project intake and before releasing each work package, the auditor identifies every repository, environment, service, permission, credential, test-data source, and deployment capability required to complete and prove the package. The owner confirms what is available, and the agents verify that the required access paths work before implementation begins. Missing access is resolved, or the dependent work is removed from the package.

• Repos and branches — which repositories and branches are required, and does the builder need permission to create new ones?
• Environments, services, and APIs — which running services, API access, databases, test environments, and deployment capabilities are required?
• Credentials, permissions, and data — which access paths and test-data sources must work, who owns them, and how will availability be verified?
• External tools — does the auditor need browser access for end-to-end testing? Does the builder need package registries, CI/CD pipelines?
• Permissions mode — what is the least-privileged sandbox and approval policy that still lets the builder complete the package? Unrestricted execution is a separate risk decision, not the default.

The operating records name the required capability, environment, owner, verification status, and approved access mechanism. They never contain secret values. Agents do not ask the owner to paste production credentials into an operating record or ordinary message.

If evidence exposes an unforeseen access dependency during implementation, the builder records exactly what exposed it and continues every independent branch that remains safe and meaningful. The auditor classifies the dependency as a planning defect or a genuinely new dependency, corrects the package, and asks the owner only for the specific authority or access that is actually required. An agent cannot convert incomplete intake into an unexplained mid-run demand on the owner.

Why files still matter with long context

A 1M-context model like Claude Opus 4.8 can hold the product goal, operating records, and history in working context for multi-week projects. The records still matter because they preserve direction, decisions, evidence, and audit history across sessions, context resets, handoffs, and model changes. The Owner/Builder record stops being just a progress log and becomes the project's durable operating memory.

4. Checkpoint-Driven Work

The project objective stays durable in the Owner/Builder record. Each agent works through one bounded, role-owned pass at a time. The builder works until the next builder-owned hand-off; the auditor then reviews independently until it records a disposition. Neither role consumes turns while waiting for the other.

This methodology has changed as the models have changed. Early versions used five-minute polling because agents worked in short bursts. The June edition moved to long autonomous runs and natural breakpoints. The July 10 edition added persistent Goals, selective activation, and checkpoint messages. The July 11 edition added the shared-understanding gate. This edition makes each active Goal a bounded pass and puts the critical path into the Auditor's instructions: stronger execution should reduce wasteful correction cycles without weakening the evidence gate.

The tools will keep changing. The controls that matter do not: durable memory, separate authority, independent review, and evidence before progress.

Five separate things

Goal. A persistent objective gives an agent purpose, scope, constraints, verification, and a measurable stopping condition. In this method, the active Goal covers one bounded role-owned pass. The longer project objective stays in the Owner/Builder record.

Understanding gate. The owner confirms falsifiable business rules, the builder restates the package, and the auditor confirms alignment before implementation. It is a release condition, not another recurring review loop.

Checkpoint. A checkpoint is a stable piece of work that can be reviewed: a coherent diff, a completed slice, a failed test with evidence, or deployment proof. The builder does not ask for review on every keystroke.

Direct message. A direct message tells the other role that a checkpoint or blocker is ready. It is the preferred return channel. The files remain the source of truth.

Pause. /goal pause temporarily holds an unfinished pass. A completed Builder hand-off ends the Goal and waits outside Goal mode. The next Builder Goal starts only after the Auditor records a new authorised pass.

Work the critical path

The critical path is the shortest safe sequence from the authorised package to complete acceptance evidence. A first passing test or ordinary defect is intermediate evidence, not a stopping condition. The Auditor uses the words critical path in the Auditor record and records the ordered gates, terminal evidence, and genuine hard-stop conditions before releasing implementation.

When something fails, classify it before deciding what happens next:

• Hard stop — stop the pass for cross-tenant effects, credential or secret exposure, destructive or irreversible state, uncontrolled external cost, unintended production activity, or evidence that falsely proves safety.
• Record and continue — record an ordinary UI, copy, presentation, persistence, or workflow defect, then complete every independent scenario that remains safe and meaningful.
• Dependency failure — do not run a scenario when its prerequisite failed and the result would be meaningless. Record the blocked branch of the evidence run and continue only independent branches.

After the bounded pass, the Auditor reviews the accumulated evidence, looks for a common cause, and writes one coherent correction package. The Builder then reruns the affected evidence together with preserved behaviour, relevant negative cases, isolation checks, and test-state cleanup. The aim is fewer wasteful build–review–deploy cycles, not fewer reviews where early intervention reduces risk.

The Builder–Auditor cycle

1. The auditor converts the owner's intent into falsifiable business rules. The owner corrects and confirms them in a named revision of the Owner/Builder record.
2. The auditor investigates the existing system, attacks its own proposed design, and writes one implementation-ready package in the Auditor record, including the critical path, terminal evidence, and hard stops.
3. The auditor walks the builder through the confirmed rules, architecture, boundaries, and acceptance evidence. The builder records its restatement, ambiguities, and contradictions in the Owner/Builder record, then sends UNDERSTANDING_REVIEW_READY.
4. The auditor compares that restatement with the owner revision and package. It resolves technical contradictions, escalates business contradictions, and records UNDERSTANDING_CONFIRMED only when the shared understanding is exact.
5. The builder now runs one bounded autonomous pass. Routine implementation decisions, ordinary test failures, and progress commentary do not end it. The builder records failures and completes every independent safe evidence branch.
6. The builder freezes the evidence in the Owner/Builder record and ends the pass with CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. It sends the doorbell and becomes idle; it does not wait inside the Goal for a reply.
7. The auditor reviews the stable evidence, runs a skeptic pass, looks for common causes, writes one actionable disposition in the Auditor record, and sends AUDIT_COMPLETE.
8. If fixes are required, the auditor defines a new bounded correction pass with its own terminal evidence. If the package is proven and another Now item is already authorised, the auditor prepares it and the understanding gate runs again before implementation.
9. After its disposition or package-preparation hand-off, the auditor also becomes idle. The owner returns only for business meaning, priority, meaningful scope change, production go/no-go, or another authority decision.

Standby rules

Never make a Goal's completion depend on another agent replying, owner approval, or indefinite waiting. Never spend Goal turns merely checking whether an unchanged file moved. Review stable diffs, not every edit. Batch non-urgent feedback. Use a second auditor only for a genuinely independent adversarial pass.

If direct checkpoint wake-ups are unavailable, use a scheduled same-task check or heartbeat: 10–15 minutes during active implementation, 30–60 minutes during slow CI or deploy work, then back off after an unchanged check. Manual owner relay is the last resort, not the normal message bus.

Step states

Each step in the Owner/Builder record moves through these states. planned is not understanding_confirmed, and builder_checkpoint_ready is not auditor_accepted. Code that compiles and tests that pass are evidence to review, not proof by themselves.

This prevents the common failure where things move fast on "PASS" without proving actual behavior. The auditor defines the required evidence before the builder starts, and the builder cannot call a step accepted until the auditor has reviewed it. Customer-facing acceptance may additionally require the owner to review whether the terminology and journey express the intended product truth. Put that review in the package's acceptance evidence instead of adding another universal workflow state.

Handoffs and compaction

Even with 1M context, sessions end — terminals close, roles switch, a human takes over. You need one handoff artefact that produces the same shape of summary whether you are compacting mid-session or starting fresh.

Use the same handoff instruction three ways: with your tool's context-compaction command, at session end, and when a new session starts. Save the result to the configured handoff path. If none exists, ask the Owner where it should live and offer handoff.md only as a default. The next agent then lands in the same informational posture.

Here's a good default. Copy it, adapt it if your project needs more, and keep it stable for the life of the project — consistent wording is what keeps every summary comparable.

Prepare a handoff for a fresh agent joining this project. Cover: Owner revision and confirmed business rules; configured operating-record paths; current authorised package and critical-path gate; understanding status; what is complete, in progress, blocked, and next; decisions that must not be relitigated; evidence and immutable references; unresolved contradictions; access blockers; and the next role-owned hand-off. Maximum three paragraphs.

5. The Goal Document

The goal document is the highest-leverage investment in the entire process. For a significant project, the interview that produces it might take hours spread over a day or two. It is worth every minute.

The agent interviews you and writes the goal document from the conversation. You don't need to be a writer. You need to know what you want. The agent's job is to pull that out of you and structure it.

Do not confuse the two meanings of goal. The product goal document is the durable product specification for the project; GOAL.md is only the default example name. Codex /goal is a thread-scoped operating objective with a stopping condition. The owner direction in the Owner/Builder record sets priority; the package sections record authorised work; the active Goal drives one bounded role-owned pass.

Structure

1. Walkthrough — A step-by-step narrative of the user's experience. Written as if the product already exists and is working. The agent drafts this from what you describe.
2. Capability questions — At least 20 questions the finished software will answer. These are the specification. The agent helps you go deeper — the first 10 are easy, the next 10 are where the real value lives.
3. Scope boundaries — Explicit list of out-of-scope capabilities. Without hard boundaries, an autonomous agent will keep expanding scope. The agent should ask you: "What should this NOT do?"

Good vs. weak questions

Weak: "Can I see a list of my customers?" — produces a database and a list view.

Strong: "Which of my customers are close to their license capacity, have a renewal coming in the next 90 days, and have had no contact from our team in the last 6 weeks?" — requires usage data, contract data, activity tracking, time-based filtering, cross-referencing, and risk surfacing. It will produce all of those things because it has to.

6. Code: Claude Code

Claude Code offers tool-specific coordination paths when direct task-to-task checkpoint wake-ups are unavailable. They are fallbacks, not a reason to run both roles continuously. Keep the durable records and checkpoint protocol from Section 4.

Manual single-turn work

This is suitable for a short, human-led task. It is not the autonomous paired-agent path: use a loop or hook fallback when the roles need to carry an authorised package forward without an owner restarting them.

claude "Your role is Builder. Read the complete methodology at https://mikkosniemela.com/build-with-agents, discover the configured operating records, and complete only the current Builder-owned pass. If understanding is not confirmed, restate the package in the Owner/Builder record, send UNDERSTANDING_REVIEW_READY, and stop. If confirmed, follow the critical path to the named Builder hand-off, update the Owner/Builder record, send the doorbell, and stop."

claude "Your role is Auditor. Read the complete methodology at https://mikkosniemela.com/build-with-agents, discover the configured operating records, and complete only the current Auditor-owned pass: prepare the critical path and package, decide the understanding gate, or audit one frozen hand-off. Record the disposition in the Auditor record, send the doorbell, and stop."

Self-paced: /loop dynamic mode

Invoke /loop with no interval and the agent picks its own check-back. Use it only where direct messaging is unavailable. The loop should inspect a real checkpoint or a meaningful scheduled follow-up, not repeatedly reread unchanged files.

/loop Read the configured Auditor record. If a new Builder pass is authorised, follow its critical path to the named hand-off, update the Owner/Builder record, send the doorbell, and stop that pass. If understanding is not confirmed, record the restatement in the Owner/Builder record, send UNDERSTANDING_REVIEW_READY, and stop. Do not create work when no new pass exists.

/loop Read the configured Owner/Builder record. If a role-owned hand-off is ready, complete one alignment or frozen-evidence audit pass, write one actionable disposition to the Auditor record, send the doorbell, and stop that pass. When there is no new evidence, do not create work; use only the configured low-frequency check-back.

Continuous: /loop with interval

Fixed-interval polling is a fallback for tools without reliable direct wake-ups. Use it for slow CI, deployment, or unattended work where a real check is needed. Start at 10–15 minutes during active implementation, not 5. Session-scoped — if the terminal closes, the loop stops.

/loop 10m Read the configured Auditor record. If a new Builder pass is authorised, follow its critical path to the named hand-off, update the Owner/Builder record, send the doorbell, and stop that pass. If understanding is not confirmed, record the restatement in the Owner/Builder record, send UNDERSTANDING_REVIEW_READY, and stop. If nothing changed, do not create work.

/loop 10m Read the configured Owner/Builder record. If a role-owned hand-off is ready, complete one alignment or frozen-evidence audit pass, write one consolidated disposition to the Auditor record, send the doorbell, and stop that pass. If nothing changed, do not create work.

Checkpoint reinforcement: Stop hook

A Stop hook can ask the role to make one additional checkpoint pass before ending its turn. The stop_hook_active guard then allows the role to stop, so this is not a persistent polling loop and it is not file-write enforcement. Use it to catch a missing file update or return-channel message. Use /loop or a scheduled task for repeated follow-up. Verify current behavior in the Claude Code hooks documentation.

Directory structure

your-project/                 # one worktree or clone per role
  .claude/
    settings.local.json      # hook configuration
    hooks/
      build-a-plan.sh        # builder hook
      audit-a-plan.sh        # auditor hook
  plan.md                    # default Owner/Builder record
  comments.md                # default Auditor record
  GOAL.md                    # default product goal document
  handoff.md                 # optional default handoff

settings.local.json

This file configures which hooks fire and when. The builder and auditor configurations below cannot coexist at the same path in one checkout. Give each role its own worktree or clone, with its own gitignored settings.local.json.

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/build-a-plan.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/audit-a-plan.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

build-a-plan.sh (Builder hook)

#!/bin/bash
# Ask for one final builder checkpoint pass before this turn stops.

INPUT=$(cat)
STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)

if [ "$STOP_ACTIVE" = "true" ]; then
  exit 0
fi

cat >&2 <<'MSG'
[Build-a-Plan] Before stopping, finish the current bounded Builder pass. Use the
configured operating-record paths. If this package lacks UNDERSTANDING_CONFIRMED,
do not change code: restate the package in the Owner/Builder record and send
UNDERSTANDING_REVIEW_READY. Otherwise update the Builder-owned sections of that
record with the critical-path gate, exact evidence, recorded failures, cleanup,
and next step. Do not edit the Auditor record or Owner-controlled sections. Send
CHECKPOINT_READY,
DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED to the auditor.
MSG
exit 2

audit-a-plan.sh (Auditor hook)

#!/bin/bash
# Ask for one final auditor checkpoint pass before this turn stops.

INPUT=$(cat)
STOP_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false' 2>/dev/null)

if [ "$STOP_ACTIVE" = "true" ]; then
  exit 0
fi

cat >&2 <<'MSG'
[Audit-a-Plan] Before stopping, finish the current alignment, audit, or package-
preparation boundary. If an understanding review is ready, compare it with the
owner rules and package before releasing implementation. Use the configured
operating-record paths. Write every disposition, critical path, hard stop,
instruction, evidence requirement, and next package to the Auditor record. Do not
edit the Owner/Builder record or code. Send the relevant doorbell or record
P1_DECISION_NEEDED, then end the current pass.
MSG
exit 2

Make both scripts executable: chmod +x .claude/hooks/*.sh

Stop safety: keep the stop_hook_active check. Without it, the hook can repeatedly continue its own continuation.

FileChanged notification

A FileChanged hook can log or notify when a watched file changes. The simple echo handlers below do not resume an idle role, carry the audit record, or enforce write boundaries. Use direct task messaging for the doorbell. If the current Claude Code release supports an idle-session wake mechanism, test that mechanism explicitly before relying on it.

Use these only as observable notifications. Replace <AUDITOR_RECORD_PATH> and <OWNER_BUILDER_RECORD_PATH> with the configured paths discovered at project entry:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "<AUDITOR_RECORD_PATH>",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Build-a-Plan] Auditor record changed. Read the configured Auditor record and take action on new instructions.'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "<OWNER_BUILDER_RECORD_PATH>",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Audit-a-Plan] Owner/Builder record changed. Read the configured record and review Builder progress.'"
          }
        ]
      }
    ]
  }
}

FileChanged fires only on subsequent modifications. It is not the preferred builder–auditor coordination path.

7. Code: OpenAI Codex CLI

Codex CLI supports hooks and persistent instructions through AGENTS.md. This is a CLI implementation path. The Goal-mode scenario in the next section is a distinct Codex app workflow; do not conflate Goal state with CLI hooks.

Use hooks for policy checks or one additional checkpoint pass. Use a scheduled task, not a recursive Stop hook, when an unattended heartbeat is genuinely needed. Hooks are an implementation aid, not the methodology's default coordination model.

Important: Codex hooks are enabled by default, but non-managed hooks must be reviewed and trusted before they run. Inspect them with /hooks. The current hooks documentation is the source of truth. If your configuration disabled hooks, re-enable them explicitly:

[features]
hooks = true

Directory structure

A single code-writing builder and a read-only auditor can share one workspace when file-write boundaries are technically enforced. If two agents can both modify implementation, use separate worktrees. When each role needs a different AGENTS.md, separate worktrees or clones are the cleanest path. If Git carries the two durable records between them, the builder may commit the Owner/Builder record and the auditor may commit the Auditor record; neither commits the other role's record.

your-project/
  .codex/
    hooks.json               # hook configuration
    hooks/
      build-a-plan.sh        # or audit-a-plan.sh
  AGENTS.md                  # role instructions for THIS instance
  plan.md                    # default Owner/Builder record
  comments.md                # default Auditor record
  GOAL.md                    # default product goal document
  handoff.md                 # optional default handoff

AGENTS.md — Builder worktree

Codex uses AGENTS.md (equivalent to Claude Code's CLAUDE.md) for persistent role instructions. Each worktree gets its own AGENTS.md matching its role. After project entry, replace the path placeholders below with the discovered configured paths.

# Builder Role

You are the Builder. Your job is to build according to the authorised package.

## Configured paths
- Owner/Builder record: <OWNER_BUILDER_RECORD_PATH>
- Auditor record: <AUDITOR_RECORD_PATH>
- Product goal document: <PRODUCT_GOAL_PATH>
- Handoff: <HANDOFF_PATH_OR_NONE>

## Write permissions
- Builder-owned sections of the Owner/Builder record — update package progress, evidence, questions, and notes
- All source code files

## Read permissions
- Auditor record — the Auditor writes instructions and dispositions here
- Product goal document — the original product goal

## Rules
- NEVER write to the Auditor record
- NEVER edit the Owner direction or decision sections of the Owner/Builder record
- Before code, restate the package in the Owner/Builder record: business rules, architecture, boundaries, acceptance evidence, ambiguities, and contradictions
- Send UNDERSTANDING_REVIEW_READY and do not implement until the Auditor record contains UNDERSTANDING_CONFIRMED for this package and Owner revision
- Challenge ambiguity or contradiction instead of guessing
- Follow the critical path in the Auditor record to the named Builder hand-off
- Record ordinary failures and continue every independent safe evidence branch
- Stop immediately for a hard-stop condition
- Update the Owner/Builder record with the immutable diff, evidence branches, failures, cleanup, and next step before the hand-off
- End the pass with CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED; never wait inside the pass for another actor
- Check the Auditor record before starting new work
- Run tests when the Auditor specifies how to test

AGENTS.md — Auditor worktree

# Auditor Role

You are the Auditor. You review the Builder's work.

## Configured paths
- Owner/Builder record: <OWNER_BUILDER_RECORD_PATH>
- Auditor record: <AUDITOR_RECORD_PATH>
- Product goal document: <PRODUCT_GOAL_PATH>
- Handoff: <HANDOFF_PATH_OR_NONE>

## Write permissions
- Auditor record — this is your ONLY writable project record

## Read permissions
- Owner/Builder record — track Builder progress and status
- All source code files — review implementation quality
- Product goal document — compare against the original goal

## Rules
- NEVER write to the Owner/Builder record, code, or any other file
- Turn Owner intent into falsifiable business rules, but return every business decision to the Owner for confirmation
- Investigate the existing system and adversarially test the proposed design before preparing the package
- Before releasing each package, declare and verify its access preconditions; record capabilities and status, never secret values
- Define the critical path, terminal evidence, and hard stops in the Auditor record
- Compare the Builder restatement with the Owner revision and release implementation only with UNDERSTANDING_CONFIRMED
- Be instructive — tell the Builder clearly what to do
- Include testing instructions in the Auditor record
- Review the complete frozen evidence, look for common causes, and batch surviving findings into one bounded correction pass
- Send actionable dispositions, not verdict-only reviews
- End the pass with AUDIT_COMPLETE or P1_DECISION_NEEDED; never wait inside the pass for another actor

hooks.json

Codex hooks use the same shell scripts but the JSON structure nests handlers inside matcher groups.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash \"$(git rev-parse --show-toplevel)/.codex/hooks/build-a-plan.sh\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash \"$(git rev-parse --show-toplevel)/.codex/hooks/audit-a-plan.sh\"",
            "timeout": 60
          }
        ]
      }
    ]
  }
}

The hook scripts are the same one-additional-pass scripts shown in the Claude Code section. Copy them into .codex/hooks/, make them executable, and keep the stop_hook_active guard.

8. Goal-Paired Agents in Codex

Codex Goal mode gives one task a persistent objective whose text also defines completion. Give it an outcome, constraints, and verification. In this method, the owner-approved roadmap slice stays in the Owner/Builder record; each active Goal covers one bounded role-owned pass ending at a measurable hand-off. Do not use a Goal for a loose backlog or make its completion depend on another actor replying. The current official guidance is Long-running work.

The operating model works with any capable Builder–Auditor pair. My recommended OpenAI-stack setup is SOL as Auditor and TERRA as Builder. The practical advantage is smooth direct task-to-task communication inside the same stack. Each role starts a Goal only for its current pass and becomes idle after delivering its hand-off.

Other valid pairs include Fable as Auditor with TERRA as Builder, or Fable as Auditor with Claude Opus as Builder. A cross-family pair may reduce correlated reasoning failures, but the products may not provide the same direct communication path. In that case the two files still preserve the method, and a tested scheduled or manual doorbell carries the notification. Choose models for capability and tool access; do not rename the roles around the models.

The templates below use SOL and TERRA as one concrete implementation. In every other pairing, substitute the task names and keep the Builder and Auditor responsibilities unchanged.

The understanding gate is itself a pair of bounded passes: TERRA ends its restatement pass at UNDERSTANDING_REVIEW_READY; SOL ends its alignment pass at UNDERSTANDING_CONFIRMED or P1_DECISION_NEEDED. After implementation is released, use the templates below for the Builder and audit passes.

TERRA implementation goal

/goal Complete the authorised Builder pass for the package named in the configured Owner/Builder record until one terminal hand-off is recorded and sent to SOL: CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Read the configured Owner/Builder record, Auditor record, product goal document, and operational source of truth first. Confirm that the Auditor record contains UNDERSTANDING_CONFIRMED for the same Owner revision and package; otherwise end BLOCKED without changing code. Never edit Owner direction or decisions. Follow the critical path in the Auditor record. Continue autonomously through routine implementation decisions, ordinary test failures, and progress updates. Record ordinary failures and complete every independent evidence branch that remains safe and meaningful. End BLOCKED for access only when a declared access precondition has failed, or evidence reveals a genuinely unforeseen dependency that prevents every remaining meaningful branch of the current pass. Record the exact evidence and required capability; never place secret values in the operating records or ordinary messages. Stop immediately for a hard-stop condition and end P1_DECISION_NEEDED. Commentary does not complete this Goal. At the terminal hand-off, update the Owner/Builder record with the immutable diff, completed and blocked evidence branches, recorded failures, cleanup, and intended next action; send SOL the matching doorbell; then end the Goal. Do not wait for SOL or the Owner inside this Goal.

SOL audit goal

/goal Audit the frozen Builder hand-off named in the configured Owner/Builder record until one actionable disposition is recorded in the Auditor record and sent: AUDIT_COMPLETE or P1_DECISION_NEEDED. Read the configured Owner/Builder record, Auditor record, product goal document, immutable diff, and operational source of truth. Do not edit implementation or the Owner/Builder record. Verify the Owner revision, package boundary, critical path, terminal evidence, and cleanup. Review the complete stable evidence, adversarially test the implementation and claims, and refute candidate findings before reporting them. Distinguish hard stops, dependency failures, and ordinary defects. Look for common causes and consolidate surviving findings into one bounded correction package with exact changes and exact rerun evidence. Record ACCEPTED only when the applicable implementation and evidence gate is genuinely met. If Owner authority is required, record and send P1_DECISION_NEEDED; otherwise send TERRA AUDIT_COMPLETE. Then end the Goal. Do not wait for TERRA or the Owner inside this Goal.

Goal lifecycle

• /goal <objective> starts one bounded pass. /goal shows its current status.
• /goal pause temporarily holds an unfinished pass, for example before connectivity is lost. Do not leave a completed hand-off paused while waiting for another actor.
• /goal resume continues the same unfinished pass.
• /goal edit changes that pass's objective, boundary, or stopping condition. A correction disposition or next package starts a new Goal rather than silently expanding the old one.
• /goal clear removes an objective that is complete, abandoned, or replaced.

Wake-up behaviour must be tested

At setup, record the exact TERRA and SOL task identifiers in the Owner/Builder record. Exchange one CHANNEL_TEST / CHANNEL_ACK pair using the current app's direct task-to-task messaging capability. Every later doorbell names the target task, package, checkpoint ID, and evidence reference so a delayed message cannot be mistaken for a newer gate.

Direct TERRA-to-SOL messaging and acknowledgement are useful, but do not assume a direct message automatically starts work in an idle task. Test the exact behaviour in the current Codex app before relying on it: leave SOL idle after its previous Goal, have TERRA send CHECKPOINT_READY, and verify whether SOL wakes, reads the stable evidence, starts the bounded audit pass, writes a disposition, and sends the next instruction without owner intervention.

If that works, direct checkpoint messages are the event-driven path. If it does not, record the failed channel test in the Owner/Builder record and configure a scheduled same-task follow-up that starts the next role-owned pass at the appropriate low frequency. Do not retry the doorbell in a tight loop. The owner should not relay ordinary technical messages or restart the loop manually.

Optional independent second audit

Fable may be the primary Auditor in an alternative pair. When it is not, you can invoke it as an independent second auditor after the primary audit is green, or when a separate semantic or business-rule perspective is valuable. The second auditor is not continuously active, does not replace the primary Auditor, and never takes the owner's authority.

Worked example: tenant-safe customer export

The owner says: “A customer administrator can export their organisation's records.” SOL makes that intent falsifiable: tenant identity must come from the authenticated server-side session; a client-supplied tenant identifier cannot expand access; a cross-tenant request returns no records and creates denial evidence; production remains out of scope. The owner corrects and confirms those rules.

SOL investigates the existing system and finds that the UI sends a tenant identifier which the service currently trusts. It rejects a design that merely validates the UI value, prepares a server-bound tenant design, and defines the critical path: implementation and local tests, accepted diff, development deployment, permitted export, cross-tenant denial, audit evidence, and cleanup. Any cross-tenant disclosure is a hard stop.

Before coding, TERRA restates the design and challenges one contradiction: the current interface asks the browser to choose a tenant, while the confirmed rule says the server owns tenant identity. SOL clarifies that the request must not accept an authority-bearing tenant field, updates the package, and confirms the revised restatement. Only then does TERRA implement it.

During the runtime pass, TERRA finds that the export filename is unclear. It records the ordinary presentation defect and continues the independent isolation and audit-evidence scenarios. At the frozen hand-off, SOL reviews the complete evidence, returns one correction package for the filename, and requires the affected journey and preserved isolation evidence to be rerun. After that proof, SOL records runtime_proven. The owner receives: “Tenant isolation and the corrected export journey are proven in development. Production remains untouched. Owner action: approve or decline a controlled production rollout.”

Anti-patterns

• Auditor polling continuously with no new evidence.
• Breaking coherent work into message-sized tasks that collapse the cycle into constant back-and-forth.
• Auditor sending many minor messages while the diff is still changing.
• Stopping the complete evidence run at the first ordinary defect when independent safe scenarios remain.
• Continuing through a hard stop or running scenarios whose failed prerequisite makes their results meaningless.
• Designing separate corrections for visible symptoms before checking for one common cause.
• A Goal whose completion depends on another agent replying, owner approval, or indefinite waiting.
• Owner manually relaying ordinary technical messages between roles.
• Verdict-only reviews that give the builder no executable correction.
• Auditor turning ambiguous owner intent into business logic without owner confirmation.
• Builder starting implementation before restating and challenging the package.
• Turning an omitted access dependency into an unexplained, urgent mid-run request to the owner.
• Builder or auditor inventing business logic, customer meaning, or owner priority.
• Treating a successful deployment as proof of the required customer behaviour.
• Building inert development behaviour that requires a separate production rewrite.
• Two implementation-writing agents modifying the same checkout.

9. Running It

If you used the one-liner from the top of this page, your agent can walk you through the interview, create the two operating files, confirm the business rules and shared-understanding gate, and choose the right coordination path. You answer the business questions; you do not operate as a message bus between agents.

If you're setting things up manually, here's the sequence:

Step by step

1. Start a conversation with Claude or Codex. Tell it what you want to build. Let it interview you and create the goal document.
2. Confirm the business rules. The Auditor turns your intent into required outcomes, prohibited outcomes, boundaries, and negative cases. Correct them until they express the product logic you actually want, then confirm the owner revision.
3. Confirm and verify access. At project intake and before each package, the Auditor names the required repos, environments, services, permissions, credentials, test data, and deployment capabilities. Confirm what is available and verify the access paths before implementation. Record capabilities and status, never secret values.
4. Review the package. Put only owner-approved work in the Now section of the Owner/Builder record. The Auditor investigates the system and writes the implementation-ready package, critical path, terminal evidence, and hard stops in the Auditor record.
5. Run the understanding gate. The Builder restates the rules, architecture, boundaries, contradictions, and acceptance evidence in the Owner/Builder record. Implementation remains blocked until the Auditor records UNDERSTANDING_CONFIRMED.
6. Choose coordination. Use the Goal-paired Codex scenario when direct checkpoint messaging is available. Use hooks or a low-frequency same-task check only when the tool cannot carry the hand-off directly.
7. Start the roles. Give the Builder one bounded pass ending at its next named hand-off. The Auditor then runs one bounded review pass ending at a disposition. Messages carry the doorbell and the loop advances without manual owner restart.

My OpenAI-stack recommendation: SOL + TERRA. Use the bounded Auditor and Builder Goals from Section 8 for their respective passes. Confirm the current app's direct wake-up behaviour before relying on it. If it does not wake an idle peer, configure the fallback before starting real work. Use the same operating model with another pair when its capabilities or environment fit the work better.

CLI fallback: hooks (Claude Code or Codex).

# Claude Code
claude "Your role is Builder. Read the complete methodology at https://mikkosniemela.com/build-with-agents and discover the configured operating records. Complete only the current Builder-owned pass. If understanding is not confirmed, restate the package in the Owner/Builder record, send UNDERSTANDING_REVIEW_READY, and stop. If confirmed, follow the critical path to CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Never wait for another actor inside the pass."

# Codex
codex "Your role is Builder. Read the complete methodology at https://mikkosniemela.com/build-with-agents and discover the configured operating records. Complete only the current Builder-owned pass. If understanding is not confirmed, restate the package in the Owner/Builder record, send UNDERSTANDING_REVIEW_READY, and stop. If confirmed, follow the critical path to CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Never wait for another actor inside the pass."

# Claude Code
claude "Your role is Auditor. Read the complete methodology at https://mikkosniemela.com/build-with-agents and discover the configured operating records. Complete only the current Auditor-owned pass: prepare the critical path and package, decide the understanding gate, or audit one frozen hand-off. Record one actionable disposition in the Auditor record, send the matching doorbell, and stop."

# Codex
codex "Your role is Auditor. Read the complete methodology at https://mikkosniemela.com/build-with-agents and discover the configured operating records. Complete only the current Auditor-owned pass: prepare the critical path and package, decide the understanding gate, or audit one frozen hand-off. Record one actionable disposition in the Auditor record, send the matching doorbell, and stop."

Hooks can reinforce a checkpoint or policy boundary. A scheduled same-task check provides the low-frequency fallback where direct checkpoint wake-ups are unavailable. The builder records a checkpoint; the auditor reviews it and records a disposition. The owner intervenes only when the auditor escalates an authority decision.

Tips

• --dangerously-skip-permissions removes confirmation before destructive commands in Claude Code. Do not use it as the default. Use the least-privileged sandbox, credentials, network access, and approval policy that can complete the package; OS-user separation alone is not enough.
• Run the auditor in a read-heavy mode — it mostly reads and only writes to one file.
• If you're running both on the same machine, they'll share the filesystem naturally. If on different machines, use a shared git repo and have both agents pull/push.
• Use direct checkpoint messages where available. For a fallback heartbeat, start at 10–15 minutes during active implementation and 30–60 minutes during slow CI or deploy work. Back off after unchanged checks.
• For large projects, you can run multiple builders on independent modules. Each gets an explicitly owned section in the Owner/Builder record.
• If you use git: the builder commits code and the Owner/Builder record after each completed package with a short message prefixed builder:. Put detailed reasoning in the record, not the commit message. In a shared workspace, the auditor writes only the Auditor record. If Git is the transport between separate worktrees or machines, the auditor may commit only that record with an auditor: prefix.

Version history

This methodology is versioned like software. Each meaningful revision gets a dated version — shown in the badge at the top of this page — and a frozen snapshot you can read, cite, or pin. If you have standardised on this method in your organisation, pin a specific version; the snapshots below never change.

• 2026-07-24 — current. Made access a verified intake and per-package precondition, prohibited secrets in operating records and ordinary messages, and defined how late access discoveries are evidenced and re-planned without abandoning independent work. View snapshot →
• 2026-07-22.1 — replaced filename-dependent entry prompts with role-only prompts, added operating-record discovery and duplicate prevention, and made operational templates portable across project-defined paths. View snapshot →
• 2026-07-22 — added critical-path execution, hard-stop / record-and-continue evidence rules, common-cause correction batching, complete runtime proof, and bounded Builder and Auditor Goals that end at role-owned hand-offs. View snapshot →
• 2026-07-11.1 — added role-specific model-performance considerations and the current SOL xhigh/Ultra Auditor with Terra medium Builder recommendation. View snapshot →
• 2026-07-11 — added the shared-understanding gate: owner-confirmed falsifiable business rules, adversarial package design, builder teach-back, and explicit auditor release before implementation. View snapshot →
• 2026-07-10 — defined the two-file operating memory: owner direction and builder packages in plan.md, audit record and prepared next packages in comments.md, and messages as doorbells only. Added dual Goals with selective activation, stronger runtime evidence gates, the SOL–TERRA operating scenario, and portable model-pair guidance. View snapshot →
• 2026-06-27 — added the owner-briefing format (Done / Left / Status & risk / Owner tasks), this version history, Opus 4.8, and the no-cadence default. View snapshot →
• 2026-05-13 — added the “speak to the owner” rule, reframed the loop as cadence (no recurring loop by default), refreshed the lineup to GPT-5.5. View snapshot →
• 2026-04-17 — model refresh, cross-family pairing, follow-the-smarter-model thinking, the reusable handoff prompt, and the methodology version badge. View snapshot →
• 2026-04-09 — introduced /loop, file-change triggers, and abstracted the loop concept. View snapshot →
• 2026-03-31 — first published version: two roles, two files, evidence-gated steps. View snapshot →

For an independent record, this guide is also archived by the Wayback Machine.

Credits

The core insight: structure replaces supervision. Confirm the business truth, prove shared understanding before code, keep the two operating files current, and work the critical path to complete evidence through bounded role-owned passes.

Dr. Mikko S. Niemelä — 2026

Last updated: July 24, 2026