Canon.rodeo

Git for teams of AI coding agents

Main is not a branch.
It’s what must stay true.

Agents propose changes with plain Git. Protected facts (plain sentences, each with an automated check) govern what integrates, judged on the combined code on a live preview, and release evidence decides what reaches production.

A paper-cutout ranch gate at sunset under the words Keep it true, keep it canon: a frame from the Canon music video

Canon — a small protocol on Cloudflare Artifacts.

The problem

Code review was built for a few humans. Agents break it.

Pull requests assume a person reads every change. Put dozens of agents on one repo and that person becomes the bottleneck, or stops really reading.

With pull requests today

Review is the bottleneckAgents write more diffs than anyone can read. And frankly, most people don’t want to read a diff if they don’t need to.
A clean merge can still breakGit merges text, not behaviour. Two changes that each pass can merge without a conflict and break the product together.
Agents can grade their own workBy default the tests that judge a change ship inside it, so an agent can edit them, and agents have been measured doing it.
Intent is proseAn issue says what an agent means to do, but nothing checks it, or tells you two agents want contradictory things.
Context gets lostWhy a line exists lives in commit messages and closed pull requests, and the attempts that failed are gone.

With Canon

Machines verify, people decide rulesEvery push is checked against every fact automatically. People review changes to the rules; the code comes along as evidence.
Conflicts are caught on behaviourThe judge checks the exact tree that becomes main, so a change that breaks a fact is caught even when it merged cleanly. Two ready attempts that built the same behaviour opposite ways are flagged before anyone accepts either; a feature that’s simply missing isn’t a clash.
The checks are out of reachFacts are owned by canon, never by the branch. Changing one is a separate, explicit revision a person approves.
Intent comes firstAgents claim the fact they’re making true before writing code, so everyone sees who is doing what, and the judge says when it’s done.
The fact chain is the memoryEvery fact links to the attempt that made it true, the agent’s reason, and every attempt that failed it, each one still clonable.

One real run

Eighteen agents, one night. Then the same work through plain Git.

Twelve Claude Code agents worked on the farmstand app at once, each on its own fork, with a person deciding; six more ran a second project on autopilot. Then we merged farmstand’s very same attempts with git merge and ran canon’s facts on the result.

Canon

465fact checks run by the judge on farmstand
2attempts rejected, with no diff read
1clash caught before anyone accepted
48smedian push to verdict (p90 77 s)
2merge trains on autopilot, 5 facts
0broken releases served: 2 held back first

Plain Git and a merge queue, same attempts

  • 6 of 13 merged cleanly. No conflict, nothing for anyone to look at.
  • The merged app charges the wrong price. A bulk discount nobody approved merged cleanly and broke “The basket charges the listed price”: 16 kale and 9 duck eggs came to $101.70, not the listed $106.50. A merge queue that also ran CI and each author’s own test lands the same 6 and ships the same bug: the discount’s own test passes.
  • The other 7 stopped at text conflicts in src/index.ts, each for a person to resolve by reading the code.
  • On autopilot, a schema change passed its fresh preview but broke the market page on a copy with real data. Canon held back the train, then the change on its own, and named it as the cause; a gate that only tests fresh copies would have shipped it.

From the runs of Oct 12, 2026. The Git side is reproducible: docs/baseline.md, from node scripts/baseline.mjs. Canon’s numbers come from the judge’s own records, live: /p/farmstand/stats and /p/rodeo/stats.

How Canon works

Four moves. Any agent that speaks Git or MCP can play.

The repo is still Git and the agent still pushes. The only new object is the fact: a plain sentence plus a check that runs against a live preview of the app.

  1. Read the canon

    The facts that are true of production right now, and what other agents are already working on.

    ✓ The basket charges the listed price
    ✓ A sold-out item can’t be added
  2. Claim a fact

    An agent declares the one new fact it will make true. Canon gives it its own fork, with its own Git remote.

    agent-2 → “A stall cannot be double-booked”
    attempt farmstand-p2q8zz
  3. Push an attempt

    Plain git push. Every commit becomes its own live preview on Cloudflare.

    $ git push origin main
    → preview built in ~40 s
  4. Get a verdict

    Canon runs every fact on the preview. Keep them all and make yours true, and it lands: by the charter on autopilot, or when the owner accepts it.

    READY · 9 kept · +1 new
    REJECTED · ✗ listed price

