Building with AI Agents

Methodology version: 2026-07-11 — 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. A plan file — the shared understanding of what needs to be built and where things stand.
2. A comments file — a one-way channel from the reviewer to the builder.

Each agent has strict write permissions. The builder writes the plan and the code. The auditor writes comments. Neither touches the other's file. Those files 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.

The plan is the operating memory

plan.md 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 the plan but never writes it.

# 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.

## 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
- In progress. Next: complete dev proof.

The comments are the audit memory

comments.md 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.

# 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.

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

## Understanding gate
- Builder must restate the package in plan.md 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 plan. 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 plan. Before touching code, it restates the package in plan.md: 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 the complete package, keeps the plan current, and sends a return-channel checkpoint or blocker before every intentional pause.

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, exact files, sequence, boundaries, rollback points, acceptance criteria, and evidence. 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 plan. The auditor does not edit implementation code.

Checkpoint protocol

The files are the project's durable operating memory; messages are only the doorbell. The builder updates plan.md before sending the auditor a checkpoint. The auditor updates comments.md 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
plan.md contains my restatement, ambiguities, and contradictions.
No code changed. Ready for alignment review.

UNDERSTANDING_CONFIRMED
Owner revision: O-17
Package: O-17.1
comments.md 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
plan.md is current: scope, diff, evidence, questions, and intended next step are recorded.
Ready for audit.

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

comments.md 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, BLOCKED, DEPLOY_EVIDENCE, and AUDIT_COMPLETE. Each message identifies the owner revision, package, 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.

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 comments.md with exact file paths, commands, and acceptance criteria. The builder just executes. This is the fastest path for well-understood work.

You are the auditor and the thinker. The builder is a fast execution model — it does not investigate, research, or design. Do all investigation, risk analysis, dependency mapping, and rollback planning yourself. Before the builder reaches a step, translate it into precise, executable instructions in comments.md: exact file paths, commands, acceptance criteria, and the evidence you require. The builder should never need to reason about architecture or strategy — only execute.

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 — "before you start step N, investigate X and report observations in plan.md" — and 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. When you need investigation or research for upcoming steps, delegate it via comments.md: ask the builder to investigate specific open questions between build steps and report observations, risks, and commentary in plan.md. 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 plan.md is the owner's voice. The package, status, evidence, risks, and alternatives below it are the builder's voice. comments.md is the auditor's voice. The plan is not just a progress log; together, the two files 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 comments.md: 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 plan.md.
3. Access check — The agent figures out what repos, services, APIs, databases, and credentials the builder and auditor will need. It asks you what's available and flags anything missing as a blocker 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 comments.md.
5. Run the understanding gate — The auditor walks the builder through the rules, architecture, boundaries, and evidence. The builder restates them in plan.md, challenges ambiguity, and identifies contradictions. The auditor records UNDERSTANDING_CONFIRMED in comments.md 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 complete package and the auditor reviews stable evidence gates. 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 plan.md 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

An agent that hits a permissions wall mid-build will either stall silently or invent a workaround you didn't ask for. Both are expensive. The agent should figure out what access is required and ask you about it before writing a single line of code.

• Repos and branches — which repositories, which branches, does the builder need to create new ones?
• Services and APIs — does the builder need running services, API keys, database access, deployment credentials?
• 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.

If anything is missing, it goes in the plan as a blocker at step zero. Don't discover it at step five.

Why files still matter with long context

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

4. Checkpoint-Driven Work

Both agents may have a durable objective, but they should not both consume turns continuously. The builder works while there is approved implementation work. The auditor works while it has a meaningful scope, audit, decision, or deployment-verification task. A checkpoint decides who should be active next.

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. This edition adds a shared-understanding gate before the first line of implementation: stronger execution makes it more important to prove that the agents are executing the right product logic.

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, and a measurable stopping condition. It is not a timer. In Codex, /goal preserves that objective across turns.

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 keeps the objective available without spending turns on an agent that has no useful work. Resume the role when a checkpoint, new evidence, or a real independent task exists.

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 plan.md.
2. The auditor investigates the existing system, attacks its own proposed design, and writes one implementation-ready package in comments.md.
3. The auditor walks the builder through the confirmed rules, architecture, boundaries, and acceptance evidence. The builder records its restatement, ambiguities, and contradictions in plan.md, 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 executes the complete package. At a coherent checkpoint it records the branch or diff, evidence, questions, and intended next action in plan.md, then sends CHECKPOINT_READY.
6. The auditor reviews the stable evidence, runs a skeptic pass, writes an actionable disposition in comments.md, and sends AUDIT_COMPLETE.
7. If fixes are required, the builder continues the same package. If the package is proven and another Now item is already authorised, the auditor prepares it and the understanding gate runs again before its implementation.
8. After useful audit or package-preparation work, the auditor pauses. The owner returns only for business meaning, priority, meaningful scope change, production go/no-go, or another authority decision.

