bmad-parallel-plan

BMAD Parallel Plan

Convert a linear backlog into waves of stories that can be developed at the same

time without colliding — then describe exactly how to merge them back together. This

skill produces a plan. Your external dev tools execute it.

Persona flavor: Winston (Architect) reasons about isolation; the workflow does the math.

Scope (read first)

• This skill plans concurrency. It NEVER spawns worktrees, runs dev agents, writes

application code, runs tests, lints, or runs git.

• Inputs are planning artifacts. The only output is parallelization-plan.md (plus an

optional dependency-graph.json / waves.json for traceability).

• Branch names and merge order are recommendations the dev tool/human carries out.

Inputs

| Artifact | Path (under output folder) | Used for |

|----------|---------------------------|----------|

| Sprint status | sprint-status.yaml | story ids, epic, status, dependency lists |

| Ready stories | stories/{epic}.{story}.{slug}.story.md | Owned File/Module Scope + Dependency Maps |

| Architecture | architecture.md | semantic-conflict prevention (boundaries, shared modules) |

| Config | userConfig.maxParallel (default 3) | wave width cap |

Only stories at status ready-for-dev (or later) are eligible for a wave.

The four steps

1. Lean on architecture for semantic safety. Read architecture.md. Architecture is

what makes parallelism safe — clean module boundaries mean two stories touching

different components won't create a hidden semantic conflict even if the files differ.

Note any shared/cross-cutting modules (auth, config, DB schema, shared types); stories

that touch them are high-conflict and rarely parallelizable.

1. Read each story's Owned File/Module Scope. Every ready story declares the explicit

list of paths it may touch. Collect {story_id -> [paths]}. A missing or empty scope

is a planning blocker — flag it; do not guess.

1. Build the dependency DAG, then topologically sort into waves. Edges come from three

conflict classes (see REFERENCE.md):

• Ordering edges — epic order (stories within an epic are usually sequential) and

each story's explicit Dependency Maps (depends_on).

• File-scope edges — any two stories whose Owned File/Module Scopes intersect must

not share a wave (an undirected conflict, resolved by lower story id first).

• Semantic edges — both touch a shared/cross-cutting module from step 1.

Topologically sort: wave N = all stories whose dependencies are already satisfied by

waves < N AND that are pairwise file-disjoint AND pairwise semantically safe. Cap each

wave at maxParallel; overflow rolls to the next wave (lowest id first).

1. Emit parallelization-plan.md. For each wave, list the ready-for-dev stories; give

each an isolated git-worktree branch name and its disjoint file scope. Then give the

ordered merge sequence: lowest story id first into an integration branch, an

integration review checkpoint, then a single PR integration -> main.

Three intents

• Create — first wave plan from the current backlog.
• Update — re-plan after stories were added/finished/re-scoped (recompute the DAG;

exclude done, re-sort remaining).

• Validate — re-check an existing plan: confirm every wave is still file-disjoint,

dependency-satisfied, and within maxParallel; report drift.

State the intent, then proceed.

Run the helper scripts

Both scripts are deterministic and read-only. Resolve paths via ${CLAUDE_PLUGIN_ROOT}.

# 1) Build the dependency DAG (edges + conflict class) from status + story scopes
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bmad-parallel-plan/scripts/build-dependency-graph.py" \
  --status   "<output>/sprint-status.yaml" \
  --stories  "<output>/stories" \
  --out      "<output>/dependency-graph.json"

# 2) Topologically sort into capped waves
python3 "${CLAUDE_PLUGIN_ROOT}/skills/bmad-parallel-plan/scripts/plan-parallel-waves.py" \
  --graph        "<output>/dependency-graph.json" \
  --max-parallel 3 \
  --out          "<output>/waves.json"

# 3) (Optional) cross-check two scope lists for overlap — shared orchestrator helper
bash "${CLAUDE_PLUGIN_ROOT}/scripts/scope-conflict-check.sh" \
  "<output>/stories/2.1.foo.story.md" "<output>/stories/2.2.bar.story.md"

Then render waves.json into the human-facing plan using

[templates/parallelization-plan.template.md](templates/parallelization-plan.template.md)

and write it to <output>/parallelization-plan.md.

Branch & merge conventions

• Branch per story: story/{epic}.{story}-{slug} (one worktree each, fully isolated).
• Integration branch per wave: integration/wave-{N}.
• Merge order inside a wave: ascending story id into integration/wave-{N}.
• After all of a wave's stories merge: integration-review checkpoint, then PR

integration/wave-{N} -> main. Wave N+1 branches off the merged main.

Output

• <output>/parallelization-plan.md — the deliverable.
• <output>/dependency-graph.json, <output>/waves.json — traceability (optional).
• Append a one-line entry to <output>/decision-log.md noting maxParallel, wave count,

and any stories deferred for missing scope.

Guardrails

• Never place two stories with intersecting Owned File/Module Scope in the same wave.
• Never schedule a story before a story it depends_on.
• A story with no declared scope is not wave-eligible — surface it for the

scrum-master to fix; do not invent paths.

• Honor maxParallel; the dev tool enforces real concurrency, the plan must not exceed it.
• Do not modify Acceptance Criteria, Dev Notes, or Testing in any story — those are LOCKED.

See [REFERENCE.md](REFERENCE.md) for the wave algorithm, conflict classes, and merge-order

rationale.

> ---

> Part of the BMAD Planning & Orchestrator plugin — a Claude Code harness for the BMAD Method by the BMAD Code Organization (https://github.com/bmad-code-org/BMAD-METHOD). Implements the spirit of bmad-parallel-plan. All methodology credit belongs to the BMAD Code Organization.