Building with AI Agents

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

1. The Method

A single agent asked to design, build, and approve its own work tends to defend the path it has already taken. The remedy is structural. Separate implementation from acceptance, keep the human in control of purpose and authority, and make claims answerable with evidence.

The project keeps two durable operating records. The Owner/Builder record contains Owner-confirmed direction and the Builder's current state, evidence, and next action. The Auditor record contains the authoritative package, review disposition, corrections, and acceptance. Projects may choose any filenames. This guide uses plan.md and comments.md only as examples.

Messages are used for direct readback and notification. A readback demonstrates what the recipient currently understands. A doorbell says that a stable package, checkpoint, blocker, or disposition is ready. Material instructions, decisions, evidence, and acceptance remain in the records.

The Builder writes implementation and the Builder-controlled parts of the Owner/Builder record. The Auditor writes only the Auditor record. Prompts and worktrees provide procedural separation. Filesystem permissions, sandboxes, separate operating-system identities, or equivalent access controls provide technical enforcement. A worktree separates Git state; it does not prevent an agent with broader filesystem access from modifying another checkout.

2. Starting and Keeping the Records

The Auditor is the front door

The opening prompt assigns the current agent as Auditor. It reads the complete guide, repository instructions, existing records, current source state, and available evidence before deciding what happens next. It does not assume that every project is new.

The Auditor classifies the current state:

• New: the idea needs an Owner interview and initial records.
• Active: an authorised Builder package is in progress.
• Paused: work has a recorded ending condition and resumption path.
• Blocked: a named decision, access dependency, contradiction, or external condition prevents the next meaningful action.
• Awaiting audit: stable Builder evidence is ready for independent review.
• Complete: the accepted outcome is proved at its intended gate and remaining work is explicitly separate.

If the starting agent wrote the implementation now under review, it cannot provide independent acceptance of that work. It may inventory the project and prepare a handoff, but a fresh Auditor must review the result. Changing the role label does not create independence.

A bounded setup state

A new project needs records before it can pass the shared-understanding gate. The setup path is therefore explicit:

1. The Auditor identifies suitable record paths from existing project conventions. If no convention exists, it proposes plan.md and comments.md.
2. The Auditor creates or updates only the Auditor record. It labels proposed business rules as unconfirmed until the Owner approves their meaning.
3. The Auditor reuses an assigned Builder or asks the Owner for permission to create one when the platform supports agent creation. Otherwise it gives the Owner one ready-to-send Builder instruction.
4. The Builder may create the Owner/Builder record during setup. Throughout the project, the Builder is the recorder of the Owner's explicitly approved direction in that record. It preserves the Owner's meaning and never invents, extends, or silently reinterprets the decision.
5. The Builder sends SETUP_RECORD_READY to the Auditor and does not change implementation until the Auditor records shared understanding.
6. The Auditor replies with the current package, the next readback action, or an explicit hold. Setup never ends without a return message.

The Owner does not need to edit a formal record manually. The Owner makes decisions in ordinary language. The Builder records confirmed Owner direction in the Owner/Builder record. The Auditor records only the decision's technical consequences in the Auditor record. When the Owner answers the Auditor directly, the Auditor sends the Builder a recording doorbell pointing to that explicit decision. If the Builder cannot access the original Owner message, the Auditor relays the exact approved wording and enough context for faithful transcription. The Builder records it and acknowledges completion. Dependent work remains held until the decision is durable. Neither role may claim that a proposal was approved or alter the Owner's meaning.

One current entry point

The Owner/Builder record is the current entry point. It identifies the active outcome, package, state, responsible role, holds, evidence pointers, and next action. It links the Auditor's package and disposition instead of copying them. Replaced instructions are marked superseded with the replacing decision and date. History remains available without leaving two live directions.

When Owner direction or the operating method changes during active work, the Auditor reconciles the affected package at the next safe handoff. Immediate safety conflicts stop the unsafe action. Other changes do not restart sound work, release holds, renew attempts, or revive historical permission.

Minimal records

