zao

zao is a workflow for AI-assisted software work that separates analysis from execution.

zao is named after the Chinese word 造, which means "to make" or "to create". It reflects the workflow's focus on getting things done while keeping analysis and execution distinct.

It uses two tracks:

• ana: decide what should be done
• zao: execute once the direction is clear

That split is the product, not an internal detail. Most AI coding sessions fail because they either start coding too early or lose structure halfway through. ana fixes the first problem. zao fixes the second.

What You Get

• less rework: unclear requirements and weak assumptions get exposed before they turn into code churn
• better decisions: options are compared with explicit trade-offs, not vague intuition
• durable context: useful conclusions, plans, and handoffs can survive beyond a single chat
• steadier delivery: implementation is broken into trackable steps instead of one large prompt
• easier recovery: long-running work can resume from plans and tasks instead of rebuilding context from memory

How It Feels To Use

You describe the work in plain language. The workflow should usually infer whether you need analysis or execution. It only needs to interrupt when the request is ambiguous or approval is required.

Typical intent handling:

• "Compare these approaches" -> ana
• "Help me diagnose this" -> ana
• "Turn this into a design" -> ana
• "Add this feature" -> zao
• "Fix this bug" -> zao
• "Continue this plan" -> zao

The point is that users should not have to memorize a control surface full of skill names. The workflow owns that split.

Why The Split Matters

zao follows one principle: thinking and doing are different jobs.

• analysis should reduce uncertainty before code is written
• execution should be visible and resumable, not hidden inside chat history
• documents should preserve important decisions and handoffs, not exist as ceremony
• the workflow should keep moving until it reaches a real human decision point

ana: Pre-Execution

Use ana when the problem is still open and the main task is to understand, compare, narrow, or explain.

Good fits:

• shaping a vague idea into something buildable
• comparing technical options
• diagnosing a problem that is still poorly understood
• producing a PRD, design note, roadmap, or research doc

What it gives you:

• clearer problem boundaries
• explicit constraints and trade-offs
• evidence-backed conclusions
• artifacts that can be handed off into execution when needed

Its collaboration flow is simple:

• explore: open the space and find the real problem
• grill: pressure-test assumptions and candidate directions
• converge: settle conclusions and prepare a document or handoff

ana does not implement code or create execution tasks.

zao: Execution

Use zao when the direction is clear enough to plan and build.

Good fits:

• shipping a feature
• fixing a bug
• refactoring without changing external behavior
• resuming an existing plan

What it gives you:

• a plan before implementation starts
• tasks that can be tracked and resumed
• execution that stays tied to review and approval points
• forward progress until a real blocker or human decision appears

Its workflow is straightforward:

1. understand the request and collect context
2. reuse an existing plan or create one
3. wait for approval before implementation starts
4. execute ready tasks
5. review, integrate, and continue

In short: plan -> task -> implement -> review -> continue.

zao is not for open-ended research. If the real question is still "what should we do?", the work belongs in ana first.

Install

Link the skills into ~/.agents/skills:

mkdir -p ~/.agents/skills
ln -s /path/to/zao/skills/ana ~/.agents/skills/ana
ln -s /path/to/zao/skills/zao ~/.agents/skills/zao

Working Paths

Both tracks use a local .zao/ working area by default.

In a target project, long-lived outputs usually live in:

• docs/ for design, research, PRD, or roadmap documents
• plans/ for execution plans

If those canonical paths already exist, the workflow prefers updating them. Otherwise it can write under .zao/.

Boundaries

• ana does not implement code or create execution tasks
• zao does not replace early-stage research, evaluation, or open-ended analysis
• zao starts implementation only after the scope is clear enough to plan and the plan is approved

Repo Layout

.
|-- skills/
|   |-- ana/
|   `-- zao/
|-- AGENTS.md
`-- README.md