workflow-authoring

Workflow authoring reference

Everything below is about writing the script. Whether a workflow may run at all is decided by the Workflow tool's own opt-in rule — this reference does not authorize a run.

Reach for one to be comprehensive (decompose the work and cover every part in parallel), to be confident (independent perspectives and adversarial checks before an answer is committed to), or to take on scale a single context cannot hold — migrations, audits, broad sweeps. The script is where that structure is encoded: what fans out, what verifies, what synthesizes. Parallelism on its own is not a reason; work that is already one short sequence of edits belongs in the main loop.

Scout first, then orchestrate

The strongest pattern is hybrid: discover the work list in the main loop (list the files, scope the diff, read the failing test), then hand that list to a workflow. You do not need to know the shape of the work before the task — only before the orchestration step. When the work has distinct phases, run several small workflows across turns and read each result before choosing the next, rather than authoring one large script that runs unattended.

Common single-phase shapes: understand (parallel readers over subsystems, merged into one map), design (independent approaches, judged, then synthesized), review (dimensions, find, verify each finding), research (broad sweep, deep read, synthesis), migrate (discover sites, transform each under isolation: 'worktree', verify).

Script contract

The source is wrapped as an async IIFE, so top-level await and a top-level return are both legal — and a trailing expression is not a return value. End every successful path with an explicit return.

It is plain JavaScript, not TypeScript, and it cannot import anything.

The script may start with a literal export const meta = {...} declaration with name, description, and optionally whenToUse and phases: [{ title, detail? }]. It must be a pure literal — no variables, calls, or interpolation — and it is stripped before execution, so nothing in the script body can read it. Fields outside that list are dropped. The approval dialog prints the name, the description, and each phase title with its detail as a one-line explanation beside it: give every phase a detail, because for a run that may dispatch hundreds of agents it is what the user reads before approving.