Building with AI Agents

Methodology version: 2026-10-09 — if you use this method as a standard in your organisation, pin this edition. View dated snapshot · Version history.

1. The Method

A capable Builder can investigate options, design the implementation and build it. It should not also be the independent judge of whether its own work is acceptable. The method separates implementation from acceptance, keeps the human in control of purpose and authority, and makes claims answerable with evidence. Both agents think: the Builder leads implementation; the Auditor challenges the approach and checks whether the agreed result has actually been delivered.

The project keeps two durable operating records. The Owner/Builder record contains Owner-confirmed direction and the Builder's implementation approach, current state, evidence, and next action. The Auditor record contains the work package: an outcome contract stating what must be delivered, the necessary boundaries and how acceptance will be decided. It also contains review dispositions and acceptance. The package need not prescribe the internal design. 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.

The Auditor identifies and records the methodology used by the project. An explicitly pinned edition remains in force until the Owner approves adopting a replacement; reading a newer guide does not silently change an active contract. 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: agreed guide reference 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: approved environments, actions, data access, resource or cost limits, exclusions, and actions still reserved for the Owner.

# 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.
Implementation approach: the Builder's chosen route and material trade-offs; update when they change.
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 agreed guide reference or pinned snapshot 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.
Required boundaries: constraints the implementation must satisfy and why each is necessary.
Implementation authority: design and routine correction choices entrusted to the Builder; exceptions and escalation limits.
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: evidenced defects and the result needed; prescribe a mechanism only when necessary.
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

In this illustrative 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, and proposes a static page using the site's existing styles. There is no need for a new application framework. The Auditor resolves one ambiguity about the venue entrance, records shared understanding, and releases implementation. The Builder chooses the internal markup and layout, fixes problems found during testing, and supplies a stable local preview plus responsive and link checks. Those routine choices need no separate approval. The Auditor compares the visible page with the confirmed details and either accepts it or returns the evidenced defects for correction.

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.

A pending Owner decision holds only the work that depends on it. The Auditor continues authorised investigation, preparation, review, and acceptance. The Builder continues independent work already covered by the package. Do not dispatch incomplete work merely to keep the Builder occupied, but do not stop the whole project because one dependency is waiting.

Prepare before building

The Auditor inspects the relevant source, tests, configuration, interfaces, dependencies, and intended environment to establish the real constraints and acceptance criteria. It resolves material uncertainty about the outcome and authority before dispatch, rather than sending an ambiguous assignment to the Builder.

Before dependent work begins, the Auditor verifies that the assigned roles can use the required repositories, tools, environments, and evidence paths. It prepares supported permissions inside the approved boundary and presents unavoidable personal login, consent, or Owner-only steps together with a concrete recommendation. Routine technical setup is Auditor preparation, not repeated technical homework for the Owner.

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.

The minimum sufficient contract identifies:

• 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 fixes required behaviour, public contracts, data ownership, security boundaries, recovery obligations, resource limits and acceptance. The Builder inspects the implementation, chooses the technical approach and records material design choices in its own record. It may choose a different internal structure or reuse a better existing component without asking permission for each choice, provided the contract still holds.

The Auditor may require a particular mechanism when a concrete customer, security, data-protection or operational requirement makes it necessary. It states that reason. Its preferred implementation is otherwise a proposal, not an additional acceptance condition. A Builder choice that would change the agreed contract or a protected boundary returns before dependent action; routine design within the contract does not.

Both roles investigate. The Builder must understand what it is changing, not merely follow instructions. The Auditor independently checks the constraints and claims that matter to acceptance, rather than relying on the Builder's account alone.

The package also records the Owner-approved outcome, environments, permitted action classes, data access, resource or cost limits, and exclusions. That authority continues through ordinary corrections, handoffs, compaction, and replacement sessions until the work completes, the Owner changes it, or a recorded time, attempt, or resource limit is reached. A replacement role verifies its identity, access, and current package before continuing. Unchanged work does not require repeated approval. Technical access alone grants no business authority, and missing or expired access does not erase authority already granted; restore and verify the access before dependent work continues.

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.