# Owner direction
Methodology: canonical guide URL or the snapshot version pinned by this project.
Purpose: what this project is for.
Current outcome: the one useful result authorised now.
Delivery constraint: Owner-set deadline or other timing constraint, or none.
Business rules: outcomes and boundaries explicitly confirmed by the Owner.
Authority: intended environment and actions that still require Owner approval.

# Current state
Package: human-readable label and dated or numbered revision; link to the current Auditor package.
Status: setup | planned | building | ready_for_audit | accepted | blocked | waiting.
Evidence: stable references sufficient to identify what was tested.
Holds: none, or the exact condition preventing progress.
Next action: one role, one action, one expected handoff.

# Current package
Methodology: same canonical or pinned snapshot URL as the Owner/Builder record.
Package: human-readable label and dated or numbered revision.
Outcome: the observable result to deliver.
Non-goals: what this package will not change.
Confirmed rules: the Owner-approved business meaning.
Fixed decisions: implementation properties the Builder cannot choose.
Open mechanics: equivalent low-level choices left to the Builder.
Proof: the simplest sufficient tests or observation.
Hard stops: material conditions that stop the current action.

# Disposition
Status: proposed | understanding_confirmed | accepted | fixes_required | owner_decision_needed.
Applies to: package revision and Builder checkpoint or evidence reference.
Evidence reviewed: stable references and material results.
Required corrections: exact changes, or none.
Evidence still needed: what remains before acceptance.
Next action: one role, one action, one expected handoff.

For projects spanning several packages, retain the intended user experience, agreed capabilities, and future ideas in the Owner/Builder record or a linked product specification. Keep future ideas separate from authorised work. Accepting one package does not authorise the next.

Consequential work adds only the assurance fields justified by its risks: identity and environment, access preconditions, affected targets, rollback, attempt authority, evidence validity, operational-flow monitoring, and planned-wait terms. A local brochure site should not inherit a production migration dossier. A tenant-sensitive deployment should not omit the controls that make its safety claims credible.

3. A Small Project

An organiser tells an agent: "I want a simple website for our neighbourhood music evening." They paste the Auditor prompt.

The Auditor asks only what changes the first useful result: who the site is for, the event date and location, what visitors should be able to do, whether registration is needed, and whether publishing is part of the current work. The Owner answers: visitors need the programme, venue, accessibility information, and a link to an existing registration form. The first package ends with a reviewed local page; publishing remains a later Owner decision.

The Auditor arranges a Builder. The Builder reads back the audience, content, non-goals, and proof. The Auditor resolves one ambiguity about the venue entrance, records shared understanding, and releases implementation. The Builder completes the page and supplies a stable local preview plus responsive and link checks. The Auditor compares the visible page with the confirmed details and either accepts it or returns one correction package.

The Owner receives: "The event page is complete and independently checked on phone and desktop. It has not been published. Owner action: review the page and decide whether to publish it." The method has added independent thinking and evidence without turning a small website into an infrastructure programme.

4. The Operating Cycle

Clarify the outcome

The Owner begins with intent, not a technical specification. The Auditor asks questions that reveal the user, desired capability, prohibited outcome, important boundary, consequence of failure, and first useful result. The number and depth of questions follow the product. One important question answered from one source can define a valuable tool; complexity is not a quality measure.

When an unresolved choice depends on business meaning, the Auditor investigates the technical facts and returns one prepared proposal:

Decision needed: [one business question]
Recommendation: [one option]
Business reason: [why it best serves the confirmed purpose]
What would make it wrong: [missing fact or competing priority]
If deferred: [what can continue and what remains blocked]
Owner action: correct, defer, or approve this decision.

The Auditor may draft proposed wording. Only the Owner can adopt business meaning, risk, priority, material scope, cost, timing, or consequential deployment authority. A new Owner approval is required when one of those properties changes, not for spelling, formatting, clearer wording with unchanged meaning, or a technical correction inside existing authority.

Prepare before building

The Auditor inspects the relevant source, tests, configuration, interfaces, dependencies, and intended environment. Before releasing the package, it tries to disprove the proposed design against the Owner-confirmed rules and material failure cases, then resolves the gaps it finds. It defines the minimum sufficient change:

