dynamic-workflows

# 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. ```javascript 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). ```javascript 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.