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

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 (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:

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 (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:

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

As detailed in 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 (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:

# 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 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 (lines 59-67) ensures plans execute only after all dependencies complete
• The executor in 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 declare dependencies through front-matter, enabling complex orchestration patterns
• Pre-execution validation in 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 (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 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 (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 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.

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