Before a commit, push, merge, deployment, migration, or activation can occur, the Auditor inspects what that action actually triggers. The package records automatic CI, deployment, Production, data, provider, and customer effects plus the authority required for each. A source operation is never assumed to be source-only.

• Outcome: the observable behaviour requested.
• Non-goals: what this package will not do.
• Expected change surface: the smallest files, interfaces, or resources likely to change. This is a forecast unless explicitly declared exhaustive.
• Proof: the least costly reliable test or observation that can falsify the acceptance claim.

The package resolves every choice that could alter behaviour, interfaces, security, data ownership, failure handling, dependencies, rollout, rollback, material cost, or evidence. The Builder may choose only mechanically equivalent details explicitly left open, such as private naming or local arrangement.

Work the shortest safe path

Record any Owner-set deadline or delivery constraint beside the authorised outcome. If the proposed work or evidence programme threatens it, the Auditor presents the smallest safe delivery option, the work deferred from that option, and the exact decision required from the Owner.

The critical path ends at the observable result, not at source completion. After the focused local evidence needed for safe deployment passes, move the smallest useful slice to the closest representative non-production environment. Prove one representative user, tenant, dataset, route, or workflow before fleet rollout, general infrastructure, or secondary polish. Production remains a separate Owner decision unless the Owner explicitly defined another authority model.

If the package depends on a deployment, migration, rollback, health-reading, or evidence-capture instrument, treat that instrument as a build artefact. Prove the mechanism needed by the current package against a disposable or otherwise safe target before it touches valuable state. The proof covers the material success, partial-failure, retry, recovery, and evidence-retention claims. It does not justify building a reusable transaction framework or fleet system that the current outcome does not need.

Keep hard stops explicit

Proportionality never makes these routine implementation decisions: authentication or authorisation bypass, credential or secret exposure, cross-boundary data disclosure, destructive or integrity-damaging state change, verified material supply-chain compromise, unintended consequential-environment activity, uncontrolled external cost, or evidence that falsely proves safety. Stop the affected action, preserve state and evidence, and return the decision through the recorded authority path. Independent safe work may continue when the package clearly separates it.

Prove shared understanding

1. The Auditor records the proposed package with a human-readable label and dated or numbered revision, then sends PACKAGE_READY_FOR_READBACK.
2. The Builder identifies that package revision and explains the outcome, fixed decisions, open mechanics, boundaries, proof, and contradictions in its own words. This raw readback stays in the direct channel.
3. The Auditor corrects the package when the readback exposes a gap. Business ambiguity returns to the Owner.
4. The Auditor verifies that the final business meaning and authority remain covered by the Owner's recorded approval. Only unresolved or materially changed decisions return to the Owner.
5. The Auditor records UNDERSTANDING_CONFIRMED for that package revision and releases implementation.

The Builder may create its operating record during setup, but it does not modify implementation before this gate. A relevant change to the package requires renewed Builder readback. A relevant implementation change after acceptance requires renewed Auditor review. Evidence unaffected by the change remains valid. The Auditor does not accept a project it previously built merely by changing roles.

Build one coherent package

The Builder works autonomously to the named handoff. It reuses suitable code and tests, fixes the root cause through one implementation path, preserves behaviour outside the outcome, and avoids future-use abstractions. Ordinary test failures and routine implementation details do not end the pass. A material contradiction stops only the affected dependency; independent authorised work may continue.

The Builder returns CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. It records the reviewed-work reference, tests and material results, failures, assumptions, limitations, unverified behaviour, cleanup, and intended next action. It does not call its own work accepted.

Audit independently

The Auditor reviews the stable result against the confirmed outcome and material risks. It tries to refute candidate findings before reporting them, looks for a common cause instead of returning symptom-sized corrections, and batches ordinary findings into one executable correction package. Findings outside the acceptance line become follow-up work unless they expose a material safety boundary or require a new Owner decision.

The evidence ladder keeps claims honest:

Communicate without making the Owner a message bus

