bmad-handoff

BMAD Handoff

Purpose: Scan the planning output folder for all stories at status ready-for-dev, compile them into a single handoff-manifest.json, and leave it where any downstream dev tool can read it — without coupling to any specific runner.

This is the last artifact the planning plugin produces. What happens next is owned by the external dev tool, not by this skill.

When to Run

Run this skill after the story-writing phase is complete and you (or the user) have confirmed that at least one story carries status ready-for-dev. The manifest is a point-in-time snapshot; re-run the skill to refresh it.

Workflow

Use TodoWrite to track progress through these steps.

1. Locate the output folder

Look for bmad-output/project-context.md (the default output folder) or ask the user for the output folder. Default: bmad-output/.

2. Discover story files

Glob for **/{epic}.{story}.*.story.md under the output folder. Accept alternative flat layouts (stories/*.story.md) if the glob turns up nothing.

3. Filter to ready-for-dev

Read the **Status:** header field of each story file (in the story header block, not a ## Status heading). Include only stories whose status value is exactly ready-for-dev.

If none are found, report which statuses were seen and stop — do not produce an empty manifest.

4. Extract per-story fields

For each qualifying story file, extract:

Field	Source in story file
id	Filename stem or ## Story heading ID
storyFilePath	Relative path from project root
status	**Status:** header field value
epic	First segment of filename, e.g. "2" in 2.1.stripe.story.md
storyNumber	Second segment, e.g. "1"
title	First H1 or ## Story heading text
ownedScope	## Owned File/Module Scope — list every path verbatim
wave	## Dependency Maps → wave/parallel_set annotation (integer or null)
parallelSet	Same section — parallel set label if present (string or null)
dependencies	## Dependency Maps → blocked-by story IDs (array, may be empty)
acceptanceCriteriaSummary	First 3 AC items from ## Acceptance Criteria, each ≤120 chars
lockedSectionsNote	Static string — see schema
devAgentRecord	Static null — placeholder for the dev tool to populate

5. Compute wave order

If stories do not already carry explicit wave annotations:

• Stories with empty dependencies arrays are wave 1.
• A story whose every dependency is in wave N or lower is wave N+1.
• Add the computed wave value; leave parallelSet null when not annotated.

6. Write the manifest

Write to {outputFolder}/handoff-manifest.json.

Use the schema from ${CLAUDE_PLUGIN_ROOT}/skills/bmad-handoff/templates/handoff-manifest.schema.json as the structural contract. Populate schemaVersion: "1.0".

Sort stories by wave ascending, then by id ascending within each wave.

7. Report to the user

Print a compact summary:

Handoff manifest written → bmad-output/handoff-manifest.json
  schemaVersion : 1.0
  stories       : <N> ready-for-dev
  waves         : <W>  (wave 1 has <X> stories, can start immediately)
  output path   : bmad-output/handoff-manifest.json

If any story was missing required sections (e.g. no ## Owned File/Module Scope), list those as warnings — do not silently omit or fabricate data.

Manifest Field Definitions (Quick Reference)

See REFERENCE.md for the full schema narrative and adapter notes.

Field	Type	Required	Notes
schemaVersion	string	yes	Semver string; current = "1.0"
generatedAt	string	yes	ISO-8601 UTC timestamp
projectName	string	yes	From project-context.md or user input
outputFolder	string	yes	Relative path used to find stories
stories	array	yes	One object per ready-for-dev story
stories[].id	string	yes	Unique story identifier
stories[].storyFilePath	string	yes	Relative path to the .story.md file
stories[].status	string	yes	Always "ready-for-dev" in this manifest
stories[].epic	string	yes	Epic identifier
stories[].storyNumber	string	yes	Story number within epic
stories[].title	string	yes	Human-readable story title
stories[].ownedScope	array	yes	File/module paths this story may modify
stories[].wave	integer	yes	Execution wave (1 = no dependencies)
stories[].parallelSet	string|null	no	Label if explicitly grouped
stories[].dependencies	array	yes	Story IDs that must complete first
stories[].acceptanceCriteriaSummary	array	yes	First 3 AC items, ≤120 chars each
stories[].lockedSectionsNote	string	yes	Instruction to dev tools
stories[].devAgentRecord	null	yes	Dev tool populates; always null at emit time

lockedSectionsNote is always the string:

"Sections Acceptance Criteria, Dev Notes, and Testing are LOCKED. External dev tools must not edit them. Populate only the Dev Agent Record section."

Subagent Strategy

For small backlogs (≤15 stories), this skill runs single-threaded — the extraction loop is fast and context fits in one session.

For large backlogs (16+ stories), fan out story extraction in parallel:

Agent	Task
Agent 1…N	Read story files in their assigned slice; extract fields; return JSON fragment
Coordinator	Merge fragments; compute wave order; write manifest

Each agent receives the list of file paths for its slice plus the field extraction table above. It returns a JSON array of story objects (no wave field yet). The coordinator merges, computes waves, sorts, and writes the manifest.

Key Guidelines

1. Never fabricate field values — if a field is missing from a story file, emit null and add a warning to the summary.
2. Do not modify story files — this skill is read-only with respect to story content.
3. ownedScope is critical for parallel-conflict safety; never collapse or summarize it.
4. This manifest is a STABLE versioned interface. Increment schemaVersion (as a separate schema revision, not within this run) before adding or removing fields.
5. Do not filter out stories based on anything other than ready-for-dev status — dependency resolution is the dev tool's job.
6. If the user asks to "re-run" or "refresh" the manifest, overwrite the existing file.

---

---

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-handoff. All methodology credit belongs to the BMAD Code Organization.