dynamic-workflows

Gives every dynamic workflow script you write a consistent, load-bearing
structure instead of an ad-hoc pile of agent() calls. It combines two
sources that play different roles:

• reference/api.md (authoritative) — distilled from Anthropic's own
  dynamic-workflows docs and the Workflow tool's own spec. This is the
  actual mechanics: what agent()/parallel()/pipeline()/workflow()
  do, what the runtime enforces (determinism, concurrency caps, no mid-run
  input), and what the tool's own quality-pattern guidance says. When in
  doubt about what a call does or what's allowed, this file is the one that's
  right.
• reference/patterns.md (semantic framework) — a vocabulary layer
  distilled from the field note "Dynamic Workflow Design Patterns"
  (zircote, July 2026): 20 named patterns across four families plus 8 named
  anti-patterns, GoF-style. This gives shapes names ("Scout-Worker",
  "Adversarial Verify", "Loop-Until-Dry") so a script's structure can be
  discussed and reused instead of reinvented per task. It is a naming and
  decision-making convenience over the API, not a second spec — if a
  pattern description and the API reference ever seem to conflict, the API
  reference is correct and the pattern's phrasing should be read loosely.

Both sources are vendored under vendor/ with a VENDOR.lock recording
where each came from and when it was last refreshed — see the plugin
README for how to re-hydrate them as the product and the
field note evolve.

Before writing any workflow script

1. Confirm the opt-in. Only write a Workflow call when the user
   actually asked for multi-agent orchestration (their own words, the
   ultracode keyword, a skill/command that says to, or a named saved
   workflow) — see reference/api.md for the exact bar. Otherwise use the
   Agent tool directly, or describe the option and ask.
2. Pick the shape before the items. You don't need to know the exact
   work-list up front, but decide the pattern first: is this a known list
   to fan out over (Streaming Pipeline), an unknown-size discovery problem
   (Loop-Until-Dry), a fix-and-recheck loop (Converge-Until-Green), or a plan
   that needs to be weighed from several angles (Judge Panel)? See the
   decision guide at the end of reference/patterns.md.
3. Default to pipeline(), not parallel(). Reach for a barrier only
   when a stage genuinely needs the complete prior result set (dedup,
   aggregate branching, ranking). This single habit avoids the catalog's
   most common mistake, Barrier Abuse — see reference/api.md's
   "pipeline() vs parallel()" section for the smell test.
4. Schema every agent() call that feeds another call. Bind schema on
   anything downstream code or another agent will consume; free-text parsing
   between stages is the Free-Text Parsing anti-pattern and silently
   forfeits the ability to route that stage to a cheaper model.
5. Decide the verification story up front, not as an afterthought: does
   a finding need Adversarial Verify (independent skeptics, majority vote),
   Perspective-Diverse Verify (distinct lenses), or a Test Gate (an
   executable oracle)? "More agents" alone does not raise confidence —
   arranging agents to check each other does.
6. Guard every unbounded construct: a budget-driven loop must check
   budget.total != null before looping on budget.remaining(); a
   discovery loop must have a round cap or a K-consecutive-empty-rounds stop
   condition. Both are the entry point for the Unbounded Loop
   anti-pattern.
7. Use log() at every meaningful milestone. Nothing that happens
   inside a running workflow reaches the conversation except the final
   return value — the progress view and log() lines are the only window
   into a background run while it's going.

Reviewing an existing workflow script

Walk it against the 8 named anti-patterns in reference/patterns.md (Barrier
Abuse, The Impatient Monitor, Hidden Clock, Context Flood, Mid-Run
Conversation, Unbounded Loop, Free-Text Parsing, Monolithic Agent) before
suggesting changes — each has a one-line symptom and a named fix. Then check
it against the hard constraints table in reference/api.md (determinism,
concurrency/agent caps, batch-size limits, no mid-run input) — those are
enforced by the runtime, not stylistic preferences, so a violation there is a
bug, not a style note.

Quick pattern index

Full pattern entries, applicability, and consequences: reference/patterns.md.
Full API mechanics, limits, and canonical code examples: reference/api.md.