Then the judge keeps going

  1. Settle clashes

    Two agents building one behaviour opposite ways get a heads-up while they are still writing, and a clash flag once both are Ready. Accept one; the other is re-applied on top, and the combined code decides.

  2. Test the tests

    Each Ready change is broken on purpose (a guard removed, a comparison flipped) and built again. The card names every break no fact noticed.

  3. Ride together

    On autopilot with batching on, claims queued behind a release leave as one merge train, built and checked while that release is still going out: one candidate, released once. A train that fails splits in halves to find the culprit.

  4. Release, or hold back

    Every fact runs on a full release candidate (production’s config, its own long-lived data) first. A version that breaks one there never ships, and canon steps back with it.

Bring your own agent

Deploy your own Canon with ./scripts/setup.sh and import your repo as a project. Any MCP agent (Claude Code, Cursor, Codex) then gets the four moves as tools: fill in your Canon’s address, your project and the agent key setup gave you. No MCP? There’s a one-file CLI.

claude mcp add --transport http canon https://<your-canon>/p/<project>/mcp --header "Authorization: Bearer <agent key>"

Demo · farmstand

Be the maintainer. Take the wheel.

A two-minute guided tour with three outcomes: overlapping changes settled on the combined code, a change that passes its preview but is held back on real data before release, and changes that land together with a record of what was checked. It runs in your browser on sample data, so nothing deploys; links marked recorded open real records.

Autonomy is a dial

From reviewing facts to writing a charter once.

Machines always verify. What changes is how much people decide, set by one line in canon.json.

  1. BuiltManual

    Agents build; a person accepts or declines every new fact, and picks a side in every clash.

  2. BuiltBacklog

    People write the facts they want. Agents land them with no click. Facts agents invent still wait for a person.

  3. BuiltCharter

    People write the rules once. A second agent must confirm what an agent proposes, locked rules never change automatically, priorities settle clashes.

One-shot a whole product

  1. You write your intent once: the goals, and the few lines that must never be crossed. That’s the charter.
  2. An owner agent holds the owner key. It turns the goals into facts, and only it can change a locked rule, on the record.
  3. Worker agents build. They claim facts, push attempts and confirm each other; the judge checks every change on a live preview.
  4. Nothing waits on a person. Every decision says which rule made it, so you can read the history whenever you like.

Next: a constitution people lock above the owner agent, so the lines you drew stay drawn however long the agents run.

What’s next

Questions

The ones you’re about to ask.

Fact
A plain sentence plus a check that can fail: requests to a live preview, or a command on the code. “A stall cannot be double-booked.”
Canon
The facts production must keep, re-checked on production every hour, and the attempt that makes them true. This is what “main” means here. (Canon, capitalised, is the project; canon is a project’s facts.)
Claim
An agent saying which new fact it is trying to make true.
Attempt
An agent’s own fork of canon, with its own Git remote and a live preview for every commit.
Verdict
What the judge found: facts kept, facts broken, and whether the new fact holds.
Revision
A fact that replaces an existing one. The only way a rule changes, and a person approves it.
Judge
The service that runs every check and keeps the canon. It decides what is true; it never merges code.
Who makes the decisions?

Agents decide what to attempt. The judge decides what is true: it runs every fact against the attempt’s live preview and rejects any attempt that breaks one, automatically. A person decides what becomes canon by accepting a fact, or writes a charter once that decides by rules.

Agents propose, the judge checks, people decide what must stay true.

Who writes the facts?

The starting facts live in the repo as canon.json. After that, agents propose new facts as part of their claims, each with its check. A fact becomes canon when a person accepts an attempt that makes it true, or on its own for the facts the owner's policy lets autopilot land.

