Building with AI Agents

Methodology version: 2026-09-04 — 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 owner's direction and the builder's current state, evidence, and next action.
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: authoritative instructions, evidence, decisions, and acceptance belong there.

Direct Builder–Auditor messages have two jobs: readback and doorbell. Readback demonstrates the recipient's current understanding; a doorbell announces that a durable record or stable checkpoint is ready. Raw readback stays in the direct channel. If it exposes an ambiguity, the auditor corrects the authoritative package in the Auditor record before implementation. Messages accelerate coordination; they never replace the files as project authority.

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. Inventory the current branch, worktrees, tracked modifications, and untracked paths before any mutation. Preserve unexplained state and establish an isolated mutation lane.
6. Do not create duplicate records merely because files named plan.md, comments.md, or handoff.md are absent.
7. If multiple candidate records exist, stop BLOCKED and ask the Owner which paths are authoritative.
8. 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.
9. 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.
10. 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.

Preserve the workspace before mutation

Unknown workspace state may contain unfinished work, evidence, or an unrecorded owner decision. Record the current branch or revision, worktrees, tracked modifications, and untracked paths before either role changes the repository. Do not classify unexplained state as stale merely because it is old or inconvenient.

Do not reset, clean, delete, overwrite, stash, or automatically commit and publish unknown state. With Git, the safe default is to leave the existing checkout untouched and create a separate worktree from the confirmed base revision. Use the project's approved preservation mechanism when isolation alone is insufficient. If preserving the state would require moving or publishing unknown data, stop BLOCKED and ask the Owner; the files may contain secrets or private data.

The Owner/Builder record

The Owner/Builder record holds the owner's direction and the builder's current execution state 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, decision, confirmed business-rule, and delivery-authority sections. The builder never edits them. The builder records the current package reference, workspace state, status, evidence, and next step without duplicating the Auditor's authoritative instructions. 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.

## Confirmed delivery authority
- Package: O-17.1.
- Observable business test and intended environment: the named tenant-safe export journey passes in development.
- Material scope and delivery constraint: prove the focused export journey before any fleet or reusable automation.
- Production boundary: separate Owner decision.
- Deferred work: fleet rollout automation, generalised tooling, and unrelated product parity.
- Acceptance revision: A-17.1.
- Any textual change to this block requires a new Owner-approved acceptance revision.
- Approved by Owner after the Auditor package and Builder direct readback matched.

# Current package (builder)
Package: O-17.1
Authoritative package: Auditor record, package revision P-17.1
Owner revision: O-17
Acceptance revision: A-17.1
Understanding status: UNDERSTANDING_CONFIRMED in the Auditor record

## Workspace baseline and mutation lane
- Starting revision, worktree, tracked changes, and untracked paths recorded before mutation.
- Unexplained state preserved through the project-approved mechanism.
- This package owns one isolated implementation lane.

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

## Checkpoint evidence
- Touched files: each path and why it was necessary for the authorised outcome.
- Commands and results: exact commands, exit status, and material output.
- Residual uncertainty: remaining assumptions, limitations, and unverified runtime behaviour.
- Cleanup: no debug code, backup files, dead paths, or scratch artefacts remain.

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
Package revision: P-17.1
Owner revision: O-17
Acceptance revision: A-17.1
Builder direct readback matched the authoritative package; raw readback remains in the direct channel.

## Owner-approved acceptance anchor
- Owner revision: O-17.
- Now item: O-17.1.
- Acceptance revision: A-17.1.
- Authoritative text: Confirmed delivery authority in the Owner/Builder record.
- Any textual change requires a new Owner-approved acceptance revision and another understanding gate.

## Authoritative package
- Package revision: P-17.1.
- Owner-confirmed delivery boundary: development proof now; Production requires a separate decision.
- Required now: the named development export journey, tenant isolation, accurate content, private download, and cleanup.
- Deferred follow-up: fleet rollout automation, generalised tooling, and unrelated product parity.
- Amendment authority: verified hard stop, or a new Owner revision approving the effect on risk acceptance, scope, cost, timing, or Production exposure.

### Minimum sufficient change
- Outcome: an authenticated administrator exports only their organisation's existing records in development.
- Non-goals: Production rollout, fleet automation, unrelated export improvements, and generalised tooling.
- Expected change surface: the existing export handler and tenant-binding path, the request interface only if needed to remove client authority, and the relevant existing tenant-isolation tests. This is a forecast, not an exhaustive allowlist.
- Proof: the narrowest existing export and authorisation tests plus the two-tenant development run.

### Delivery topology
- Closest representative environment: development.
- Branch, merge, deployment, migration, and promotion triggers inspected before implementation.
- Production action requires a separate Owner decision.

### 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: authentication or authorisation bypass, cross-tenant disclosure, credential exposure, destructive or integrity-damaging state change, verified material supply-chain compromise, violation of the Owner-approved security or compliance baseline, unintended Production activity, uncontrolled external cost, or false safety evidence.

## Alignment evidence
- Builder direct readback demonstrated the business rules, observable business test, delivery topology, architecture, fixed decisions, mechanically open choices, exclusions, boundaries, contradictions, and acceptance evidence.
- The package matches Owner revision O-17 and acceptance revision A-17.1.
- 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.

## Minimum sufficient change
- Outcome: the exact observable behaviour required by this package.
- Non-goals: behaviour, cleanup, hardening, and improvements excluded from this package.
- Expected change surface: the smallest files, interfaces, and resources expected to change after direct inspection of the actual code, tests, configuration, and runtime contracts. This is not an exhaustive allowlist unless explicitly labelled as one.
- Proof: the narrowest reliable existing tests and runtime evidence that prove the outcome.
- Testing: run the narrowest existing tests that exercise the changed behaviour; extend the relevant existing test before creating separate infrastructure; add tests only for uncovered acceptance criteria or material regression risks; do not backfill unrelated coverage.
- Scope growth: if implementation crosses the tripwire defined in this guide, return the affected dependency chain and evidence to the Auditor while continuing independent authorised work.

## Observable business acceptance test
- Named actor, action, intended environment, and observable result.
- Owner-approved deadline or decision point for reaching representative-environment evidence.

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

## Exact implementation instructions
- Expected files and interfaces, commands, sequence, and rollback points.

## Decision boundary
- Fixed decisions: the exact selected behaviour, interfaces, security and data-ownership rules, failure handling, dependencies, rollout, rollback, cost controls, and evidence requirements.
- Mechanically open choices: private naming and equivalent local code arrangement that cannot change any fixed decision.
- Explicit exclusions: everything outside this package.

## Frozen acceptance line
- Acceptance revision linked to the Owner revision and Now item.
- Owner-confirmed business test, intended environment, material scope, delivery constraint or deadline, Production boundary, and deferred follow-up work.
- Authoritative Owner-controlled block and rule that every textual change requires a new Owner-approved acceptance revision.
- Required evidence before any Owner-approved Production canary and explicit follow-up work after the current package.
- Auditor corrections may enforce this line or a verified hard stop; every other new requirement is deferred or returned to the Owner as a prepared proposal.

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

### Delivery topology
- Actual branch, merge, CI, deployment, migration, promotion, and rollback triggers.
- Closest representative non-Production environment and the first Owner-approved Production canary boundary.
- Production authority and automatic Production side effects.

### Execution instruments
- Applicable deployment, migration, rollback, health-reading, and evidence-capture tools.
- Smallest proof needed for the current business test and its material risks: disposable-target result, applicable failure and retry behaviour, recovery path, and durable evidence location.
- Reusable frameworks and fleet automation are separate packages unless the frozen acceptance line requires them.
- If none apply, state why this package does not use or change an execution instrument.

