workflows

A workflow structures work across many agents — 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.

ONLY call this tool when the user has explicitly opted into multi-agent orchestration. Workflows can spawn dozens of agents and consume a large amount of tokens; the user must request that scale, not have it inferred. Explicit opt-in means one of:

• The user included the workflow or workflows keyword (you'll see a system-reminder confirming it).
• Ultracode is on (a system-reminder confirms it) — see Ultracode below.
• The user directly asked you to run a workflow or use multi-agent orchestration in their own words (run a workflow, fan out agents, orchestrate this with subagents). The ask must be in the user's words — a task that would merely benefit from a workflow does not count.
• The user invoked a skill or slash command whose instructions tell you to call Workflow.
• The user asked you to run a specific named or saved workflow.

For any other task — even one that would clearly benefit from parallelism — do NOT call this tool. Use the Agent tool for individual subagents, or briefly describe what a multi-agent workflow could do and how much it would roughly cost, and ask the user whether to run it. Mention they can include workflow in a future message to skip the ask.

When you do call it, the right move is often hybrid: scout inline first (list the files, find the channels, scope the diff) to discover the work-list, then call Workflow to pipeline over it. 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 (example below)
• Research — multi-modal sweep -> deep-read -> synthesize
• Migrate — discover sites -> transform each (worktree isolation) -> 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.

Ultracode. When a system-reminder confirms ultracode is on, that opt-in is standing: author and run a workflow for every substantive task by default. The goal is the most exhaustive, correct answer you can produce — token cost is not a constraint. For multi-phase work (understand -> design -> implement -> review), that often means several workflows in sequence — one per phase — so you stay in the loop between them. The quality patterns below (adversarial verify, multi-modal sweep, completeness critic, loop-until-dry) are the tools; pick what fits the task. Lean toward orchestrating with workflows and adversarially verifying your findings — unless the work is trivial or already verified. Solo only on conversational turns or trivial mechanical edits. When a reminder says ultracode is off, revert to the opt-in rule above.

Pass the script inline via script — do not Write it to a file first. Every invocation automatically persists its script to a file under the session directory and returns the path in the tool result. To iterate on a workflow, edit that file with Write/Edit and re-invoke Workflow with {scriptPath: "<path>"} instead of resending the full script.

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

export const meta = {
  name: 'find-flaky-tests',
  description: 'Find flaky tests and propose fixes', // one-line, shown in permission dialog
  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()
phase('Scan')
const flaky = await agent('grep CI logs for retry markers', {schema: FLAKY_SCHEMA})
...