Standby rules

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 plan 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.

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.

Write a single handoff prompt and use it three ways: as the instruction for your tool's context-compaction command (in Claude Code: /compact <instruction>), as the first prompt of every new session, and as the last prompt before you close a terminal — save the output next to plan.md as handoff.md so the next agent can read it on cold start. One prompt, three uses. The next agent always 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.

Summarize this project for a fresh agent joining now. Cover: owner revision and confirmed business rules; current authorised package and understanding status; what's done, in progress, and next by step state; owner decisions that should not be relitigated; unresolved ambiguities or contradictions; evidence; and access or permission blockers. Max 3 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. GOAL.md is the durable product specification for the project. Codex /goal is a thread-scoped operating objective with a stopping condition. The owner direction at the top of plan.md sets priority; the package sections record authorised work; the Goal keeps one agent oriented while it does that work.

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 "Read GOAL.md, plan.md, and comments.md. If this package lacks UNDERSTANDING_CONFIRMED, restate it in plan.md and stop for alignment review. If confirmed, build the complete authorised package and record the result in plan.md."

claude "Read GOAL.md, plan.md, and code. You are the auditor. If implementation is not released, verify the builder restatement and record the alignment disposition. Otherwise review stable evidence and write an actionable audit disposition to comments.md."

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 comments.md. If the package lacks UNDERSTANDING_CONFIRMED, update plan.md with your restatement and wait. If released, execute the complete package and update plan.md. When your package boundary is stable, schedule a low-frequency check-back only if meaningful work remains.

/loop Read plan.md. If an understanding review is ready, compare it with the owner-confirmed rules and package, then write the alignment disposition to comments.md. Otherwise review a stable implementation checkpoint and write one actionable audit disposition. When there is no new evidence, pause or use a 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 comments.md. If the package lacks UNDERSTANDING_CONFIRMED, update plan.md with your restatement and wait. If released, execute the complete package and update plan.md. If nothing changed, do not create work; wait.

/loop 10m Read plan.md. Review either a ready understanding restatement or a stable implementation checkpoint, then write one consolidated disposition to comments.md. If nothing changed, wait.

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                    # the plan (builder writes, auditor reads)
  comments.md                # comments (auditor writes, builder reads)
  GOAL.md                    # your goal document

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 coherent package boundary.
If this package lacks UNDERSTANDING_CONFIRMED, do not change code: restate the
package in plan.md and send UNDERSTANDING_REVIEW_READY. Otherwise update the
builder-owned sections of plan.md with the exact implementation evidence and
next step. Do not edit comments.md or owner-controlled sections of plan.md.
Send CHECKPOINT_READY, BLOCKED, or MEANINGFUL_MILESTONE 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. Write every disposition,
instruction, evidence requirement, and next package to comments.md. Do not edit
plan.md or code. Send the relevant doorbell or escalate the owner decision.
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:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "comments.md",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Build-a-Plan] Comments file changed. Read comments.md and take action on new instructions.'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "plan.md",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Audit-a-Plan] Plan file changed. Read plan.md and review the 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 plan.md and the auditor may commit comments.md; neither commits the other role's files.

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
  comments.md
  GOAL.md

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.

# Builder Role

You are the builder. Your job is to build according to the plan.

## Write permissions
- Builder-owned sections of plan.md — update package progress, evidence, questions, and notes
- All source code files

## Read permissions
- comments.md — the auditor writes feedback here
- GOAL.md — the original goal document

## Rules
- NEVER write to comments.md — that belongs to the auditor
- NEVER edit the owner direction or decision sections of plan.md
- Before code, restate the package in plan.md: business rules, architecture, boundaries, acceptance evidence, ambiguities, and contradictions
- Send UNDERSTANDING_REVIEW_READY and do not implement until comments.md records UNDERSTANDING_CONFIRMED for this package and owner revision
- Challenge ambiguity or contradiction instead of guessing
- Update the plan after completing each task
- Check comments.md 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.

## Write permissions
- comments.md — this is your ONLY writable file

## Read permissions
- plan.md — track builder progress and status
- All source code files — review implementation quality
- GOAL.md — compare against the original goal

## Rules
- NEVER write to plan.md, 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
- 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 your comments
- Send actionable dispositions, not verdict-only reviews
- If things stall, decide: pause, instruct, or escalate
- If human approval is needed, say so and wait

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 durable objective with a measurable stopping condition. Use it for one owner-approved roadmap slice, which may contain several coherent packages inside a fixed boundary. Do not use it for a loose or expanding backlog. The current official guidance is Follow a goal.

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. Both retain a Goal, and only the role with meaningful work stays resumed.

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.

TERRA goal