Challenge unnecessary work

The Builder should question the plan as well as implement it. At the initial readback, a useful major handoff, or when prerequisites and preparation keep growing, ask: What can we remove, combine, reuse or defer, and what would we lose? Bring concrete alternatives: an existing tool instead of a new helper, one complete workflow instead of several tiny assignments, or a focused check instead of repeating unchanged evidence.

The Auditor answers each material proposal with adoption, rejection or deferral and a brief reason in the existing record. It should be willing to change its own plan. A shorter plan that omits the promised outcome or necessary protection is not an improvement. Keep the challenge bounded and useful; do not turn it into a recurring meeting, another approval stage or an interruption to active recovery.

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, required boundaries, acceptance, proposed approach and material gaps in its own words. It challenges unnecessary prescriptions and names any decision outside its authority. This raw readback stays in the direct channel.
3. The Auditor corrects the contract when the readback exposes a gap, checks necessary constraints and considers the Builder's alternatives. Business ambiguity returns to the Owner; routine implementation choices remain with the Builder.
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 contract revision and releases implementation. This confirms shared understanding and authority, not prior approval of every internal design choice.

The Builder may create its operating record during setup, but it does not modify implementation before this gate. A material contract change requires renewed Builder readback. In-contract design choices and corrections do not each need another readback or GO. 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

Assign a complete useful workflow, not a new task for every file, test or small correction. The Builder owns its implementation approach and works autonomously to the named handoff. It reuses suitable code, tools and tests, fixes the root cause, preserves behaviour outside the outcome, and avoids future-use abstractions. Ordinary test failures and routine design choices do not end the pass. A material contradiction stops only the affected dependency; independent authorised work may continue.

Inside a verified development boundary, the Builder may diagnose and correct implementation defects, rerun relevant tests, and repeat permitted development deployments without returning after every defect. It remains inside the confirmed contract. A change returns to the Auditor when it would alter the agreed outcome, customer behaviour, public interface, shared-system ownership, data or security boundary, scope, material cost, recovery obligation, acceptance or authority. The Auditor resolves what remains inside its mandate and returns Owner decisions to the Owner. Internal implementation choices do not become approval requests merely because they involve design. Independent Auditor acceptance still occurs at the completed checkpoint.

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, necessary constraints and material risks. It checks source and actual behaviour, tries to refute candidate findings before reporting them, and looks for a common cause instead of returning symptom-sized corrections. It batches ordinary findings into one coherent correction pass, stating the evidence and required result. The Builder normally chooses the fix. A prescribed fix needs a reason tied to the contract or risk, not the Auditor's coding preference.

Independent review remains rigorous. The Auditor must not accept a result just because the Builder is capable or confident. Equally, it must not reject a correct result because the implementation differs from its original suggestion. 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. Review ready work promptly: a fast Builder gains little from waiting behind unnecessary preparation. A checkpoint submission does not cancel explicitly authorised independent work or the bounded source continuation described below. The Builder acknowledges the disposition before acting. Send messages when they release work, request a decision, return a result or report a material change. Avoid unchanged status notices and acknowledgements of acknowledgements. 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. Reuse existing approved settings where possible, and verify the actual role's execution path rather than assuming that available source code or a documented capability proves usable access.

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, tools, deployment methods, tests and accepted evidence when they satisfy the contract. Before adding a dependency, abstraction, framework, service or test system, explain why the existing route cannot do the job and what would fail without the addition. "Safer" or "more robust" is not a sufficient explanation on its own. Fix causes rather than stacking patches around a false premise. Preserve behaviour outside the requested change and remove replaced paths unless a real compatibility requirement keeps them temporarily.

Both roles are responsible for keeping work proportionate. If future-use layers, unrelated cleanup, duplicate implementations or checks for unspecified behaviour accumulate, challenge them before doing more. The Auditor removes unnecessary requirements within its authority and the Builder simplifies the implementation within its contract. Passing tests never authorise more scope. A genuine new requirement names the outcome or failure that makes it necessary and follows the appropriate decision path; it is not silently inserted into acceptance.

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

