Mastering /workflows

01 What is a Workflow

A Workflow is a deterministic multi-agent orchestration script. You write plain JavaScript, Claude Code executes it, spawning subagents for each agent() call — potentially dozens or hundreds of them — with control flow you define: loops, conditionals, fan-out, fan-in.

The two pieces: Workflow tool vs /workflows command

Key properties

• Scripts are plain JS, not TypeScript. No type annotations, no interfaces, no generics.
• Runs in an async context. Use await directly at the top level — no wrapper needed.
• Always returns immediately. The Workflow tool call returns the run ID; agents run in the background.
• Resumable. Every run is journaled. Edit the script and re-invoke with resumeFromRunId — unchanged agents return cached results instantly.
• Explicit opt-in required. Claude will NOT launch a workflow unless you say "use a workflow", "ultracode", or name a specific workflow type.

02 Anatomy of a Workflow Script

Every script must begin with export const meta = {...} — a pure literal — followed by the script body.

export const meta = {
  name: 'find-dead-code',        // kebab-case slug, required
  description: 'Find unused exports across the codebase',  // shown in permission dialog, required
  phases: [                          // optional — titles must match phase() calls exactly
    { title: 'Scan',  detail: 'grep for exports and imports' },
    { title: 'Verify', detail: 'confirm each candidate is truly unused' },
    { title: 'Fix',    detail: 'remove dead exports', model: 'haiku' },  // per-phase model override
  ],
}

// ── Script body — async context, await directly ──

const FINDINGS_SCHEMA = {
  type: 'object',
  properties: { exports: { type: 'array', items: { type: 'string' } } },
  required: ['exports']
}

phase('Scan')
const found = await agent('Find all exported symbols with no import anywhere', {
  label: 'scan:exports',
  phase: 'Scan',
  schema: FINDINGS_SCHEMA
})
log(`Found ${found.exports.length} candidates`)

The meta literal rule — CRITICAL

The resume-breaking functions

These three are banned in workflow scripts because they would make the same script produce different results on resume, breaking the cache:

// ✅ Correct — stamp time BEFORE calling Workflow, pass it in
// In the main loop (not inside the script):
await Workflow({ script: '...', args: { timestamp: Date.now() } })

// Inside the workflow script:
const ts = new Date(args.timestamp)  // ✅ deterministic — same value on resume

03 Full API Reference

agent(prompt, opts?)

Spawns a subagent with the given prompt. The subagent's final text is its return value (not a human-facing message — so it returns raw data).

pipeline(items, ...stages)

Runs each item through all stages independently — no barrier between stages. Item A can be in stage 3 while item B is still in stage 1.

• Wall clock = slowest single-item chain (not sum of slowest per stage)
• Each stage receives (prevResult, originalItem, index)
• A stage that throws drops that item to null and skips its remaining stages
• This is the default. Use it unless you genuinely need a barrier.

parallel(thunks)

Runs tasks concurrently. This is a barrier — awaits all thunks before returning.

• Takes Array<() => Promise<any>> — thunk functions, not promises
• A thunk that throws resolves to null in the result — the call itself never rejects
• Use ONLY when stage N needs cross-item context from all of stage N-1

phase(title)

Starts a new named phase. Subsequent agent() calls are grouped under this phase box in /workflows.

phase('Scan')       // opens "Scan" box in /workflows
const a = await agent('...')  // appears under Scan
phase('Verify')     // opens "Verify" box
const b = await agent('...')  // appears under Verify

log(message)

Emits a narrator line above the progress tree in /workflows. Use for progress milestones and loop counters.

log(`Round ${round}: ${bugs.length} found, ${dryStreak} dry`)

args

The value passed as Workflow's args input, verbatim. Pass arrays/objects as actual JSON values — not JSON-encoded strings.

// Caller (main loop):
await Workflow({ script: '...', args: ['src/auth.ts', 'src/user.ts'] })
// NOT: args: JSON.stringify(['src/auth.ts', ...])  ← breaks args.map()

