# Parallel Execution

> ⚠️ **Experimental** — Squad is alpha software. APIs, commands, and behavior may change between releases.


**Try this to launch concurrent work streams:**
```
Have three agents work on this in parallel: UI mockups, API spec, and database schema
```

**Try this to work multiple issues simultaneously:**
```
Work on issues #12, #15, and #18 at the same time
```

**Try this to control concurrency for cost savings:**
```
Run at most 2 agents at once to save costs
```

Squad launches independent work in parallel by default — multiple agents work simultaneously, no waiting. You control concurrency limits and can force sequential execution when needed.

---

## How Parallel Execution Works

Squad runs agents in parallel whenever possible. The fan-out pattern launches all independent agents simultaneously, waits for results, then proceeds — no sequential bottlenecks unless data dependencies or reviewer gates require them.

## How Parallel Execution Works

When the coordinator receives work:

1. **Dependency Analysis** — Check if tasks have data dependencies (A needs output from B).
2. **Fan-Out** — Launch all independent agents in parallel using `mode: "background"`.
3. **Wait** — Coordinator polls agent status until all complete.
4. **Collect** — Aggregate results, check for errors, route to next step.

### Example: Feature Implementation

> "Implement user authentication: API endpoints, frontend form, tests, and documentation"

Coordinator spawns **4 agents in parallel**:
- Backend → API endpoints
- Frontend → Login/signup form
- Tester → Integration tests
- DevRel → Auth documentation

All work simultaneously. No agent waits for another unless there's a code dependency.

## Background vs Sync Mode

| Mode | When to Use | Behavior |
|------|-------------|----------|
| `background` | Independent work, no data dependencies | Agent runs in parallel, coordinator polls for completion |
| `sync` | Data dependency (one agent needs output from another) | Agent runs sequentially, coordinator waits |
| `sync` | Reviewer gate (Lead must approve before continuing) | Agent runs, coordinator waits for review decision |

### Background Mode

Used for **fan-out parallelism**:

```
Coordinator → [Agent1, Agent2, Agent3] (background)
                ↓        ↓        ↓
              Result1  Result2  Result3
                ↓        ↓        ↓
            Coordinator collects all
```

Agents don't see each other's output until the coordinator collects and synthesizes.

### Sync Mode

Used for **dependencies and gates**:

```
Coordinator → Agent1 (sync) → Result1
                ↓
      Coordinator → Agent2 (sync, uses Result1) → Result2
                ↓
      Coordinator → Reviewer (sync, gates next step)
```

Each step blocks until the previous completes.

## Eager Execution Philosophy

Squad's default is **eager parallelism** — launch everything that can run, let the coordinator handle synchronization. Benefits:

- **Faster throughput** — No artificial sequencing.
- **Better resource utilization** — Multiple agents saturate available compute.
- **Resilient to blocking** — If one agent stalls, others keep working.

Trade-off: Increased API cost (multiple agents running simultaneously). If cost is a concern, tell the coordinator:

> "Work sequentially to save costs"

Coordinator switches to sync mode for all agents.

## Deadlock Avoidance

When agents have circular dependencies:

- **Agent A** needs output from **Agent B**
- **Agent B** needs output from **Agent A**

The coordinator detects the cycle during dependency analysis and prompts:

```
⚠️ Circular dependency detected: A ↔ B
Choose resolution:
1. Run A first, then B
2. Run B first, then A
3. Redesign to remove dependency
```

## Reviewer Gates

Some tasks require **sequential review**:

1. Agent writes code → Draft PR
2. Lead reviews → Approves or rejects
3. If approved → Merge and close
4. If rejected → Reassign or escalate (agent is **locked out**)

This is a **sync gate** — the next step cannot proceed until the reviewer completes.

## Parallel Execution Logs

The coordinator logs parallel execution in `.squad/orchestration-log/`:

```
[2024-01-15 14:30:00] FAN-OUT: Spawning 4 agents (Backend, Frontend, Tester, DevRel)
[2024-01-15 14:30:15] AGENT: Backend started (background)
[2024-01-15 14:30:16] AGENT: Frontend started (background)
[2024-01-15 14:30:17] AGENT: Tester started (background)
[2024-01-15 14:30:18] AGENT: DevRel started (background)
[2024-01-15 14:35:42] COLLECT: Backend completed (success)
[2024-01-15 14:36:10] COLLECT: Frontend completed (success)
[2024-01-15 14:36:55] COLLECT: DevRel completed (success)
[2024-01-15 14:38:20] COLLECT: Tester completed (success)
[2024-01-15 14:38:21] FAN-IN: All agents complete
```

## Parallel Limits

The coordinator respects concurrency limits to avoid rate limits or resource exhaustion:

- **Default:** 5 agents in parallel
- **Adjustable:** `"Run at most 3 agents at once"` → Coordinator batches work in groups of 3

## Sample Prompts

```
Build the new dashboard feature — everyone work in parallel
```
Coordinator spawns all relevant agents (Frontend, Backend, Tester, DevRel) simultaneously.

```
Implement the API first, then write tests — do it sequentially
```
Forces sync mode: Backend runs, completes, then Tester starts.

```
Work on issues #12, #15, and #18 at the same time
```
Spawns 3 agents in parallel, one per issue. Assumes no dependencies between issues.

```
Run at most 2 agents at once to save costs
```
Sets concurrency limit. Coordinator batches work: runs 2, waits for completion, runs next 2.

```
Why is Tester waiting? Show me the dependency graph.
```
Coordinator explains why Tester is blocked (e.g., waiting for Backend to finish implementation).
