PRD: caw v0.1 — local-first CLI agentic workflow orchestrator

[qinhaihong-red]

Tracker handle for the v0.1 PRD. The full specification lives in the repo at
docs/prd/0001-cli-agentic-workflow.md, with decisions recorded in
docs/adr/0001-local-first-python-bash-workflow-kernel.md,
docs/adr/0002-pattern-iteration-as-run-groups.md, and the glossary in CONTEXT.md.
This issue summarizes the PRD and is the anchor for breaking work into implementation issues.

Problem Statement

Modern agent CLIs (claude -p, codex exec) can do useful autonomous work, but multi-step
workflows live in ad hoc prompts, shell scripts, or manually supervised sessions. Workflow
intent cannot be inspected before execution, intermediate outputs are not persisted,
parallelism and retries are hand-written every time, agent decisions are hard to audit, and
a successful workflow shape is cumbersome to reuse across repositories or across competing
agent CLIs.

Solution

caw: a local-first workflow CLI that turns agent invocations into structured, inspectable,
repeatable Runs. Users declare a Workflow in YAML; caw validates it before any token is
spent, renders the planned graph, executes nodes through vendor-neutral Adapters, persists
State/Events/Artifacts locally, parks on Human Gates, resumes interrupted Runs, and renders
reports. Reusable Patterns (pipeline, parallel, classify-and-act, generate-and-filter,
fan-out synthesis, adversarial verification, tournament, loop-until-done) package common
agentic shapes.

User Stories

1. As a solo developer, I want to define a workflow in a YAML file and run it from the CLI, so that my multi-step agent tasks are repeatable instead of ad hoc prompts.
2. As a solo developer, I want caw validate to fail before any Agent CLI is invoked, so that workflow mistakes cost zero tokens.
3. As a maintainer, I want caw graph to render the planned DAG before execution, so that I can audit workflow intent up front.
4. As a maintainer, I want to resume an interrupted Run without repeating completed Nodes, so that long workflows survive interruptions cheaply.
5. As a user, I want every Run to persist State, Events, and Artifacts locally, so that I can inspect what happened after the fact.
6. As a reviewer, I want reports to distinguish final conclusions from trace evidence, so that I can trust a result without rereading the whole trace.
7. As a user, I want final output in Markdown, JSON, JSONL, or plain text, so that reports fit both humans and downstream tools.
8. As a user, I want to switch an agent Node between claude.print and codex.exec by changing only its uses value, so that workflows stay vendor-neutral.
9. As a workflow author, I want conditional behavior expressed only by node-level when predicates, so that the graph stays a plain DAG and branching is explicit.
10. As a workflow author, I want built-in Patterns for the common agentic shapes, so that I do not hand-write parallelism, verification loops, or tournaments every time.
11. As a workflow author, I want caw patterns init to scaffold complete runnable examples, so that I start from working workflows rather than abstract templates.
12. As a maintainer, I want a human_gate Node that parks the Run until I approve, so that high-impact steps cannot proceed without me.
13. As a user, I want approval through an interactive TTY confirmation or caw resume <run-id> --approve <node-id>, so that gates work in both attended and detached sessions.
14. As a workflow author, I want iterative patterns to materialize each iteration as a separate immutable Run linked into a Run Group, so that every iteration's graph remains inspectable before it executes.
15. As a reviewer, I want aggregate reporting over a Run Group, so that I can read a loop's full history as one result.
16. As a workflow author, I want Output Contracts validated when a Node completes, so that schema mismatches fail fast instead of corrupting downstream nodes.
17. As a tooling engineer, I want a mock Adapter that replays fixtures, so that I can test workflows and Patterns without spending tokens or installing agent CLIs.
18. As a user, I want env vars passed to a Node only when declared in its env field and never persisted into State, Events, or Artifacts, so that secrets do not leak.
19. As a user, I want the underlying CLI's sandbox and approval flags exposed as agent node options, so that security decisions stay visible instead of hidden behind defaults.
20. As a user, I want missing Agent CLI dependencies detected with actionable setup errors, so that first runs do not fail mysteriously.
21. As a user, I want token and cost usage reported by Adapters recorded into State and reports, so that I can see what a Run cost.
22. As a maintainer, I want error messages that name the workflow file, node id, adapter, and failed contract, so that failures are debuggable without spelunking.
23. As a tooling engineer, I want Run state stored in inspectable local files, so that I can debug with standard tools instead of a proprietary console.
24. As a new user, I want a first sample workflow that runs locally within 10 minutes, so that I can evaluate the tool without operational setup.
25. As a user, I want conservative defaults for concurrency and retries, so that parallel agent runs do not burn tokens unexpectedly.

Implementation Decisions

All decided 2026-06-11 and recorded in the repo docs:

