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

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

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.