boshu2__agentops/docs/3.0.md

AgentOps 3.0: the north star

This is the single source of truth for what AgentOps 3.0 is. Decision records: ADR-0002 (hookless) and ADR-0009 (daemon deletion / in-session-only identity). Mechanism: docs/cdlc.md. The loop model: canonical-loop-model.md. Execution discipline: operating-loop.md. Seams: ports-and-adapters.md. Everything else in the repo should be consistent with this page; when a doc disagrees, this page and the executable behavior win.

AgentOps 3.0 is the in-session agent operating loop and the context compiler that feeds it. It compiles the best of software engineering into compact, verifiable, reusable agent context, then compounds that context across every session, model, and harness. The product is the in-session loop plus the corpus it compounds. It is not a hook bundle, not a daemon, and not a hosted control plane.

---

The thesis in one paragraph

A software factory runs the same loop at every scale: turn declared intent into validated work, then recycle the exhaust as context for the next turn. AgentOps names that loop, runs it in session, and makes the exhaust first-class. Skills are the portable agent runtime. rpi is the inner loop, one research-plan-implement-validate cycle. evolve is the outer loop, N rpi cycles toward a goal. crank and swarm are the in-session agent teams that fan a wave out across worktrees. The loops are fractal: the same shape at every layer, run by a human or by a stand-in agent. Context is the engineering artifact handed off at every loop edge, and it compounds at every level. The .agents/ corpus is where it accumulates, and it is the moat. Running that loop out of session — always-on, scheduled, queue-driven — is a separate concern that AgentOps delegates to an orchestration substrate.

---

The 3.0 loop (the whole product, in one picture)

The SDLC is a loop for producing reliable code from non-deterministic humans. The CDLC (Context Development Life Cycle) is the same loop for producing reliable context for non-deterministic agents. 3.0 runs that loop:

SDLC (code)  ─────────────  CDLC (context, the same loop)

intent  ──▶  behavior, written as BDD / Gherkin     ← behavior-driven PLANNING
            (Given / When / Then is the plan)
        ──▶  tests derived from the behavior          ← TDD: the behavior's executable proof
        ──▶  implement inside ONE bounded context     ← DDD vocabulary + boundaries
             through explicit ports                    ← hexagonal seams (domain never imports the shell)
        ──▶  validate BOTH ENDS against behaviors + contracts
               entry: does the planned behavior hold up?   (/pre-mortem, /council)
               exit:  does the implementation satisfy it?   (/vibe, CI gates)
        ──▶  feedback: pass/fail on behavior + contract IS "is it good?"
        ──▶  ratchet the learning back into the corpus  ← compounding, dense
        └───────────────────────── loop ──────────────────────────┘

Behavior is the plan. Tests come from behavior. Contracts and behaviors are what you validate on each end of an implementation, and that is how the system feeds back whether the work is good. Between every step, context density is the rule: every high-value token carries intent, a boundary, evidence, a decision, a constraint, or a next action, and nothing else, so the loop stays cheap.

This loop runs end-to-end in a plain session today, with zero AgentOps-managed always-on infrastructure. It was proven end-to-end (T4/T5) on 2026-05-24: .agents/discovery/2026-05-24-gvkj6-e2e-proof.md.

---

Fractal loops: one shape at every scale

The 3.0 loop above is not a single ceremony. It is one tick that nests inside itself.

• rpi is one tick: research, plan, implement, validate over one bead, one behavior, one acceptance proof.
• evolve runs N rpi ticks toward a goal, selecting the next-best work, running a post-mortem, and repeating.
• crank / swarm fan one wave of an rpi tick across an in-session team of agents in isolated worktrees.

Each scale has the same five beats and the same ratchet. The only differences between scales are the driver (a human in a session, or a stand-in agent) and the stop policy (a session ends with its budget; an out-of-session driver stops only on an operator marker). This is why the model collapses cleanly to one loop body, two drivers, one inner tick, one config, documented in canonical-loop-model.md.

This shape has a lineage. It is the reconciliation loop applied to agent work (Kubernetes-era control plane, 2025), refined into typed loop code with explicit ratchet rules (Mount Olympus, 2026), and crystallized here as named inner and outer loops over a compounding context corpus. The recurring unit was always a loop that turns intent into validated work and feeds its own output back in. 3.0 names it and makes the compounding artifact, context, the point.

---

What makes the loop compound instead of repeat: the ratchet rules

A loop that runs without rules repeats flat. Three invariants turn repetition into compounding:

Rule	What it forces
No self-grade	The agent that did the work never validates its own work. Validator is not implementer.
Fresh agent on failure	On failure, spawn a fresh-context agent rather than retrying inside a saturated window. A failed attempt's context is exhaust, not seed.
Knowledge becomes constraints	A learning is not durable until it compiles into a gate, a test, or a rule that prevents the next regression. Prose advice decays; a constraint holds.