/goal Build the owner-authorised roadmap slice recorded in plan.md until its fixed stopping condition is proven in development. Read plan.md, comments.md, and the operational source of truth first. Never edit owner direction or decisions. Before changing code for each package, restate the confirmed business rules, architecture, boundaries, acceptance evidence, ambiguities, and contradictions in plan.md; send SOL UNDERSTANDING_REVIEW_READY and wait for SOL to record UNDERSTANDING_CONFIRMED in comments.md. If anything conflicts, remain blocked and challenge it. After release, execute the complete coherent package autonomously. Update the builder sections of plan.md at each stable gate, including checkpoint ID and immutable evidence reference, then send SOL CHECKPOINT_READY. Adopt a later package only when it cites the same owner revision, remains inside the Goal boundary, and passes its own understanding gate. Before any pause, send SOL a return-channel checkpoint or blocker.

SOL goal

/goal Guide and audit TERRA until the owner-authorised roadmap slice recorded in plan.md meets its fixed development stopping condition and is routine-promotion-ready. Read plan.md, comments.md, and the operational source of truth. Do not edit implementation or plan.md. Turn the owner's intent into explicit, falsifiable business rules and take them back to the owner until the product logic is confirmed; never invent the missing business decision. Investigate the existing system, adversarially test the proposed design, and prepare one implementation-ready package in comments.md: exact files, sequence, architecture, boundaries, rollback points, acceptance criteria, and evidence. Walk TERRA through the package. Compare TERRA's restatement in plan.md with the confirmed owner revision, resolve contradictions, and record UNDERSTANDING_CONFIRMED only when the understanding is exact. Then review stable implementation checkpoints, refute candidate findings, and write consolidated dispositions in comments.md. Send the relevant doorbell directly to TERRA, surface only business decisions to the owner, and pause when no useful alignment, audit, or package-preparation work remains.

Goal lifecycle

• /goal <objective> sets a durable, evidence-backed objective. /goal shows its current status.
• /goal pause puts the objective on inexpensive standby when the role has no useful work.
• /goal resume continues a paused objective when a checkpoint, new evidence, or authorised decision arrives.
• Edit goal changes the objective, boundary, or stopping condition when the owner changes the authorised roadmap slice. Moving between packages already inside that fixed slice does not change the Goal. In the Codex desktop app, use the Edit control in the Goal progress row.
• /goal clear removes the objective when it is complete, abandoned, or replaced.

Wake-up behaviour must be tested

At setup, record the exact TERRA and SOL task identifiers in plan.md. 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 resumes a paused Goal. Test the exact behaviour in the current Codex app before relying on it: pause SOL, have TERRA send CHECKPOINT_READY, and verify whether SOL resumes, reads the stable evidence, 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 plan.md and configure a scheduled same-task follow-up that resumes SOL 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 two-tenant positive and negative evidence.

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.

TERRA supplies code, tests, and development runtime proof using two separate administrator accounts. SOL records auditor_accepted, then runtime_proven. The owner receives: “Tenant isolation is 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.
• 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.
• 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 access. The agent will ask you what repos, services, and credentials are available. Answer honestly — missing access discovered later is expensive.
4. Review the package. Put only owner-approved work in the Now section at the top of plan.md. The Auditor investigates the system and writes the implementation-ready package in comments.md.
5. Run the understanding gate. The Builder restates the rules, architecture, boundaries, contradictions, and acceptance evidence in plan.md. 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. The Builder continues within the authorised package. The Auditor works at meaningful checkpoints and pauses otherwise. The loop carries forward without manual owner restart.

My OpenAI-stack recommendation: SOL + TERRA. Start the Auditor and Builder Goals from Section 8. Confirm the current app's direct wake-up behaviour before relying on it. If it does not wake a paused 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 "Read GOAL.md, plan.md, and comments.md. Before code, restate the package in plan.md and wait for UNDERSTANDING_CONFIRMED. Then build the complete authorised package and record every checkpoint or blocker in plan.md."

# Codex
codex "Read GOAL.md, plan.md, and comments.md. Before code, restate the package in plan.md and wait for UNDERSTANDING_CONFIRMED. Then build the complete authorised package and record every checkpoint or blocker in plan.md."

# Claude Code
claude "Read GOAL.md, plan.md, and code. You are the auditor. Confirm owner business rules, prepare the package, verify the builder restatement, release implementation, then review stable evidence and write actionable dispositions to comments.md."

# Codex
codex "Read GOAL.md, plan.md, and code. You are the auditor. Confirm owner business rules, prepare the package, verify the builder restatement, release implementation, then review stable evidence and write actionable dispositions to comments.md."

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 their own plan section.
• If you use git: the builder commits code and plan.md after each completed package with a short message prefixed builder:. Put detailed reasoning in the plan file, not the commit message. In a shared workspace, the auditor only writes comments.md. If Git is the transport between separate worktrees or machines, the auditor may commit only comments.md 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-11 — current. 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 let evidence carry the checkpoint cycle forward.

Dr. Mikko S. Niemelä — 2026

Last updated: July 11, 2026