# 12-Factor AgentOps > The doctrine for trustworthy agent-built software: twelve operating rules for fixed intent, one bounded build, fresh validation, and a content-addressed verdict. No verdict, not done. --- # The 12 Factors ## 01 Ship Packets Not Transcripts ## Rule Brief each agent with a bounded packet: the exact intent source, constraints, relevant files, and proof command. That packet is the interface between units of work. The running transcript stays behind. A transcript accumulates; a packet is selected. When work moves from one context to another, pass the caller-owned bead, issue, or intent snapshot plus the evidence the next role needs. AgentOps does not require a second model-written plan packet that can drift from the source. ## Put It to Work - Start every unit of work from the caller's durable intent: task, boundary, relevant files, constraints, validation path. - Hand work between agents as packets (findings, decisions, open questions). Leave raw transcripts out of the handoff. - Keep unrelated history, broad docs, stale assumptions, and speculative plans out of the window. - Amend the source when the task changes instead of dragging an obsolete brief forward. ## Failure Signal - A handoff pastes the whole conversation because nobody decided what mattered. - The agent repeats itself, ignores recent instructions, or asks for information it already saw. - The answer sounds plausible but cannot point to files, commands, or evidence. - The session keeps growing because nobody knows what can be removed. ## Done Looks Like The next context can state the task, boundary, relevant files, and proof command from the same intent source without reading the author's transcript. ## 02 Keep Ground Truth In Git ## Rule The repository is the ground truth. Work state, decisions, evidence, and learnings live in git; everything else (sessions, terminals, task lists, dashboards) is a projection that dies with its host. Sessions are disposable. A terminal closes, a context window compacts, a host reboots, and whatever lived only there is gone. The store survives because it is files in a repo: diffable, reviewable, cloneable by the next agent. ## Put It to Work - Put issues, plans, session notes, validation evidence, and promoted learnings in repo-owned files. - Treat in-memory task lists and live sessions as views over the store, never as the store. - Make every meaningful change diffable and reviewable. - Push finished work so the remote is the shared source of truth. ## Failure Signal - A decision exists only in chat history. - Ending a session loses work state that no file records. - A new agent needs credentials to five systems before it can see the project state. - A handoff says "check my notes" instead of pointing to committed files. ## Done Looks Like A fresh clone contains the work, the issue state, the evidence, and enough history for the next agent to continue, with every live surface reconstructable from it. ## 03 One Agent One Job ## Rule Give each job the smallest sufficient agent: one bounded job, one fresh context window, no more machinery than the job needs. The corollary cuts the other way: a one-shot task gets no orchestration. If a single agent with a clear brief can finish the job, adding coordination layers only adds failure modes. Scale the agent shape to the work: split when context needs differ; keep one agent when they don't. ## Put It to Work - Scope each assignment tightly enough that completion is obvious. - Split research, implementation, review, and release work when their context needs differ. - Start a new session for a new phase instead of appending work to a saturated thread. - Reach for a single agent first; add coordination only when the work demonstrably exceeds one. ## Failure Signal - A research-heavy session starts editing code from stale assumptions. - A five-minute fix acquires a plan, a queue, and three coordinating agents. - The task cannot be summarized in one sentence. - The session is kept alive because "it already knows the project." ## Done Looks Like The agent has one job, one owner, one workspace, and a clear stopping condition. The setup is no bigger than the job required. ## 04 Cap The Blast Radius ## Rule Before an agent acts, bound what it can touch and what it can spend. The envelope has walls (capabilities, file scope, credentials) and a meter: budget caps, step caps, attempt caps. Untrusted input must never widen the envelope. A fetched page, a file, a tool result can ask for anything; the envelope answers. And the meter is not optional: public reports of runaway agent runs burning five-figure bills in a weekend all share one root cause: nobody set a number the run could not exceed. Isolation is the license for autonomy: the tighter the envelope, the more freely the agent can act inside it. ## Put It to Work - Deny by default; grant the minimum capability the task needs, then revoke it. - Set explicit budget, step, and attempt caps before unattended work starts. - Treat fetched and loaded content as untrusted: it cannot change what the agent may do. - Keep secrets out of context, commits, learnings, and traces unless the task requires them. - Put destructive or irreversible actions behind an explicit grant or a human gate. ## Failure Signal - Agents run with broad or shared credentials "because it's easier." - A retry loop runs all night because no attempt cap existed. - A prompt injection in fetched content changes what the agent does. - "How much could this run cost?" has no bounded answer. ## Done Looks Like The blast radius of a mistake or a compromise was bounded before the agent acted: what it could touch, what it could spend, and where it had to stop. ## 05 Map The Terrain Then Pave It ## Rule Map first: read the code that owns the behavior, find the existing patterns, name the risks, before anything is built. Then pave: turn what the map found into instructions files, contracts, and tests: a surface later agents can drive on without rediscovering the terrain. Paving beats model quality. Public reports from one large open-source repository found that adding a repo instructions file roughly doubled an agent's task success rate, from about 38% to 69%, with no model change at all. Written-down conventions, machine-checkable contracts, and tests are cheaper than intelligence, and they don't reset when the session ends. ## Put It to Work - Read the files that own the behavior before changing it; search for existing patterns before adding new ones. - Identify the validation commands before implementation begins. - Write findings into repo instructions, contracts, and tests. Leaving them only in the current session wastes the map. - Treat every mapped trap as a paving candidate: if an agent fell in once, put a rail there. ## Failure Signal - The patch duplicates a helper that already exists. - The agent says "I assume" when the repo can answer the question. - The same terrain gets re-researched every session because nothing was written down. - Conventions live in one person's head and surprise every new agent. ## Done Looks Like Before editing, the agent can name the owner files, the local pattern, the risk, and the proof command. What it learned is paved into files the next agent inherits. ## 06 One Lane One Owner ## Rule Every concurrent worker gets a lane: an isolated workspace and exclusive ownership of the files it may edit. One lane, one owner. A claim on a task list does not lock a file. Write-scope ownership is the license for parallelism. Two agents can work at full speed only when neither can touch what the other owns. Isolation also makes workers disposable: when a sealed-off worker fails, delete it, spawn a fresh one, reassign the job. The tracked task is durable. The worker is disposable. ## Put It to Work - Give each worker its own isolated checkout of the repo. - Assign disjoint file ownership before parallel work starts; combine tasks that touch the same file. - Keep conversation history and tool state separate per worker. - Integrate through review, tests, and explicit merge steps. Shared mutable state is not a coordination channel. ## Failure Signal - Two workers edit the same surface because "the task list said it was theirs." - One agent reads another's uncommitted changes and treats them as baseline. - A failed worker leaves shared state that changes another worker's output. - Merge conflicts become the primary coordination mechanism. ## Done Looks Like Each worker can succeed or fail independently inside its own lane, and integration happens through a deliberate gate. ## 07 No Verdict Not Done ## Rule Before a change counts as done, a fresh context has to judge it. The author supplies the candidate and factual check receipts. Validate recomputes the exact subject, checks the fixed intent and changed scope, judges every criterion, and writes `PASS`, `FAIL`, or `NOT_PROVEN`. Three properties make the gate real. Identity binds the verdict to the exact intent and content. Freshness separates authorship from judgment. Evidence makes every criterion inspectable. Deterministic tests and builds establish facts; the fresh validator decides whether those facts satisfy the intent. Missing identity, freshness, scope coverage, or evidence produces `NOT_PROVEN`, not a confident guess. ## Put It to Work - Keep claim and verdict separate: the author supplies evidence, a fresh context decides. - Bind validation to the exact intent digest and subject manifest. - Use deterministic checks for facts and criterion-level evidence for meaning. - Persist the content-addressed verdict with checked and unchecked scope. - Report the result and stop. The caller owns any later revision or retry. ## Failure Signal - The closeout says "looks good" but names no command. - The same context that wrote the patch checks only the happy path it expected. - A gate got relaxed because "the new model doesn't need it." - The validation step cannot fail. ## Done Looks Like The candidate has a fresh `verdict.v2` bound to unchanged intent and exact content, with evidence for every criterion and an explicit list of what was not checked. ## 08 Ratchet The Baseline ## Rule A verified result can become the new floor after the caller accepts and lands it. Keep the verdict with the change, then turn the behavior into a test or check that later work must still pass. Done requires a verdict. A pull request can merge on optimism and still leave the floor where it was. Progress is the change that passed its gate and became the new baseline. One large open-source repository's ten-month public dataset makes the social version of this rule visible: hundreds of agent-authored pull requests, every one held at draft until a human reviewed it, over half needing human follow-up commits before landing. The airlock is what made the throughput safe. ## Put It to Work - Let the caller's repository policy decide whether verified work is committed, pushed, or merged. - Record the proof that made each change acceptable alongside the change. - Close or update the issue that tracked the work; file follow-ups for unfinished scope. - Treat any regression below a ratcheted baseline as a stop-everything event. Do not file it as flaky. ## Failure Signal - A fix exists only in an unpushed local checkout. - Work merges because it looked finished, and the gate runs afterward, or never. - A later agent reopens solved ground without knowing it was solved. - The project cannot tell a failed attempt from accepted progress. ## Done Looks Like The accepted change is landed under repository policy, its verdict remains inspectable, and a later regression fails a named check. ## 09 Close The Learning Loop ## Rule Keep two ledgers with different jobs. [Beads](https://github.com/steveyegge/beads) records the work, acceptance, decisions, and evidence. A reviewed LLM wiki records the smaller set of explanations and patterns worth reusing. Link them so every durable claim has a trail back to the work that tested it. The model does not learn because a session ended. An LLM can draft a wiki page, propose links, and flag stale material. Review decides what the page may claim. A later task links the page when it is relevant. ## The Two Ledgers | Surface | What it records | Question it answers | | ----------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------- | | Beads | Intent, acceptance, dependencies, status, decisions, and evidence | What are we doing, and what happened? | | Reviewed LLM wiki | Source-linked explanations, patterns, decisions, and maintenance notes | What should a future session know, and where did it come from? | An issue tracker alone scatters reusable knowledge across closed work. A wiki alone can become a polished story detached from the evidence. The link between them makes the record inspectable. ## Put It to Work 1. Start with a bead or another durable intent source that names the work and acceptance. 2. Run the implementation and record the result next to the original intent. 3. Promote a lesson only when it generalizes beyond that task. 4. Make the wiki page cite the bead, commit, verdict, or other source that supports it. 5. Link the relevant page from a later bead before implementation starts. 6. Open repair work when the page proves stale or wrong. Most sessions should not create a wiki page. Good candidates prevent a repeated mistake, preserve an architectural decision, or document a procedure another operator must run. Transcript dumps, status updates, and unsupported hunches stay out. ## Where AgentOps Fits [AgentOps](https://github.com/boshu2/agentops) runs the binding work loop: Plan fixes the intent, Implement builds one bounded candidate, and a fresh Validate context judges the same acceptance and evidence. It writes a durable verdict and stops. The wiki is optional later work. It may inform a future plan, but it cannot change the verdict for the current candidate. This boundary keeps reusable knowledge useful without turning it into a second source of truth. ## Failure Signal - A wiki page has no source or review date. - Every session creates another page, including one-off status notes. - Closed beads contain repeated lessons that nobody can find. - A future task loads the whole wiki instead of linking the small relevant slice. - A stale page remains authoritative because there is no repair path. ## Done Looks Like A later bead links one reviewed page, that page cites the work that supports it, and a named repair path exists if the guidance stops being true. ## 10 Own The Verdict Rent The Conductor ## Rule Build and own the machinery that decides whether work is real. Rent everything that merely moves the work around. Dispatch, queues, worker pools, session management, isolation: that is the conductor, and it is a commodity. Every agent vendor ships more of it each release, and whatever you build in-house will be obsoleted by someone's next launch. We learned this the expensive way: we built the conductor twice, and both died the same death, outrun by the platforms within months. What no platform ships is a binding verdict, computed by checks you wrote for your own codebase, stored where the author can't touch it. The market is full of conductors and advisory reviewers; a verdict that can actually block is the part you must own, because it encodes what _your_ system means by done. ## Put It to Work - Put engineering effort into verdict machinery: gates, checks, refuters, the record of what passed. - Take orchestration from the platform you already run; replace it freely when a better one ships. - Keep the verdict layer portable: plain files and commands in your repo, not a vendor feature. - When a new orchestration surface launches, migrate the conductor and keep the gates unchanged. ## Failure Signal - The team maintains a bespoke dispatcher while validation is still "the agent said it passed." - A vendor release obsoletes a year of in-house orchestration work. - Review tooling is advisory: it comments, but nothing blocks. - Switching platforms would mean losing the definition of done. ## Done Looks Like Orchestration is rented and replaceable; the verdict (the checks, the gate, the record) is yours, survives every platform migration, and is the one thing that can say no. ## 11 Stop The Line ## Rule When an agent hits ambiguity, missing information, or failure, it reports the boundary and stops. Guessing forward is how small confusions become large incidents. AgentOps runs Plan, Implement, and fresh Validate at most once. `FAIL` and `NOT_PROVEN` are terminal results for that invocation. The caller may revise the original intent and start another experiment, but the core never repairs, retries, or selects the next action by itself. ## Put It to Work - Define stop conditions up front: ambiguous intent, missing authority, subject mutation, and incomplete evidence. - Preserve `FAIL` and `NOT_PROVEN` as evidence instead of rewriting them into success. - Amend the original intent when acceptance changes; do not create a parallel revision story. - Keep the next decision with the caller. ## Failure Signal - An agent resolves ambiguity by picking the interpretation that lets it keep going. - Work bounces sideways between peers until nobody knows who owns the decision. - The same failure retries all night because stopping was never an option. - Humans discover the incident from the damage. No escalation fired. ## Done Looks Like The invocation reports its exact boundary and stops. Any later run begins from a deliberate caller decision and the amended source of intent. ## 12 Price The Proof ## Rule Verification has a price. Measure what verified-done costs (tokens, minutes, review effort) and drive it toward the cost of unverified-done, without giving up the verdict. Rigor is tiered by risk, because proof you can't afford is proof you'll stop running. A deterministic check is nearly free; a fresh-context review costs more; an adversarial cross-model review costs most. Spend the expensive tiers where mistakes are expensive, and let the cheap tiers carry the routine. Metered cycles answer the question every unattended run must face: was the outcome worth the tokens? ## Put It to Work - Track the cost of each verification tier alongside the outcomes it caught. - Match rigor to risk: deterministic checks for routine work, escalating review for irreversible or high-blast-radius changes. - Tie metrics to goal movement: proof quality, recurrence, lead time. Agent activity alone is not a goal. - Reject metrics that reward token burn, session count, or code volume by themselves. ## Failure Signal - Every change gets the most expensive review, so verification quietly gets skipped under deadline. - The dashboard improves while the product does not. - Nobody can say what a verified change costs versus an unverified one. - A metric cannot tell you whether to continue, stop, or roll back. ## Done Looks Like Each verified change carries a known cost, that cost trends toward the unverified baseline, and every measured number helps decide whether the loop is making delivery better.