Builder and Auditor exchange readback and doorbells directly when the platform supports it. Detailed instructions and evidence stay in the records. A checkpoint message identifies the package, current gate, stable evidence reference, disposition, and requested next action. It does not reproduce the working record.

CHECKPOINT_READY
Package: responsive event page
Gate: Builder evidence complete; Auditor acceptance pending
Evidence: [stable preview or change reference]
The Owner/Builder record is current.
Requested action: audit the completed package.

AUDIT_COMPLETE
Package: responsive event page, revision 2
Checkpoint: [stable evidence reference]
Disposition: ACCEPTED | FIXES_REQUIRED
The Auditor record contains the evidence review and any exact corrections.
Next action: [next authorised Builder pass] | HOLD [ending condition].

Every handoff has a return path. The Auditor records acceptance or required corrections, directly notifies the Builder, and assigns either the next authorised pass or an explicit hold. The Builder acknowledges the disposition before acting. If direct messaging cannot wake the receiving role, use the recorded scheduled check. If neither messaging nor scheduling is available, state that limitation and give the Owner one manual relay action; do not pretend the loop is autonomous.

Owner updates begin with business truth. Use a compact structure when a decision or meaningful status boundary is reached:

• Done: what users can now do, stated at the proved evidence level.
• Left: the remaining business milestones in order.
• Status and risk: whether the project is healthy, blocked, or slipping, and the most important risk.
• Owner action: one exact decision or "no Owner action."

5. Proportional Assurance

The same operating cycle supports a local page, a business workflow, and a production system. The assurance burden changes with the claim. The Auditor records why an additional control is necessary and applies it only to the affected capability and material risk.

Evidence precision follows the claim

Use a stable reference sufficient to identify the work that was reviewed. A local preview or document version may be enough for a draft. A pull request, commit, or saved diff normally identifies source work. A deployment identity matters when several candidates could be confused or rollback must select one. A cryptographic digest, signature, or byte-identical artefact is appropriate when integrity, tamper detection, regulated provenance, certificate identity, or exact binary promotion is part of the claim.

Do not create separate hash ceremony for routine records. Do not accept a moving branch or changing live URL as proof of what was tested previously. The package chooses the lightest reference that remains stable enough for the decision.

Record the commands and material results needed to reproduce the acceptance claim. Routine exploratory commands, harmless navigation, and irrelevant output do not belong in the permanent evidence record. Exact account, environment, tenant, or destructive target identification remains necessary whenever acting on the wrong one would change the consequence.

Workspace and access

Before mutation, inventory the relevant current revision, tracked changes, untracked paths, and active worktrees or equivalent lanes. Treat unexplained state as intentional until its ownership is known. Do not reset, delete, overwrite, stash, or publish it. Isolate new mutation where practical.

The Auditor names access required by the current package: repositories, environments, services, credentials, permissions, test identities, and data. Verify each access path before the work that depends on it. Record capability and status, never secret values. A late access surprise is a package defect; it does not justify abandoning independent work or demanding an unrelated credential.

Target readiness and recovery

For a package that changes or depends on an external target, inspect the affected target's material capabilities before disruption. The relevant baseline may include versions, permissions, extensions, flags, certificates, runtime paths, capacity, and retained recovery assets. Compare only what matters to the proposed change and its recovery.

Recovery must be available and independently proven before the forward mutation. It need not be historically older than the release. It must remain usable under the failure being tested and must not depend on successfully completing the forward change. Proportionate proof may be a documented manual reversal for a reversible low-impact change or an interrupted-migration and restore exercise for consequential state.

If the expected recovery does not restore the business outcome, record the failure even when manual recovery is fast. State the affected capability and duration, how it was restored, and whether data, identity, isolation, or customer state changed.

Correction is separate from retry authority

The Auditor can correct a technical package inside the Owner-approved outcome and risk boundary. That correction does not automatically authorise another state-changing attempt. After failure or uncertainty, inspect what actually ran or committed. Determine whether the original authority was standing, conditional, one-shot, held, expired, or separately Owner-gated. Record the safe next action and who can authorise it.

