How I build · The operating model

The one idea. The operating model is a small set of standing documents, each with one job, an update trigger, and a rule for what happens when it drifts. The process does not live in anyone's head: a session reads the documents, does one phase, and writes back to them, and a fresh session can pick up from the documents alone.

Reading path. Entry from How I build · The delivery method, which holds the gates: session gates, the phase spec, review by role, sign-off. This page is the documents those gates read and write. The product artefacts (PRD, personas, metrics, the eval framework, the risk registers) are on The artefact set, by the decision each one makes; the rules and hooks that hold the model to all of this are on The harness. Everything here is from one build: a sovereign OSINT platform built for a defence innovation challenge. The second product, MyWarren, runs the same SOP; it is not re-described here.

1 · Everything a project produces

One table, by stage of the work. Owner role is the role that writes the document; the human owner signs every phase whatever the row says. The roles are sub-agents with one job each: a spec drafter, a code reviewer, a domain expert (who also owns the backlog), and a test lead (who owns the test framework, never the per-module tests). "The session" is the orchestrating session that runs the phase.

Scale of what these rows add up to: 45 phase specs, 29 phase sign-off tags and 1,711 tests passing (2026-08-28).

2 · The process map

The ways-of-working map states the session as six phases, run once per session, for one phase of the release per session. The loop closes by arming the next one.

1 · Sync and orient. The first action of every session is a fetch from the remote, before any file is read. If the local copy is behind, it is brought level and the progress log is read again. Then the progress log and the release's master spec are each read once. A status question is never answered from a tree that has not been fetched: "where are we" feels read-only, and it is the question that once reported the build behind where it was.

2 · Scope and gate. The one phase for this session is confirmed with the owner, with its boundaries and open decisions. Then the standing gates, in order (The delivery method §1). The scope-shape gate decides whether the session stops at a written spec or carries on into the build, by the work's risk shape: work that extends existing plumbing with no new model is scoped and built in one pass; work with a new model to validate or an open external question is scoped only, and stops for review.

3 · Spec first. The phase spec is written before any code (The delivery method §2). Non-functional targets are declared as numbers to be measured: throughput, latency at P50, P95 and maximum, scale ceiling, recovery, index coverage. If the scope moves, the spec says so.

4 · Build and verify. The increment is exercised against the running stack with re-runnable scripts, and each target is measured at a stated scale. Every number is tagged measured or projected. The code review is written to its own file before the reviewer returns, and the session fills a resolution per finding: fixed, deliberately not taken with the reason, or deferred. A review that lives only in a sub-agent's reply is gone at the next compaction, and what is lost is which findings were not taken, and why.

5 · Demo and sign-off. The phase's journeys are added to the runbook before the demo runs. A serving check confirms that the running server is the committed code. The demo runs on real data, and the evidence is captured. Until the owner approves, the phase is recorded as "built, awaiting sign-off". There is no self-sign-off.

6 · Close out and hand off. At a release boundary, the as-built diagrams are updated in place. Any phase that changed what a user sees updates its release's user guide in the same session; if there is no room, the gap is recorded as debt, never left to drift. Then a commit that says what changed and why, a tag per phase, a push, a roll-off of the progress log if it is over its cap, and the session block with the next pick. Then the session ends: a finished phase's context is pure cost from that point.

The documents carry the state, not the session. What each phase reads and writes:

At release level. One master spec per release; phase specs drawn from it; increment specs for work that falls between releases. At each release sign-off the living as-built diagrams are updated in place, with git history as their record, while that release's design snapshots are frozen.

3 · Ways of working

The map states the working agreement in three parts.

Principles and engineering practices. Spec before implementation. NFR targets as numbers, measured, not asserted. Every claim keeps development scale and production scale apart. Verification against the live stack, with scripts that can be run again without side effects. Each code review logged to a file with its resolutions. A finding that is real but not this phase's work goes to the backlog with enough context to become a spec, never left in the transcript, because a transcript is gone at the next compaction. And a list of what efficiency never cuts: the spec, the unit suite, live verification, the logged reviews and the hand-off records stay whatever the budget says. Cut the cost of looking, not the looking itself.

Alongside these, a sensitivity rule: programme and customer names never reach a commit message, tag, README, CI file or the code.

