workflow-authoring

Workflow authoring reference

A workflow structures work across many subagents — to be comprehensive (decompose and cover in parallel), to be confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps). The script is where you encode that structure: what fans out, what verifies, what synthesizes.

When you do call the Workflow tool, the right move is often hybrid: scout inline first (list the files, scope the diff, find the modules) to discover the work-list, then call Workflow to pipeline over it, passing the list via args. You don't need to know the shape before the task — only before the orchestration step.

Common single-phase workflows you can chain across turns:

• Understand — parallel readers over relevant subsystems → structured map
• Design — judge panel of N independent approaches → scored synthesis
• Review — dimensions → find → adversarially verify
• Research — multi-modal sweep → deep-read → synthesize
• Migrate — discover sites → transform each → verify

For larger work, run several in sequence — read each result before deciding the next phase. You stay in the loop; each workflow is one well-scoped fan-out.

Every script must begin with export const meta = {...}:

export const meta = {
  name: 'find-flaky-tests',                       // kebab-case, required
  description: 'Find flaky tests and propose fixes',  // required
  phases: [                                       // one entry per phase() call
    { title: 'Scan', detail: 'grep test logs for retries' },
    { title: 'Fix', detail: 'one agent per flaky test' },
  ],
}
// script body starts here — use agent()/parallel()/pipeline()/phase()/log()

The meta object must be a PURE LITERAL — no variables, function calls, spreads, or template interpolation.

What a subagent is

Every agent() call is one agent-free ephemeral conversation linked to the invoking parent agent (is_subagent: true, named after the call's label). It starts with nothing but its prompt: no memory, no conversation context, no skills. Put ALL context a stage needs in the prompt — file paths, the rule it should apply, what shape to return.