# Builder/Adversary example

A complete, self-contained instance of the **Builder/Adversary loop pair** — the pattern
[cc-ci](https://git.autonomic.zone) runs in production, distilled to a tiny, fully-local task so you
can read it end-to-end and run it without any infrastructure.

Two AI loops work the same plan but never trust each other; they coordinate **only through a git
repo**:

- **Builder** (`prompts/builder.md`) — builds to the phase plan's Definition of Done, and *claims*
  each gate with a `claim(...)`-prefixed commit when it believes a DoD item is met.
- **Adversary** (`prompts/adversary.md`) — *disbelieves* the Builder, cold-verifies every claim from
  its **own clone**, and records PASS/FAIL with a `review(...)`-prefixed commit. Holds veto.
- **Orchestrator** (persistent) supervises; **Reporter** (one-shot) writes a summary when the phase
  sequence finishes.

The watchdog keeps the loops alive, paces them, and turns those commit prefixes into the handoff:
a `claim(` commit pings the Adversary, a `review(` commit pings the Builder.

## Files

```
agents.toml            the whole project: backends, the 4 agents + a service, the phase machine
prompts/
  kickoff.md           per-phase preamble (slots {phase_id}/{plan}/{status}/{role})
  builder.md           Builder role + loop protocol
  adversary.md         Adversary role + anti-anchoring verification discipline
plans/
  wc.md                phase 1 — build a `wc` CLI (the single source of truth for that phase)
  json.md              phase 2 — add `--json` (shows a per-phase model override)
machine-docs/          where the loops write STATUS / REVIEW / BACKLOG / JOURNAL at runtime
```

## The task

Build a small `wc` clone (`wc.py` + a `pytest` suite) in the **work repo**, in two phases. It is
deliberately trivial and offline — the point is to exercise the *protocol* (claim → cold-verify →
PASS/FAIL → advance), not to build anything hard. See `plans/wc.md` and `plans/json.md` for the
Definitions of Done.

## Run it

Needs `claude` on `PATH` (the loops are real agents). From this directory:

```bash
python3 ../../agents.py status --config agents.toml      # read-only: what would run
python3 ../../agents.py up     --config agents.toml      # start builder + adversary + orchestrator + watchdog
python3 ../../agents.py logs   builder  --config agents.toml
python3 ../../agents.py phase  show     --config agents.toml
python3 ../../agents.py down   --config agents.toml      # stop everything
```

To watch the **mechanics** without an agent CLI, set `defaults.backend = "demo"` in `agents.toml`
(the demo backend just idles) and run `up` / `status` / `down` — sessions start and the watchdog
ticks, but no real work happens. The repo's top-level `./smoke.sh` shows this end-to-end for the
sibling `agents.example.toml`.

## The work repo (and isolation)

The loops build in a **work repo** — `handoff.repo` in `agents.toml`, here `./work`. For this
quick start both loops can share it, but the pattern's real strength is **cold verification**: give
each loop its **own clone of the same remote** so the Adversary verifies from a genuinely
independent checkout (exactly what cc-ci does with separate `cc-ci` / `cc-ci-adv` clones).

To set that up:

1. Create the work repo with a remote both loops can push/pull (any git host, or a bare repo on the
   same box). Put `machine-docs/` in it.
2. Clone it twice: into `./work` (Builder's `dir`) and `./work-adv` (Adversary's `dir`).
3. Point `handoff.repo` at the Builder's clone (`./work`).

The watchdog then watches that repo's `origin/main` for `claim(`/`review(` commits and the two
`*-INBOX.md` files, and pings the right loop on each.

## How to adapt it

- **Different task** → rewrite `plans/*.md` (each is one phase's source of truth + DoD) and adjust
  the `[loop].phases` list. Nothing else needs to change.
- **More/fewer phases** → add or remove entries in `[loop].phases`; the watchdog advances when a
  phase's `status` file contains `## DONE`.
- **Per-phase models** → `models = { builder = "...", adversary = "..." }` on a phase (see `json`).
- **A periodic supervisor nudge** → uncomment the `wake = { ... }` line on the `orchestrator` agent.

This example carries **no** project-orchestrator/fleet metadata — like any project, it can be run by
hand and has no idea a fleet exists. See the repo root `README.md` for the full harness reference.