`for each`

Run a template once per item. Compose

Syntax

for each <var> in "<file>":
  run "<template.loop>"

What it does

Dynamic fan-out inside a flow: read a plan file and run a single template loop once per item — each item's text becomes that run's context (what to build). The source is a .yaml file (a list, or a single-key list like items:) or a .md file (which splits on each ## section). If an item's own checklist fails, the flow pauses and asks: continue with the next item, or stop?

Reach for for each when you have a backlog of same-shaped work — a dozen endpoints to scaffold, a list of stories to deliver, a set of files to migrate — where the steps are identical but the subject differs each time. Instead of writing one stage per item by hand, you write the template once and let a planning step discover the list at run time. That is the key difference from a fixed pipeline: the number and content of items are not known when you author the flow; they are read from the plan file when the flow runs, so the same flow adapts as the backlog grows or shrinks. It is method-neutral — the plan file can be any checklist, not only a BMAD backlog — and the per-item pause on failure keeps a single bad item from silently poisoning the whole batch.

Examples

flow "deliver":
  for each item in "plan.yaml":
    run "item-template.loop"

examples/foreach/deliver.loop

# plan.yaml — .yaml list (or .md: each "## " section is one item)
items:
  - title: Parse the uploaded CSV into rows
  - title: Validate rows against the schema

the source file

How it runs

for each is dynamic fan-out: a planning step discovers the items, then the same template runs once per item.

Common mistakes

Using it outside a flow. for each only lives inside a flow. It is not a general loop construct — a single self-correcting loop uses loop, and a fixed sequence uses pipeline.
An unsupported source file. The list must come from a .yaml file (a list or a single-key items: list) or a .md file split on ## headings. Point it at anything else and there are no items to fan out over.
A template with no per-item check. The pause-on-failure only triggers if the template's own done when can fail. A template with no real check will "succeed" on every item, including the broken ones — give the template a verifiable predicate.
Expecting items to share context. Each item runs the template fresh with only that item's text as context. Items don't see each other's results; if item 3 depends on item 1's output, model that dependency explicitly rather than assuming order carries state.

for each