Wave-based parallel execution: speedup 3-5x with sub-agent parallelism

To execute ten plans in sequence requires linear time. To execute ten plans in three to four parallel waves halves (or more) the wall-clock. The GSD wave is not an optional optimization: it's the main scaling mechanism when phases grow in size. I measured this on my portfolio: 3-5x typical speedup, with phases like Phase 20 making a difference between "executable in a day" and "spread over a week".

Independence Disclaimer: I am not affiliated with XPHX0XPHX or XPHX1XPHX. Measurements of speedup are on my personal sample, 19 phases GSD performed, ~80 plans total distributed in ~30 waves.

What is a wave

A wave is a group of planes that can be executed in parallel without interference. Every NN-NN-PLAN.md has a field wave: front matter (e.g. XPHX0XPHX XPHX1XPHX XPHX2XPHX), you can include metadata about your document, such as author names, publication dates, and other relevant information. wave: 2Plan with the same wave and modified file = parallelizable.

The workflow /gsd-execute-phase It seems like you forgot to provide the Italian text that needs to be translated. Please paste the text, and I'll translate it according to the rules you specified.

1. Reads all PLAN.md files in the phase.
2. Group by wave.
3. For each wave (in order), respect depends_on of plans within the wave.
4. Spawn an executor sub-agent in parallel (one for each plan).
5. Wait until everyone completes the wave.
6. Verify success + commit batch (or failure management).
7. Proceed to the next wave.

Real example: XPHX0XPHX wave structure

Phase 20 (the phase that planned this editorial series) has 10 plans distributed in 5 waves:

Wave 1 (sequential, CHECKPOINT):
  20-01 - infra scaffold + PII audit + OSS skeleton

Wave 2 (parallel x2):
  20-02 - backend lead-magnet PDF stack
  20-03 - frontend 9 nuovi component + SeoService

Wave 3 (parallel x3):
  20-04 - cornerstone /career/claude-code-workflow/
  20-05 - sub-page /career/superpowers/
  20-06 - sub-page /career/gsd/

Wave 4a (single):
  20-07A - build pipeline Mermaid + highlight + OSS full

Wave 4b (parallel x2):
  20-07B - cluster 01-09 IT body 6000 parole
  20-07C - cluster 10-18 IT body + internal linking

Wave 5 (sequential, CHECKPOINT):
  20-08 - i18n bulk + Lighthouse + verify + go-live

Wave 2 and Wave 3 are where parallelism counts the most: 5 parallel planes on 10 = 50% of the phase executed in half the linear time.

Measured speedup

On the portfolio, distribution speedup for wall-clock time by type of wave:

• Single wave plan 11x (sequential by definition).
• Parallel lines of Wave 21.7-1.9x (overhead orchestration + token sharing).
• Parallel lines of Wave 3 plan2.5 to 2.8 times.
• Wave 4-plan parallel lines3.0-3.5x (cap effective around 3-4 planes, beyond which orchestration overhead decreases speedup).

speed up the clock; total token usage remains linear in N plan (no savings on paying for sub-agents). The advantage is the Note: I've preserved the exact format, punctuation, and capitalization of the original text, as well as the HTML tags with their textual content. timeThe tokens are not included.

The essential condition: files are disjointed.

Parallelism works only if parallel planes touch files I couldn't find any Italian text to translate. Please provide the Italian text you'd like me to translate, and I'll be happy to assist you.If Plan A and Plan B are in the same wave, they both modify blog-manifest.jsonThere is a race condition: the last one to write wins, the first one's changes are lost.

Plan-checker (cluster 9207) has this control in its dimensions: verifies that files_modified of parallel plans have empty intersection. If you find an overlap, BLOCKER requires or:

1. Moving a plan to a different wave (sequence alignment).
2. Reassign the shared file to a single "owner".
3. Split the shared file into separate files per-plan-disjoint.

Pattern: shared file in wave dedicated

When a file needs to be modified by many plans, pattern used on portfolio:

1. Wave N: parallel plans that produce output to aggregate.
2. Wave N+1: single plan that aggregate Output in the shared file (e.g., manifest, registry).

Example from Phase 20: the 18 cluster articles in Wave 4b produce frontend/public/content/articles/<id>/it.json for each cluster (file per-cluster disjoint). Wave 5 has a plan that aggregates all the front matter in blog-manifest.json + _series_registry.json single step sequential manner.

Anti-pattern: parallelism with undeclared dependency

Realistic example: Plan A writes a script migrate.shPlan B (same wave) modifies package.json to call migrate.sh in postinstallPlan A and B do not modify the same files (apparent disjoint), but Plan B depends semantically on Plan A (must exist the script before referencing it).

Solution: declare depends_on: [planA] front matter of Plan B. Wave-based parallelism then handles: even though both are in Wave 2, B waits for A to complete before starting.

Pattern: split by domain

When a phase is naturally split-friendly for domain (separate backend from separate frontend from i18n), the wave organizes itself obviously:

