/dynamic-workflows

name: dynamic-workflows
description: >-
  Designs and runs task-specific JavaScript harnesses with the `workflow` tool. Use for broad,
  long-running, highly structured, or adversarial work that benefits from many isolated agents:
  exhaustive audits, root-cause investigations, research, large triage queues, competing proposals,
  repeated verification, and independent changes across disjoint files. Covers decomposition patterns,
  agent and model routing, structured handoffs, failure handling, and the workflow runtime API.

Dynamic workflows

The `workflow` tool runs a JavaScript program that coordinates isolated subagents. Use the program as a task-specific harness: JavaScript owns iteration, routing, barriers, and completion checks, while each `agent()` call handles one focused unit of work in a fresh context window.

Only the script's return value enters the parent context. Intermediate results stay inside the workflow, while structured progress and logs remain visible in the tool call. End broad workflows with a compact synthesis instead of returning every worker transcript.

This separation is useful when one long conversation would make it hard to remain complete, impartial, or faithful to the original goal. It is not a default for ordinary work. More agents mean more latency and token use.

Decide whether a workflow earns its cost

Use a workflow when at least one of these is true:

• **Breadth:** the task covers many independent files, records, systems, claims, or alternatives.
• **Structure:** the work needs explicit stages, routing, aggregation, or a completion condition.
• **Independent judgment:** a result should be challenged by an agent that did not produce it.
• **Competing approaches:** several agents should attempt the same problem before a separate judge chooses.
• **Unknown work size:** the task should repeat until no unresolved items or new findings remain.
• **Context isolation:** each unit benefits from a clean context that contains only its evidence and rubric.

Good requests include:

• Audit every ingestion stage for one invariant, then verify each reported violation.
• Form independent explanations for a production symptom and try to disprove each one.
• Generate several migration plans, compare their risks, and return one tested recommendation.
• Classify a large issue backlog, deduplicate related reports, and prepare actions for confirmed groups.
• Check every factual statement in a technical report against primary evidence.
• Apply the same independent change across disjoint packages, then review the combined diff.

Do not use a workflow for:

• One question, one investigation, or one edit.
• One or two independent delegations. Use `subagent` parallel mode instead.
• Work where nearly all parent conversation context is essential.
• Several writers that would edit the same files or shared state concurrently.
• A routine task where direct execution is cheaper and easier to verify.

Define success before writing JavaScript

Write down these decisions first:

1. **Final outcome:** what compact value must the workflow return? 2. **Work units:** what list will the script iterate over? 3. **Evidence:** what must each worker cite or return? 4. **Rubric:** what makes an item pass, fail, rank higher, or require another pass? 5. **Coverage:** how will the result prove that every required item was processed? 6. **Failure policy:** which failures may become `null`, and which must stop the workflow? 7. **Write boundaries:** which agents may edit, and can their files overlap?

Keep these decisions in JavaScript variables, schemas, and stop conditions. Do not rely on one agent to remember the whole plan across a large run.

Choose an orchestration pattern

Patterns compose. Use the smallest combination that creates a reliable feedback loop.

Classify and act

Use one agent to assign each item to a small set of categories, then route each category to a specialized prompt or agent.

Use it for mixed backlogs, heterogeneous files, and requests where not every item needs the same treatment. Keep classification structured and include an `unknown` route. Do not force uncertain items into a confident category.

Fan out and synthesize

Map independent items to agents, wait for all results, then give a bounded set of structured outputs to one synthesis agent.

Use it for broad audits, research, and repeated checks. The synthesis step is a barrier: it runs only after the fan-out settles. Return coverage and failures with the synthesis so missing work stays visible.

Adversarial verification

Separate production from judgment. A worker proposes a finding or change; another agent checks it against an explicit rubric and evidence.

Use it when false positives, unsupported claims, or self-review bias would be costly. A verifier must receive the original requirement and evidence, not only the worker's conclusion.

Generate and filter

Ask several agents for candidates, normalize and deduplicate them, then use a separate agent to reject weak candidates against a rubric.

Use it for designs, names, hypotheses, and solution exploration. Preserve reasons for rejection when they help the final decision.

Tournament

Have multiple agents solve the same task independently. Compare two candidates at a time with a judge until one or a small shortlist remains.

Use comparative judgment when absolute scores would be vague. Randomize or rotate candidate order when ordering could bias the judge. Do not let an author judge its own output.

Loop until done

Repeat discovery and action until a measurable stop condition is true, such as no failing tests, no unprocessed items, or no new evidence after a pass.

Always set a hard pass or agent limit. Track what changed between passes. Stop if a pass makes no progress, and return the unresolved state instead of claiming completion.

Independent hypothesis testing

Give separate agents disjoint evidence or differe