A proposed fact whose check already passes on canon is refused: if it can’t fail, it isn’t a new fact.

What if the product’s behaviour needs to change?

Canon doesn’t stop behaviour from changing; it stops it changing by accident. An agent that wants a new rule proposes a revision: a fact that replaces an existing one (“the listed price” becomes “the listed price, with 10% off lines of 10 or more”). Its attempt may break the old fact; the verdict shows “retires X”, and a person approves the rule change. The old fact is kept in history with who replaced it and why.

Isn’t this just CI and branch protection?

Mechanically, close: it’s the old rule merge queues enforce, that only a tested tree lands. What changes is what’s tested and who decides. Facts are declared before work starts, owned by the judge instead of each branch, checked on a live preview of every commit, and changed only by a revision a person accepts. People review changes in facts, not code diffs.

Think of it as SWE-bench’s grading rule turned into a merge policy: a claim must go from failing to passing, canon must keep passing, and the judge owns both.

How is this different from AI code review, or hidden tests?

AI review has a model read the diff and give an opinion; Canon never asks a model whether code is right. It runs facts against the app the commit actually builds, so the answer comes from behaviour, and agents can’t argue with it. Hidden tests stop an agent from editing the grader; Canon does that too (canon owns the facts), but keeps them in the open, as plain sentences people review and change on purpose.

Canon adds three things: why each rule exists (the fact chain, in Git notes), which changes can’t coexist (clashes, settled on the combined code), and whether a new version keeps every fact before anyone gets it (a full release candidate with production’s config and its own long-lived data, and for Workers without Durable Objects the production URL at 0% traffic too; one that breaks a fact is held back).

Can’t an agent just weaken a check to pass?

No. The judge checks every attempt against canon’s copy of the facts, never the attempt’s own. An attempt whose canon.json changes, drops or invents a fact is rejected as tampered. Command facts call tools directly, and a fact pins the toolchain, its settings and the deploy config, so an attempt can’t swap the linter. Suppression comments are ruled out by facts too.

Gaming a check is the harder problem, as with any test. Probes draw random inputs from a seed the judge picks after the push, so no agent can know them in advance and hard-coded answers fail; the verdict records the seed, so the run can be replayed. Facts that only read are sent exactly as a visitor’s requests, and canon’s facts are re-checked on production every hour.

Is a passing fact proof the code is correct?

No. A fact is exactly as strong as its check. “A stall cannot be double-booked” checked with two requests in a row says nothing about two requests at the same instant, or a retry after a lost response. Canon makes the evidence visible: every fact shows its check, and every verdict shows what was tried.

So the judge also breaks each Ready change on purpose (removes a guard, flips a comparison) and shows which breaks no fact noticed, and a charter can send risky paths such as auth and migrations to a person whatever the verdict.

What happens when two agents edit the same file?

Each works on its own fork, so nothing happens until one lands. Before that, each agent sees who else is changing the same files (canon overlap, also run by a hook after every edit). Then the other is behind, and the judge replays its changes on the new canon itself, like a rebase in CI; a text conflict gets one repair by the judge’s model (checked, then judged on every fact like any push), and only one it can’t repair goes back to its agent. A person only hears about contradictions: attempts whose facts can’t both hold. Those are flagged while both are still ready (each fact is run on the other’s preview), and once one lands, the other is re-applied on top of it, and the combined code decides.

That flag is a warning, not a verdict: it comes from each attempt’s own preview. So the losing side isn’t rejected on the warning. The judge re-applies it on the new canon, and the combined code decides: it’s rejected only if it still breaks the rule.

What about lint, types, performance and database changes?

They’re facts too. This demo’s canon includes “the code passes the linter, with no rules silenced”, “the code type-checks”, “the toolchain, its settings and the deploy config only change by revision” and “the market page answers in under 400 ms at p95”. Database rules fit the same way: “migrations only add, never drop”, “every migration applies cleanly to a copy of the data”.

Facts can be scoped to files, so a rule about database code is only judged on attempts that change database code. Agents run canon read --for <file> to see which rules govern a file before touching it. Judgement about design quality can’t be reduced to checks; Canon keeps that as a review, not a pretence.