• The CLI is named caw (also the package and local state directory name).
• Local-first Python workflow kernel; bash only as leaf-level adapter glue; no external workflow framework (e.g. iii) required in v0.1 (ADR 0001). An internal Engine Backend interface keeps a future engine swappable.
• YAML is the only v0.1 configuration format; TOML/JSON are later extensions.
• The Workflow IR is strictly acyclic per Run and immutable once execution starts. Iteration is expressed by Pattern Controllers that materialize successive Runs linked into a Run Group; Pattern Expanders compile static shapes into a single Run's graph (ADR 0002).
• Edges carry ordering and data dependencies only. Conditional behavior lives exclusively in node-level when predicates; a false when marks the node skipped; skipped dependencies skip dependents by default; join nodes declare an explicit join policy; failed dependencies always block.
• Await parks a Run on a condition outside the graph. In v0.1 its only trigger source is the Human Gate (required feature); external-event triggers reuse the same parking mechanism later.
• Two agent Adapters are required with symmetric capabilities: claude.print and codex.exec — identical structured output contracts, exit-code normalization, and artifact capture. A mock Adapter replays fixtures for tests and simulation. Capability checks record CLI versions. Sandbox/approval flags of the underlying CLIs pass through as node options; caw adds no policy engine of its own.
• State persists per Run: definition checksum, run group id and iteration index, node status, attempts, normalized outputs, artifact paths, error classification, resume eligibility — stored in inspectable local files (SQLite state, JSONL event log, normalized workflow snapshot, artifact directories).
• Reporters render Markdown, JSON, JSONL, and plain text.
• CLI surface: init, validate, graph, run, resume, report, patterns list, patterns init.
• Fan-out synthesis is the first end-to-end agent sample: the same task fans out to both adapters and a synthesis node joins the results.
• Implementation proceeds in phases (scaffold → IR/validation → executor/state → adapters → patterns → reporting/hardening) per the PRD's Implementation Plan.

Testing Decisions

A good test exercises external behavior only — what a user observes through the CLI, the
run directory, a report, or a real agent-CLI run — never internal objects or call sequences.
Tests reach the system through several co-weighted seams (the codebase is greenfield, so
these establish the repo's prior art):

1. CLI seam: tests invoke caw validate / graph / run / resume / report and assert on exit codes, stdout formats, and report content.
2. Mock adapter seam: full workflows execute through the real kernel (scheduling, retries, resume, human gate, patterns) against the fixture-replaying mock adapter — no real agent CLIs, no tokens. It covers behaviors a fixture can verify completely and offline; it complements the real-CLI seam, it does not replace it.
3. Run directory seam: the per-run layout (state database, event log, artifacts) is an observable contract; tests assert on persisted state and event sequences rather than in-process state.
4. Real agent-CLI e2e seam: a real claude -p / codex exec node runs through the kernel end to end. Because most real usage runs agent CLIs as nodes, this is mandatory coverage that grows as features land — not an afterthought. e2e tests FAIL (never skip) when the selected CLI is absent; they run locally for now (cloud auth is not provisionable in CI yet) and migrate into a CI gate once auth lands (see Require real agent-CLI e2e tests for graph runs; split suite into non-e2e and e2e #86).

Cover a behavior at the seam that can actually verify it — mock where a fixture suffices and is deterministic, real-CLI e2e where correctness depends on the real CLI. Neither side is privileged, and over-emphasizing either is a mistake.

Out of Scope

• Replacing Claude Code, Codex, or any agent CLI; guaranteeing deterministic agent outputs.
• Hosted control plane, distributed scheduler, browser UI, long-lived remote worker fleets.
• Requiring an external workflow framework such as iii.
• Prompt template versioning (git plus the recorded definition checksum covers traceability for now).
• Active token/cost/rate-limit enforcement (v0.1 records usage only).
• External-event await triggers (files, webhooks, timers).
• TOML/JSON configuration formats.

Further Notes

• Canonical spec: docs/prd/0001-cli-agentic-workflow.md (zero open questions as of 2026-06-11). Decisions: ADR 0001 (local-first kernel), ADR 0002 (run-group iteration). Vocabulary: CONTEXT.md — issue titles and implementation work should use these terms.
• Per repo rules, keep cross-references between this issue, the docs, and future code in sync; if a decision here changes, update the PRD/ADRs in the same change.
• Suggested next step: break this PRD into implementation issues following the phase plan, starting with the project scaffold.

[qinhaihong-red]

Broken down into 16 tracer-bullet implementation issues (all labeled ready-for-agent), in dependency order:

Issue	Slice	Blocked by
#2	Walking skeleton: caw run, single shell node, run directory	none
#3	caw validate + caw graph, multi-node DAGs	#2
#4	Parallel scheduling and joins	#3
#5	Adapter interface, agent nodes, mock adapter, output contracts, env policy	#3
#6	Failure semantics: retries, timeouts, cancellation, resume	#4
#7	when predicates and skip semantics	#4
#8	Pattern expander infra, pipeline/parallel, caw init, caw patterns	#4
#9	claude.print adapter	#5
#10	Human gate: await parking and approval	#6
#11	codex.exec adapter, symmetric capabilities	#5, #9
#12	Reporters and caw report	#6
#13	Expanders: classify-and-act, generate-and-filter, fan-out-synthesis	#7, #8
#14	Fan-out synthesis end-to-end sample and quickstart	#4, #9, #11
#15	Run groups, pattern controllers, loop-until-done (ADR 0002)	#6, #8, #12
#16	Hardening: artifact cleanup, final output schema validation	#12
#17	Controllers: adversarial verification and tournament	#15

Two independent swimlanes after #3: the executor lane (#4 → #6/#7/#8 → ...) and the adapter lane (#5 → #9 → #11), converging at #14.