Guardrails, each learned once. The map marks some steps as hard guardrails, each with the incident that produced it. One example, from a single scoping session that produced two confident, specific and wrong statements. It reported a defect after searching for the implementation it expected; the code that does the job had been built earlier under other names. And it measured a figure of 45.7 % with a pattern match; sampling the matches showed the pattern was detecting something else, and the real figure was 0.4 %. The rules that came out of it: a search that comes back empty is evidence about the search, not about the code; any count that will be quoted is sampled in the same session before it is stated; and a correction is made in the document that carried the wrong number, not only in the conversation.

The harness. The rules are loaded as instructions every session, and the hooks that back them report; they never block. The map gives the reason: a rule written as prose is followed or it is not, so a rule that must not be skipped becomes a hook; but each thing a hook might block has a legitimate case, and a hook that blocked it would be a worse trap than the one it guards. The mechanism is on The harness.

When the session runs remotely. The six phases run the same way from a cloud session with no machine attached. The map states only the difference:

• Sync matters more. Several remote sessions can push between two desktop sessions, so a stale local view is the normal case to guard against.
• "The owner is away" is the default. A check that needs only the database and cache runs in the container; a check that needs the full stack is recorded as built, awaiting live verification, and goes on the desktop queue (§4). It is never routed around.
• Evidence is captured, not watched. A headless-browser render and a screenshot stand in for someone at the screen; sign-off is the owner reviewing that evidence afterwards. Any visual edited in the session is rendered and read by a sub-agent that returns a short verdict, before it is called done.
• Two pushes before the session ends, one to the trunk and one to the session branch, then a check that the local and remote copies are level. Work pushed only to a session branch is invisible to every later session, and a reclaimed container loses it with no error at all; this happened once, on 2026-08-21.

4 · Backlog sequencing

Three layers, one job each. Nothing is held in two places.

The backlog says what each candidate item is and why it matters. The phase spec is the contract once an item is specified. Neither says in what order, and what blocks what, and answering that had meant cross-referencing many files by hand each time it was asked. The sequencing page is that missing view: every open item and every spec not yet signed off, in build order with its dependencies explicit. It links to both sides and adds only sequence. Closed work leaves the page for the sign-off log and the progress log.

The page orders work by what is left to do, which is the scope-shape gate from §2 applied to the whole backlog: close-outs that need only a sign-off or a demo; items specified and waiting for a decision to build; eval-heavy items that stay scope-only until an open question is answered; and deferred items, each with the prerequisite that must hold before it is reconsidered.

Kept current by checks that report, never rewrite. One check is meant to fire when the backlog or a spec's status line is edited; a scheduled check runs daily as a backstop for edits the first cannot see. Both report; neither rewrites the page. The page says why a schedule alone is not enough: two earlier documents drifted because their trigger was a calendar or a release boundary, while the thing they protected grew session by session.

The drift, told as it happened. On 2026-08-25 one flagged item led to a re-audit of every item the page tracked. 17 of 32 were misreported: closed items shown open, open items shown closed, and part-done items flattened into "done" or "not started". The correction itself took two rounds. The first, by four parallel sub-agents, still over-claimed closure on five items, because it read the same weak signals that had caused the drift. The second went to tags, commit authorship and each spec's own sign-off text, and reversed them.

The RCA names five root causes:

1. The spec's status header was treated as authoritative, though it is the field least likely to be kept current.
2. Closing a phase does not have to touch its own spec, so a spec can sit stale while the capability is live.
3. Evidence was not ranked, so prose in the progress log, a claim, was taken as a record.
4. The correction inherited the failure it was correcting: the audit was told to check everything, and not told which evidence to trust.
5. No check compared a spec's header with its own body; the existing check compared files with the page.

And four preventions: a check that compares each spec's header with its sign-off section; the evidence ranking written down as a standing rule; that ranking named in any audit handed to sub-agents; and the header updated in the same commit that closes the phase.

What counts as closed. The ranking the RCA wrote down:

The same rule reappears in a later design document (2026-09-20): where a status table and a git tag disagree, the tag is evidence and the table is a claim.

Parked work does not roll off. The progress log keeps ten blocks and moves the rest to its archive. An item parked in a session block would slide into the archive ten sessions later, acted on or not, and remote sessions are short, so ten pass quickly. The desktop queue exists for that reason: it has no roll-off. A session that hits a desktop-only wall appends an item, newest first, with the exact commands to run, why it needs the desktop, and what done looks like. A desktop session that clears one moves it to closed with the date and the measured result, and never deletes it, because the measured result is usually what a later session needs.

5 · The operating documents

