.claude/agents/. Each is a Markdown file with YAML frontmatter (name, model tier, role, team) plus a structured prompt body covering ownership, off-limits, contracts, coordination protocol, and a self-validation checklist.
The two teams
ZO uses two distinct team configurations:Project Delivery Team
Executes the projects defined in
plan.md. 12 launch + phase-in agents covering data, model, oracle, code review, testing, XAI, domain evaluation, ML engineering, infrastructure, and live training monitoring.Platform Build Team
Used to build and maintain ZO itself. 6 specialised agents including software architect, backend engineer, frontend engineer, platform code reviewer, platform test engineer, and documentation agent.
Tiered model routing
Each agent declares a model tier in its frontmatter, balancing capability against cost:| Tier | Model | When |
|---|---|---|
| Critical reasoning | claude-opus-4-7 | Lead Orchestrator, Software Architect, Plan Architect, Init Architect, decisions where one wrong call cascades |
| Standard execution | claude-sonnet-4-6 | Data Engineer, Model Builder, Oracle/QA, Code Reviewer, Test Engineer, the workhorses |
| Routine tasks | claude-haiku-4-5 | Documentation Agent, Infra Engineer, headline summaries, bounded scope, format-following work |
**Agent overrides:** block bumps the tier for that run.
Project Delivery Team: launch agents
Active by default on every project:Lead Orchestrator (Opus)
Lead Orchestrator (Opus)
Reads the plan, decomposes phases, generates contracts for each agent, gates work between phases, detects plan edits and re-plans. Owns all orchestration entries in
DECISION_LOG.md. Routes model tiers based on task complexity. The single agent that holds the whole project in context.Data Engineer (Sonnet)
Data Engineer (Sonnet)
Phase 1: data audit, schema validation, exclusion filters, train/val/test splits, drift baselines. Phase 2 support: feature engineering, input representation. Pipeline principles default to denylist-first for DL projects (PR-026), exclude leakage, include all signals, defer feature selection to the model layer.
Model Builder (Opus)
Model Builder (Opus)
Architecture design, loss function design, hyperparameter search, training orchestration, evaluation. In Phase 4 with the autonomous loop, also acts as the auto-proposer: drafts the next
hypothesis.md from the parent experiment’s shortfalls without prompting the human.Oracle / QA (Sonnet)
Oracle / QA (Sonnet)
Executes oracle criteria against deliverables. Reports pass/fail with evidence. Runs tiered evaluation, statistical significance tests, per-class breakdown, error analysis. Writes
result.md after each Phase 4 iteration so the orchestrator can compute delta_vs_parent.Code Reviewer (Sonnet)
Code Reviewer (Sonnet)
Reviews all code produced by other agents. Enforces conventions (PEP8, type hints, Google-style docstrings, files under 500 lines, functions under 50 lines). Catches hardcoded paths, security issues, missing docstrings. Cross-cutting, runs after any agent produces code.
Test Engineer (Sonnet)
Test Engineer (Sonnet)
Writes and runs tests for code artifacts. Unit, integration, regression, edge cases. Distinct from Oracle/QA: Oracle validates model performance; Test Engineer validates code correctness.
Research Scout (Sonnet)
Research Scout (Sonnet)
Cross-cutting agent activated on every phase. Surfaces relevant prior art, baselines, open-source implementations. Customer projects rarely have published benchmarks, Research Scout finds analogous problems, typical performance ranges, working implementations.
Project Delivery Team: phase-in agents
Activated for specific phases or by plan opt-in:XAI Agent (Sonnet)
XAI Agent (Sonnet)
Phase 5 explainability, feature importance, SHAP, GradCAM, attention visualisation. Generic by default; per-project domain context lands via the plan’s
**Agent adaptations:** block.Domain Evaluator (Opus)
Domain Evaluator (Opus)
Reviews model outputs for business/domain coherence. Flags edge cases, distributional shift, real-world applicability. Owns domain-specific PRIORS updates. Generic shell, domain identity injected at build time via plan adaptations (PR-020).
ML Engineer (Sonnet)
ML Engineer (Sonnet)
Productionisation, containerisation, inference optimisation, serving setup. Phase 6 packaging.
Infra Engineer (Haiku)
Infra Engineer (Haiku)
Compute resource allocation, experiment tracking setup, artifact storage, logging. Format-following work, appropriate for the smaller model.
Training Checker (Sonnet)
Training Checker (Sonnet)
Phase 4 live training monitor — the Lead spawns one per model run as
training-{modelname}-checker. Tails the active experiment’s metrics.jsonl / training_status.json, alerts on NaN/divergence/gradient-blowup/overfit/stall so a broken run dies early, and writes a mechanistic diagnosis.md plus next-round suggestions (pairs with Research Scout’s general-AI literature track).Platform Build Team
Used to build ZO itself, invoked once during initial development and during major platform upgrades. You don’t interact with these unless you’re modifying ZO’s source.| Agent | Tier | Role |
|---|---|---|
| Software Architect | Opus | Reads ZO specs, decomposes the platform, defines inter-module contracts |
| Backend Engineer | Sonnet/Opus | Builds core ZO infrastructure (memory, orchestration, comms, parsers) |
| Frontend Engineer | Sonnet | Builds the v2 command dashboard (deferred per PRD) |
| Platform Code Reviewer | Sonnet | Enforces ZO’s own coding conventions on platform code |
| Platform Test Engineer | Sonnet | Tests ZO modules, unit, integration, end-to-end |
| Documentation Agent | Haiku | Maintains docstrings, README, API docs, keeps docs in sync with code |
Per-project agent customisation
Beyond the built-in roster, plans support three levers:Active / phase-in / inactive lists
**Active agents:** runs every phase. **Phase-in agents:** activated for specific phases. **Inactive agents:** explicitly skipped.Custom agents
**Custom agents:** declares project-specific specialists (e.g. signal-analyst: Sonnet for vibration-signal analysis). The orchestrator auto-creates .claude/agents/custom/{name}.md from the plan declaration at build start.Agent adaptations
**Agent adaptations:** tunes generic agents per project. The Plan Architect drafts these during zo draft based on Research Scout + Data Scout findings. At build time, the Lead Orchestrator appends the adaptation to the agent’s spawn prompt, the agent’s .md file is unchanged, so it stays reusable.Peer-to-peer communication
Agents don’t shout into a void. They communicate through Claude Code’s native team APIs:TeamCreate, Agent(team_name=...), SendMessage. The Lead Orchestrator creates the team inside its session; teammates send messages directly to each other.
The Python LifecycleWrapper observes the team via ~/.claude/tasks/ and tmux pane output, captures lifecycle events, and pipes them to the JSONL comms log. Wrapper observes; agents communicate.
Validating the agent roster
.claude/agents/ are caught at preflight, before any compute is spent.
Next
Phases & gates
When each agent runs and what gates their output.
Memory & continuity
How agents share context across sessions.