A corrected low-risk development attempt may proceed when existing authority covers it and actual-state inspection shows that retry is safe. A consumed Production approval, explicit hold, or uncertain destructive result requires the authority appropriate to the next action.

Reuse evidence by claim

Evidence remains useful while the source, configuration, dependencies, identity, environment, and assumptions relevant to its claim remain unchanged. At correction or resumption, the Auditor records which claims retain valid evidence and which require fresh proof. Refresh affected claims and their dependants rather than rerunning an unrelated test programme.

Restoring an expired browser or cloud session does not require another build by itself. Re-establish the identity, authorisation, environment, and candidate needed by the missing proof. Evidence produced through a different identity cannot establish the required actor.

Plan waits before pausing

A planned wait records its ending event or time, responsible role, verified wake mechanism, exact next action, checks requiring fresh evidence, and escalation condition. A pre-authorised CI run, deployment, or observation period resumes when its recorded condition is met. An Owner-decision hold resumes only on that decision; elapsed time is not approval.

On resumption, inspect what actually happened and continue from that state. Do not repeat a mutation merely to recreate the plan's expected starting point. If direct wake-up is unavailable, use a scheduled check suited to the likely duration and cost of the work, then back off after unchanged checks. Fixed intervals are examples, not methodology.

Expected operational flows

When a package creates an ongoing flow, acceptance includes explicit failure and unexplained silence. Define the expected event or cadence, the point at which silence becomes abnormal, the reporting path, and evidence that both an error and a missing result are visible. A flow can fail by producing an error or by producing nothing.

Scope guard

Reuse existing code and tests when they satisfy the package. Fix causes rather than stacking patches around a false premise. Add a dependency, abstraction, framework, service, or test system only when the current outcome needs it. Preserve behaviour outside the requested change and remove replaced paths unless a real compatibility requirement keeps them temporarily.

If the work begins accumulating future-use layers, unrelated cleanup, parallel implementations, or tests for unspecified behaviour, stop the affected branch and return the scope evidence to the Auditor. Passing tests never authorise more scope. A new material requirement names the failure it prevents; otherwise it becomes follow-up work.

Higher-assurance triggers

Add stronger controls when the package can expose credentials or private data, cross an identity or tenant boundary, destroy or migrate state, incur uncontrolled cost, affect many users, change a public contract, operate unattended, or reach Production. These controls may include negative-path tests, multiple identities, target readback, recovery exercises, signed or hashed artefacts, independent peer review, canary rollout, and longer observation.

The control remains tied to its risk. A certificate pin may need an exact digest. A copy change does not. A tenant-authorisation claim may need two identities and a denied path. A static event page does not.

6. A Consequential Project

The Owner says: "A customer administrator can export their organisation's existing records." The sentence is simple; the consequences are not. The Auditor asks who owns tenant identity, whether export starts new processing, which environment proves the first release, what a correct record count means, and who may approve Production.

The Owner confirms the business rule: tenant identity comes from the authenticated server-side session, an administrator receives only their organisation's records, export never starts a new analysis, and the first acceptance gate is Development. Production remains a separate decision.

The Auditor inspects the current interface and discovers that the browser sends a tenant identifier that the service trusts. It rejects a design that merely checks the browser value and specifies a server-bound identity path. It inspects the affected deployment topology and target capabilities, names the stable source and deployment references needed to distinguish candidates, and requires recovery evidence proportionate to the changed state.

The package requires focused source tests, two authenticated test organisations, permitted export, cross-tenant denial, authoritative count reconciliation, private download, no new analysis, and cleanup. Those controls are justified by confidentiality, integrity, and cost. Fleet automation, a general rollout framework, unrelated browser polish, and exhaustive infrastructure simulation remain outside the package.

The Builder reads the package and identifies a contradiction: the existing request contract asks the browser to choose a tenant while the confirmed rule gives that authority to the server. The Auditor corrects the interface decision and requests another readback. Because the correction preserves the recorded business rule and authority, the Auditor verifies that the existing Owner approval still covers it and releases implementation without another Owner decision.

