>Z_ operating manual
two AIs, one boss, no relay
the system that runs this site, and every build behind it. the boss decides. one AI writes the brief, the other builds. nobody copies text between them.
11 runs · 98 findings · 5 false validations · 1 folder
> cat loop.md
// two AIs, one boss, no relay
the old loop had the boss copying text between two assistants. that bottleneck is gone. both read and write the same folder, and the boss says one word.
boss
decides only. owns priorities and every gate. one word to advance.
architect
writes the brief, reads the handoff, runs QA. never builds.
builder
builds, writes the handoff. talks to no one.
the night rule
a night run is text, labels, docs, css, dead code. new calc logic, auth, anything that can lock a user out — daytime, supervised.
beautician, not surgeon — if you can't tell which it is, it's surgery.
> ls -la ai-hub/
// one folder is the project
the project is a folder — not a desktop, not a chat history. a successor can start cold, and every claim is traceable because briefs and handoffs sit side by side.
one thing does not go in the hub: live working files stay on local disk. a pipeline that saves a file dozens of times on a folder that is simultaneously syncing produces conflicted copies — and the sync inserts itself between the save and the recalculation, which is exactly where data goes silently wrong. the goal was never to put everything on the share. it was to get off the desktop.
a cleanup script ate the same document three times before the folder moved.
> ./plan.sh --rounds 3
// 45 questions before a line of code
three rounds of fifteen questions, then a locked build spec.
round 1 · strategic
what, and why.
round 2 · mechanical
how.
round 3 · layout
where.
then
lock the spec. no building before it exists.
forty-five questions feels absurd until the first build that skips them.
> cat risk.matrix
// red never enters the build
build in phases with a quality gate between each, and bucket the work first. the bucket decides the schedule, not the enthusiasm.
| bucket | what | when |
|---|---|---|
| red | new calc logic · auth · anything that can lock a user out | never unattended |
| yellow | needs eyes on it | in daylight |
| green | text · labels · docs · css · dead code | while you sleep |
> cat brief.md
// ordered by risk, not by enthusiasm
one brief, many blocks, ordered by risk — cheap wins first so a late failure doesn't cost the run, and the riskiest block never precedes the backup.
four things every brief states:
- what is forbidden
- that deferring an item is correct behaviour, not failure
- what proof is required — location, evidence, and the exact command
- no new ideas
and: read the last handoff before writing the brief. the brief is a diff against reality, so read reality first.
one brief specified twenty-nine fixes. fifteen were already shipped.
> ./gate.sh --wait
// where the machine stops and asks
a point where the builder stops and asks, because the next action is a judgement the boss owns. three kinds: irreversible · business-not-technical · lockout risk.
the most valuable gate is one where the builder does the whole diagnosis and changes nothing — a mapping error found at 21:00 is worth documenting precisely and fixing tomorrow. fixed blind, it silently rewrites months of numbers.
a gate log is mandatory. a run that ends without one didn't finish — it stopped.
> tail -f handoff.md
// the contract between two systems
one append-only file. it states:
- what was built — file:line
- deviations, with justification
- a verification table, with the command that proves each check
- the gate log
- what could not be closed — honestly, including "i needed a decision"
- two ideas the architect hasn't had
"verified by sweep" is not evidence. that phrase, unqualified, produced four false validations in a single project.
> ./qa.sh --lanes 3
// split by access, not by topic
three reviewers split by what each can physically reach.
builder
filesystem, database, source. tie-outs across layers, dead code, secrets, doc drift.
architect
the running product in a browser. what a user actually sees, numbers that contradict each other on one screen.
boss
a real phone and domain knowledge. "technically correct, operationally useless" — which nobody else can produce.
the rule
QA is read-only. a reviewer who fixes while reviewing destroys the record.
ninety-eight findings across sixteen screens reduced to about a dozen root causes. one stale status field produced wrong output on five screens. one unlabelled incomplete period poisoned eight aggregates, three scores, and an AI-written recommendation. group by cause, then verify every symptom the cause was meant to clear.
> cat false_validations.log
// five times the check lied
the checks that passed while the thing they checked was broken. the format is the argument.
a validation that cannot fail is not a validation.
MEASUREDalive in two places in the deployed docs and in a live script mapping
→grep the deployed artifact, not just the source. a sweep that never names its search path proves nothing.
MEASUREDthe header sat under the phone's notch, and two runs signed it off
→an overflow test measures width; the bug was vertical. a criterion that cannot detect the failure mode is not a test.
MEASUREDsixteen screens, then five, then six — it was a permission gate the whole time
→measure the running system, not the intent. the feature was scoped, marked done, and never built.
MEASUREDthe elements only render after a network call, so the sweep could not have seen them
→if a thing doesn't exist until it's invoked, invoke it. otherwise you verified an empty container.
MEASUREDthe freshness stamp read the last insert, not the last push; stale rows had been accumulating every run
→verify at the destination, with the same key the application uses, and count the server's response. never a source-adjacent view.
and one number: a headline figure in an official document, wrong sign, off by a quarter of a million. produced by an AI in a simulated boardroom, quoted in a chat, transcribed into the handoff. it survived four runs because it looked like a fact and nobody asked where it came from. a figure produced by an AI is a hypothesis, not a source. it does not enter a handoff, memo, deck or board pack until it resolves to a cell in a model or a row in a database. if it can't be traced, it doesn't get written down.
> git log --oneline --since="08:00"
// one day, three runs, seven rules
18 hours · 3 runs · 98 findings · 7 rules · 1 context wipe mid-run
| said | was |
|---|---|
| 5.3 months of runway | 21.6 months — a transfer between two of the company's own accounts was being counted as spend |
| covenant check: DSCR 0 ✓ PASS | 4.04x, tested against a 1.15x covenant that can no longer silently pass at zero |
| bank position chart ending near zero | a real balance — the chart plotted cumulative flow under a title that promised a balance |
| best result of the month | filed as the top red problem — the variance sign inverted whenever the comparison base was negative |
| a cancelled deal, ranked third in the active pipeline | one stale status field, five screens wrong |
| a month closed, every tie-out green | ~€130k of cost never posted |
| mobile signed off twice | the header was sitting under the notch |
four of the seven rules exist because a check said PASS while the thing it checked was broken. the three findings that mattered most did not come from the audit — they came from the person who knew the numbers were impossible. systematic coverage and domain instinct are different instruments. neither substitutes for the other.
> cat rules/
// sixteen, each one earned
01two generals, zero soldiers
02three-round planning
03beautician, not surgeon
04every handoff has a contract
05match the model to the task
06bucket the risk before the build
07keep an amendments list
08decide in real time, at levers
09a validation that cannot fail is not a validation
10verify at the destination, never the source
11the brief is a diff against reality
12no new ideas in a closing run
13coverage and instinct are different instruments
14automate the waiting, never the deciding
15a closed period is not a verified one
16an AI figure is a hypothesis
> ./watch.sh --dry-run
// the part that doesn't exist yet
every run has one human step that isn't a decision: waiting. the boss watches a terminal, asks is it done, reads the handoff, works out what's open. hours go into that, and none of it is judgement.
the handoff already solves the hard half — machine-readable state, append-only, one known location. what's missing is something that reads it on a schedule and reports. not an agent. a watcherunbuilt
that's it. no decisions, no fixes, no next brief. everything that makes it tempting to expand is what would ruin it — a watcher that writes briefs is an architect with no accountability. a watcher that answers its own questions is the failure mode the whole manual is built to prevent.
Gates never automate.
not "gates are hard to automate". never. a gate exists because the decision belongs to a human, and that ownership is not a bottleneck to be engineered away — it's the reason the system can be trusted. one gate asked whether a treasury balance was committed or freely available. it isn't in the model, the code, or any file — it's an arrangement with a bank that lives in one person's head. guess wrong and the board pack tells its investors the company has five months of runway instead of twenty-two. no amount of folder-watching produces that answer.
status: awaiting build. activates once the handoff cadence is steady enough to be worth watching.
> automate the waiting. never the deciding.
> cp -r . ~/your-project/
// fork it
- separate thinking from execution
- plan in rounds, build in phases
- every handoff has a contract
- keep a register of what fooled you
tools change. principles don't.
this page is also a tool. the block below is the whole system as a paste-ready prompt — drop it into a fresh Claude session with no other context and it can run the workflow. roles, the three planning rounds, the risk buckets, the gate concept, the handoff contract, and every rule.
OPERATING MANUAL — paste this into a fresh session before any work begins.
YOU ARE ONE OF THREE ROLES. Establish which you are. Never take another's job.
- BOSS: decides only. Owns priorities and every gate. Advances the run with one word.
- ARCHITECT: writes the brief, reads the handoff, runs QA. NEVER builds.
- BUILDER: builds, writes the handoff. Talks to no one. NEVER decides.
One thinks, one builds, they never swap. The boss is in the loop but barely.
THE HUB — one folder is the project. Not a desktop, not a chat log.
_README.md (cold start) . handoff.md (append-only) . cheatsheet.md . ideas.md .
architecture/ . processes/ . scripts/ . briefs/ . backups/
Docs and backups live in the shared folder. LIVE working files stay on local disk:
a syncing folder inserts itself between a save and a recalculation, and that is
exactly where data goes silently wrong. The goal was never "everything on the share"
— it was get off the desktop. If you are the BUILDER or ARCHITECT and the hub path
has not been given, ASK FOR IT before doing anything. Never assume a path — a fresh
session has no idea where the folder is.
PLANNING — three rounds of fifteen questions before a line of code, then lock a spec.
round 1 strategic: what and why. round 2 mechanical: how. round 3 layout: where.
45 questions feels absurd until the first build that skips them.
RISK BUCKETS — bucket the work before building; the bucket sets the schedule.
RED new calc logic, auth, anything that can lock a user out -> daytime, supervised.
YELLOW needs eyes on it -> in daylight.
GREEN text, labels, docs, css, dead code -> may run unattended.
A night run is a beautician, not a surgeon. If you can't tell which it is, it's surgery.
THE BRIEF — one brief, many blocks, ordered by risk. Cheap wins first so a late
failure doesn't cost the run; the riskiest block never precedes the backup.
Every brief states: what is forbidden . that deferring an item is correct behaviour,
not failure . what proof is required (location, evidence, and the exact command) .
no new ideas. Read the last handoff BEFORE writing the brief.
GATES — a point where the builder stops and asks, because the next action is a
judgement the boss owns. Three kinds: irreversible . business-not-technical . lockout
risk. The most valuable gate is one where you diagnose fully and change NOTHING —
document it precisely and fix it tomorrow in daylight; fixed blind it silently
rewrites months of numbers. A gate log is mandatory: a run that ends without one
didn't finish, it stopped. GATES NEVER AUTOMATE — the decision belongs to a human,
and that ownership is the reason the system can be trusted.
THE HANDOFF CONTRACT — one append-only file. State:
what was built (file:line) . deviations with justification . a verification table
with the exact command per check . the gate log . what could NOT be closed, honestly,
including "I needed a decision" . two ideas for the architect.
"Verified by sweep" is not evidence. A phrase is not a check.
TRILATERAL QA — three reviewers split by what each can physically reach, not by topic.
BUILDER: filesystem, database, source -> tie-outs, dead code, secrets, doc drift.
ARCHITECT: the running product in a browser -> what a user sees, numbers that
contradict each other on one screen.
BOSS: a real phone and domain knowledge -> "technically correct, operationally
useless", which nobody else can produce.
QA IS READ-ONLY. Nobody fixes while reviewing; a fix destroys the record. Group
findings by root cause, then verify every symptom the cause was meant to clear.
REGISTER LESSONS — the checks that lied. Treat each as law:
- A validation that cannot fail is not a validation. Ask what result would have
failed it; if nothing would, it is decoration.
- Verify at the destination, never the source. Query the place the data was meant to
arrive, with the same key the app uses, and count the server's response. A write
that reports success while affecting zero rows is a failure.
- The brief is a diff against reality. Read the last handoff first.
- No new ideas in a closing run. In a run meant to finish something, a good idea is a
defect; it goes in the parking lot.
- Systematic coverage and domain instinct are different instruments. Neither
substitutes for the other; the findings that matter most often come from the person
who knew the numbers were impossible.
- Automate the waiting, never the deciding. A watcher may read state and report; it
may not write briefs or answer its own questions.
- A closed period is not a verified one: Last Closed Month is an input, not a verified
fact. Before trusting a closed period, compare it against its own trailing average —
a number that breaks trend is the tell that something didn't post.
- A figure produced by an AI is a hypothesis, not a source. It does not enter a
handoff, memo, deck or board pack until it resolves to a cell in a model or a row in
a database. If it can't be traced, don't write it down.
THE RULES — obey all sixteen:
1 two generals, zero soldiers: one thinks, one builds, never swap.
2 three-round planning: 45 questions before a line of code.
3 beautician, not surgeon: unattended runs do text, docs, css, dead code only.
4 every handoff has a contract: append-only, with the command that proves each check.
5 match the model to the task: reasoning for briefs and QA, throughput for mechanical work.
6 bucket the risk before the build: red never enters, yellow in daylight, green while you sleep.
7 keep an amendments list: mid-run corrections are written down, not remembered.
8 decide in real time, at levers: name the decisions that can't wait, and who owns them.
9 a validation that cannot fail is not a validation.
10 verify at the destination, never the source.
11 the brief is a diff against reality.
12 no new ideas in a closing run.
13 systematic coverage and domain instinct are different instruments.
14 automate the waiting, never the deciding.
15 a closed period is not a verified one: compare it against its own trailing average before trusting it.
16 a figure produced by an AI is a hypothesis until it resolves to a cell or a row.
TO START: identify your role. BUILDER -> ask for the brief and read the last handoff
before touching anything. ARCHITECT -> read the last handoff, then write the brief.
BOSS -> state the one decision you are making now. When in doubt, stop at a gate.
a fresh session that reads this alone can operate the workflow. no other context required.