In this second illustrative 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. The contract must therefore require the service to derive and enforce tenant identity from the authenticated session, not trust a browser-supplied tenant. That is a necessary security boundary, not a preference about internal code structure. The Auditor also checks the deployment constraints and requires evidence sufficient to identify and recover the candidate.

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 inspects the existing code and proposes reusing the authenticated-session helper and export formatter rather than building a new export framework. It identifies the request-contract change needed to remove the browser's authority over tenant selection. The Auditor checks that this fits the approved rule, records the necessary interface boundary and confirms shared understanding without another Owner decision. The Builder chooses the internal structure, implements the complete export path and corrects defects found by its tests. Those implementation choices do not each return for approval.

The Builder returns a stable checkpoint and evidence. The Auditor independently checks the diff, tests, target identity, permitted and denied runtime paths, count, side effects, and cleanup. It does not require its preferred implementation when the Builder's approach satisfies the contract. An in-contract defect returns for Builder correction; a newly exposed material boundary is resolved before dependent action. Any further runtime attempt must remain within the recorded authority, and still-valid evidence is retained.

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, required boundaries, implementation approach, 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 about the user outcome, investigation, necessary constraints, evidence and independent review. Choose the Builder for implementation judgement as well as reliable execution: understanding unfamiliar code, finding a simpler route, testing and correcting the whole workflow. 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.

In my own work, I have used Fable and Astra successfully as Auditors. I have used Opus, SOL, Terra, Luna, and DeepSeek 4.1 successfully as Builders. Each has worked well in the named role with this methodology. This is a record of models I have tried, not a requirement, a ranking, or a claim that other models cannot work.

In my October 2026 work at Cyber Intelligence House, I found that an Opus 5.5 Builder could be better placed to identify unnecessary steps and simpler implementation paths than an Auditor that had prepared a detailed plan. I shifted implementation leadership to the Builder while keeping the outcome, necessary constraints and independent QA with the Auditor. This is operating experience, not a controlled comparison or a claim that one model is always better.

Model names and relative performance will change. Give implementation discretion to a Builder qualified for the work rather than assuming that it is the less capable thinker. If it cannot work reliably within the contract, narrow the assignment or use a better-qualified Builder; do not compensate with endless instructions and correction rounds. The durable separation is between making the implementation and independently accepting its result.

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.

Both roles record the same selected methodology reference. An existing pinned edition stays authoritative unless the Owner approves a change. The following prompts already name this dated edition; the agents check it against the project record and ask if they cannot access the selected text or reconcile a conflict. The reader does not need to replace a placeholder. Record and adopt a new edition at a safe handoff without restarting unaffected work.

Starting the Builder

Use the optional Builder prompt in Start Here only after the Auditor asks for a separate Builder and the Owner has authorised or performed agent creation. The Builder reads the current outcome contract and recorded methodology before acting.

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. Submitting a checkpoint completes that reviewable part; it does not cancel permission for an eligible next part that is already explicitly authorised. The Builder may continue under the recorded source-continuation rules, preserving the submitted checkpoint and giving returned corrections priority. Otherwise end the pass at the handoff, without waiting for another agent to respond. Explicit holds, safety stops and the agreed unfinished-work limit still apply.

/goal Read the complete methodology at https://mikkosniemela.com/build-with-agents-2026-10-09 and the current project records; respect any explicitly pinned methodology. If the required text is unavailable or conflicts remain unresolved, ask before proceeding. Complete the current authorised Builder assignment. Lead implementation and routine design within the confirmed outcome contract, challenge unnecessary work, and provide proportionate evidence. Return material boundary changes before acting. Update only the Builder-owned record and implementation, and send the matching checkpoint or blocker doorbell. Continue only with an explicitly pre-authorised, eligible next part under the recorded source-continuation rules: preserve submitted checkpoints, prioritise returned corrections, and respect holds, safety stops and the unfinished-work limit. Otherwise end this pass without waiting for another actor. Construction authority never grants release authority.

