Skip to main content
zo draft is how you go from an empty plans/<project>.md skeleton to a fully-populated, schema-valid plan ready for zo build.

​
Synopsis

zo draft -p PROJECT_NAME [OPTIONS]

​
What it does

The Plan Architect (Opus, lead) coordinates with the Data Scout (Sonnet) and Research Scout (Sonnet) to populate every section of the plan against specs/plan.md:
1

Inspect inputs

Reads any source documents you provide (--docs), inspects data samples (--data), or asks you for a description (--description). All optional — the agent can also work conversationally with no inputs.
2

Research

Research Scout surfaces relevant prior art: published benchmarks, baseline ranges, open-source implementations of analogous problems. For domain-specific projects, finds relevant techniques.
3

Data understanding

Data Scout characterises the dataset: schema, class distribution, splits, known issues, scale. For remote data, reads a YAML manifest if provided.
4

Draft

Plan Architect drafts every section: objective, oracle (with must/should/could tiers), workflow mode, data sources, domain priors, agents (with adaptations and custom agents if relevant), constraints, milestones, delivery, environment.
5

Confirm and write

Each section is presented for your approval. Validates against the schema as it generates. The agent runs --dry-run first; you see exactly what will land. Then writes to the main repo (not worktrees — see PR-013).
6

Wrap-up

Asks “anything else?”, then tells you to /exit and run zo build.

​
Inputs (all optional)

zo draft -p my-project --docs ./scope-doc.pdf --docs ./domain-handbook.md
Repeatable. Plan Architect indexes documents into a project-scoped semantic index for grounding. Useful for projects with a written scope or domain documentation.

​
Custom agents and adaptations

Two of the most powerful plan features are populated during draft:
Project-specific specialists not in the standard roster. The Plan Architect proposes them based on Research Scout findings. Example: for vibration-signal analysis, a signal-analyst: Sonnet — frequency-domain reasoning, BPFO/BPFI fault frequencies, envelope demodulation block lands in the plan, and the orchestrator auto-creates .claude/agents/custom/signal-analyst.md at build start.
Per-project tuning of generic agents. The Plan Architect drafts adaptations for xai-agent and domain-evaluator (which are generic shells by design — see PR-020). Adaptations are appended to the spawn prompt at build time; the agent’s .md file stays unchanged and reusable.

​
Options

OptionPurpose
-p, --projectProject name. Required.
--docs PATHSource document (PDF, MD, TXT). Repeatable.
--data PATHData file or manifest. Repeatable.
-d, --descriptionOne-line description of the project.
--no-tmuxDisable conversational mode. Headless run with single best-effort draft.

​
Examples

zo draft -p mnist-demo

zo draft -p customer-churn --docs ./scope-2024Q3.pdf

zo draft -p sensor-faults \
  --data ./manifest.yaml \
  -d "Multi-sensor fault classification across 6 classes, target AUC >= 0.80"

​
Output

After a successful draft, the plan at plans/<project>.md is fully populated and ready for preflight: 
zo preflight plans/<project>.md
If preflight passes, you’re ready for zo build.

​
Important notes

Drafts always write to the main repo, never worktrees. ZO uses git worktree list to find the main repo. If you ran zo draft from a worktree, the plan still lands at <main-repo>/plans/<project>.md, and ZO tells you so. See PR-013.
The Plan Architect is conversational, not encyclopedic. It won’t research everything in the world for you. Provide grounding via --docs for projects with a defined scope, or -d for projects you can summarise in one sentence. The richer the input, the sharper the plan.

​
Next

zo preflight

Validate the drafted plan before spending compute.

zo build

Launch the agent team against the validated plan.