BMAD Parallel Plan Skill

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

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.
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.
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).
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 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 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.

Agent Skills: BMAD Parallel Plan

Install this agent skill to your local

Skill Files