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

Don't run production
on vibes.

Agents generate code with no record of what was tried, no gate it had to pass, no proof it works. Twelve operating rules close that gap. Before a change counts as done, something that didn't write it has to check it. No verdict, not done.

Run it in your agent →GitHub ↗Read the 12 factors →

// 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 — and Govern feeds back into the next brief.

BRIEF THE AGENTI - IIIcompile what the actor needs
IPacketsBrief each agent with a compiled packet; the packet, not the transcript, is the interface.IIGround TruthKeep work state, decisions, and learnings in git; sessions are disposable, the repo is not.IIIScopeGive each job the smallest sufficient agent; a one-shot task 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 worker reports evidence; an independent deterministic check writes the verdict.VIIIRatchetTurn every verified result into a baseline the system cannot slip back below.IXLearnCapture what the session learned and re-inject it at the next plan — one loop, not two jobs.
GOVERN THE LOOPX - XIIsteer the system
XOwnBuild and own the verdict machinery; rent the orchestration around it.XIStopOn ambiguity or repeated failure, stop and escalate instead of guessing forward.XIIPriceTrack what verified work costs and drive it toward the cost of unverified work.

// the three gaps they close

The failure modes that make agent work unreliable, each closed by a named surface.

G1JUDGMENTPressure-test plans before code.closed by /pre-mortem · /validate · /council
G2DURABLE LEARNINGSolved problems stay solved: the measured, still-unproven bet.closed by /post-mortem · ao search · ao lookup
G3LOOP CLOSUREShipped work compounds into the next session: measured, still unproven.closed by /post-mortem · the promotion ratchet · /rpi

// the bet

THE WAGER — Vendors will ship managed memory, review councils, and overnight learning loops natively; they will lock them to their runtime. Your corpus stays in .agents/ in your repo, runs on whichever harness you already pay for, and is portable across whichever frontier model wins next quarter.

Good architecture principles outlive every tool that implements them.
// your agent said done; something else proved it. the proof is yours.
the corpus stays yours