### Expected operational flows
- For each new ongoing flow: expected cadence, explicit failure signal, silence threshold, reporting path, deduplication, and proof.
- If none apply, state that this package creates no ongoing expected flow.

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

### Critical path
- Ordered gates: focused vertical slice, focused local tests, applicable proportionate instrument proof, earliest representative-environment proof, complete runtime evidence, cleanup.
- Terminal evidence: permitted and denied paths proven with two administrators and two tenants.
- Hard stops: authentication or authorisation bypass, cross-tenant disclosure, credential exposure, destructive or integrity-damaging state change, verified material supply-chain compromise, violation of the Owner-approved security or compliance baseline, unintended Production activity, uncontrolled external cost, or false safety evidence.

## Understanding gate
- Auditor sends PACKAGE_READY_FOR_READBACK after writing the authoritative package.
- Builder sends a direct readback in its own words, including ambiguities and contradictions; raw readback is not copied into either durable record.
- If readback exposes a gap, Auditor corrects this package and requests another readback.
- No implementation until the auditor records UNDERSTANDING_CONFIRMED; that disposition freezes the acceptance line.

The builder must not infer business logic from old code, historical plans, customer comments, or its own judgement. The auditor may challenge a business decision and present options, but it cannot make that decision. Nothing enters builder scope until the owner has placed it in Now in the Owner/Builder record. The owner confirms the observable business test, intended environment, material scope, delivery constraint, Production boundary, and deferred work. After the Auditor package and Builder direct readback match, the Owner approves the final acceptance revision in Confirmed delivery authority; the auditor owns the technical design and proportionate evidence inside that boundary. Every package and checkpoint records the owner revision, Now item, acceptance revision, and package revision that authorised it. Any textual change to the Owner-controlled acceptance block requires a new Owner-approved revision and another understanding gate.

The builder owns implementation, tests, commits, deployment evidence, and the Builder-controlled sections of the Owner/Builder record. Before touching code, it reads the Auditor's package and sends a direct readback in its own words: business rules, observable business test, architecture, delivery topology, fixed decisions, mechanically open choices, exclusions, boundaries, acceptance evidence, ambiguities, and contradictions. The readback demonstrates current understanding but does not become another durable version of the package. 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.

A routine implementation decision is a mechanically equivalent choice explicitly left open by the auditor. It may change private naming, local arrangement, formatting, or equivalent mechanics only when every permitted option preserves the specified behaviour, interfaces, security boundaries, data ownership, failure handling, dependencies, rollout, rollback, cost controls, and acceptance evidence.

If a choice can affect any of those properties, the builder does not decide it. The builder records the ambiguity or contradiction, may propose options with consequences, and returns the affected branch to the auditor while continuing independent work that remains safe and meaningful. Before UNDERSTANDING_CONFIRMED, the auditor resolves technical design and returns business meaning to the owner. After confirmation, the acceptance line is frozen: the auditor may correct work against that line or a verified hard stop, but it may not turn a new hardening idea into a delivery gate. A change to business outcome, risk acceptance, material scope, cost, timing, or Production exposure requires a prepared Owner proposal, a new Owner revision, and another understanding gate.

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, inspects the real delivery topology, adversarially tests the proposed design, and prepares the next implementation-ready package: one observable business acceptance test, dependencies, verified access preconditions, fixed decisions, mechanically open choices, explicit exclusions, the expected change surface, critical-path sequence, proportionate execution-instrument proof, the earliest representative-environment gate, boundaries, rollback points, terminal evidence, and hard stops. Before implementation, it checks the builder's direct readback, corrects the durable package when needed, and records the final understanding disposition. During implementation it reviews stable checkpoints rather than shadowing every edit or expanding the frozen acceptance line.

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 authority forks — decisions that change owner-approved scope, risk, cost, timing, or Production exposure.
• Access and permissions — anything the agents can't resolve themselves.
• Cross-team coordination — anything that involves people or systems outside the project.

The auditor resolves technical design inside the confirmed business rules. The owner decides business meaning, priority, risk acceptance, material scope, and Production action; the auditor translates those decisions 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. Direct Builder–Auditor messages carry readback or a doorbell. Readback demonstrates current understanding and remains ephemeral. A doorbell announces that a durable record, blocker, or stable checkpoint is ready. The builder updates the Owner/Builder record before sending a checkpoint doorbell; the auditor updates the Auditor record before sending a disposition doorbell. Messages do not carry authoritative instructions or detailed evidence.

PACKAGE_READY_FOR_READBACK
Owner revision: O-17
Package: O-17.1
Package revision: P-17.1
Acceptance revision: A-17.1 proposed
The authoritative package is current in the Auditor record.
Read it, then reply directly in your own words with the business test, architecture, boundaries, fixed and open choices, evidence, ambiguities, and contradictions.

READBACK
Package: O-17.1, revision P-17.1
The customer outcome is a tenant-safe export proven in development. Tenant identity comes only from the authenticated server session. Production, fleet automation, and reusable rollout tooling are excluded. I will prove permitted export, cross-tenant denial, audit evidence, and cleanup. I see no remaining contradiction.

This message demonstrates understanding. It is not copied into either durable record.

P1_DECISION_NEEDED
Decision: approve package O-17.1 for implementation.
Package revision: P-17.1
Acceptance revision: A-17.1 proposed
The Auditor record contains the exact proposed package and the Builder's direct readback matches it.
Owner action: verify the business test and delivery terms, then approve acceptance revision A-17.1 in Confirmed delivery authority; otherwise state the required change.

UNDERSTANDING_CONFIRMED
Owner revision: O-17
Package: O-17.1
Acceptance revision: A-17.1 frozen
Package revision: P-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
Acceptance revision: A-17.1
Package revision: P-17.1
Evidence: commit 4f27c1a
Critical-path gate: complete local evidence run.
Outcome milestone: locally accepted; development proof is next.
The Owner/Builder record is current: every touched file and why it was necessary; the immutable diff; exact commands and results; completed and blocked evidence branches; recorded failures; remaining assumptions, limitations, and unverified runtime behaviour; cleanup confirmation; questions; and intended next step are recorded.
Ready for audit.

AUDIT_COMPLETE
Checkpoint: O-17.1-C3
Evidence reviewed: commit 4f27c1a
Acceptance revision: A-17.1
Package revision: P-17.1
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: PACKAGE_READY_FOR_READBACK, READBACK, UNDERSTANDING_CONFIRMED, PACKAGE_STARTED, MEANINGFUL_MILESTONE, CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, P1_DECISION_NEEDED, and AUDIT_COMPLETE. Doorbells identify the owner revision, acceptance revision, package revision, package, critical-path gate, achieved environment milestone, and relevant checkpoint or evidence reference. Readback uses plain language and stays in the direct channel. Neither message type replaces the durable records.

The auditor interrupts the builder mid-build only for an authentication or authorisation bypass, credential or secret exposure, cross-tenant leakage, destructive or integrity-damaging state change, verified material supply-chain compromise, violation of the Owner-approved security or compliance baseline, unintended Production action, uncontrolled paid-provider use, or evidence 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 investigate first, then translate the system's state into something the owner can act on. Three 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.