The Builder completes the focused path and returns Builder evidence. The Auditor independently checks the diff, tests, target identity, permitted and denied runtime paths, count, side effects, and cleanup. If a real environment exposes a provider or configuration difference, the Auditor preserves still-valid evidence, corrects the package, and authorises only the next action covered by the recorded attempt authority.

When Development passes, the Owner receives: "The complete export journey and tenant isolation are proven in Development. Production remains unchanged. Owner action: approve or decline a controlled Production canary." The same roles used for the event page now carry stronger evidence because the claim and consequence require it.

7. Sessions and Model Choices

Sessions are replaceable

Long-running agent sessions can lose initiative, return only part of a coherent assignment, shorten into constant back-and-forth, recite process instead of purpose, or speak confidently from stale evidence. Decay follows context consumption and work intensity more than clock time. Asking an agent whether it remains aligned usually produces reassurance, not diagnosis.

The CEO check

The Owner can use an unannounced side conversation as a quick alignment signal:

How is our progress? Give me a CEO-level update: what is this project for, what value does it deliver, what is done, what remains, and how are we doing?

Only the Owner initiates and judges this check. Do not add it to startup instructions, scheduled checks, or agent self-tests. The Owner judges the whole reply. A response beginning at the wrong level is a strong drift signal. A partly inaccurate business account suggests milder misalignment. A concise but false answer still fails when checked against the records. This is a practical heuristic for drift, not a guaranteed diagnostic and not an audit of correctness.

Do not coach a poor answer into a pass. Rotate the degraded role at a safe boundary. Ask it to preserve its owned work, but do not treat a newly written handoff from that session as the sole account of reality. A fresh role reconstructs the project from the pre-existing durable records, preserved workspace, stable evidence, and independently verified state, then performs the normal direct readback. Durable memory makes replacement inexpensive.

Prepare a handoff for a fresh agent joining this project. Identify the Owner-confirmed purpose and current outcome, configured record paths, current package and state, fixed decisions, exclusions, proved evidence level, holds, unresolved contradictions, and next role-owned action. Link the stable evidence rather than copying it. Keep the handoff brief enough for a fresh agent to act.

Choose capability by role

The method is model-neutral. Choose the Auditor for judgement, investigation, architecture, risk, and evidence design. Choose the Builder for reliable execution of a prepared package. A same-stack pair can communicate with less friction. A cross-family pair may contribute different failure patterns but can require an external notification bridge.

For complex projects, my current Codex configuration uses SOL with xhigh reasoning as Auditor and SOL with high reasoning as Builder. I use Astra with max reasoning for an optional fresh whole-project peer pass at selected gates. This is a dated example, not a requirement. Other models and stacks can fill the same roles.

Model-turn speed is only part of delivery time. CI, tests, deployment, external systems, audit, and Owner decisions often dominate. In internal operating data from projects I supervised, covering roughly 60 billion tokens of agent work, Fast mode was associated with about an 11% improvement in total project completion time. Treat that as an observation from one environment. Optimise for total cost and elapsed time per independently accepted outcome, including clarification and rework.

Additional agents are lanes, not new authorities

An additional agent has a named purpose, bounded read and write scope, stopping condition, durable output, and attributable evidence. A second implementation writer uses a non-overlapping worktree or equivalent isolated lane. A peer reviewer remains read-only and reports to the primary Auditor. The primary Auditor investigates and tries to refute its observations before recording anything as a finding.

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

8. Optional Tool Setup

You do not need to configure hooks or persistent Goals before trying the method. Start through the Auditor prompt. Use the options below when the project or tool benefits from stronger autonomy, direct task communication, persistent role instructions, or unattended resumption.

The Auditor records the selected methodology URL in its record. The Builder records the same URL in the Owner/Builder record. Use the canonical URL for the current method or the frozen snapshot URL selected by the project. Substitute that value for [METHOD_URL] in every later role prompt and Goal so a pinned project does not silently drift to a newer method.

Starting the Builder

The Auditor sends this only after it has prepared the package and the Owner has authorised or performed agent creation:

