Loops

Some work is iterative by nature. A loop node repeats one prompt until the output contains a completion signal or the maximum iteration count is reached.

Current YAML Shape

Use the field-discriminated loop: form. Do not add type: loop, body:, iterations:, or over: fields.

nodes:
  - id: refine-draft
    loop:
      prompt: |
        Improve the draft in $ARGUMENTS.
        When the draft is ready, end with READY.
      until: READY
      max_iterations: 5
      fresh_context: true

Z.E.N. runs the prompt and repeats until the completion signal is detected or max_iterations is reached. The signal is recognized as an XML-like tag (<promise>COMPLETE</promise>, recommended) or as the plain until value at the very end of the output or on its own line — not merely appearing mid-sentence.

Bash Gate

Use until_bash when a deterministic command should decide whether the loop can stop:

nodes:
  - id: implement-until-tests-pass
    loop:
      prompt: |
        Fix the next failing test. End with DONE when you have made a change.
      until: DONE
      until_bash: bun test
      max_iterations: 5

The loop stops when the prompt emits DONE or until_bash exits successfully.

When to Avoid Loop

If each pass needs a different node type, separate agent review, delivery, or per-item fanout, model that as normal DAG nodes around a loop node. The current loop node repeats one AI prompt. For multi-agent review loops, use first-class agent: nodes and gate them with normal DAG dependencies and conditions.