Bring a prepared proposal. When owner authority is required, the auditor fetches the technical facts before escalating. The proposal states the decision required, established facts, every viable option, the business consequence of each option, one recommendation with reasoning, what happens if the owner defers, and the exact owner action. The owner decides business meaning, priority, and risk acceptance; the owner does not perform technical discovery for the agents.

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, using the exact evidence ladder: “locally accepted,” “development proven,” “Production deployed — delivery only,” or “Production business scenario passed.” Never report source completion, test count, merge status, or deployment alone as user availability.
• 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 Codex configuration for complex projects uses separate Auditor and Builder tasks, both running SOL: xhigh reasoning for the Auditor and high for the Builder. I use Astra with max reasoning as an optional fresh whole-project peer at selected gates. This dated implementation note records my current practice. The methodology remains vendor-neutral, and any capable same-model, mixed-model, or cross-family stack can fill the roles.

Use the strongest model selectively at high-leverage gates. A fresh peer pass can concentrate additional reasoning before an expensive implementation or deployment decision while the primary Auditor retains authority. That placement has produced substantially fewer correction rounds and lower total token use in my complex projects.

Measure end-to-end delivery

Fast mode accelerates model turns. Complete projects also wait on CI, testing, deployment, audit, external systems, and Owner decisions. Measure elapsed time and token or credit use from the authorised package to the runtime-proven outcome, together with correction rounds and Owner interruptions. Response speed alone does not describe delivery speed.

In internal operating data from projects I have supervised, covering roughly 60 billion tokens of agent work, Fast mode was associated with about an 11% improvement in total project completion time. Treat this as an observational result from one operating environment. Faster inference produced a much smaller end-to-end gain because model generation occupied only part of the critical path.

Current Codex documentation reports approximately 1.5× model speed for GPT-5.6 Fast mode at 2.5× standard credit consumption, while Astra Fast mode also consumes credits at 2.5× where available. Use the current Fast mode documentation for product details. The practical optimisation target is total cost per Auditor-accepted, runtime-proven package, including clarification and rework.

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 the expected file paths and interfaces, commands, fixed decisions, mechanically open choices, exclusions, 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: expected file paths and interfaces, commands, fixed decisions, mechanically open choices, explicit exclusions, acceptance criteria, and the evidence you require. Treat the expected change surface as a forecast, not an exhaustive allowlist unless you explicitly label it as one. Mechanically open choices must be equivalent options that cannot change behaviour, interfaces, security, data ownership, failure handling, dependencies, rollout, rollback, cost, or evidence. Require the Builder to send a direct readback and challenge the package before code; keep raw readback out of the durable records. 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 labels its risks, alternatives, and commentary as proposals. The auditor resolves technical design and updates the package; the human decides business meaning 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, alternatives, and commentary in the Owner/Builder record. Treat those outputs as proposals, not Builder authority. Resolve technical design, update the package, and rerun the understanding gate before implementation. For owner-authority forks, investigate first and send one prepared proposal with the viable options, business consequences, recommendation, consequence of deferral, and exact owner action.

The rule. The owner direction at the top of the Owner/Builder record is the owner's voice. The package reference, status, evidence, risks, and alternatives below it are the builder's voice. The authoritative package and audit disposition in the Auditor record are 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 Owner decision interview

The goal interview discovers what the Owner wants. The Owner decision interview resolves business ambiguity uncovered later by system investigation or audit. Builder readback then proves that the implementation package reflects the adopted decisions.

The Auditor investigates first and presents one standalone decision at a time when each answer can change the next question. Independent decisions may be batched. The Owner should receive a recommendation and its business consequences, not technical homework or a blank questionnaire.

Decision to settle
A standalone business rule naming the actor, trigger, outcome, boundary, failure behaviour, and what must never happen.

Recommendation
The Auditor's recommended decision.

Business reason
Why this serves customers, revenue, cost, trust, or operating simplicity.

Wrong if
The Owner context or observable evidence that would invalidate the recommendation.

Owner response
Correct it, defer it, or explicitly adopt it.

The Owner may reject the options, correct the premise, or supply context the Auditor could not know. When that makes the recommendation wrong, the Auditor withdraws it immediately instead of defending the earlier design. Confidence language never substitutes for approval and numerical alignment estimates are unnecessary.

For example, an audit may suggest continuous reconciliation between several billing systems. The Owner may clarify that the customer charge becomes final when the invoice is issued and later source changes must not rewrite it. The Auditor then withdraws the reconciliation framework and records the simpler adopted rule. The interview has prevented a technically impressive implementation of the wrong business logic.

After explicit adoption, the exact rule enters the Owner-controlled record through the project's authorised path. Record what it supersedes and any unresolved dependent decision. The Auditor may draft the wording and update its own record, but it cannot declare adoption or write the Owner's decision on the Owner's behalf.

The interview ends when every material business fork is adopted, corrected, or deferred; evidence-dependent questions have an evidence owner; technical design remains with the Auditor; and the Auditor can write one observable business test without guessing.

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. Establish the starting business rules and delivery boundary — The auditor converts the owner's intent into explicit, falsifiable rules and a proposed observable business test. The Owner corrects the starting rules and confirms the intended environment, material scope, delivery constraint, Production boundary, and deferred work.
3. Preserve workspace state — Inventory the current revision, worktrees, tracked changes, and untracked paths. Preserve unexplained state through the project's approved mechanism and establish the package's isolated mutation lane.
4. 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.
5. Inspect delivery topology — Before implementation, the auditor verifies the actual branch, merge, CI, deployment, migration, promotion, and rollback triggers. It records automatic Production side effects and the closest representative non-Production environment.
6. Investigate, settle, and prepare — The auditor investigates the existing system and tests the proposed design against the starting rules. It uses the Owner decision interview for every material business ambiguity uncovered by that work. For complex or consequential packages, it may request one bounded, read-only whole-project peer pass and refute the observations itself. The Owner adopts the final business rules; the Auditor then writes the implementation-ready package.
7. Run the understanding gate — The auditor sends PACKAGE_READY_FOR_READBACK after writing the authoritative package. The builder replies directly in its own words, challenges ambiguity, and identifies contradictions. Raw readback stays in the direct channel. The Auditor corrects the package when needed; the Owner approves the final acceptance revision; and the Auditor records UNDERSTANDING_CONFIRMED only when all three parties share the same product logic.
8. Coordination setup — Use direct messages for readback and checkpoint doorbells when available. Otherwise create the low-frequency hook or scheduled check needed to carry the work forward without making the owner a message bus.
9. Freeze and start the authorised package — UNDERSTANDING_CONFIRMED freezes the acceptance line. The builder executes the focused vertical slice along the shortest safe path to representative-environment evidence, and the auditor reviews its stable hand-off independently. The owner intervenes only for an authority decision or a proposed change to the frozen line.

The shared-understanding gate

This gate prevents a technically competent implementation of the wrong product logic. The auditor makes the rules testable, exposes missing decisions, and uses the Owner decision interview until the owner confirms the product truth. The Auditor resolves technical design after the business meaning is settled.

The builder then proves that the package was understood through a direct readback in its own words. The readback answers six questions: What must the user be able to do? What must never happen? How does the proposed architecture enforce those rules? Which decisions are fixed and which mechanics are explicitly open? 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. It then corrects the authoritative package in the Auditor record and requests another readback. The raw readback is ephemeral; only the corrected package and final understanding disposition become durable.

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