These are the difference between a corpus that grows into a landfill and one that grows into a moat. They are enforced by the promotion ratchet in operating-loop.md, not by hooks. Both reference implementations honor the same three rules — that is what makes "one doctrine, two implementations" true rather than aspirational.

---

The four load-bearing practices (the narrow waist)

3.0 introduces no new methodology. It composes four proven practices into a small, executable waist, and everything else attaches to it:

Practice	What it gives the agent
BDD / Gherkin	Observable intent as behavior; the densest signal-per-token planning channel there is
DDD	Shared vocabulary and bounded contexts humans and agents both use
Hexagonal (ports & adapters)	Explicit seams: the domain core never imports the runtime; tools, vendors, and substrates live outside as adapters
TDD	A local, executable done-condition for every slice

Around the waist: CI/CD repeats the proof, SRE/DORA measure fitness, ADRs and provenance preserve why-memory, the wiki and ratchet preserve durable learning, Agile/XP keeps work in vertical slices. The atomic unit is one behavior, one bounded context, one failing test, one write scope, one acceptance proof. A new learning is added only when it would change a future run.

---

Hookless-first: density over noise

Hookless-first is the most misunderstood part, so be precise.

3.0 ships zero hooks. The hooks were deleted, not demoted. Context flows through explicit, bounded channels instead of being pushed in as noise.

• The 2.x failure mode: hooks were the architecture. Dozens fired on every event and pushed context into the window: standards for files you were not touching, learnings that did not apply, warnings that did not fire. Resident context stacked (a real RPI run hit ~10.35M tokens at 97.6% cache-read), and the A/B eval showed the injected context made no difference (delta = 0). The problem was never hooks; it was noise stacking in the prompt.
• The 3.0 model: context is pulled through explicit channels. BDD/Gherkin for intent, execution and context packets through ports for the phase-scoped working set, hexagonal boundaries for the seams. Dense and just-in-time, not stacked.
• The default install works with zero hooks. Workflow is guided by skills plus the ao CLI, and CI is the authoritative gate. If you want a bounded gate of your own (block a dangerous operation, bootstrap a session, run a parity check), author it with the hooks-authoring skill. AgentOps does not ship one.

The rule in one line: context is pulled, dense, and just-in-time; nothing sprays noise into a prompt.

---

In session is the product; out of session is the substrate's job

3.0 draws a clean line between what AgentOps owns and what an orchestration substrate owns.

AgentOps owns the in-session loop and the context: rpi and evolve, crank and swarm, the ratchet rules, the skills runtime, the context compiler (ao inject, ao compile), and the .agents/ corpus. All of it runs in a plain session with zero AgentOps-managed daemon, scheduler, or always-on runner.

An orchestration substrate owns out-of-session execution: when work runs unattended, the queue, which agents run it, how they are supervised and coordinated, and where the human sits on the loop. AgentOps does not ship any of this. The standalone daemon, scheduler, and overnight runner were deleted in the 3.0 rearchitecture (not deprecated, not retained-behind-a-flag — removed; see ADR-0009). Out-of-session orchestration is delegated to a substrate, and AgentOps ships a reference one.

The governing test: is it about when, where, who supervises, or coordination? That is the substrate. Is it about what the loop does or how context compounds? That is AgentOps.

Domain	Owner	Primitives
Orchestration: when / where / who-supervises / coordination	Substrate (reference: NTM + MCP + managed-agents)	a tmux agent swarm (NTM), the MCP tool surface (ao mcp serve), managed/agent-SDK drivers (ao agent), cron/event triggers, the bead queue, human on the loop and merge, runtime providers
The in-session loop + the context: what the agent does, how context compounds	AgentOps	the /rpi and /evolve loops (run as skills), crank/swarm, the ratchet rules, skills, ao inject / compile / maturity, the .agents/ corpus

rpi is never re-expressed in the substrate. Decomposing it into substrate-side steps would duplicate the loop shape (the exact surface-sprawl disease, re-introduced across the seam) and pit the substrate's retry machinery against the ratchet rules. Whoever owns the loop owns its invariants, and AgentOps owns the loop. The substrate dispatches a whole loop as one unit — it spawns an agent that runs the /rpi skill over the bead; it never drives the loop's insides.

---

Running the loop out of session

AgentOps ships no out-of-session driver of its own — it adopts a substrate. The reference substrate is the trio AgentOps actually runs on, none of it AgentOps-owned:

• NTM (a local tmux agent swarm) — spawns and supervises worker agents that each run the /rpi skill over a bead; the operator, or a lead agent, runs bd ready and dispatches the next bead.
• MCP via ao mcp serve (shipped) — exposes the ao tool surface to any MCP-aware harness, so coordination and tool calls cross the seam without bespoke glue.
• managed-agents / agent-SDK via ao agent (agent-native) — hosted, unattended drivers (e.g. Anthropic Managed Agents) that run the loop on a schedule.