• Plan backend: only files backend/**.
• Frontend plan: only files frontend/src/** + frontend/public/**.
• Internationalization plan: only files frontend/src/locale/**.
• Plan content: only files frontend/public/content/articles/**.

Disjoint by construction. Maximum speedup with zero coordination overhead. Preferred pattern when applicable.

Pattern: split by feature

When the domain is a single layer but the phase has more independent features,

• Plan feature A: frontend/src/app/pages/feature-a/**.
• Plan feature B: frontend/src/app/pages/feature-b/**.
• Plan feature C: frontend/src/app/pages/feature-c/**.

Three features are implemented on the frontend in parallel, each isolated in its own folder. Wave 3 of Phase 20 follows this pattern: cornerstone + sub-page SP + sub-page GSD = three parallel plans, three disjoint folders.

Partial execution: --wave N

For pacing, quota management, or staged rollout, GSD allows for executing

/gsd-execute-phase 20 --wave 2

Executes only Wave 2 plans. The verification and completion phases occur only when there are no incomplete plans remaining after the selected wave. Useful for: Note: Token XPHX0XPHX, XPHX1XPHX remains unchanged.

• Divide a phase into multiple sessions (Phase 20 has 5 waves; execute one per day).
• Pause for a human checkpoint between waves (e.g., Wave 1 Phase 20 requires approval from Buttondown list and OSS repository Federico).
• Managing Anthropic Quota (Sub-Agent Rate Limit) by distributing over time.

Output marker and completion detection

Every sub-agent executor returns a marker that the orchestrator heard:

• ## TASKS COMPLETEThe project has been completed with success.
• ## TASKS COMPLETE - CHECKPOINT REQUIREDThe plan is complete, but human action is required before proceeding (autonomous: false).
• ## EXECUTION BLOCKEDStuck plan for blocker (e.g. red unresolvable test, undocumented missing dependency).

Orchestrator parses marker, decides whether to proceed with the next wave or stop for checkpoint/blocker. Without conventional markers parsing is fragile.

Typical session: Phase 20 wave 2-3 clock-based

Approximate measurement Phase 20:

• Wave 1 (1 plan, sequential)About 2 hours of wall clock time.
• Wave 2 (2 plan parallel, backend || frontend)About 3 hours on a clock face (compared to around 5-6 hours in sequence).
• Wave 3 (3 plan parallel)About 3 hours on a clock face (compared to around 7-8 hours in a row).
• Wave 4a (1 plan)About 2 hours of wall clock time.
• Wave 4b (2 plan parallel)Approximately 4 hours on a clock face (compared to around 7-8 hours in a sequence).
• Wave 5 (1 plan, sequential)It's been about 3 hours since we started working on this project.

Total wall-clock time: ~17 hours. Estimated sequential time: ~25-30 hours. Actual speedup: ~1.7-1.8x (limited by single-sequence plans in Wave 1, 4A, and 5).

Error handling during wave

What happens if one of the N plans fails while riding a parallel wave? Behavior GSD:

1. I am currently implementing (no kill cascading).
2. Orchestrator aggregates results: who is OK, who is BLOCKED.
3. If at least 1 blocked: stop wave subsequent.
4. Ask for a decision: I don't see any Italian text provided. Please provide the Italian text you'd like me to translate, and I'll be happy to assist you. Manual interventions, Respawn blocked (respawn alone the plan failed). abort phase.

Completed plans completed in a partial wave remain committed (atomic for the plan). Re-spawn fixed to take from the failed plan without re-executing the successes.

Anti-pattern: too many waves

Split obsessively into small waves (8 waves for every 10 plans, each with 1-2 plans) eliminates parallelism: every wave waits for the next one, losing the advantage.

Balance: 3-5 phase per wave is the sweet spot. Under 3 = little parallelization. Above 5 = orchestration overhead (async notifications, status verification, coordination cost).

Anti-pattern: parallelism with physical file lock

Even if file_modified are disjoint logically, some files have a physical runtime lock (e.g. XPHX0XPHX). node_modules/.package-lock.json, frontend/dist/** During the build). Parallel plans that trigger npm install o ng build They can corrupt each other simultaneously.

Mitigation: plans that execute locking-prone commands should be serialized (separate wave or depends_on Explicitly stated.

What I learned writing this article

The most important lesson is on Nature of parallelism in brownfieldsIt's difficult to parallelize on a greenfield (vertical slice MVP) because everything is connected. On the brownfield mature one, the The majority The plans are in a thematic horizontal phase and are naturally independent. Do not parallelize them for optimization, parallelize them because They were already.Wave structure makes visible this independence.

According to insight: actual benefit of parallelism is 3-4 plans per wave. Beyond that, orchestration overhead (notifications, verify status, partial failures to manage) consumes the gain. 8 parallel plans in a single wave seems ideal; in practice it's chaotic management. Better split into two waves of 4.

Avoided pattern

• Hidden wave with file overlapAlways check with a plan-checker to ensure that files_modified are disjoint. A silent race condition is the worst category of bug.
• Too many waves3-5 plan per wave. Less = underutilization parallelism; more = orchestration overhead.

A story worth sharing

Placeholder Section If you have set up a parallel wave with more than 5 plans that worked (or self-destructed), write to me at federico@federicocalo.dev.

Previous cluster: Agent orchestration Next cluster: Ingest-docs synthesizer →