Large context windows can delay compaction, but they do not preserve active understanding indefinitely. Long sessions can retain tasks and recent activity while losing the connection between the work and its business purpose. The records preserve authoritative direction, decisions, evidence, and audit history across session decay, context resets, handoffs, and model changes. The Owner/Builder record stops being just a progress log and becomes part of 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. July added persistent Goals, selective activation, the shared-understanding gate, critical-path execution, and verified access preconditions. The first August 19 edition closed the execution-authority gap and extended evidence to operational instruments. Version 2026-08-19.1 prevented Auditor-driven delivery drift by freezing the business acceptance line, requiring proportional proof, and moving representative-environment evidence ahead of generalised hardening. Version 2026-08-29 removed unnecessary fingerprint ceremony, moved readback to the direct channel, and added deliberate detection and rotation for degraded sessions. Version 2026-08-31 added minimum-sufficient-change scope inside the frozen line. Version 2026-09-04 adds an Owner decision interview, selective whole-project peer review, and end-to-end delivery measurement.

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 sends an uncoached direct readback of 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 carries either readback or a doorbell. Readback demonstrates current understanding; a doorbell tells the other role that a durable record, checkpoint, or blocker is ready. 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 an authentication or authorisation bypass, cross-tenant effects, credential or secret exposure, destructive or integrity-damaging state, a verified material supply-chain compromise, violation of the Owner-approved security or compliance baseline, 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.

Make the minimum sufficient change

The frozen acceptance line controls what the package means. The minimum sufficient change controls how much implementation is authorised inside that line. After directly inspecting the actual code, tests, configuration, and runtime contracts, the Auditor writes four things into the implementation-ready package in the existing Auditor record:

• Outcome — the exact observable behaviour required.
• Non-goals — behaviour and improvements excluded from the package.
• Expected change surface — the smallest files, interfaces, and resources expected to change. This is a planning forecast, not an exhaustive allowlist unless the Auditor explicitly labels it as one.
• Proof — the narrowest reliable existing tests and runtime evidence that prove the outcome.

The Builder confirms that it can execute that definition; it does not invent or expand scope. Reuse existing code, patterns, helpers, and test infrastructure when they satisfy the package. Fix the root cause instead of stacking workarounds. Use one implementation path unless compatibility explicitly requires two. Do not introduce abstractions, dependencies, frameworks, services, or test infrastructure for anticipated future needs. Preserve behaviour outside the authorised outcome, and remove replaced code unless the package explicitly retains it.

Testing follows the same boundary. Run the narrowest existing tests that exercise the changed behaviour. Extend the relevant existing test before creating separate infrastructure. Add tests only for uncovered acceptance criteria or material regression risks; do not backfill unrelated coverage. Passing tests never authorise additional scope or abstractions.

Scope-growth tripwire. The Builder stops the affected dependency chain and returns the evidence to the Auditor when implementation requires materially more files or unrelated cleanup; a new dependency, framework, service, or infrastructure component; an unauthorised public API, schema, storage, or wire-format change; a deletion, overwrite, migration, or workspace mutation not already authorised by the package; parallel old and new implementations; or future-use layers, workaround stacks, or tests for unstated behaviour. Independent work already authorised may continue. The Auditor investigates the actual system and corrects the package. The Owner is involved only when that correction changes business meaning, material scope, risk, cost, timing, or Production exposure.

The tripwire does not weaken the hard-stop rules. Actual or imminent destructive state, integrity damage, credential exposure, cross-tenant effects, unintended Production action, or false safety evidence stops the pass immediately.

At the existing checkpoint, the Builder explains why every touched file was necessary; records the exact commands and results; names remaining assumptions, limitations, and unverified runtime behaviour; and confirms that no debug code, backup files, dead paths, or scratch artefacts remain.

Freeze the acceptance line

Every package names one observable business acceptance test: the actor, the action, the intended environment, and the evidence that proves the result. It also names the material scope, delivery constraint or deadline, Production boundary, earliest representative-environment gate, and deferred follow-up work. The Owner confirms those delivery terms under a named acceptance revision. The Auditor then defines the technical design and smallest evidence set that proves the outcome and controls its material risks. After the Builder's direct readback matches, the Owner approves the acceptance revision in the Owner-controlled delivery-authority section. The auditor records UNDERSTANDING_CONFIRMED against that revision; the acceptance line is now frozen.

Later findings fall into three classes:

• Defect against the frozen line — the auditor writes the exact correction and evidence required.
• Verified hard stop — the pass stops. The auditor records the concrete failure and prepares any Owner decision required by its effect on risk acceptance, scope, timing, cost, or Production exposure.
• New hardening or generalisation — the auditor records it as follow-up work. It does not become a pre-delivery gate without Owner approval.

The auditor cannot front-load or later add a broader framework, more exhaustive simulation, cleaner abstraction, or fleet-wide solution unless each requirement is necessary for the Owner-confirmed business test or a material risk on its path. Any textual change to the Owner-controlled acceptance block requires a new Owner-approved revision; Git or the project's record history makes ordinary changes visible. If a blocked user or Owner deadline is at risk, the auditor removes everything that is not required by the frozen line or a verified hard stop and records it as follow-up work. If the proposed addition changes delivery, risk acceptance, material scope, cost, timing, or Production exposure, the Owner receives a prepared proposal and decides whether to create a new acceptance revision and understanding gate.

For regulated, distributed, or high-assurance work, the project may additionally fingerprint or sign the exact acceptance block. That is an optional assurance control, not a universal requirement. It is separate from identifying implementation evidence with a commit, branch, or exact diff.

Every technical gate in the line names the exact acceptance claim or material risk it proves and the least costly reliable evidence that will prove it. If the proposed proof would break the Owner-confirmed delivery constraint, the Auditor presents a prepared proposal instead of freezing the expanded package unilaterally.

Reach the real environment early

After the focused vertical slice passes the local evidence needed to deploy safely, the next meaningful gate exercises the closest representative non-Production environment. The package records an Owner-approved deadline or decision point for reaching that gate. Repeated local simulations do not substitute for provider behaviour, deployed configuration, real tenancy, or actual promotion mechanics.

Use the narrowest representative proof first: one named customer, tenant, dataset, route, or workflow. Prove that outcome before fleet provisioning, generalised rollout automation, documentation polish, secondary metrics, or unrelated parity work. A Production canary remains a separate Owner decision.

Prove the execution instrument

Deployment, migration, rollback, health-reading, and evidence-capture tools are build artefacts when the package depends on them. Their code and instructions determine whether a correct change reaches the intended state, whether a partial failure can be recovered, and whether anyone can later prove what happened.

Before an instrument touches valuable state, prove the exact mechanism needed by the current package against a disposable target. The Auditor selects the smallest evidence set that controls the material risks of the current delivery. A documented manual rollback, exact readback, or attended recovery can be sufficient when the frozen acceptance line does not require reusable automation. The applicable proof considers:

• Success — the intended state is reached and independently verified.
• Partial failure — an interrupted or failed run stops safely and reports the exact boundary reached.
• Retry and idempotence — retry behaviour is defined and repeated execution cannot silently duplicate or corrupt state.
• Rollback or recovery — the documented recovery path works from the failed state actually produced by the instrument.
• Health truth — health checks distinguish success, partial success, failure, and stale state.
• Durable evidence — run identity, logs, outputs, and recovery evidence remain retrievable after the instrument or its runner fails.

The Auditor names the proportionate instrument proof in the package before release. The Builder supplies disposable-target evidence, and the Auditor reviews it before authorising that instrument for the next valuable target. A successful application test does not prove the mechanism that deploys or migrates it, but instrument proof does not authorise the Auditor to build a reusable transaction framework, fleet system, or generalised rollback engine that the current business test does not need.

For example, a database change with a backfill needs more than a clean migration run. Use a disposable database, interrupt the migration after partial progress, verify the recorded boundary, rerun it safely, exercise recovery, and retrieve the run evidence after the migration process has ended. If the only evidence disappears with the failed job, the instrument has not passed.