Demo runbook. The standing script for every live demo and every sign-off demo; a sign-off demo is never run from ad-hoc commands. It opens with a pre-flight check that the running server is the committed code (exit 0 current, exit 1 stale, naming the process and the restart command), added after a server left running served old code while every page looked current. It then says where each command runs and where each journey's result appears, before the numbered journeys. Every page footer carries the build, start time and process id, so a screenshot kept as evidence dates itself. New journeys go at the end of the last file, with one line in the index. It grew to 57 journeys and was split on 2026-09-19 into seven files near 35 KB each.

User guides. One per release, four in all, in plain language: what each part does, how an analyst uses it and why, with worked examples. They are separate from the specs and the runbook. Later guides mark each section built, signed off or planned, and close with what the release does not yet do.

Sign-off log. The index of everything built but not closed: what is outstanding on each, the items that are scope-only, documentation flags, and a window of recently closed items. The spec stays the authority; the log is reconciled against each spec's own sign-off section, not its header. The sign-off step itself is on The delivery method §4, and a skeleton of the log is a download on The artefact set.

Retrospective. An index of incidents where state or process went wrong, newest first, in a fixed template: scenario, risk, root cause, fix, prevention, source. Where an RCA exists, the entry is a summary and a pointer, not a copy.

6 · AI-assisted development

The model builds; the human specifies, reviews and signs (The delivery method). Three things are specific to how the operating documents work with a model doing the building.

Roles are sub-agents, and their output goes to a file. The four roles in §1 run as sub-agents. The code reviewer writes its review to a file before it returns, because a sub-agent's context dies when it returns. The standing delegation rule: large payload, small answer (a visual check, a repository-wide search, reading a long log to answer one question) goes to a sub-agent; judgement that needs the main session's context does not.

The model is chosen at a gate, and the instruction matters more. The model-choice gate's test: if being wrong would be found later by someone reading a document, rather than by a failing test, it is work for the stronger model. The drift re-audit in §4 is the evidence that this is not the whole answer. Both rounds ran on the same model tier. Between them, the instruction changed, from "audit every item" to "trust tags and commit authorship, not headers", and the outcome changed with it. The RCA's conclusion: the higher-leverage fix was the instruction, and it applies whichever model runs the next audit.

The agent runtime, mapped against a reference workflow. For the platform's own agents, a design document walks a fourteen-stage reference workflow for AI agents, from user request to production infrastructure, and rules on each stage. The point of the document is a distinction most comparisons blur: a stage that does not apply is marked not applicable by decision (a recorded decision forbids it), by construction (some other property means it cannot arise), or not built, which is the only one of the three that is a gap. By its block headings: six stages apply, seven apply in part, one (multi-agent) mostly does not.

Most of the not-applicable rulings trace to three recorded decisions:

• The coordinator is code. No model chooses which agent runs, which tool runs, or whether anything is written. The model decides three bounded things: how a claim breaks into sub-claims, whether the evidence it was given is enough, and, for the critic, whether a citation supports its sentence.
• Tools are read-only, and there are three. No write tool and no network tool; a contract test pins the set.
• A run is one claim, not a conversation. Nothing carries over from one run to the next.

Human review is therefore inverted. There is no approval step before a tool runs, because no tool can change anything. The critic agent flags; it does not revise; a human holds the decision.

7 · Stated honestly

• The process map and the ways of working exist as HTML visuals, not text documents. A reader of the repository finds them only through the visuals folder.
• The sequencing page was wrong on 17 of 32 items until the re-audit. The fix is a rule and a check, not a guarantee.
• The page that exists to stop drift carries a contradiction of its own. Its status panel says both checks are live; its own maintenance table lists the event-triggered check as specified and not yet wired. Only the daily backstop is confirmed as running there.
• The RCA's first prevention was not re-run against the corrected state in the session that wrote it; it lists that as the next session's first item. This page does not claim it was done.
• The hooks report; they do not block. That is the design, and it means a warning can be ignored.
• One human holds the last seat at every gate, as on The delivery method.

Measured figures on this page

What this page does not claim

• No count of code reviews, hooks or visuals. Each has two or three sources that disagree; none is quoted until they are reconciled.
• No count of desktop-queue items or RCAs.
• No claim that the event-triggered sequencing check runs: see §7.
• No claim that the documents are complete or current today. Each describes itself as living, and §4 is the record of one that was not.
• None of the documents is reproduced. They are described and their structure re-typed; their text, file names and screenshots stay private.