Dynamic Workflows

The workflow tool executes a JavaScript orchestration script you write. The script holds the loop, branching, and intermediate results; each agent() call runs one isolated subagent in its own pi process; only the script's return value comes back into your context. This is how you audit 20 files, research 8 topics, or apply the same change across 20 independent files without burning your own context window on the intermediate output.

When to use it

• The work decomposes into several independent investigations or changes whose intermediate outputs you don't need verbatim - only a synthesis (or a report of what changed).
• Examples: audit every route/module for a property, summarize each package of a monorepo, verify a list of findings adversarially, research N alternatives, rename an API across every file that references it.

Do not use it for: a single question or a single edit (use subagent or just do it directly), one or two parallel tasks (use subagent parallel mode), or work needing your full conversation context.

Script shape

Prefer the strict declared-plan contract below. Strict mode turns on only when meta.phases is a literal object the runtime can read without executing code; older/dynamic scripts keep their legacy behavior. Do not set token budgets: choose only the appropriate persona/model tier and let the host account actual usage.

export const meta = {
  name: 'audit_routes',
  goal: 'Produce a decision-ready router audit',
  inputs: ['repository'],
  phases: [
    { title: 'Scan', goal: 'Map routers', inputs: ['repository'], produces: ['router inventory'] },
    { title: 'Audit', goal: 'Check the inventory', inputs: ['router inventory'], produces: ['router audits'] },
    { title: 'Synthesize', goal: 'Deliver the verdict', inputs: ['router audits'], produces: ['audit verdict'] },
  ],
  synthesis: { phase: 'Synthesize', inputs: ['router audits'], produces: ['audit verdict'] },
}

phase('Scan')

const inventory = await agent(
  'List every *.router.ts file under packages/host-router/src/routers. Reply with only JSON.',
  {
    label: 'route inventory',
    objective: 'Produce the complete router inventory for the audit.',
    inputs: ['repository'],
    produces: 'router inventory',
    schema: { type: 'object', required: ['files'], properties: { files: { type: 'array', items: { type: 'string' } } } },
  },
)
if (!inventory) return { ok: false, error: 'inventory failed' }

phase('Audit')
const audits = await agent(
  'Audit the router inventory against the one-line-forward rule. Return every violation as JSON.',
  { label: 'router audit', objective: 'Audit all discovered routers for inline logic.', inputs: ['router inventory'], produces: 'router audits', schema: { type: 'object', required: ['violations'] } },
)

phase('Synthesize')
const verdict = await agent(
  'Summarize the supplied router audits into {ok, violations: [...]}. Reply with only JSON.',
  { label: 'final verdict', agent: 'Plan', objective: 'Create the final decision-ready audit report.', inputs: ['router audits'], produces: 'audit verdict', schema: { type: 'object', required: ['ok', 'violations'] } },
)
return verdict

In strict mode, activate declared phases exactly in order; agent inputs are artifact-name arrays (not inline records), every declared phase output must be published exactly once (an agent automatically publishes its declared produces, or use publish(name, value) for aggregates), and the final synthesis phase must publish its named final artifact. Give every phase a goal, every agent a unique label and objective, and all real handoffs named inputs/outputs.

Rules: plain JavaScript (no TypeScript, no import/require); the leading export const meta = { name, description } is optional but conventional; the script must call agent() at least once; the return value must be JSON-serializable (a common mistake is returning an unawaited agent() promise).

API

Global	Behavior
agent(prompt, opts)	Runs one subagent; resolves to its final text, or the parsed+shape-checked object when opts.schema is set, or null on failure. Opts: label (short, unique - drives the live display), objective (responsibility), inputs (artifact-name strings or a record of named string values), produces (one artifact name), agent ('Explore' default, 'Plan', or 'General'), schema (plain JSON Schema), cwd, model (tier keyword, see below).
parallel(thunks)	await parallel(items.map(i => () => agent(...))) - functions, not promises. Results in input order; failed branches are null.
pipeline(items, ...stages)	Fans items through sequential stages (map → verify → summarize). Items run concurrently; each item's stages run in order; each stage receives (previousValue, originalItem, index). A failed stage nulls that item's slot.
phase(title, meta?)	Marks a new stage of work for the live progress display. Prefer phase('Audit', { goal: '...', inputs: ['inventory'], produces: ['findings'] }) so the upcoming plan and dependencies are visible before it runs. goal, inputs, and produces are optional; dynamic/conditional phases remain supported.
log(message)	Appends a workflow-level log line (shown in the expanded view).
parseJson(text)	Extracts JSON from an agent's text reply, tolerating fences and surrounding prose. Prefer schema on agent() instead.
args	The JSON value passed in the tool call's args parameter.
cwd	The workflow's working directory (string).

Limits: 8 agents run concurrently, 256 per workflow. require, fs, fetch, and timers are unavailable inside the script - all real work happens inside subagents.

Which agent

Agent	Capability	Model (default)	Use for
Explore (default)	Read-only	Fast/cheap	Recon, per-item checks, broad search
Plan	Read-only	Inherits your model	Judgment-heavy planning or synthesis
General	Read-write	Inherits your model	The actual edits an investigation identified, or any fan-out that needs real changes

Only General edits files. Reach for it when a change is mechanical/independent enough to parallelize (e.g. the same fix across many files) rather than applying every edit yourself after the workflow returns.

Model override

agent()'s model option picks a different model than the persona's own default for just that call, using a tier keyword, not a guessed exact model id (the available model list changes over time, so a literal id can silently be wrong):

• 'strong' - the best available model. Use for a genuinely hard General edit or a judgment call worth spending more on.
• 'medium' - a solid mid-tier model.
• 'cheap' - fast and cheap. Use to bump a Plan/General call down for something simple, or to run more Explore-style recon than the default budget would allow.

Omit model entirely to use the persona's own default (most calls should).

await agent('Investigate whether this auth check has a bypass.', { agent: 'Plan', model: 'strong', label: 'auth bypass check' })

Failure semantics

A failed agent() / parallel() branch / pipeline() item becomes null plus a log line; the rest of the workflow continues. Always check for nulls before synthesizing - audits.filter(Boolean) or an explicit guard. Only aborts and script bugs (unknown agent name, bad arguments, exceeding limits) fail the whole workflow.

Writing good workflows

• Subagents share no context with you or each other: every prompt must carry its own file paths, constraints, and any prior findings it depends on. Add objective, inputs, and produces to each agent call: they add a concise child context block and let the live workflow show responsibility and downstream artifact use.
• Use schema whenever an agent's output feeds a later stage; use free text only for the final human-readable synthesis. Define a schema once in a const and reuse it across parallel agents instead of repeating large nested object literals.
• End with a synthesis step and return a compact value (verdict + key findings), not a dump of every intermediate output - the return value is all you get back.
• Default to Explore for recon and per-item checks, Plan for judgment-heavy synthesis, and General only for the calls that actually need to write files.