Prove expected operational flows

When a package creates an ongoing expected data flow, acceptance covers explicit failure and unexplained silence. The package defines the expected cadence or triggering event, the silence threshold, the reporting path chosen by the project, deduplication and rate limiting, and the evidence that both failure modes were exercised. A flow can fail by producing an error or by producing nothing.

The Builder–Auditor cycle

1. The auditor converts the owner's intent into starting falsifiable rules and a proposed observable business test. The owner corrects the rules and confirms the delivery boundary in the Owner-controlled record.
2. The auditor directly inspects the code, tests, configuration, runtime contracts, and delivery topology, then attacks its proposed design. It uses the Owner decision interview to settle business ambiguity. For complex or consequential work, it may request one bounded whole-project peer pass, refute the observations, and record only what survives. After the Owner adopts the final rules, the Auditor writes the implementation-ready package with the business test, decisions, exclusions, critical path, environment gate, evidence, and minimum-sufficient-change definition.
3. The auditor writes the confirmed rules, architecture, boundaries, and acceptance evidence into one authoritative package, then sends PACKAGE_READY_FOR_READBACK.
4. The builder reads the package and replies directly in its own words with the business test, architecture, boundaries, fixed and open choices, evidence, ambiguities, and contradictions. Raw readback stays in the direct channel. The auditor resolves technical contradictions, escalates business contradictions, corrects the durable package, and requests another readback when needed.
5. When the readback matches, the Owner approves the acceptance revision in the Owner-controlled delivery-authority section. The auditor records UNDERSTANDING_CONFIRMED against the Owner revision, package revision, and acceptance revision. That disposition freezes the acceptance line.
6. The builder now runs one bounded autonomous pass along the shortest safe path to the observable business test. It reuses what already satisfies the package, makes one root-cause implementation, preserves behaviour outside the outcome, and runs the narrowest relevant existing tests. When scope crosses the tripwire, it returns the affected dependency chain and evidence to the Auditor while completing independent authorised work.
7. 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. The record explains every touched file, gives exact commands and results, states residual uncertainty, and confirms cleanup. It sends the doorbell and becomes idle; it does not wait inside the Goal for a reply.
8. The auditor reviews the stable evidence, runs a skeptic pass, looks for common causes, verifies that the Owner and acceptance revisions are unchanged, and checks the diff against the outcome, non-goals, expected change surface, and proof. It investigates scope growth, corrects the package itself unless Owner authority changes, classifies every finding against the frozen line, a verified hard stop, or follow-up work, and sends one actionable disposition.
9. If fixes are required against the frozen line or a verified hard stop, the auditor defines a new bounded correction pass with its own terminal evidence. New hardening and generalisation remain follow-up work. If the package is proven and another Now item is already authorised, the auditor prepares it and the understanding gate runs again before implementation.
10. 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 an additional agent only through an explicit lane for genuinely independent work.

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 two opposite failures: moving on "PASS" without proving actual behaviour, and accumulating technically impressive work while user availability remains zero. The auditor defines the frozen evidence before the builder starts, and the builder cannot call a step accepted until the auditor has reviewed it. Every status report names the achieved environment gate. 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.

Session decay, detection, rotation, and handoff

Sessions can degrade while they are still running. The first visible symptom may be loss of initiative, a coherent assignment returned only partly complete, increasingly short back-and-forth cycles, process language replacing business purpose, or a confident claim based on stale evidence. Context consumed and work intensity matter more than wall-clock age. Builder sessions often degrade sooner because implementation absorbs source, tool output, test results, failures, and repeated edits. Use behaviour and context-heavy boundaries, not a universal timer or fixed Builder-to-Auditor ratio.

Self-assessment is weak: asking an agent whether it is aligned invites a claim. The Owner needs a quick demonstration that requires no technical knowledge.

The CEO check: an Owner-operated, unannounced alignment canary

At a natural boundary, after context-heavy work, before accepting a major checkpoint, or whenever behaviour feels wrong, ask the working Builder or Auditor this ordinary side question without warning or preparation:

How's our progress? CEO level. Business value. What's done, what's left, what's the purpose of this project, and how are we doing?

Observe the whole reply. Its opening shows which level currently governs the agent's understanding; the rest shows how accurately that purpose remains connected to present reality.

• Aligned — starts with purpose and business or user value, separates done from left honestly, and gives a coherent assessment that matches the project record.
• Mild drift — starts at the correct level but contains small omissions, stale details, or an imperfect done/left split.
• Serious drift — uses the right executive framing but materially misstates purpose, progress, risk, or decision ownership.
• Severe drift — starts with files, packages, checkpoint codes, tests, or technical process; substitutes activity for value; or cannot explain why the project exists.

Keep the canary out of agent startup prompts, Goals, scheduled checks, and durable records; ask it as an ordinary Owner question. Do not clarify the question, provide an answer format, or coach the session after a poor opening. Compare the full answer with the durable records afterward when practical. A fluent executive answer that is materially wrong is serious drift, not alignment. The canary detects loss of purpose and current project understanding; the Auditor's evidence review remains responsible for detecting defects.

An aligned session continues. A mildly drifting session completes only its current bounded pass and rotates at the next natural boundary. For serious or severe drift, stop at a safe boundary, preserve unexplained and uncommitted workspace state, and replace the affected role before assigning new work. If Builder and Auditor give materially different purpose or progress accounts, treat it as crew-level misalignment and determine which role no longer matches the Owner's truth.

Do not spend rounds asking a degraded session to diagnose itself. Do not make it the sole author of an emergency handoff. A fresh agent reconstructs truth from the durable records, preserved workspace, stable evidence, and any previously verified handoff; it then sends the normal direct readback before the Auditor releases work. When the records are current, replacement takes minutes and rotation becomes hygiene rather than an emergency.

Planned compaction and session changes still use one stable handoff artefact. Use the same handoff instruction with your tool's context-compaction command, at a planned session end, and when a fresh 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. Treat a summary produced after a failed CEO check as unverified until a fresh role compares it with the records and evidence.

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 planned summary comparable.