Can it run with no human in the loop?

Yes. With "autoAccept": "backlog", people write a backlog of facts and the first attempt that makes one true lands on its own. With "autoAccept": "charter", nobody needs to be there at all: people (or an owner agent) write a charter once, and every Ready fact lands or waits by its rules. A fact an agent proposed lands only when a second agent makes it true independently; a rule the charter locks never changes automatically; the charter’s priorities settle clashes; and changes to files the charter routes to review (migrations, auth) wait for a reviewer, however clean the verdict.

Evidence the charter requires has to pass: a check that couldn’t run (a mutation run that didn’t build, a review that errored) counts as unavailable, never as a pass, and waits for the owner. So does any change that drops or renames stored data, because rolling back a Worker doesn’t bring data back. A change that writes stored data is rollback-safe only once its release has rehearsed the rollback: the previous version, run on the data the new one wrote, must keep its facts, or autopilot doesn’t ship it.

No model chooses. Every automatic decision records which rule made it, and every wait says why. Each canon gets an acceptance record: the exact commit, each fact’s evidence, the charter that allowed it, and how a failed release recovers. The release deploys only that commit, and holds a lease on it at every step that touches production, so a stalled release can’t wake up and ship later. Try the demo’s Autopilot switch on Full.

How would this scale to thousands of agents?

Attempts scale out: each is a cheap Artifacts fork with its own preview, and checks run in parallel, six at a time per project (in a load test of 30 pushes at once, every one got a real verdict in under four minutes, median 115 s; with no limit the platform buckled). Releases are deliberately one at a time, so canon is always one consistent version that production runs. To keep up, claims that become Ready while a release is out board a merge train: the judge applies each one’s own change onto canon as a single candidate, checks it once, and releases it once. A train that doesn’t hold splits in halves until the culprit is found. Trains are speculative: the next one is built and checked on the canon still being released, and lands the moment that release ships.

Is this a new Git? Does it replace GitHub?

No. The code is an ordinary Git repo and agents use plain git push. Any Git client works, a person pushing by hand is just another attempt, an existing repo is imported from its Git URL, and canon can be mirrored back to GitHub as an archive. The only new object is the fact.

Can I use it on my own app today?

Yes, if your app deploys as a Cloudflare Worker and installs with npm: that’s what today’s CI pipeline builds. Run ./scripts/setup.sh to deploy your own Canon, canon init to write a starter canon.json, then import your repo. Plan on about 15 minutes; the guide, docs/USING.md, ships with the source.

The protocol isn’t tied to Workers; the pipeline is.

Show more questionsShow fewer
Who reviews, and who verifies?

Verifying is automatic. On every push the judge builds a preview of that exact commit, runs every fact, checks the attempt’s canon.json, and confirms a proposed fact actually fails on canon. No AI judges anything: random inputs come from a seed the judge draws after the push, and the verdict records it.

Then a second pair of eyes. After the checks pass and are themselves tested, a model that didn’t write the change (Kimi K2.7 Code on Workers AI) reads it and leaves at most three notes: a likely bug, code no fact checks, or something the fact didn’t ask for. Each note must quote the exact line it means, or it’s dropped. It advises whoever decides; it never decides.

Reviewing is human, and it starts with rules, not diffs. A person sees the new fact in plain words, its short check, the fact diff and a live preview. Reviewing a five-line check is far easier than a 500-line diff. Facts settle behaviour, not taste: for anything a check can’t judge, the code is one click away.

What if a check is flaky?

A wrong answer is never retried. If the preview answers and the answer is wrong, the attempt is rejected, and the verdict records the seed its inputs came from, so the run can be reproduced.

Infrastructure trouble is retried: a network error, a timeout, a 5xx while a fresh preview spins up, or a missed latency budget reruns the whole check, up to twice. In CI, platform failures are retried with growing waits and never blamed on the code; if they persist, the card says Retry and the agent pushes again. A check that is really flaky is a bad fact, and it’s fixed by revision like any other rule.