Your role is Builder. Read and follow the complete methodology at [METHOD_URL]. Discover the configured operating records. If this is setup, create or update only the Owner/Builder record from Owner-confirmed direction, send SETUP_RECORD_READY to the Auditor, and do not change implementation. Otherwise read the identified Auditor package revision, send a direct readback, and wait for UNDERSTANDING_CONFIRMED for that revision before building.

Persistent Goals in Codex

A Goal preserves one role's objective. It is not a polling mechanism. Start a Goal only while that role has meaningful work. End the pass at a role-owned handoff; do not make completion depend on another agent responding.

/goal Complete the current authorised Builder package using the methodology at [METHOD_URL]. Work autonomously to CHECKPOINT_READY, DEPLOYMENT_READY_FOR_AUDIT, BLOCKED, or P1_DECISION_NEEDED. Follow the confirmed package revision and proportional proof. Update only the Builder-owned record and implementation, send the matching doorbell, and end without waiting for another actor.

/goal Complete the current Auditor-owned pass using the methodology at [METHOD_URL]. Assess project state, prepare one identified implementation-ready package revision, advance its understanding gate through the next Auditor-owned action, or audit one identified stable Builder handoff. Apply assurance proportional to the accepted claim and record one actionable disposition in the Auditor record. If progress requires a readback or Owner decision, record the pending question, send the request, and end this pass; continue when the response arrives. Otherwise send the matching doorbell with the next pass or hold, and end without waiting for another actor.

/goal pause holds an unfinished pass. /goal resume continues it. /goal edit changes its objective or stopping condition. /goal clear removes a completed or abandoned objective. Use the current official OpenAI long-running work documentation for product behaviour.

Test direct wake-up in the actual tool before relying on it. Exchange one channel test, let the Builder send a checkpoint while the Auditor is idle, and verify whether the Auditor resumes without Owner relay. If it does not, record that limitation and use a scheduled same-task check suited to the expected work duration.

# Builder
Read the complete methodology at [METHOD_URL].
Write only implementation and the Builder-controlled operating record.
During setup, you may establish that record from Owner-confirmed direction; do not change implementation.
Before building, read back the Auditor package and wait for UNDERSTANDING_CONFIRMED.
Complete one coherent package, apply the specified proportional proof, report limitations honestly, send the terminal doorbell, and stop.

# Auditor
Read the complete methodology at [METHOD_URL].
Write only the Auditor operating record; never edit implementation.
Assess project state, confirm Owner meaning, inspect the relevant system, and prepare the minimum sufficient package.
Choose assurance proportional to purpose, consequence, reversibility, and claim.
Confirm Builder understanding, independently audit stable evidence, issue one actionable disposition, and escalate only decisions that belong to the Owner.

Read the configured operating record once. If a new role-owned package or checkpoint exists, complete that bounded pass and send its doorbell. If nothing materially changed, do not create work and increase the next check interval. Never infer authority from elapsed time.

#!/bin/sh
INPUT=$(cat)

if printf '%s' "$INPUT" | grep -Eq '"stop_hook_active"[[:space:]]*:[[:space:]]*true'; then
  exit 0
fi

cat <<'JSON'
{"decision":"block","reason":"Before stopping, complete one final checkpoint pass for your current role. Update only your owned durable record. If the role-owned work is complete, send its doorbell or explicit hold, then stop. Do not wait for another actor."}
JSON

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "/bin/sh \"${CLAUDE_PROJECT_DIR}/.agent-hooks/checkpoint-pass.sh\"",
        "timeout": 30
      }]
    }]
  }
}

{
  "hooks": {
    "Stop": [{
      "hooks": [{
        "type": "command",
        "command": "/bin/sh \"$(git rev-parse --show-toplevel)/.agent-hooks/checkpoint-pass.sh\"",
        "timeout": 30
      }]
    }]
  }
}

9. Reference

Common failure patterns

