# How the Execute-Phase Orchestrator Manages Parallel Subagents in GSD-Build

> Discover how the GSD-build execute phase orchestrator manages parallel subagents using wave-based scheduling to optimize build processes and respect dependencies.

- Repository: [GSD/get-shit-done](https://github.com/gsd-build/get-shit-done)
- Tags: internals
- Published: 2026-02-16

---

**The execute-phase orchestrator in gsd-build uses wave-based scheduling to run multiple gsd-executor subagents in parallel within each wave while processing waves sequentially to respect dependencies.**

The execute-phase orchestrator serves as the central driver in the `gsd-build/get-shit-done` repository, transforming verified phase plans into concrete code changes. By decoupling orchestration from work-execution, the system enables parallel execution across independent plans while maintaining deterministic, dependency-aware progression through complex build phases.

## Understanding the Execute-Phase Orchestrator Architecture

When you invoke `/gsd:execute-phase <phase>`, the orchestrator initializes a complete execution context through the `init execute-phase` helper located in `gsd-tools.cjs`. This JSON payload includes the selected **executor model**, a `PARALLELIZATION` boolean flag, and a **wave-grouped plan list** where each wave contains plans with no file conflicts or mutual dependencies.

The architecture intentionally separates the orchestrator's scheduling logic from the actual code generation performed by subagents. This separation allows the orchestrator to remain lightweight while delegating CPU-intensive work to specialized `gsd-executor` agents running in parallel waves.

## Wave-Based Scheduling: The Core Parallelization Strategy

The orchestrator implements a **wave-based scheduling algorithm** that balances parallelism with dependency safety. This approach groups independent plans into waves that execute sequentially, while plans within each wave run concurrently.

### Sequential Wave Processing

Waves are processed in strict order to guarantee dependency satisfaction. If a plan in wave 3 depends on output from a plan in wave 1, the orchestrator ensures wave 1 completes entirely before wave 3 begins. This sequential control prevents race conditions and ensures file system state remains consistent across dependent operations.

### Within-Wave Parallelism

For each wave, the orchestrator checks the `PARALLELIZATION` flag defined in the phase's `.planning` metadata. When enabled, the orchestrator spawns a **Task** for every plan in the wave using `subagent_type="gsd-executor"`. These tasks run as independent background processes, allowing multiple executors to generate code simultaneously. If parallelization is disabled, plans within the wave execute sequentially using the same subagent type but without concurrent spawning.

## Spawning GSD-Executor Subagents in Parallel

Each plan execution involves spawning a dedicated `gsd-executor` subagent through the Task tool. The orchestrator constructs a task payload specifying:

```json
{
  "subagent_type": "gsd-executor",
  "model": "sonnet",
  "prompt": "Execute plan /path/to/.planning/phases/03-auth/plan-01-PLAN.md",
  "run_in_background": true
}

```

The `run_in_background` flag enables true parallelism, allowing the orchestrator to launch multiple executors without blocking. Each `gsd-executor` subagent receives the full plan file, performs atomic Git commits, handles deviations from expected outcomes, and manages internal checkpoints. Because these subagents operate independently, they can utilize available CPU cores efficiently while the orchestrator monitors their collective progress.

## Handling Checkpoints and Failures in Parallel Execution

Parallel execution introduces complexity when subagents encounter checkpoints or failures. The orchestrator implements specific protocols to maintain consistency across concurrent operations.

When a subagent reaches a checkpoint, it returns a continuation token to the orchestrator. The orchestrator records this token but **waits for all subagents in the current wave** to either complete or pause at their own checkpoints before proceeding to the next wave. This synchronization point ensures that partial wave completion never leaves the repository in an inconsistent state.

If any subagent fails during execution, the orchestrator immediately aborts the entire wave and surfaces the error to the user. The system supports idempotent re-runs: when you re-execute the phase, the orchestrator automatically skips plans marked as already completed, allowing the phase to resume from the point of failure without redundant work.

## Configuration: Enabling and Disabling Parallelization

Parallelization behavior is configurable at multiple levels. The `PARALLELIZATION` flag resides in the phase's `.planning` metadata, typically defined in [`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md) during the planning stage. Users can override this setting when invoking the execute command:

```text
/gsd:execute-phase 3 --no-parallel

```

The `--no-parallel` flag forces sequential execution within waves regardless of the default configuration. Conversely, omitting this flag when `PARALLELIZATION=true` in the metadata enables full parallel execution across independent plans.

## Key Source Files and Implementation Details

The execute-phase orchestration logic is distributed across several key files in the `gsd-build/get-shit-done` repository:

- **[`get-shit-done/workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/get-shit-done/workflows/execute-phase.md)** – The declarative workflow implementing wave-based parallel orchestration and the core execution loop.
- **[`agents/gsd-executor.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-executor.md)** – Definition of the executor subagent responsible for atomic commits, deviation handling, and checkpoint management during plan execution.
- **[`agents/gsd-verifier.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-verifier.md)** – Optional verification subagent spawned after all executors complete to validate `must_haves` criteria.
- **[`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md)** – Template defining phase metadata including the `parallelization` flag and `must_haves` requirements.
- **[`docs/USER-GUIDE.md`](https://github.com/gsd-build/get-shit-done/blob/main/docs/USER-GUIDE.md)** – High-level documentation describing the `/gsd:execute-phase` command and parallel execution behavior.
- **[`commands/gsd/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/commands/gsd/execute-phase.md)** – CLI command wrapper that invokes the underlying workflow.

## Summary

- The **execute-phase orchestrator** uses **wave-based scheduling** to balance parallelism with dependency safety, processing waves sequentially while executing plans within each wave concurrently.
- **GSD-executor subagents** are spawned as independent background tasks using `subagent_type="gsd-executor"`, allowing multiple code generation processes to run simultaneously across available CPU cores.
- **Checkpoint synchronization** ensures the orchestrator waits for all subagents in a wave to complete or pause before proceeding, maintaining repository consistency during parallel operations.
- **Configuration flexibility** allows users to enable or disable parallelization via the `PARALLELIZATION` flag in `.planning` metadata or the `--no-parallel` CLI flag.

## Frequently Asked Questions

### How does the execute-phase orchestrator handle dependencies between plans?

The orchestrator organizes plans into **waves** based on dependency analysis. Plans with no mutual dependencies or file conflicts are grouped into the same wave, while dependent plans are placed in subsequent waves. The orchestrator processes waves sequentially, ensuring that a wave containing dependent plans only executes after all previous waves have completed successfully.

### What happens if one parallel subagent fails while others are still running?

If any **gsd-executor** subagent fails during parallel execution, the orchestrator immediately aborts the entire current wave and surfaces the error to the user. The system supports idempotent re-runs, meaning when you re-execute the phase, the orchestrator automatically skips plans already marked as completed, allowing the phase to resume from the point of failure without redundant work.

### Can I disable parallelization for specific phases while keeping it enabled for others?

Yes, parallelization is configurable at the phase level through the `.planning` metadata defined in [`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md). Each phase can have its own `PARALLELIZATION` flag setting. Additionally, you can override the configured behavior at runtime using the `--no-parallel` flag when invoking `/gsd:execute-phase <phase>`, allowing you to force sequential execution for specific runs regardless of the phase's default setting.

### How does the orchestrator ensure file system consistency when multiple subagents modify code simultaneously?

The orchestrator maintains consistency through **wave-based synchronization** and **atomic commits**. Within a wave, subagents operate on plans that have been verified to have no file conflicts. The orchestrator waits for all subagents in a wave to either complete or reach a checkpoint before proceeding to the next wave. Each **gsd-executor** subagent performs atomic Git commits, ensuring that partial changes from different subagents never interleave in a way that leaves the repository in an inconsistent state.