// Inside script:
const results = await pipeline(
  args,  // ← the array of file paths
  path => agent(`Review ${path}`)
)

budget

Token budget from the user's +500k-style directive. Shared across main loop and all workflows.

// Guard: only loop when a budget was set AND tokens remain
while (budget.total && budget.remaining() > 50_000) {
  const r = await agent('Find more issues', { schema: SCHEMA })
  results.push(...r.items)
  log(`${results.length} found, ${Math.round(budget.remaining()/1000)}k remaining`)
}

workflow(nameOrRef, args?)

Runs another workflow inline as a sub-step. Returns whatever the child returns.

// By name (saved workflow):
const map = await workflow('codebase-mapper')

// By script file:
const r = await workflow({ scriptPath: '.claude/workflows/my-scan.js' }, { target: 'src/' })

• Child shares concurrency cap, agent counter, abort signal, token budget
• Child's agents appear under a ▸ name group in /workflows
• One level only — calling workflow() inside a child throws

04 pipeline() vs parallel() — The Critical Distinction

This is the most commonly misunderstood part of the API. The names suggest similarity; the behavior is fundamentally different.

When to use each

The smell test

// ❌ Unnecessary barrier — transform doesn't need all results first
const a = await parallel(items.map(x => () => agent(x)))
const b = a.filter(Boolean).flatMap(r => r.items)   // just a transform
const c = await parallel(b.map(x => () => agent(x)))

// ✅ Pipeline — A can verify while B and C are still scanning
const results = await pipeline(
  items,
  item => agent(`Scan ${item}`, { schema: FINDINGS }),
  scan => [scan].flatMap(r => r.items),        // transform inside a stage — no barrier
  (flat, _orig, i) => agent(`Verify item ${i}: ${JSON.stringify(flat)}`)
)

// ✅ Barrier IS justified — dedup needs all results before verification
const scans    = await parallel(FINDERS.map(f => () => agent(f, { schema: FINDINGS })))
const deduped  = dedupeByKey(scans.filter(Boolean).flatMap(r => r.items))  // needs ALL
const verified = await parallel(deduped.map(b => () => agent(`Verify: ${b}`)))

05 Structured Output — The Schema Pattern

When you pass a schema option to agent(), the agent is forced to call a StructuredOutput tool. Validation happens at the tool-call layer — if the output doesn't match the schema, the model retries automatically. agent() returns the validated object directly. No JSON.parse, no try/catch.

// Define the schema once as a plain JS object (not TypeScript)
const BUGS_SCHEMA = {
  type: 'object',
  properties: {
    bugs: {
      type: 'array',
      items: {
        type: 'object',
        properties: {
          file:     { type: 'string' },
          line:     { type: 'number' },
          desc:     { type: 'string' },
          severity: { type: 'string', enum: ['low', 'medium', 'high', 'critical'] }
        },
        required: ['file', 'line', 'desc', 'severity']
      }
    }
  },
  required: ['bugs']
}

// Use it
const result = await agent('Find all null pointer dereference bugs in src/', {
  schema: BUGS_SCHEMA
})

// result.bugs is a validated Bug[] — no parsing needed
const critical = result.bugs.filter(b => b.severity === 'critical')

06 Quality Patterns

These are composable recipes. Mix them freely — e.g. multi-modal sweep → dedup (barrier) → adversarial verify (pipeline) → loop-until-dry.

// Spawn N independent skeptics per finding — each is prompted to REFUTE
// Majority rules: ≥2 of 3 must fail to refute for the finding to survive
const VERDICT_SCHEMA = {
  type: 'object',
  properties: {
    refuted: { type: 'boolean' },
    reason:  { type: 'string'  }
  },
  required: ['refuted', 'reason']
}

