Skip to main content
ZO has five primitives. Master these and the rest of the system follows.

The plan

A single Markdown file is the human’s only lever of control. Eight sections describe what to build, how to verify it, and what’s off-limits.

The oracle

Every project must define a hard, verifiable success metric. Without a measurable criterion, autonomous agents become hallucinating cost centers.

The team

20 specialised personas — orchestrator, data engineer, model builder, oracle, XAI, code reviewer, and more — communicate peer-to-peer through Claude Code’s native team APIs.

Phases & gates

Six sequential phases, each separated by a gate. Automated gates run validation; blocking gates pause for a human.

Memory & continuity

STATE.md, DECISION_LOG.md, PRIORS.md, plus a semantic index — every session reads state at entry and writes it at exit.

Self-evolution

When agents fail, they don’t just fix the bug — they update the rule that allowed it. After 23 sessions, ZO has accumulated 34 documented priors.

​
How they fit together

                  ┌──────────┐
       writes     │          │     decomposes
       ──────▶    │ plan.md  │     ──────────▶
       human      │          │     orchestrator
                  └──────────┘
                       │
                       ▼
              ┌────────────────┐
              │   Phase 1–6    │  ──┐
              └────────────────┘    │
                       │             │
              ┌────────────────┐    │ peer-to-peer
              │     Gates      │    │ comms
              └────────────────┘    │
                       │             │
                       ▼             ▼
              ┌────────────────┐    ┌─────────────┐
              │     Oracle     │ ◀──│   Agents    │
              └────────────────┘    └─────────────┘
                       │                   │
                       │ verifies          │ writes
                       ▼                   ▼
                  ┌──────────┐       ┌──────────┐
                  │ Delivery │       │  Memory  │
                  │   repo   │       │  layer   │
                  └──────────┘       └──────────┘
The plan is the input. Agents execute it. The oracle validates. Memory persists everything for the next session.

​
Design principles

No agent operation proceeds without a verifiable metric. If something can’t be measured, it can’t be validated. The oracle is the system’s source of truth.
Before spawning parallel agents, all interfaces, inputs, outputs, and acceptance criteria are defined. Eliminates mid-execution clarifications.
Every session reads state at entry, executes work, and writes state at exit. Not optional — required infrastructure.
When agents discover a bug or inefficiency, they fix the immediate issue and update the rule or spec that allowed the bug to exist. Same mistake never happens twice.
The ZO codebase is the surgeon; the delivery repo is the patient. ZO infrastructure (agents, memory, specs) never leaks into delivery artifacts.
CLAUDE.md is the index. Spec files are chapters. Agents load only what they need. Context windows are finite resources managed by design.
Planning, building, maintenance — separate phases with separate conversation contexts. Transitioning closes the previous context and opens a fresh one with only the previous phase’s artifacts loaded.