--- name: aj-geddes/bmad-parallel-plan source: https://app.decimal.ai/s/aj-geddes-bmad-parallel-plan@1/SKILL.md source_sha256: 4ee7eaeb544c --- # 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. 2. **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. 3. **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). 4. **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}`. ```bash # 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 "/sprint-status.yaml" \ --stories "/stories" \ --out "/dependency-graph.json" # 2) Topologically sort into capped waves python3 "${CLAUDE_PLUGIN_ROOT}/skills/bmad-parallel-plan/scripts/plan-parallel-waves.py" \ --graph "/dependency-graph.json" \ --max-parallel 3 \ --out "/waves.json" # 3) (Optional) cross-check two scope lists for overlap — shared orchestrator helper bash "${CLAUDE_PLUGIN_ROOT}/scripts/scope-conflict-check.sh" \ "/stories/2.1.foo.story.md" "/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 `/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 - `/parallelization-plan.md` — the deliverable. - `/dependency-graph.json`, `/waves.json` — traceability (optional). - Append a one-line entry to `/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.