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 force a recorded check before done. 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. 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 TruthKeep work state, decisions, and learnings in git so the next session reads the repo, not a dead chat.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 author supplies evidence; a fresh context judges the exact intent, scope, and result.VIIIRatchetLand accepted work with its proof so later changes can test against that floor.IXLearnUse Beads for the work trail and a reviewed LLM wiki for reusable, source-linked knowledge.
GOVERN THE LOOPX - XIIsteer the system
XOwnBuild and own the verdict machinery; rent the orchestration around it.XIStopReport ambiguity or failure and stop; the caller decides whether another run exists.XIIPriceTrack what verified work costs and drive it toward the cost of unverified work.

// the three gaps they address

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

G1JUDGMENTFresh Validate judges the fixed intent, exact scope, and current evidence.addressed by Plan · Implement · fresh Validate
G2DURABLE CONTEXTBeads preserve the work; a reviewed LLM wiki preserves reusable knowledge.addressed by Beads · reviewed LLM wiki
G3LOOP CLOSUREA durable verdict ends this experiment; later learning remains optional work.addressed by verdict.v2 · optional Learn

// the boundary

ONE EXPERIMENT · Plan → Implement → fresh Validate → durable verdict → report and stop. AgentOps owns that proof boundary. Your repository still owns retries, Git, merge, release, and every later decision.

Beads preserve the work trail. A reviewed LLM wiki preserves reusable knowledge and its sources.
Review decides what enters the wiki. A later task links what it needs. The model does not learn merely because a session ended. See the maintenance loop →
// your agent said done; something else proved it. the proof is yours.
the verdict stays inspectable