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. A script with a dynamic import() anywhere in it — even in a branch that never runs — is refused before it starts, so none of its agents runs first; do file, network, and package work inside an agent instead.