async function adversarialVerify(claim) {
  const votes = await parallel(
    Array.from({ length: 3 }, (_, i) => () =>
      agent(
        `Try to REFUTE: "${claim}". Default refuted=true if uncertain.`,
        { label: `refute:${i}`, phase: 'Verify', schema: VERDICT_SCHEMA }
      )
  )
  return votes.filter(Boolean).filter(v => !v.refuted).length >= 2
}

// Usage in pipeline — each finding verified as soon as it's found
const confirmed = await pipeline(
  findings,
  f => adversarialVerify(f.desc),
  (survives, f) => survives ? f : null
).then(r => r.filter(Boolean))

// Dedup against `seen` (not `confirmed`) — else rejected findings reappear every round
const seen = new Set()
const bugs = []
let dry = 0

while (dry < 2) {
  const found = await agent(
    `Find bugs. Already know about: ${JSON.stringify([...seen])}`,
    { schema: BUGS_SCHEMA }
  )
  const key  = b => `${b.file}:${b.line}`
  const fresh = found.bugs.filter(b => !seen.has(key(b)))

  if (!fresh.length) { dry++; continue }
  dry = 0
  fresh.forEach(b => seen.add(key(b)))
  bugs.push(...fresh)
  log(`${bugs.length} total, dry streak reset`)
}

const FINDERS = [
  { key: 'by-file',    prompt: 'Scan every modified file for security issues' },
  { key: 'by-import',  prompt: 'Trace import chains for vulnerable dependencies' },
  { key: 'by-test',    prompt: 'Find issues surfaced by failing test patterns' },
  { key: 'by-history', prompt: 'Read recent git commits for regressions' },
]

phase('Sweep')
const sweeps = await parallel(FINDERS.map(f => () =>
  agent(f.prompt, { label: f.key, phase: 'Sweep', schema: FINDINGS_SCHEMA })
))

// Barrier justified: need ALL sweep results to dedup before verification
const all     = sweeps.filter(Boolean).flatMap(r => r.items)
const deduped = dedupeByKey(all)
log(`${all.length} raw → ${deduped.length} unique after dedup`)

const APPROACHES = ['MVP-first', 'risk-first', 'user-first']

phase('Design')
const proposals = await parallel(APPROACHES.map(angle => () =>
  agent(`Design the auth system from a ${angle} perspective`, {
    label: angle, phase: 'Design', schema: PROPOSAL_SCHEMA
  })
))

phase('Judge')
const synthesis = await agent(
  `Score these proposals, pick the winner, graft the best ideas from runners-up: ` +
  JSON.stringify(proposals.filter(Boolean)),
  { phase: 'Judge', schema: SYNTHESIS_SCHEMA }
)

// Guard on budget.total first — without a target, remaining() is Infinity
// and the loop runs to the 1000-agent cap
const findings = []

while (budget.total && budget.remaining() > 50_000) {
  const r = await agent('Find more edge cases not already in the list: ' +
    JSON.stringify(findings), { schema: FINDINGS_SCHEMA })
  findings.push(...r.items)
  log(`${findings.length} found, ${Math.round(budget.remaining()/1000)}k tokens remaining`)
}

07 Resume & Iteration

Every Workflow invocation auto-persists its script under the session directory and returns the path in the tool result. This enables a tight edit-and-resume loop.

// Typical resume invocation:
await Workflow({
  scriptPath: '.claude/sessions/abc123/workflow-wf_abc123.js',
  resumeFromRunId: 'wf_abc123'
})

08 Concurrency & Limits

What happens when you exceed concurrency

Excess agent() calls queue and run as slots free. You can pass 100 items to pipeline() or parallel() — all 100 will complete, just not all simultaneously. Wall-clock time scales with the slowest item, not the count.

worktree isolation cost

Token budget is a hard ceiling

When budget.spent() reaches budget.total, further agent() calls throw. Always guard loops with budget.total && to avoid this in unconstrained sessions.

09 Common Gotchas & Anti-Patterns

10 When to Use What

Decision heuristic

• 1 thing to look up → inline tool
• 1–3 things to research → Agent tool
• N items × M stages, or unknown N → Workflow
• N agents writing files simultaneously → Workflow + worktree
• Uncertain scope → scout inline first, then call Workflow once you know the work-list shape