agent-operating-system

A governance protocol for running several AI coding agents on one repo: single-writer ownership, prepend-only handoffs, decision-class delegation with veto and kill switch, scored critic seats, and build gates that stop claims drifting from the source of truth.

Once more than one coding agent works in the same repo, the failures stop being about code quality and start being about coordination:

• Two agents edit the same file and one silently reverts the other.
• An agent is asked to do work in a folder it was told not to touch. It stops, correctly, and the stall looks like a broken agent rather than a broken contract.
• A session ends and the next one starts from a stale picture of what is done.
• An agent grades its own work and reports PASS.
• Every small, reversible decision waits a day for the human, so the work crawls.
• A number on a public page is typed by hand, and three weeks later it no longer matches the product.
• Finished work sits on a cloud agent's VM or a branch, and the next agent reports it as missing.

Each of these happened in a private workspace where two primary agents (Claude Code and Cursor) and two critic seats (Codex and Gemini) worked on one repo in August–September 2026. This repo is the protocol that grew out of those incidents, and the build gates that enforced the parts that could be enforced in code.

• Governance as data. Ownership, privilege and delegation are written as short contract files (_bus/) that every agent reads on entry. Each rule records the date and the incident behind it.
• Delegation with a veto. A three-gate test decides which calls an agent may make itself (and log), which fall back to the smallest option, and which always go to the human. Any agent call can be reversed with VETO <id>; the whole scheme stops on DELEGATION OFF.
• Maker ≠ checker. The agent that builds an artifact never verifies it. New critic agents are scored on a rubric (≥14/18, zero hard fails) and admitted only to a write-quarantined folder.
• Verification gates. Stdlib Python tools generate every factual claim from a manifest, check published pages against it, and refuse to print a pass for a check that examined nothing.
• Evidence discipline. Every number carries a tag, and research sources carry a grade (below).

flowchart LR
  OP[Human operator<br/>Class C, taste, pass tokens]
  CC[Claude Code<br/>plans, contracts, gates]
  CU[Cursor<br/>executes, runs builds]
  CR[Codex + Gemini<br/>critics, quarantined]
  BUS[(_bus/<br/>CONTEXT · QUEUE · HANDOFF · DELEGATION)]
  SRC[catalogue/ manifest + product files]
  G{build gates<br/>claims · zips · readability · a11y}
  PUB[site + packs]

  CC -->|briefs, queue rows| BUS
  BUS -->|top unblocked row| CU
  CU --> SRC --> G
  G -->|green| PUB
  PUB -->|fresh-session critique| CR
  CR -->|notes only| BUS
  CC -->|VERIFY, never own work| PUB
  OP -->|rulings, VETO, kill words| BUS

1. One writer per path, listed path by path. The first stall came from naming an agent's work without granting it a path. Carve-outs are now exact globs, and a plan is checked against the granted list before it is handed over.
2. Prepend-only handoff; read the top entry only. The log is history; only the newest entry is instruction. This keeps each session's reading list small.
3. Delegate by decision class, not by trust. An agent may decide alone only when the choice is reversible in one session with the losing option already banked, touches no locked surface, and picks between options already built. Operator words are relayed, never ledgered — the ledger is a veto trail for agent decisions only (see DL-001 in DELEGATION.md).
4. Critics are quarantined and scored first. Codex scored 17/18 and Gemini 15/18 on the seat rubric. Both were admitted as critics only; Gemini's soft spots (ownership framing, tag discipline) are exactly what a general writer needs most.
5. Claims are generated, never typed. claims.py derives price, file list, ZIP name and legal wording from the manifest and the files themselves. --check reads the published pages and fails on any drift. A check that examined zero tagged claims is reported as a failure, not a pass.
6. Incidents become standing rules. Two custody misses in two days became ACCURACY.md, CLOUD-CUSTODY.md and an always-on Cursor rule: finished work is not done until the files are in the local checkout and the human artifact is open.
7. No toolchain to install. The gates are standard-library Python plus headless Chrome for PDFs. A tool the operator has to install is a failure mode.

Every number carries a tag. Full detail in docs/EVIDENCE.md.

Research sources are graded A (government, official statistics, regulator) · B (industry body, or a platform describing its own product) · C (law-firm briefing or specialist practitioner) · D (trade press) · F (content-marketing estimate with no traceable primary). There is no E. Nothing graded F is load-bearing.

Requires Python 3.10+. No packages to install for the core gates.

# every tool compiles
python3 -m py_compile build/*.py

# the full smoke suite (11 tests, stdlib unittest)
python3 -m unittest discover -s tests -v

# claims gate: generate blocks, then check a site against the manifest
python3 build/claims.py --catalogue examples --out dist/claims
python3 build/claims.py --catalogue examples --site examples/site --check --strict          # passes
python3 build/claims.py --catalogue examples --site examples/site-drifted --check --strict  # fails, names 3 drifts

# reading grade, static accessibility, accent contrast
python3 build/readability.py --catalogue=examples
python3 build/a11y.py --site examples/site --strict
python3 build/palette.py

# semantic copy lint — dry run only; --run needs the anthropic SDK and a DeepSeek key
python3 build/copy_lint.py --catalogue=examples

# render PDF/DOCX/MD packs and ZIP them (needs Google Chrome; set CHROME_PATH if not at the macOS default)
python3 build/render.py --catalogue examples --dist dist/examples
python3 build/zips.py --catalogue examples --dist dist/examples --out dist/examples/zips --check

dist/ is regenerable output and is git-ignored.

• Status: a sanitised extract of a protocol used in a private workspace (Aug–Sep 2026, 200+ handoff entries). Not deployed; no users. The example catalogue, brand and prices are fictional.
• Genericised documents. Paths such as strategy/, site/ and review/ in the contract files describe the layout the protocol governed; most do not exist in this repo. Dates and rulings are the real ones; product details, IDs and domain-specific content were removed.
• Governance is enforced by agents reading files, not by code. Nothing technically blocks a cross-lane edit; git authorship and the separate verify step catch it after the fact.
• The seat eval is small. Four runs per agent, scored by one orchestrator seat. It was used as a gate for a narrow, revocable grant, not as a benchmark.
• Tool limits. a11y.py is static only (it says so in its output). readability.py uses a heuristic syllable count, English only. claims.py assumes this manifest and listing format and formats prices as A$. ad_qa.py is macOS-only, needs ocrmac and Pillow, and is not exercised here because the example has no ad assets. copy_lint.py --run is not exercised (it spends on an external API); only the dry run is tested.

Built by directing AI coding agents (Claude Code and Cursor, with Codex and Gemini as critics). Wol set the direction of the protocol and ratified its rules, made the operator rulings recorded in _bus/, specified what each gate must check, and reviewed the output. The agents drafted the contract prose, wrote the gate code in build/ and ran the verification passes, inside the protocol this repo describes. The seat evals were scored by the orchestrator agent (Cursor), not by Wol.

MIT © 2026 Wol