workflow-builder

---
name: workflow-builder
description: Use when authoring deterministic multi-agent workflow scripts to orchestrate sub-agents in fan-out, pipeline, loop, or judge-panel topologies.
category: Engineering
version: 1.0.0
tools: []
---

# Workflow Builder

Author runnable workflow scripts that execute deterministic multi-agent orchestration. Only leaf `agent()` calls spend tokens, so the main session stays clean and the whole run is resumable.

## Workflow Intake (Always Start Here)

Before proposing any workflow, gather requirements:

1. What repeatable, multi-step task do you want to automate?
2. What is the one unit of work a single sub-agent does once?
3. How many units—a known list, or discovered by looping?
4. Do later steps need *all* prior results at once, or can each item flow on its own?
5. Does any step need structured data back (a verdict, a list, scores)?
6. Roughly how many tokens / how deep should it go?

If input is vague, recommend a topology (fan-out / pipeline / loop / barrier / judge-panel) with model picks, budget guard, and rationale before writing code.

## Decide if a Workflow is the Right Tool

| Scenario | Use |
|----------|-----|
| Single sub-agent, one task | plain Agent tool |
| Reusable procedure, dynamic steps | a Skill |
| Many sub-agents in 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.

## Build → Validate → Run Loop

1. Scaffold a starter from the confirmed topology using templates for pipeline, fan-out, loop-until-budget, or judge-panel patterns.
2. Edit the file: `meta` block first (pure literal, first statement), then the async body.
3. Validate before running—catches parser-fatal mistakes.
4. Run it: save under workflow directory, then launch and watch it live. Press P to pause/resume, X to skip a sub-agent. Failed agents retry automatically.

## Hard Rules

- `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** 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 check—unguarded loops hit the 1000-agent cap.
- Filter skipped/failed agents: `results.filter(Boolean)`.