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

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:

{
  "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 during the planning stage. Users can override this setting when invoking the execute command:

/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 – The declarative workflow implementing wave-based parallel orchestration and the core execution loop.
• 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 – Optional verification subagent spawned after all executors complete to validate must_haves criteria.
• templates/phase-prompt.md – Template defining phase metadata including the parallelization flag and must_haves requirements.
• docs/USER-GUIDE.md – High-level documentation describing the /gsd:execute-phase command and parallel execution behavior.
• 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}