Prepare a handoff for a fresh agent joining this project. Cover: Owner revision and confirmed business rules; observable business acceptance test and frozen acceptance revision; configured operating-record paths; preserved workspace state and mutation lane; current authorised package and package revision, delivery topology, and environment gate; fixed decisions, mechanically open choices, exclusions, and deferred follow-up work; understanding status; what is locally accepted, development proven, Production deployed as delivery only, Production business scenario passed, blocked, and next; decisions that must not be relitigated; proportionate instrument and runtime evidence with 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 Auditor record holds the authoritative package; 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, read the authoritative package, send a direct READBACK in your own words with contradictions and questions, and stop without changing code or either durable record. If confirmed, follow the frozen acceptance line and shortest safe path to the named Builder hand-off and earliest representative-environment gate, 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 observable business test and critical path, decide and freeze the understanding gate, or audit one frozen hand-off. Reject only against the frozen line or a verified hard stop; record other hardening as follow-up. 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 frozen acceptance line and shortest safe path to the named hand-off and earliest representative-environment gate, update the Owner/Builder record, send the doorbell, and stop that pass. If understanding is not confirmed, send a direct READBACK in your own words with contradictions and questions, change no durable record or code, 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. Reject only against the frozen acceptance line or a verified hard stop; record other hardening as follow-up. 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 frozen acceptance line and shortest safe path to the named hand-off and earliest representative-environment gate, update the Owner/Builder record, send the doorbell, and stop that pass. If understanding is not confirmed, send a direct READBACK in your own words with contradictions and questions, change no durable record or code, 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. Reject only against the frozen acceptance line or a verified hard stop; record other hardening as follow-up. 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 or either durable record: send a direct READBACK of the
authoritative package in your own words, including contradictions. Otherwise
update the Builder-owned sections of the Owner/Builder record with the
critical-path gate, exact evidence, instrument proof, recorded
failures, cleanup, environment milestone, and next step. Follow the frozen
acceptance line and reach the earliest representative-environment gate when
focused local evidence permits. Choose only mechanically equivalent options
explicitly left open by the Auditor. Record and return any material design gap;
do not fill it. 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, frozen acceptance revision,
critical path, hard stop, fixed decision, mechanically open choice, exclusion,
proportionate instrument proof, environment gate, operational-flow evidence
requirement, and next package to the Auditor record. Reject only against the
frozen line or a verified hard stop; record other hardening as follow-up work.
Do not edit the Owner/Builder record or code. Send the relevant doorbell or
record one prepared P1_DECISION_NEEDED proposal, 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 mutation, inventory the current revision, worktrees, tracked changes, and untracked paths; preserve unexplained state and use the package's explicit mutation lane
- Before code, read the authoritative package and send a direct READBACK in your own words: business rules, observable business acceptance test, Owner-confirmed delivery terms, frozen acceptance revision, architecture, delivery topology, boundaries, fixed decisions, mechanically open choices, exclusions, acceptance evidence, ambiguities, and contradictions
- Keep raw readback out of both durable records; do not implement until the Owner-controlled delivery-authority section approves this package's acceptance revision and the Auditor record contains UNDERSTANDING_CONFIRMED against the same Owner, package, and acceptance revisions
- Confirm that the package defines its exact outcome, non-goals, expected change surface, and narrowest reliable proof; confirm you can execute that scope but do not invent or expand it
- Challenge ambiguity or contradiction instead of guessing
- Choose only mechanically equivalent implementation options explicitly left open by the Auditor; never decide a gap that can affect behaviour, interfaces, security, data ownership, failure handling, dependencies, rollout, rollback, cost, or evidence
- When a material gap appears, record the contradiction or proposal, return the affected branch to the Auditor, and continue only independent safe work
- Follow the frozen acceptance line and critical path to the named Builder hand-off; do not implement deferred follow-up work
- Reuse existing code, patterns, helpers, and test infrastructure when they satisfy the package; fix the root cause; use one implementation path unless compatibility explicitly requires two
- Do not add abstractions, dependencies, frameworks, services, or test infrastructure for anticipated future needs; preserve behaviour outside the authorised outcome and remove replaced code unless the package explicitly retains it
- Stop the affected dependency chain and return evidence to the Auditor when the scope-growth tripwire is crossed; continue independent work already authorised
- After focused local evidence permits safe deployment, move the vertical slice to the earliest representative non-Production gate instead of adding unrelated local hardening
- Prove the exact execution instrument required by the current package against the specified disposable target and store evidence outside the instrument's failure boundary
- Record ordinary failures and continue every independent safe evidence branch
- Stop immediately for a hard-stop condition
- Run the narrowest existing tests that exercise the changed behaviour; extend the relevant existing test before creating separate infrastructure; add tests only for uncovered acceptance criteria or material regression risks; never backfill unrelated coverage or treat passing tests as authority for more scope
- Update the Owner/Builder record with why every touched file was necessary, the immutable diff, exact commands and results, evidence branches, failures, assumptions, limitations, unverified runtime behaviour, cleanup, and next step before the hand-off
- Confirm that no debug code, backup files, dead paths, or scratch artefacts remain
- 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 the tests and runtime proof specified by the Auditor

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
- When investigation exposes unresolved business meaning, use the Owner decision interview: one standalone decision, your recommendation, business reason, what would make it wrong, and an explicit request for the Owner to correct, defer, or adopt it; never assign yourself adoption authority
- For complex or consequential work, you may request one bounded read-only whole-project peer pass before implementation or a major deployment gate; refute its observations yourself and record only surviving findings or corrections
- Directly inspect the actual code, tests, configuration, runtime contracts, and delivery topology, including automatic deployment and Production triggers, before preparing the package
- Before releasing each package, declare and verify its access preconditions; record capabilities and status, never secret values
- Confirm that unexplained workspace state is preserved and the package has an explicit mutation lane
- Define fixed decisions, mechanically open choices, and explicit exclusions; never delegate an unresolved material design choice as routine Builder work
- Define the exact outcome, non-goals, expected smallest change surface, and narrowest reliable existing tests and runtime proof in every implementation-ready package; the expected surface is not an exhaustive allowlist unless explicitly labelled as one
- Get Owner confirmation of the observable business test, intended environment, material scope, delivery constraint or deadline, Production boundary, and deferred work before freezing the package
- Define the shortest safe critical path, earliest representative-environment gate, proportionate execution-instrument proof, operational-flow failure and silence evidence, terminal evidence, and material security and delivery hard stops in the Auditor record
- Tie every technical gate to one acceptance claim or material risk and specify the least costly reliable evidence; return any delivery-impacting expansion to the Owner before freezing the line
- Send PACKAGE_READY_FOR_READBACK after writing the authoritative package; compare the Builder's direct readback, correct the package when needed, and request another readback until it matches
- Ask the Owner to approve the final acceptance revision in the Owner-controlled delivery-authority section after the Builder readback matches; release implementation only with UNDERSTANDING_CONFIRMED against the same Owner, package, and acceptance revisions
- Reject work only against the frozen acceptance line or a verified hard stop; record new hardening, generalisation, fleet automation, and unrelated parity as follow-up work unless the Owner approves a revised line
- When the Builder returns scope-growth evidence, investigate the affected system and correct the package; involve the Owner only if the correction changes business meaning, material scope, risk, cost, timing, or Production exposure
- Be instructive — tell the Builder clearly what to do
- Specify the narrowest existing tests that exercise the changed behaviour; prefer extending a relevant existing test, add tests only for uncovered acceptance criteria or material regression risks, and never require unrelated coverage
- Review the complete frozen evidence, touched-file necessity, exact commands and results, residual uncertainty, and cleanup; look for common causes, classify findings against the frozen line, hard stops, or follow-up work, and batch required corrections into one bounded pass
- Report progress with the exact evidence ladder: locally accepted; development proven; Production deployed — delivery only; Production business scenario passed
- Investigate before escalating Owner authority; present viable options, business consequences, one recommendation, the consequence of deferral, and the exact Owner action
- 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. A same-stack pair can make direct task communication easier; a mixed or cross-family pair may bring different reasoning patterns. Each role starts a Goal only for its current pass and becomes idle after delivering its hand-off.

The current Codex configuration described under model performance uses the generic templates below. Choose models for capability, cost, and tool access; keep the roles and authority boundaries unchanged.

The templates below name the tasks Builder and Auditor. Personal task names and model choices do not change their responsibilities.

The understanding gate is itself a pair of bounded passes: the Auditor writes the authoritative package and sends PACKAGE_READY_FOR_READBACK; the Builder returns an ephemeral direct READBACK; the Auditor corrects the package when needed and ends its alignment pass at UNDERSTANDING_CONFIRMED or P1_DECISION_NEEDED. UNDERSTANDING_CONFIRMED freezes the observable business test and acceptance line. After implementation is released, use the templates below for the Builder and audit passes.