/goal Read the complete methodology at https://mikkosniemela.com/build-with-agents-2026-10-09 and the current project records; respect any explicitly pinned methodology. If the required text is unavailable or conflicts remain unresolved, ask before proceeding. Complete the current Auditor-owned pass: prepare an outcome contract with necessary boundaries and acceptance criteria, advance shared understanding, or independently review a stable Builder checkpoint. Leave in-contract implementation choices to the Builder and assess its simplification proposals. Apply proportionate assurance and record one actionable disposition in the Auditor record. If a readback or Owner decision is needed, record and send the request, then end this pass. Otherwise send the next authorised action or explicit hold 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 https://mikkosniemela.com/build-with-agents-2026-10-09 and the project records. Respect any explicitly pinned methodology; ask if required text is unavailable or conflicts remain.
Write only implementation and the Builder-controlled operating record.
During setup, establish that record from Owner-confirmed direction without changing implementation.
Before the first implementation pass, read back the outcome contract and wait for UNDERSTANDING_CONFIRMED.
Lead implementation investigation, design, tests and corrections within the agreed boundaries. Record material choices and challenge unnecessary work.
Return material changes to the outcome, authority or protected boundaries before acting. Never accept your own work.
Deliver a stable checkpoint with proportionate evidence and honest limitations. Send its doorbell, then continue only with an explicitly pre-authorised, eligible next part under the recorded source-continuation rules. Preserve submitted checkpoints, prioritise returned corrections, and respect holds, safety stops and the unfinished-work limit. Otherwise stop. Construction authority never grants release authority.

# Auditor
Read the complete methodology at https://mikkosniemela.com/build-with-agents-2026-10-09 and the project records. Respect any explicitly pinned methodology; ask if required text is unavailable or conflicts remain.
Write only the Auditor operating record; never edit implementation.
Confirm Owner meaning and authority, investigate material constraints, and prepare a clear outcome contract and acceptance criteria.
Leave implementation leadership to the Builder. Require a particular mechanism only for a concrete necessary requirement; assess and answer simplification proposals.
Choose proportionate evidence, confirm shared understanding, review stable results independently and promptly, and issue one actionable disposition.
Keep approved delivery moving; escalate only decisions outside your authority. Do not turn routine corrections into new approval stages.

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 changes business meaning, authority, data ownership, security, recovery obligations, cost limits, or acceptance.
• Material requirements remain unresolved and are discovered through repeated Builder correction rounds.
• The Auditor treats its preferred implementation as mandatory without a concrete requirement.
• The Builder follows an unnecessarily complex plan without challenging it.
• A fast Builder accumulates unfinished work while ready reviews or customer delivery wait.
• 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. A revised role allocation takes effect only when the project adopts it; an existing edition does not change underneath an active crew.

• 2026-10-09 — current. Gives the Builder implementation leadership within an outcome contract, focuses the Auditor on necessary constraints and independent acceptance, adds explicit challenges to unnecessary work, and permits bounded, pre-authorised source continuation during review. Aligns role prompts and examples with that division of responsibility. View snapshot →
• 2026-09-16 — Adds an optional ready-to-copy Builder entry, carries approved project authority through routine execution, keeps bounded Development corrections with the Builder, continues independent work around pending decisions, and records the Auditor and Builder models used successfully with the method. View snapshot →
• 2026-09-05 — simplified entry through one Auditor prompt, resolved new-project setup and independence, introduced proportional assurance, preserved delivery constraints and product direction across packages, restored verified optional coordination setup, and consolidated 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

Start with one useful outcome. Keep the Owner in control of meaning and authority. Let the Builder lead implementation within a clear contract. Let the Auditor challenge unnecessary work and independently verify the result. Both roles should shorten the path to useful delivery without weakening the outcome or its necessary protection.

Dr. Mikko S. Niemelä — 2026

Last updated: October 9, 2026