cao-workflow

# CAO Workflows A CAO workflow is a **Python script** you write, validate, and — only after asking the user — run through `cao workflow run`. Each script drives one or more agent *steps* through CAO's shared substrate, so you can fan work out across agents, collect their results, and resume a run that was interrupted. > Your job as an author ends at a **validated script file on disk**. Authoring does NOT run the > workflow. Never claim a workflow ran, or will run, when all you did was write it. Running is a > separate step the user must approve (see Lifecycle step c). ## When to use Reach for this skill when the user asks to **build or run a multi-step or parameterized workflow** — for example: - "Analyze every file in `reports/` and summarize the findings." - "Run a review pipeline: implement, then review, then verify." - "Do the same batch job but with a different input directory each time." If the work is a single one-off agent call, you don't need a workflow. Workflows earn their keep when there are multiple steps, fan-out, parameterization, or a need to resume. ## The script API Author scripts import from the `cao_workflow` package. This package runs **only in the script subprocess** and imports nothing from `cli_agent_orchestrator.*` — it talks to CAO over HTTP. Its public surface: - `run_step(provider, agent, prompt, *, step_id=None, timeout=None, **opts) -> StepHandle` — run one agent step. `StepHandle` has `.step_id`, `.terminal_id`, `.output`, `.status`. ...