• One agent builds and accepts its own work.
• The starting agent wrote the existing implementation and is appointed as its independent Auditor.
• A new Builder cannot create its record because setup and implementation gates are confused.
• The Owner becomes the routine message bus between Builder and Auditor.
• Messages become the working record and the durable files become stale.
• Several files claim to be the current package or old permission remains apparently active.
• The Builder silently decides business meaning, security, data ownership, failure handling, rollout, rollback, cost, or evidence.
• The Auditor discovers the design through repeated Builder correction rounds.
• The Auditor expands the acceptance line with theoretical hardening after implementation begins.
• A small reversible project receives production-grade ceremony with no named risk.
• A consequential project omits a control because proportionality is mistaken for convenience.
• A moving branch or live URL is treated as stable proof of what was previously reviewed.
• Hashes or signatures are required without an integrity, provenance, or candidate-identity claim.
• Tests pass, but the actual user outcome or intended environment is never exercised.
• A healthy target is disrupted before its relevant prerequisites are inspected.
• Recovery depends on the forward change succeeding.
• A corrected package is treated as permission to repeat a consumed or uncertain action.
• The full evidence programme is rerun although only one claim changed.
• A planned wait has no ending condition, wake mechanism, or safe resumption action.
• A long-running session recites process confidently after it has lost the business purpose.
• An additional agent works invisibly without bounded ownership or attributable evidence.

Version history

This methodology is versioned like software. Published versions receive a dated badge and frozen snapshot. Organisations can pin the version they adopted.

• 2026-09-05 — current. Simplifies entry through one Auditor prompt, resolves new-project setup and independence, introduces proportional assurance, preserves delivery constraints and product direction across packages, restores verified optional coordination setup, and consolidates repeated instructions. View snapshot →
• 2026-09-04.1 — added the Auditor bootstrap, project-state intake, current-entry discipline, target readiness, rollback independence, retry authority, evidence reuse, and resumable waits. View snapshot →
• 2026-09-04 — added the Owner decision interview, bounded whole-project peer review, vendor-neutral Goals, current SOL/SOL/Astra configuration, and end-to-end delivery measurements. View snapshot →
• 2026-08-31.2 — corrected Quick Start clipboard behaviour. View snapshot →
• 2026-08-31.1 — integrated minimum-sufficient-change boundaries and shortened duplicated Goal language. View snapshot →
• 2026-08-31 — added the scope-growth tripwire, Builder execution limits, and touched-file evidence. View snapshot →
• 2026-08-29 — replaced mandatory acceptance fingerprints with revisions, moved readback to direct messages, and added session rotation and the Owner-operated alignment check. View snapshot →
• 2026-08-19.1 — froze the business acceptance line, required early representative-environment proof, and separated proportional delivery proof from deferred hardening. View snapshot →
• 2026-08-19 — defined mechanically open choices, workspace preservation, prepared Owner proposals, execution-instrument proof, flow silence detection, and explicit additional-agent lanes. View snapshot →
• 2026-07-24 — made access a verified precondition and kept secrets out of records. View snapshot →
• 2026-07-22.1 — made record discovery and role prompts independent of filenames. View snapshot →
• 2026-07-22 — added critical-path execution, correction batching, runtime proof, and bounded role Goals. View snapshot →
• 2026-07-11.1 — added role-specific model-performance considerations. View snapshot →
• 2026-07-11 — added Owner-confirmed rules, adversarial package design, Builder teach-back, and the shared-understanding gate. View snapshot →
• 2026-07-10 — defined two-file operating memory, messages as doorbells, selective Goal activation, and portable model-pair guidance. View snapshot →
• 2026-06-27 — added the Owner briefing and version history. View snapshot →
• 2026-05-13 — added the speak-to-the-Owner rule and removed recurring cadence as the default. View snapshot →
• 2026-04-17 — added cross-family pairing, model placement, and reusable handoff. View snapshot →
• 2026-04-09 — introduced loops and file-change triggers. View snapshot →
• 2026-03-31 — first published version: two roles, two files, evidence-gated work. View snapshot →

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

Credits

The core insight is simple: structure replaces supervision. Start with one useful outcome. Keep the Owner in control of meaning and authority. Let the Auditor prepare and challenge the work. Let the Builder execute one coherent package. Increase assurance only when the accepted claim and its consequences require it.

Dr. Mikko S. Niemelä — 2026

Last updated: September 5, 2026