Builder 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 the Auditor: 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 unexplained workspace state is preserved, the mutation lane and delivery topology are explicit, and the Auditor record contains UNDERSTANDING_CONFIRMED for the same Owner revision, package revision, observable business test, and acceptance revision recorded in the Owner/Builder record; otherwise end BLOCKED without changing code. Never edit Owner direction or decisions. Follow the frozen acceptance line, shortest safe critical path, and package's minimum-sufficient-change definition. Reuse suitable existing code and tests, fix the root cause through one implementation path, preserve behaviour outside the outcome, remove replaced code unless retained, and add nothing for anticipated future needs. Build the focused vertical slice and reach the earliest representative non-Production gate when focused local evidence permits safe deployment. Continue through mechanically equivalent choices explicitly left open by the Auditor, ordinary test failures, and progress updates. Do not decide any gap that can affect behaviour, interfaces, security, data ownership, failure handling, dependencies, rollout, rollback, cost, or evidence. Apply the scope-growth tripwire without weakening any hard stop: return the affected dependency chain and evidence to the Auditor, then complete every independent safe evidence branch. Use the package's narrowest reliable proof; extend existing tests before creating separate infrastructure and add focused tests only for uncovered acceptance criteria or material regression risks. Passing tests never authorise more scope. Do not implement deferred hardening or unrelated parity. Prove any execution instrument required by the package against its specified disposable target and preserve evidence outside the instrument's failure boundary. End BLOCKED for access only when a declared precondition failed or a genuinely unforeseen dependency blocks every remaining meaningful branch. Never place secret values in 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 touched-file necessity, immutable diff, exact commands and results, achieved environment, completed and blocked evidence, failures, assumptions, limitations, unverified runtime behaviour, cleanup, deferred follow-up, and intended next action; send the Auditor the matching doorbell; then end the Goal. Do not wait for the Auditor or the Owner inside this Goal.

Auditor 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, observable business test, frozen acceptance revision, matching package revision, mutation lane, delivery topology, decisions, open mechanics, exclusions, critical path, proportionate instrument proof, environment milestone, operational-flow evidence, terminal evidence, and cleanup. Confirm that the package's minimum-sufficient-change definition came from direct inspection of the actual code, tests, configuration, and runtime contracts. Review the stable evidence against its outcome, non-goals, expected change surface, and proof, including touched-file necessity, exact commands and results, residual uncertainty, and cleanup. Adversarially test the implementation and claims, refuting candidate findings before reporting them. Check that the Builder reused suitable existing code and tests, fixed the root cause through one path, preserved unrelated behaviour, removed replaced code unless retained, and added no future-use layers or unrelated coverage. Investigate scope-growth evidence, preserve hard stops, and correct the package; involve the Owner only if business meaning, material scope, risk, cost, timing, or Production exposure changes. Classify every surviving finding as a defect against the frozen line, a verified hard stop, or follow-up work. Do not create a new delivery gate for theoretical hardening, reusable tooling, fleet automation, documentation polish, secondary metrics, or unrelated parity. Consolidate required findings into one bounded correction package with exact changes and rerun evidence. Record ACCEPTED only when the applicable gate is genuinely met. Report progress as locally accepted; development proven; Production deployed — delivery only; or Production business scenario passed. If a proposed change needs Owner authority, investigate first and record the viable options, business consequences, recommendation, consequence of deferral, and exact Owner action; then send P1_DECISION_NEEDED. Otherwise send the Builder AUDIT_COMPLETE. Then end the Goal. Do not wait for the Builder 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 Builder and Auditor 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 Builder-to-Auditor 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 the Auditor idle after its previous Goal, have the Builder send CHECKPOINT_READY, and verify whether the Auditor 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.

Additional agent lanes

The method still has two authority roles when more agents participate. Every additional agent works inside a named Builder-owned or Auditor-owned lane. Before delegation, the responsible role records the lane's purpose, bounded question or package, read and write scope, mutation ownership, stopping condition, durable output location, and required evidence in its existing operating record.

Every delegated lane is visible in the durable record. Evidence identifies which lane produced it and which responsible Builder or Auditor verified it. An additional implementation-writing lane uses a separate worktree or equivalent isolation and cannot overlap another lane's files. An additional audit lane remains read-only and returns findings to the primary Auditor, who refutes them and owns the final disposition.

Fresh whole-project peer review

For complex or consequential work, a strong model can provide one fresh whole-project review before implementation or a major deployment gate. It operates as a temporary read-only lane under the primary Auditor. Use it where a new context may expose a shared assumption, missing decision, or design improvement that would be expensive to discover during implementation. End the lane when it returns its observations.

Review this project as a whole using the current operating records, source, and evidence. Identify concerns, misalignments, missing decisions, and high-value improvements.

Return neutral, non-authoritative peer observations for the primary Auditor's consideration. Separate established evidence, inference, and suggestion. Do not instruct the Builder, edit project records or implementation, decide business logic, or claim acceptance.

The lane is declared in the Auditor record with its purpose, read scope, stopping condition, and required evidence. The peer returns its raw response to the primary Auditor as a temporary review input; the durable output is the Auditor's adjudication of what survived. The Auditor investigates and tries to refute each material observation, then records only surviving findings, corrections, or Owner decisions. The peer must not instruct the Builder and has no acceptance authority.

Any capable model can fill this lane. My current Codex implementation uses Astra with max reasoning; another team may use a different OpenAI model, a cross-family model, or omit the peer pass. Fresh context can expose shared assumptions. Evidence and Auditor judgement still decide what survives.

Worked example: tenant-safe customer export

The owner says: “A customer administrator can export their organisation's records.” The Auditor makes that intent falsifiable and names the business test: in development, an authenticated administrator requests and downloads the organisation's existing records as a CSV; the count is authoritative, no other tenant's data appears, no unrelated processing starts, and test state is removed. Production remains out of scope. The owner corrects and confirms those rules.

The Auditor inspects the existing system and deployment topology before build. It finds that the UI sends a tenant identifier which the service currently trusts and rejects a design that merely validates the UI value. It also confirms which branch deploys to development, which action can reach Production, and how the narrow canary is rolled back. The frozen acceptance line requires the server-bound design, focused local tests, proportionate deployment proof, one development proof, permitted export, cross-tenant denial, accurate content, and cleanup. Any cross-tenant disclosure, destructive state change, or unintended Production action is a hard stop.

Before coding, the Builder sends a direct readback of 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. The Auditor clarifies that the request must not accept an authority-bearing tenant field, updates the durable package, and requests a corrected readback. Only then does the Builder implement it.

After focused local evidence passes, the Builder deploys the vertical slice to development instead of expanding it into fleet provisioning. The real environment exposes a provider response that the local fixture did not represent. The Builder records the evidence and completes the independent denial and cleanup branches. The Auditor returns one correction tied to the frozen business test. It does not require a generalised provisioning journal, fleet-wide rollout engine, or exhaustive browser refinement; those remain follow-up work.

