Controlled document · COPS-OG · evaluation copy
The delivery platform where AI does the building and machinery — not vigilance — enforces the standard. This guide explains why it exists, how work moves through it, and what it asks of you.
AI can now write software far faster than any person can read it. That sounds like a productivity story, but it is really a trust story: when the code arrives faster than you can check it, the bottleneck stops being the building and becomes the believing. Most teams answer that with heroics — a founder reading every line, a senior engineer staying up late, a growing pile of “we’ll test it properly later.” Heroics don’t scale, and they fail quietly on the one bad day.
COPS is the other answer. It treats quality as an engineering problem rather than a discipline problem: rails that make the right path the easy path, gates that physically refuse the wrong one, and evidence — signed, hashed, tied to the exact version of the code — that lets you trust the result without re-doing the work.
It began as internal tooling with a modest goal: help us ship more, safely. It worked well enough that the machinery itself became the product. This guide is written so that an intelligent person without a software background can operate it and ship work to the same standard we do — and, once the public installer lands, install it themselves — because the standard lives in the machinery, not in the operator’s head.
Never trust a claim you can verify, and never require a human to verify what a machine can prove. People decide what and whether; machinery proves that it was done right.
COPS is an operating system for AI-assisted delivery. AI models write the code, review the code, and shepherd it through checks; COPS supplies the three things raw AI doesn’t have:
COPS enforces that every change travels the same five-stage pipeline — review, quality check, ship, bot review, land — each stage a packaged procedure, not a habit. Work that skips a stage arrives at the merge gate without evidence, and is refused — so quality never depends on someone remembering to be careful.
Each completed stage signs a receipt bound to the exact version of the code it checked. Receipts link into a chain, and the chain is verified — by machine — before anything merges. “It was reviewed” is a checkable fact here, never a recollection.
Merging — the moment a change joins the main codebase — is refused on a broken or missing chain. Anything destructive or irreversible stops and asks a human, with the exact target named. When the system can’t classify a situation, it fails closed — it holds and escalates rather than guessing.
Everything else — which AI writes, which AI reviews, which checks run for which kind of change — is configuration on top of those three ideas.
COPS did not appear in a vacuum, and it does not replace the excellent tools it grew up alongside. It is one layer in a deliberate stack, and knowing the boundaries tells you what each piece is for — and who COPS is actually aimed at.
When two layers could both claim a moment, the boundary is simple: workflow steps belong to G-Stack; discipline inside a step belongs to the process skills; proof belongs to COPS. A ship follows G-Stack’s procedure, is built test-first per the process skills, and is merged only because the COPS chain verifies. The layers compose; none substitutes for another.
Skills and workflows are ultimately conventions — superb ones, but an agent (or a person) can skip a convention on a bad day and nothing stops them. COPS exists precisely for that day. Its receipts, gates, and terminal states assume good intent and verify anyway. That is the divergence: the other layers make quality easy; COPS makes cutting it visible and refusable.
A fair question: GitHub already offers branch protection, required checks, and merge queues — doesn’t that cover it? Those verify that named checks passed, and COPS builds on them rather than competing with them: they are the server-side substrate its enforcement targets. What they don’t hold is everything this guide has been describing — who did each stage, in what order, on which exact version, with what disclosed provenance; independent multi-model review orchestrated as a loop that terminates; a lifecycle with honest endings; and holds that reach a human instead of a task silently rotting in a queue. Branch protection knows a checkbox went green. COPS can show you the case file.
Who it’s aimed at: the skills ecosystems serve any developer working with AI. COPS is aimed at the person accountable for the output — a founder, an operator, a small studio — who wants AI-built software shipped unattended to a standard they can defend, without personally re-checking every line. If you need to be able to say “here is the proof” rather than “I’m fairly sure,” you are who this is for.
The pipeline you’ll meet in the next section starts at “claim a ticket” — but the journey starts earlier, and the early part is where quality is actually decided. Nothing in COPS is picked up on a whim:
For small, unambiguous work the ceremony shrinks to fit — a clear ticket and a clean pipeline run. The principle doesn’t shrink: the work is defined before it is begun, and the definition has an owner.
Work enters as a ticket and leaves as shipped, verified software. In between it occupies exactly one state at a time, and every move between states is recorded. This is not bureaucratic decoration — it is what makes an unattended system safe: at any moment, anyone (or any machine) can ask where is this task, and how did it get there? and receive a provable answer.
Three things in that picture matter more than the boxes:
The heart of the methodology is a rule you already know from every other high-stakes field: the one who did the work never certifies the work. A model reviewing its own code inherits its own blind spots — it re-reads its mistakes as intentions. So COPS staffs each change like a case, with independent minds at every step.
Two habits make this loop terminate instead of running forever. First, a stopping rule is set before the round starts (“checks green and every thread resolved → merge; anything raised after that becomes a ticket”) — because a sufficiently keen reviewer can always find one more nitpick. Second, fixes for a round are batched into one commit, so the reviewers re-read one new version, not a drizzle of ten.
Everything above could be done on trust — and would then be worth nothing on the day someone (a human or a model) cuts a corner. So each completed stage signs a receipt: a small structured record naming the stage, the executor, the time, and — crucially — the fingerprint of the exact code version it checked. Receipts link, each one binding to its predecessor, forming a chain the merge gate verifies mechanically.
Three properties are worth understanding even if you never look at a receipt:
A page that asks you to trust receipts owes you the boundaries of that trust, stated before you ask.
What a receipt proves: that a named stage completed, in order, bound to the exact code version, with its provenance disclosed, and that the whole chain re-verified at merge time. What it doesn’t: the quality of the work itself — that judgment comes from the independent reviewers and the automated checks, witnesses the author doesn’t control. Receipts are honest bookkeeping; the bots and checks are the substance.
Today, receipts are signed and the enforcing gates run on the operator’s own machine. That means COPS currently protects you from mistakes, drift, and cut corners — an agent or operator skipping a stage, merging on stale evidence, forgetting a check — by making the skip visible and the merge refusable. It does not yet make bypass impossible for a determined operator on their own machine, and this guide won’t pretend otherwise. The target architecture closes that gap by moving enforcement server-side — required checks on the code host that no local machine controls — and is rolling out repo by repo on an observe → advise → enforce ladder. The code host’s own web merge button is part of the same story: enrolled repositories close it with the host’s protection rules, the very substrate the server-side enforcement builds on.
Assume a model will eventually be fooled — by a poisoned document, a malicious dependency, a cleverly worded issue. The design answer is not “our models are too smart for that.” It is that a fooled model still hits the same walls a careless one does: gates that fail closed, destructive actions that stop for a fresh human approval with the exact target named, one-way doors that hold, and evidence that makes a skipped or forged stage visible after the fact. COPS does not claim a model can’t be deceived — only that a deceived model cannot merge without evidence or destroy without a human’s explicit, per-action yes.
Most of the time the pipeline runs without you. It interrupts for exactly the decisions it is not entitled to make — and every interruption arrives as a notification, states its reason, and waits. Here is the complete vocabulary of those moments:
| Moment | What it means | What you do |
|---|---|---|
| PLAN APPROVAL | Before any real implementation starts, the reviewed plan is presented with a fingerprint (hash) of the exact text you’re approving. If the plan changes later, the fingerprint changes and approval is required again — the plan can never drift silently from what you signed. | Read it. Approve it, amend it, or reject it. Your approval is bound to that fingerprint. |
| HELD FOR A HUMAN | The pipeline met a judgment call — a one-way door (an action that can’t be undone), a review round that stopped converging, a gate it couldn’t classify. Work is parked safely, nothing is lost. | Read the stated reason, decide, signal. The task resumes exactly where it paused. |
| DESTRUCTIVE ACTION | Something irreversible — deleting, overwriting, an action against live infrastructure or a whole fleet of repositories. These always stop, with the exact target named. Approval is never standing; it is for this action, on this target, now. | Confirm the named target is what you intend, or refuse. When in doubt, refuse — a held task costs minutes. |
| FAILED — ESCALATED | An invariant broke or evidence couldn’t be verified. The system froze the task rather than improvising. This is rare, and it is the system telling the truth. | Don’t force it through. Read the trail (it’s complete), fix the cause or hand it to someone technical, and let the pipeline re-verify. |
| MERGE AUTHORITY | Repositories declare who may authorise the final merge. Some allow the machinery to merge on a fully verified chain; others require a fresh human go-ahead, bound to the exact version being merged. Absent that authority, the task holds — it never falls through to merging by default. | Where your say-so is required, you give it per-merge, with the version fingerprint in front of you. |
Whenever the machinery is unsure whether it may proceed, the answer is always no, hold, and ask — never “probably fine.”
By the time the first command below is typed, the work has already been defined, planned, approved, claimed, and built — test-first, in an isolated lane (a private working copy of the code) — per Where work begins and How a task moves above. The commands are the proving half of the journey, and they are typed into your Claude Code session: each /command invokes a full packaged procedure that runs the stage and signs its receipt. You invoke the stage; you never perform it from memory. In order:
| Stage | Command | What actually happens |
|---|---|---|
| 1 · Review | /review | An independent model reads the finished change against the codebase and the plan. Findings become fixes before anything goes further. |
| 2 · QA | /qa | The change is exercised — tests run, the product is actually driven, documentation coverage is checked. “It runs” is not QA. |
| 3 · Ship | /ship | Version and changelog are updated, the change is pushed, and the pull request opens — the moment the work goes public to the review bots. |
| 4 · Bot loop | /pr-loop | Every bot finding from every source — inline comments, review bodies, statuses — is fixed, answered, and resolved, round by round, until the reviewers have nothing left. |
| 5 · Land | /land-and-deploy | The chain is verified against the final version, the merge executes pinned to that exact fingerprint, deployment runs, and a live check proves it’s really working. |
What “green” means when you’re asked to trust it: every required check passed on the final version of the code, every reviewer finding was resolved, the receipt chain verifies end-to-end against that same version, and the live proof came back healthy. If any of those is missing, the system will have told you which one and why — that’s the difference between this green and a dashboard’s green.
Honesty first: today, COPS installs from this repository by an operator who has done it before, and the installer enrols one repository at a time. A one-command public installer is on the roadmap as part of the open-source release; this section will be rewritten — and re-certified — when it lands.
What installation actually does, in plain terms:
The one discipline installation asks of you afterwards: keep the installed layer current. Upgrades are deliberate re-runs of the installer, and the platform’s own telemetry will tell you when an enrolled repository is running behind.
A guide to a system of receipts should not itself be taken on faith. This document is a controlled document, maintained under the same doctrine as the code:
shasum -a 256 on the saved page, compared against the ledger entry). Until then, the plate tells you what was certified and when; the proof is internal.If you find the guide and the system disagreeing, the system is right and the guide has a defect — report it to the author, and the ledger will show the correction land as a new certified revision.