workflow-builder

Workflow Builder — scaffold a Claude Workflow script

Counterpart to skill-builder. skill-builder authors a SKILL.md (a leaf

capability); this authors a Workflow (a composite capability — deterministic

orchestration of subagents). Reach this skill via automation-shape-routing

once the shape is confirmed Workflow (deterministic DAG + structured-JSON

returns + headless). If the shape is NTM or plain skill, you're in the wrong

builder — go back to automation-shape-routing.

Confirm the shape first

Do NOT scaffold a workflow for: an attach-and-steer run (→ NTM: ntm / vibing-with-ntm), or a hard-sequential edit-loop with no parallelism (→ plain skill: skill-builder). If unconfirmed, run automation-shape-routing.

The template

Start from .claude/workflows/operating-loop.js — the canonical worked example. Copy its skeleton, don't reinvent it. A Workflow script is plain JS:

export const meta = {                 // REQUIRED — pure literal, no variables
  name: 'my-workflow',
  description: 'one line shown in the permission dialog',
  phases: [ { title: 'Find' }, { title: 'Verify' } ],  // one per phase() call
}

phase('Find')
const found = await parallel(FINDERS.map(f => () =>
  agent(f.prompt, { schema: FINDINGS_SCHEMA, phase: 'Find' })))   // barrier

phase('Verify')
const verified = await pipeline(found.flat().filter(Boolean),
  f => agent(`verify: ${f.title}`, { schema: VERDICT, phase: 'Verify' }))

return { verified }

Building blocks (pick by control-flow shape)

| Primitive | Use when | |---|---| | agent(prompt, {schema}) | one subagent; schema forces structured JSON back | | parallel([thunks]) | barrier — need ALL results together (dedup/merge/early-exit) | | pipeline(items, ...stages) | default multi-stage — no barrier, each item flows independently | | phase(title) | progress grouping; match meta.phases titles | | loop-until-budget / loop-until-dry | unknown-size discovery; guard on budget.total |

Authoring checklist

1. Shape confirmed Workflow (via automation-shape-routing).
2. Schemas first — define the JSON schema each agent() returns; structured

output is what makes a workflow deterministic and composable.

1. Default to pipeline(); reach for parallel() only when a stage genuinely

needs all prior results at once.

1. Conflict-free fan-out — if branches write files, give each a disjoint

write-scope (the wave-validity invariant) or run in worktree isolation.

1. Budget — for loops, gate on budget.total && budget.remaining() > N.
2. Dry-run to validate — invoke the workflow on a tiny input; confirm the

meta block parses and each phase returns its schema. This is the workflow analog of skill-auditor.

Relationship to the SDK

A workflow is a composite capability; the portable contract for it (a shape: skill|workflow discriminator, a StepGraph, a control_flow enum, a budget, an OrchestrationPort interface) is net-new agentops-core-sdk work. Author the script here; the SDK is where the contract for workflow-capabilities lives. See operating-loop-workflow for installing/running a finished workflow.