# How gsd-build Handles Wave-Based Parallel Plan Execution: Dependency Orchestration in the Get-Shit-Done Orchestrator

> Discover how gsd-build handles wave-based parallel plan execution by pre-computing wave numbers from dependency graphs for efficient, ordered concurrency. Learn dependency orchestration.

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

---

**gsd-build orchestrates parallel plan execution by pre-computing wave numbers from dependency graphs, ensuring plans run concurrently within waves while maintaining strict sequential ordering between waves.**

The `gsd-build` orchestrator (short for "Get-Shit-Done") implements a deterministic **wave-based parallel plan execution** model that transforms dependency declarations into optimized execution schedules. By analyzing `depends_on` relationships before runtime, the system assigns each plan to a specific wave, enabling safe parallelization while guaranteeing that prerequisites complete before dependent work begins.

## Computing Wave Numbers from Dependency Graphs

### Parsing depends_on Relationships

During the planning phase (`/gsd:plan-phase`), the orchestrator reads each plan's front-matter to extract the `depends_on` array. In [`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md) (lines 59-67), the system constructs a directed dependency graph where nodes represent plans and edges represent execution prerequisites.

### The Wave Calculation Algorithm

The planner assigns wave numbers using a topological approach that ensures a plan's wave is always greater than the maximum wave of its dependencies:

```typescript
waves = {}
for each plan in plan_order:
    if plan.depends_on is empty:
        plan.wave = 1
    else:
        plan.wave = max(waves[dep] for dep in plan.depends_on) + 1
    waves[plan.id] = plan.wave

```

This algorithm, implemented in [`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md) (lines 59-67), guarantees that plans with no dependencies start in wave 1, while downstream plans inherit incrementally higher wave numbers based on their deepest dependency chain.

## Executing Plans with Wave-Based Parallelism

### Loading the Plan Inventory

During the execution phase (`/gsd:execute-phase`), the orchestrator loads the pre-computed plan inventory using the `gsd-tools.cjs` utility:

```bash
PLAN_INDEX=$(node ~/.claude/get-shit-done/bin/gsd-tools.cjs phase-plan-index "${PHASE_NUMBER}")

```

As detailed in [`workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) (lines 50-58), the JSON payload contains both individual `wave` fields for each plan and a `waves` map that groups plan IDs by their assigned wave number.

### Sequential Waves, Parallel Plans

The executor processes waves sequentially while parallelizing within each wave. According to [`workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) (lines 74-78), the orchestrator respects the `PARALLELIZATION` environment flag:

- **When `PARALLELIZATION=true`**: All plans within the same wave execute simultaneously through independent executor sub-agents
- **When `PARALLELIZATION=false`**: Plans within a wave execute sequentially, though wave ordering still respects dependencies

This architecture ensures that **wave-based parallel plan execution** maintains strict dependency guarantees—since a plan's wave number exceeds all its dependencies' waves, the system never initiates execution until prerequisites complete.

## Defining Plans with Dependencies

Plans declare their execution requirements through front-matter in [`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md):

```yaml

# get-shit-done/templates/phase-prompt.md (excerpt)

- id: "01-01"
  wave: 1
  depends_on: []                # No dependencies → Wave 1

  objective: "Create core utils library"

- id: "01-02"
  wave: 1
  depends_on: []                # Independent, can run parallel with 01-01

  objective: "Set up CI pipeline"

- id: "02-01"
  wave: 2
  depends_on: ["01-01"]         # Must wait for core utils (Wave 1)

  objective: "Implement feature X using utils"

- id: "02-02"
  wave: 2
  depends_on: ["01-01","01-02"] # Needs both utils and CI to be ready

  objective: "Add integration tests for feature X"

```

When `/gsd:execute-phase` processes this configuration, Wave 1 executes `01-01` and `01-02` in parallel. Only after both complete does Wave 2 begin, launching `02-01` and `02-02` concurrently.

## Validation and Consistency Checks

The [`agents/gsd-plan-checker.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-plan-checker.md) agent (lines 128-140) validates wave assignments before execution. It verifies that:

- All `depends_on` references point to existing plan IDs
- Computed wave numbers match the pre-calculated values in plan front-matter
- No circular dependencies exist in the graph

These checks prevent runtime failures by ensuring the **wave-based parallel plan execution** model operates on a valid, acyclic dependency graph.

## Summary

- **gsd-build** implements **wave-based parallel plan execution** by pre-computing wave numbers from `depends_on` relationships during the planning phase
- The wave calculation algorithm in [`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md) (lines 59-67) ensures plans execute only after all dependencies complete
- The executor in [`workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) processes waves sequentially while running plans within each wave in parallel (when `PARALLELIZATION=true`)
- Plan definitions in [`templates/phase-prompt.md`](https://github.com/gsd-build/get-shit-done/blob/main/templates/phase-prompt.md) declare dependencies through front-matter, enabling complex orchestration patterns
- Pre-execution validation in [`agents/gsd-plan-checker.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-plan-checker.md) ensures wave consistency and detects circular dependencies

## Frequently Asked Questions

### How does gsd-build determine which wave a plan belongs to?

The orchestrator calculates wave numbers by analyzing the `depends_on` array in each plan's front-matter. Plans with no dependencies receive wave 1. For plans with dependencies, the system takes the maximum wave number among all dependencies and adds 1. This algorithm, implemented in [`agents/gsd-planner.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-planner.md) (lines 59-67), ensures that a plan's wave always exceeds its deepest dependency chain.

### Can plans within the same wave have dependencies on each other?

No. By definition, plans within the same wave must be independent. If plan A depends on plan B, the wave calculation algorithm assigns A to a higher wave number than B. The [`agents/gsd-plan-checker.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-plan-checker.md) validation agent (lines 128-140) explicitly verifies that wave assignments respect dependency relationships, preventing any circular dependencies or same-wave dependencies from reaching execution.

### What happens if the PARALLELIZATION flag is set to false?

When `PARALLELIZATION=false`, the executor processes plans sequentially even within the same wave. According to [`workflows/execute-phase.md`](https://github.com/gsd-build/get-shit-done/blob/main/workflows/execute-phase.md) (lines 74-78), the orchestrator still respects wave boundaries—meaning no wave 2 plan starts until all wave 1 plans complete—but plans within wave 1 execute one at a time rather than simultaneously. This mode is useful for debugging, resource-constrained environments, or when strict ordering is required beyond dependency guarantees.

### How does gsd-build prevent circular dependencies in the plan graph?

The [`agents/gsd-plan-checker.md`](https://github.com/gsd-build/get-shit-done/blob/main/agents/gsd-plan-checker.md) agent performs pre-execution validation on the dependency graph (lines 128-140). It verifies that all `depends_on` references point to existing plans and checks for circular dependencies by ensuring that wave numbers strictly increase along dependency chains. Since a plan's wave must always exceed its dependencies' waves, any circular reference would require a plan to depend on itself or a descendant, which the wave calculation algorithm cannot resolve, triggering a validation error before execution begins.