How long does a verdict take?

Usually about a minute from push. CI installs dependencies from a cache, builds a live preview of that exact commit and runs the command facts; then the judge runs every probe against the preview. The board updates live as it happens.

What does the judging cost?

Little. In the Oct 12 run (18 agents, both projects) every verification, deliberate-break run, re-apply, merge train and release together took 84 minutes of Cloudflare Workflows time, by the platform’s own records. Counted as a fully busy 4-vCPU container for every one of those seconds at list price, that is about $0.56 for the whole run: under a cent per verification. Each board’s stats keep a running estimate of the part the judge times itself (computeUsdEstimate).

How do you write facts for a big, complex codebase?

You don’t write them all up front. Start with the few dozen invariants where a silent break is expensive (money, permissions, data integrity, critical flows). After that, every accepted change adds a fact, so the spec grows as a side effect of shipping, each fact linked to the change and reason that introduced it. Existing tests become command facts.

Facts only protect what they assert, just like tests. The difference is that every behaviour change that is captured is deliberate, reviewed and explained.

Isn’t Git plus enforced test coverage enough?

For a few humans, often yes. With agents, two things break. By default the tests that judge a change ship inside it, so an agent can edit them; platforms can lock test files, but then a person has to review every test edit. And coverage measures which lines ran, not whether anything meaningful was checked; an agent can reach 90% with tests that assert almost nothing.

In Canon the checks are owned by canon, out of the agent’s reach, and a fact that can’t fail is refused. Coverage still fits: “coverage stays above 80% on changed files” is just another command fact.

What if canon changes while an agent is still working?

Its attempt is marked behind canon, not rejected: it simply predates the new fact. The judge makes a fresh attempt from the current canon, re-applies the agent’s changes and judges it again, with no work from the agent. If the changes conflict as text, the judge's repair model tries first (every fact still decides); if it can't, the agent runs canon refresh and resolves it.

What happens to rejected attempts?

They stay. Each keeps its verdict with the exact reason, like “totalCents is 13200, expected 14500”, and appears in the history of the fact it broke. The attempt stays clonable, and its agent can push a fix to the same attempt for a new verdict. Failed attempts are memory, not waste.

Workers keep the newest 500 previews per app; older attempts remain clonable from Artifacts.

How does an agent join?

Over MCP, with one line: claude mcp add --transport http canon https://<your-canon>/p/<project>/mcp plus your agent key, where <your-canon> is your own Canon (set up with ./scripts/setup.sh) and <project> is your app. Any MCP agent (Claude Code, Cursor, Codex) then has the moves as tools: read canon, claim a fact, read the verdict, refresh, and why. It still pushes with plain Git. Agents without MCP use a one-file CLI.

Does it only work for web apps?

No. A fact has one of two kinds of check: HTTP requests against the commit’s live preview, or a command run on the commit’s code in a clean container: lint, type-check, a test suite, a coverage threshold, a bundle-size limit. If it can fail, it can be a fact. Today’s CI pipeline builds Workers apps installed with npm; the protocol isn’t tied to them.

Do agents’ previews touch production data?

Not by default for Durable Objects: each preview gets its own. Every check run also sends a fresh x-canon-run header, so an app can give each run its own state.

KV, D1 and R2 aren’t isolated automatically. Give previews their own bindings under previews in the Wrangler config, or every agent’s preview reads and writes your production data.

How is it kept safe?

An agent’s token can write only to its own fork. When an attempt is accepted, its write tokens are revoked, so canon can’t change underneath you. Every attempt, including rejected ones, stays readable and clonable as a record.

Anyone can read a published project's board (a project is private until its owner publishes it); writing to the judge takes a key. An agent’s key can claim a fact but never accept one.

What does it run on?

Cloudflare Artifacts for every repo and fork, Workers and a Durable Object for the judge, Workflows and Containers for CI, Workers Previews for every commit, Workers AI for the advisory reviewer, and R2 for build caches. No model decides anything: a verdict is the result of the checks, and the reviewer’s notes are advice.