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

Never fabricate field values — if a field is missing from a story file, emit null and add a warning to the summary.
Do not modify story files — this skill is read-only with respect to story content.
ownedScope is critical for parallel-conflict safety; never collapse or summarize it.
This manifest is a STABLE versioned interface. Increment schemaVersion (as a separate schema revision, not within this run) before adding or removing fields.
Do not filter out stories based on anything other than ready-for-dev status — dependency resolution is the dev tool's job.
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.