After the corrected development proof establishes the complete export journey, the Auditor records runtime_proven. The owner receives: “The named export journey and tenant isolation are proven in development. Production remains untouched. Follow-up automation is outside this delivery. Owner action: approve or decline a controlled Production canary.”

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.
• Asking a session whether it is aligned instead of requiring an unannounced CEO-level demonstration.
• Coaching or reprompting a session after it fails the CEO check, making the failed probe appear green.
• Keeping a seriously degraded session because replacing it feels expensive, instead of relying on the durable records.
• Using wall-clock age or a fixed Builder-to-Auditor ratio as the only rotation signal.
• Letting a session that failed the CEO check become the sole authority for its emergency handoff.
• 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.
• Auditor defending a recommendation after the Owner corrects its premise, or recording adoption without the Owner's explicit decision.
• Treating raw peer observations as accepted findings, or letting the peer instruct the Builder directly.
• Running the strongest peer continuously on routine work or reporting model-turn speed as total project speed.
• Builder starting implementation before directly reading back and challenging the package.
• Builder silently completing rollout, rollback, interface, failure-handling, or evidence design that the package left unresolved.
• Auditor discovering material package design during audit and treating the resulting rework as Builder incapability.
• Auditor moving the acceptance line during correction rounds because a broader or more elegant solution is possible.
• Auditor declaring an implementation-ready package without direct system inspection or a clear outcome, non-goals, expected change surface, and proof.
• Builder crossing the scope-growth tripwire through unrelated cleanup, parallel paths, future-use layers, dependencies, or test infrastructure without returning evidence to the Auditor.
• Using passing tests as permission to broaden the package, or handing off without touched-file necessity, exact results, residual uncertainty, and cleanup.
• Building reusable infrastructure, fleet automation, or generalised rollback machinery before the named representative proof or Owner-approved Production canary requires it.
• Repeating local simulations while the closest representative environment remains untested.
• Provisioning an entire fleet before proving one named customer, tenant, or representative workflow.
• Reporting passing tests, accepted source, or a merge as customer progress without naming the achieved environment gate.
• Merging before inspecting what the branch or merge automatically deploys.
• Turning an omitted access dependency into an unexplained, urgent mid-run request to the owner.
• Resetting, cleaning, deleting, overwriting, stashing, or publishing unexplained workspace state.
• Using an unproven deployment, migration, rollback, health-reading, or evidence-capture instrument on valuable state.
• Keeping instrument evidence only inside the process or environment that can destroy it when it fails.
• Asking the owner an open technical question before investigating the viable options and consequences.
• Delegating work to an unnamed agent with no bounded ownership, durable output, or attributable evidence.
• Creating an expected operational flow with no proof of explicit failure reporting or silence detection.
• 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 and delivery boundary. The Auditor turns your intent into required outcomes, prohibited outcomes, boundaries, negative cases, and one observable business acceptance test. Correct them until they express the product logic you want, then confirm the intended environment, material scope, delivery constraint or deadline, Production boundary, deferred work, and owner revision.
3. Preserve the workspace. Inventory the current revision, worktrees, tracked changes, and untracked paths. Preserve unexplained state through the project's approved mechanism and create the package's isolated mutation lane.
4. 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.
5. Inspect delivery topology. The Auditor verifies the actual branch, merge, CI, deployment, migration, promotion, and rollback triggers, including any automatic Production effect.
6. Review the package. Put only owner-approved work in the Now section of the Owner/Builder record. After inspecting the actual code, tests, configuration, and runtime contracts, the Auditor defines the exact outcome, non-goals, expected smallest change surface, and narrowest reliable proof alongside the business test, decisions, exclusions, critical path, environment gate, terminal evidence, and hard stops. For complex or consequential work, run the bounded peer pass before releasing the package and record only the Auditor's adjudicated result.
7. Run the understanding gate. The Auditor writes the authoritative package and sends PACKAGE_READY_FOR_READBACK. The Builder replies directly in its own words with the rules, business test, Owner-confirmed delivery terms, architecture, delivery topology, boundaries, contradictions, and acceptance evidence. Raw readback stays out of the durable records. The Auditor corrects the package when needed; the Owner approves the final acceptance revision; and implementation remains blocked until the Auditor record contains UNDERSTANDING_CONFIRMED against the same Owner, package, and acceptance revisions.
8. 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.
9. Start the roles. The Builder makes the minimum sufficient root-cause change using existing code and tests, preserves everything outside the outcome, and returns scope-growth evidence to the Auditor without blocking independent authorised work. At hand-off it explains every touched file, reports exact commands and results plus residual uncertainty, and confirms cleanup. The Auditor corrects the package, rejects only against the frozen line or a verified hard stop, and involves the Owner only when business authority changes.

Current Codex example. For complex projects, my current configuration uses SOL at xhigh for the Auditor, SOL at high for the Builder, and an optional Astra max peer pass at selected gates. Use the generic bounded Goals in Section 8. Test direct wake-up behaviour before relying on it and configure the fallback when needed. Other models and stacks use the same roles and records.

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, read the authoritative package, send a direct READBACK in your own words with contradictions and questions, and stop without changing code or either durable record. If confirmed, follow the frozen acceptance line and critical path to CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Reach the earliest representative-environment gate when focused local evidence permits. 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, read the authoritative package, send a direct READBACK in your own words with contradictions and questions, and stop without changing code or either durable record. If confirmed, follow the frozen acceptance line and critical path to CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Reach the earliest representative-environment gate when focused local evidence permits. 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 observable business test and critical path, decide and freeze the understanding gate, or audit one frozen hand-off. Reject only against the frozen acceptance line or a verified hard stop; record other hardening as follow-up. 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 observable business test and critical path, decide and freeze the understanding gate, or audit one frozen hand-off. Reject only against the frozen acceptance line or a verified hard stop; record other hardening as follow-up. 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 messages for readback and checkpoint doorbells 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.
• Use the unannounced CEO check after context-heavy work, before a major checkpoint, or when a session's behaviour feels wrong. Rotate degraded sessions at a safe boundary instead of coaching them back to a green answer.
• Report progress with the exact evidence ladder: locally accepted; development proven; Production deployed — delivery only; Production business scenario passed. Test count, source completeness, merge status, and deployment alone do not describe user availability.
• For large projects, additional agents use named lanes with bounded ownership, explicit read/write scope, a stopping condition, durable output, and attributable evidence. Implementation-writing lanes use non-overlapping files in separate worktrees or equivalent isolation.
• 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-09-04 — current. Added the Owner decision interview, a bounded whole-project peer-review lane, vendor-neutral Goal templates, the current SOL/SOL/Astra Codex configuration, and field evidence showing why end-to-end delivery speed matters more than model-turn latency. View snapshot →
• 2026-08-31.2 — corrected the Quick Start copy controls after live clipboard verification exposed an empty-copy result. View snapshot →
• 2026-08-31.1 — clarified that scope growth never weakens hard stops, integrated minimum-sufficient-change at the main process boundaries, and shortened duplicated Goal and anti-pattern language. View snapshot →
• 2026-08-31 — added a minimum-sufficient-change definition to every implementation-ready package, Builder execution and testing limits, a scope-growth tripwire, and stronger checkpoint evidence for touched files and residual uncertainty. View snapshot →
• 2026-08-29 — replaced mandatory acceptance fingerprints with Owner-approved revisions and optional high-assurance signing; moved Builder readback from duplicated durable text to direct messages; and added session-decay symptoms, the Owner-operated unannounced CEO alignment canary, and deliberate role rotation. View snapshot →
• 2026-08-19.1 — added an Owner-confirmed, fingerprinted business acceptance line; required early representative-environment proof and canary-first Production rollout after approval; made operational proof proportional to the current outcome; added deployment-topology intake; and prohibited Auditor-created delivery gates for deferred hardening. View snapshot →
• 2026-08-19 — defined mechanically open Builder choices, added workspace-state preservation and prepared Owner proposals, required disposable-target proof for execution instruments, added operational-flow silence detection, and made additional-agent work explicit and attributable. View snapshot →
• 2026-07-24 — 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, freeze the observable acceptance line, prove shared understanding before code, keep the two operating files current, and work the shortest safe path to real customer evidence through bounded role-owned passes.

Dr. Mikko S. Niemelä — 2026

Last updated: September 4, 2026