Parallel Execution · Foundry docs

Parallel ExecutionParallel Execution (V2)

Information

Start building in parallel from a ready-made starter kit that you can white-label and own the source of.

Foundry V2 introduces a Task Dependency Graph (DAG) and a Parallel Worker Pool, allowing independent tasks to run concurrently.How It WorksThe monolithic control loop splits into two components:The Scheduler (The Brain)Runs on every "Task Completed" event:

Update Graph: Mark completed task.

Check Dependents: Find all tasks depending on the completed one.

Promote: If all dependencies are met, atomically move task from Waiting → Ready.

The Worker Pool (The Muscles)A configurable set of workers (default: 3):

Poll: Take the next task from the ready queue.

Lock: Acquire execution lock for the task.

Execute: Spawn isolated agent context in a git worktree.

Report: Write result to state. Emit task completed event.

Dual-Queue System

Queue

Contains

Behavior

Ready (queue:ready)

Tasks with all dependencies met

Active: polled by Worker Pool

Waiting (queue:waiting)

Tasks with unmet dependencies

Passive: checked on task completion

Concurrency Control

File Locking: Tasks declare affects_files. The scheduler uses file-level locking with exponential backoff so no two tasks edit the same file.

Git Worktree Isolation: Each worker operates in its own worktree, preventing file system conflicts between concurrent tasks.

Task Recovery: On scheduler crash, interrupted tasks are re-enqueued automatically.

Task Fields for Parallel Mode

affects_files (required): Files this task modifies: used for file-level locking.

depends_on (optional): Task IDs that must complete first: auto-promoted when deps met.