In every case the substrate dispatches a whole loop as one unit — an agent running the /rpi (or /evolve) skill — while ao inject / ao validate --gate run in the dispatched workdir, and the corpus compounds in .agents/. AgentOps never moves its loop, ratchet, or context into the substrate — it adopts orchestration, it does not own it.

---

One doctrine, two reference implementations

The CDLC loop is one doctrine. It has two honest reference implementations, differing in runtime substrate, both fully local with no cloud required. Both honor the same ratchet rules (no self-grade, fresh agent on failure, knowledge becomes constraints) and prove the same fractal loop.

Axis	AgentOps (adopted substrate)	Mount Olympus (full-custom Rust)
What it is	A skills + ao CLI distribution that adopts NTM + MCP + managed-agents	A sovereign product with its own Rust core
Loop encoding	Skills (portable runtime) + the ao CLI, dispatched by the substrate	Typed Rust state machines
Out-of-session driver	NTM swarm / ao agent managed drivers — adopted, not owned	Its own Rust daemon
Daemon	None — AgentOps deleted its daemon; always-on adopts a substrate	Kept — the daemon is the product; a sovereign core to protect
Build cost	Low: reuse shipped orchestration (NTM / MCP / managed-agents)	High: re-implement supervision in Rust
Sovereignty floor	The in-session loop runs with zero dependencies; always-on adds a substrate	The typed Rust core is the floor
When to pick	You want the loop now, with always-on on adopted infrastructure	The typed loop is the product, for maximum control and auditability

The difference in daemon posture is deliberate and is the crux of the deletion decision: AgentOps has no core of its own to protect — it owns no orchestration substrate, so it deletes its daemon and adopts one (NTM + MCP + managed-agents) for always-on. Olympus is a sovereign product — its typed Rust daemon is the product, so it keeps it. AgentOps proves you do not have to hand-roll a daemon to own your factory; Olympus proves you can, when the typed loop is the point. See ADR-0009.

---

What "3.0-ready" means

3.0-ready is reconciled, hardened, and grounded: the repo matches reality and the doctrine is encoded end-to-end.

• This north star is the single referenced source of truth; README, PRODUCT, GOALS, and the docs index point here.
• Docs match reality: no aspirational claims in the north-star or primary surfaces, no dead code, no stale paths or counts, no unsubstantiated market claims. The standalone daemon/scheduler/overnight-runner surfaces are gone from the CLI and from live doc prose (only historical surfaces — ADRs, the CHANGELOG, release notes, and the 3.0 migration record — still name them, by design); the validate-sku-catalog-drift linkage gate now blocks any new skill→command rot.
• Hexagon complete: every skill carries hexagonal_role plus accurate consumes/produces plus canonical .feature acceptance, with the deprecated/internal/meta exceptions enumerated in the readiness level-set.
• Hookless by default: AgentOps 3.0 ships zero hooks. Workflow is guided by skills plus the ao CLI, and CI is the authoritative gate. Author your own via the hooks-authoring skill if you want them.
• The loop is executable in session: BDD intent → tests → bounded build → both-ends validation → ratchet, documented in operating-loop.md and exercised end-to-end.
• The loop model is named: one loop body, two drivers, one inner tick, one config, documented in canonical-loop-model.md. Out-of-session orchestration is the substrate's job.
• Every AgentOps bead is worked or closed against this north star. (Reconciliation waves closed; remaining 3.0-aligned coherence and ledger beads are open and tracked.)

Status: see the 3.0-readiness level-set for the honest box-by-box state, fitness snapshot, and named remaining work.

---

Non-goals (settled)

• No new practices or methodology; 3.0 is composition, not invention.
• No coupling to a consumer's domain vocabulary; bounded contexts are named by the consuming repo.
• No always-on daemon, scheduler, or overnight runner shipped by AgentOps. Those surfaces were deleted; out-of-session orchestration is the substrate's job (reference: NTM + MCP + managed-agents). The in-session loop is the zero-dependency sovereignty floor.
• No new required tooling; the floor is unchanged — git + an agent runtime stay hard-required, bd is required for the bead-tracked workflow ("No bead, no PR"), and the ratchet + ao CLI carry the rest.
• No required cloud, telemetry, or hosted control plane; state lives in .agents/ in your repo and is portable across model and harness.
• Hooks-as-default-primitive: abandoned (the A/B delta = 0 result); 3.0 ships zero hooks.

---

Canonical references: ADR-0002 · ADR-0009 · cdlc.md · canonical-loop-model.md · operating-loop.md · ports-and-adapters.md · PRODUCT.md · GOALS.md