Skip to main content

​
Foreach & Parallel

Most real workflows decompose work into items and process each one. Gump handles this with foreach and optionally parallel.

​
Foreach

The foreach field points to a plan step. Gump iterates over the items produced by that step and runs the child steps for each one. 
steps:
  - name: decompose
    agent: claude-opus
    output: plan
    prompt: "Decompose {spec} into items."
    gate: [schema]

  - name: build
    foreach: decompose
    steps:
      - name: impl
        agent: claude-sonnet
        prompt: |
          Implement: {item.description}
          Files: {item.files}
        gate: [compile, test]
If decompose produces 3 items, the build group runs 3 times — once per item. Inside the group, {item.name}, {item.description}, and {item.files} refer to the current item. Items are processed sequentially by default. Each item’s sub-steps run in the worktree, results are committed, and the next item starts from the updated state.

​
Parallel

Add parallel: true to run all items simultaneously: 
- name: build
  foreach: decompose
  parallel: true
  steps:
    - name: impl
      agent: claude-sonnet
      prompt: |
        Implement: {item.description}
        Only touch: {item.files}
      gate: [compile, test]
Each item gets its own worktree (cloned from the current state). Agents work simultaneously. When all items complete, Gump merges the worktrees back together sequentially in declaration order.

​
The MECE requirement

Parallel execution requires items with strictly disjoint blast radii. If two items modify the same file, the merge will create a Git conflict and trigger the circuit breaker — the run stops. Your plan prompt should enforce this: 
prompt: |
  Decompose {spec} into independent items with strictly disjoint
  blast radii. No two items may touch the same file.

​
Parallel steps (without foreach)

You can also parallelize steps within a group without foreach: 
- name: reviews
  parallel: true
  steps:
    - name: arch-review
      agent: claude-opus
      output: review
      prompt: "Review architecture..."

    - name: security-review
      agent: gemini
      output: review
      prompt: "Review security..."
Both reviews run simultaneously. Since they produce review output (no file changes), there’s no merge conflict risk. Their outputs are available in the state bag once both complete.

​
Group-level gate and on_failure

An orchestration step (with child steps) can have its own gate and on_failure: 
- name: build
  foreach: decompose
  steps:
    - name: impl
      agent: claude-sonnet
      gate: [compile, test]
    - name: review
      agent: claude-opus
      output: review
  gate: [compile, test]
  on_failure:
    retry: 2
    restart_from: impl
The group-level gate runs after all child steps complete. If it fails, on_failure retries the entire group (or restarts from a specific step). The worktree is reset to the pre-group state before each retry.