Skip to content
~/agentops
GitHubInstall
// 12-FACTOR AGENTOPS

Don't run production
on vibes.

Twelve operating rules for running coding agents whose work you can trust. An agent says done after one green test run. Whether the change does what you asked is a separate question, and the agent that wrote it is the worst one to answer it. These rules put a fresh reviewer between that claim and your acceptance: a context that didn't write the change, citing evidence for every criterion or naming what's missing.

Read the 12 factors →Install and try Research →GitHub ↗

// the 12 factors

all 12 →

Four tiers a unit of work passes through: Brief the Agent, Lay the Rails, Gate the Work, Govern the Loop. Govern feeds back into the next brief.

BRIEF THE AGENTI - IIIcompile what the actor needs
IPacketsPass exact intent and bounded evidence between roles; leave the author transcript behind.IIGround TruthGive every claim one authority: Git for content and history, the tracker for work, the runtime for execution.IIIScopeGive each job the smallest sufficient agent; a job one agent can finish gets no orchestration.
LAY THE RAILSIV - VIconstrain where work can go
IVBlast RadiusBound what an agent can touch and spend: capabilities, budget, steps, attempts.VPaveResearch the terrain first, then pave it with instructions, contracts, and tests.VILanesGive each concurrent worker exclusive ownership of what it edits; claims are not locks.
GATE THE WORKVII - IXdecide what survives
VIIVerdictThe author supplies evidence; a fresh context judges the exact change, and the author cannot pass itself.VIIIRatchetLand accepted work and leave a check behind that later changes must still pass.IXLearnYour tracker keeps the work; reviewed project context keeps knowledge worth reusing, after review.
GOVERN THE LOOPX - XIIsteer the system
XOwnBuild and own the verdict machinery; rent the orchestration around it.XIStopStop at boundaries you lack authority to cross; repair failures inside accepted scope.XIIPriceTrack what verified work costs, drive it toward unverified, and never buy green by weakening acceptance.

// the three gaps they address

Three failure modes. Each one has a named operating surface.

G1JUDGMENTA fresh reviewer checks the exact change against the accepted request.addressed by native checks · fresh independent review
G2DURABLE CONTEXTYour tracker owns the work; reviewed project context keeps knowledge worth reusing.addressed by your tracker · reviewed .context/
G3LOOP CLOSURERepair failures inside accepted scope, then finish on a fresh judgment.addressed by accepted intent · checks · bounded repair · fresh judgment

// the route to done

Enter wherever the work is. Every route ends at the same place: a fresh judgment of the exact change.

AgentOps routes. Clear, accepted intent goes straight to implementation and checks. Unclear intent goes to Plan first, then to implementation. An existing change goes straight to fresh independent judgment. Judgment finishes when acceptance is established, sends failed behavior back to implementation, and sends missing evidence out to be gathered before judging again. Repair stays within real limits; when they are spent, the work goes back to the caller. Beside it, an optional learning loop takes a result to a protected draft outside Git, then a fresh support and disclosure review, then reviewed .context/ pages that later work queries.
Accepted intent → native implementation and checks → fresh independent judgment → finish

INDEPENDENT JUDGMENT · The context that wrote a change can't issue its PASS. A fresh reviewer checks the exact result and returns PASS, FAIL or NOT_PROVEN, and PASS needs evidence for every criterion. Failed behavior goes back to implementation, missing evidence gets gathered, and the updated change is judged fresh. Intent that turns out ambiguous mid-work, missing authority, or spent limits stop the line and come back to you. Your repository keeps Git, merge, release, and rollback.

Your tracker owns the work. Git owns the content. A reviewed .context/ holds what later work can reuse.
Drafts stay in protected storage outside Git until a fresh review checks their support and disclosure. Reuse counts only when later work shows it helped. See the maintenance loop →

// the reference implementation

AgentOps is the reference implementation of these rules: 36 optional skills for Claude Code, Codex and other coding agents. Your agent does the work with your existing tests, tracker, and Git. This site tracks AgentOps v3.8.0; the details of each release live in its README and release notes.

Browse the 36 skills →v3.8.0 README ↗v3.8.0 release notes ↗

// start where the work is

Each entrypoint is an independent choice. Pick the row that matches your task; Plan is optional, and a clear task can go straight to your agent.

where you areenter withwhat you get
You know what needs to changeImplement, or Test and Refactor for focused workThe change, with the checks that ran against it.
Behavior or scope is unclearPlan or ResearchPlan settles the behavior. Research traces the code and cites files and lines.
A change or design already existsReview or ValidateReview gives advice. Validate returns PASS, FAIL or NOT_PROVEN against acceptance.
Work spans tasks or agentsOrchestrateDisjoint scopes, one integrated change, and a fresh judgment of it.
Earlier work may answer itMemoryReviewed context that can change the next step, with its sources.

The Research task on the install page is read-only and needs no ao CLI, so it's the safest first run in a repository you already work on.

Try the read-only Research task →
// your agent said done; something else proved it. the proof is yours.
make the change inspectable