Workflow Builder

# Workflow Builder Author runnable workflow scripts for Claude Code's Workflow tool: deterministic multi-agent orchestration files (`.js`) that fan work out to fresh-context sub-agents under plain JavaScript control flow. Only leaf `agent()` calls spend tokens, so the main session stays clean and the whole run is resumable. ## ALWAYS start every session with intake (non-negotiable) Before proposing or writing any workflow, run the intake. Do not skip to code. 1. **Ask what kind of workflow they want.** Use this opening question set: - What repeatable, multi-step task do you want to automate? - What is the one unit of work a single sub-agent does once? - How many units — a known list, or discovered by looping? - Do later steps need *all* prior results at once, or can each item flow on its own? - Does any step need structured data back (a verdict, a list, scores)? - Roughly how many tokens / how deep should it go? 2. **If the user is vague, do NOT stall.** Run the recommendation engine to turn whatever you have into 1-2 concrete proposals, then present them *with the reasoning*: ```bash python scripts/workflow_intake.py --task "their description" \ --units unknown --stages unknown --needs-all unknown --structured unknown ``` The engine returns a recommended topology (fan-out / pipeline / loop / barrier / judge-panel), model picks, a budget guard, and a one-line rationale per choice. Present those as "Here's what I'd build and why" — never ask the user to re-answer questions they already half-answered. 3. **Confirm the shape with the user** (topology + phases + parallel-vs-pipeline) before writing the file. This is the only approval gate. See [references/decision_and_intake_guide.md](references/decision_and_intake_guide.md) for the full question framework, the vague-input playbook, and worked recommendation examples. ## Decide if a workflow is even the right tool | Scenario | Use | |----------|-----| | Single sub-agent, one task | plain Agent tool | | Reusable procedure, Claude picks steps dynamically | a Skill | | Many sub-agents in a fixed topology, deterministic + resumable | **Workflow** ✓ | Workflows earn their cost when work is parallel or multi-stage, must be reproducible, long enough to fail halfway (so resume matters), or benefits from isolating each step in its own context window. For one-off tasks, just use Claude directly. ## Build → validate → run loop 1. **Scaffold** a starter from the confirmed topology: ```bash python scripts/scaffold_workflow.py --topology pipeline --name pr-triage \ --description "Triage open PRs" > .claude/workflows/pr-triage.js ``` 2. **Edit** the file: `meta` block first (pure literal, first statement), then the async body using the injected globals — `agent()`, `pipeline()`, `parallel()`, `phase()`, `log()`, `budget`, `args`, `workflow()`. Full surface in [references/api_reference.md](references/api_reference.md); copy-paste shapes in [references/orchestration_patterns.md](references/orchestration_patterns.md). 3. **Validate** before running — catches the parser-fatal mistakes: ```bash python scripts/validate_workflow.py .claude/workflows/pr-triage.js ``` 4. **Run** it: enable the feature with `export CLAUDE_CODE_WORKFLOWS=1`, save the file under `.claude/workflows/`, then use `/workflows` to launch and watch it live. Press **P** to pause/resume, **X** to skip a sub-agent. Failed agents retry automatically. ## Hard rules (validator enforces these) - `meta` is a **pure literal** and the **first statement** — no variables, spreads, template strings, or function calls inside it. - **No non-determinism:** `Date.now()`, `Math.random()`, argless `new Date()` break resume — pass timestamps via `args`. - **No filesystem / Node APIs** (`require`, `fs`, `process`, network) in the orchestrator — that work belongs *inside* `agent()` prompts. - `parallel()` takes **thunks** (`() => agent(...)`), not bare promises. Default to `pipeline()` unless a stage needs the whole prior result set. - **Guard every open-ended loop** with a counter or `budget.remaining()` check — unguarded loops hit the 1000-agent cap. - Filter skipped/failed agents: `results.filter(Boolean)`. ## Tooling - `scripts/workflow_intake.py` — intake recommendation engine (topology + model + budget + rationale from vague input). - `scripts/validate_workflow.py` — stdlib linter for the rules above; PASS / WARN / FAIL with line numbers. - `scripts/scaffold_workflow.py` — generate a starter `.js` for any topology. - `assets/templates/` — fan-out, pipeline, loop-until-budget starters. `assets/examples/` — a complete runnable workflow. All scripts run with `--sample` (no args) and `--help`.