> the doctrine behind the operational layer
12-Factor AgentOps
The principles behind bookkeeping, validation, primitives, and flows
AgentOps is the operational layer for coding agents. 12-Factor AgentOps is the doctrine behind it: the public rules that explain why bookkeeping, validation, primitives, and flows compound instead of resetting every session.
Inspired by The Twelve-Factor App, 12-Factor Agents, and HumanLayer.
The 12 Factors
Context Is Everything
Manage what enters the context window like you manage what enters production.
Track Everything in Git
If it's not in git, it didn't happen.
One Agent, One Job
Each agent gets a scoped task and fresh context. Never reuse a saturated window.
Research Before You Build
Understand the problem space before generating a single line of code.
Validate Externally
No agent grades its own work. Ever.
Lock Progress Forward
Once work passes validation, it ratchets — it cannot regress.
Extract Learnings
Every session produces two outputs — the work product and the lessons learned.
Compound Knowledge
Learnings must flow back into future sessions automatically.
Measure What Matters
Track fitness toward goals, not activity metrics.
Isolate Workers
Each worker gets its own workspace, its own context, and zero shared mutable state.
Supervise Hierarchically
Escalation flows up, never sideways.
Harvest Failures as Wisdom
Failed attempts are data. Extract and index them with the same rigor as successes.
// ready_to_start.sh
Start with Factor I
Begin with context management and build the foundation for durable bookkeeping, validation, and compounding work.
Begin Factor I