bmad-sprint-planning

name	bmad-sprint-planning
description	Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"

Sprint Planning Workflow

Goal: Generate sprint status tracking from epics, detecting current story statuses and building a complete sprint-status.yaml file.

Your Role: You are a Developer generating and maintaining sprint tracking. Parse epic files, detect story statuses, and produce a structured sprint-status.yaml.

Conventions

• Bare paths (e.g. checklist.md) resolve from the skill root.
• Bare paths resolve from this skill's directory.
• Project paths resolve from the current working directory.

On Activation

Inspect the current project root, AGENTS.md, project-context.md, and all epic/story planning artifacts. Match the user's language. Use stories/ for story files when it exists, otherwise implementation/; use planning/, docs/planning/, or docs/ for epics. Do not run BMAD resolver scripts or load _bmad/ config. Continue directly to the workflow below.

When the caller supplies a feature scope, use its feature_root as the only planning root. Resolve stories, epics, and sprint-status.yaml from that root; do not scan the project root or another feature.

Paths

• tracking_system = file-system
• project_key = NOKEY
• story_location = existing stories/ or implementation/ directory
• story_location_absolute = same as story_location
• epics_location = existing planning/, docs/planning/, or docs/
• epics_pattern = *epic*.md
• status_file = story_location/sprint-status.yaml

Input Files

Input	Path	Load Strategy
Epics	epics_location/*epic*.md (whole) or epics_location/*epic*/*.md (sharded)	FULL_LOAD

Execution

Document Discovery - Full Epic Loading

Strategy: Sprint planning needs ALL epics and stories to build complete status tracking.

Epic Discovery Process:

1. Search for whole document first - Look for epics.md, bmm-epics.md, or any *epic*.md file
2. Check for sharded version - If whole document not found, look for epics/index.md
3. If sharded version found:
   • Read index.md to understand the document structure
   • Read ALL epic section files listed in the index (e.g., epic-1.md, epic-2.md, etc.)
   • Process all epics and their stories from the combined content
   • This ensures complete sprint status coverage
4. Priority: If both whole and sharded versions exist, use the whole document

Fuzzy matching: Be flexible with document names - users may use variations like epics.md, bmm-epics.md, user-stories.md, etc.

Load {project_context} for project-wide patterns and conventions (if exists) Communicate in the user's language Look for all files matching `{epics_pattern}` in {epics_location} Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files

For each epic file found, extract:

• Epic numbers from headers like ## Epic 1: or ## Epic 2:
• Story IDs and titles from patterns like ### Story 1.1: User Authentication
• Convert story format from Epic.Story: Title to kebab-case key: epic-story-title

Story ID Conversion Rules:

• Original: ### Story 1.1: User Authentication
• Replace period with dash: 1-1
• Convert title to kebab-case: user-authentication
• Final key: 1-1-user-authentication

Build complete inventory of all epics and stories from all epic files

For each epic found, create entries in this order:

1. Epic entry - Key: epic-{num}, Default status: backlog
2. Story entries - Key: {epic}-{story}-{title}, Default status: backlog
3. Retrospective entry - Key: epic-{num}-retrospective, Default status: optional

Example structure:

development_status:
  epic-1: backlog
  1-1-user-authentication: backlog
  1-2-account-management: backlog
  epic-1-retrospective: optional

For each story, detect current status by checking files:

Story file detection:

• Check: {story_location_absolute}/{story-key}.md (e.g., stories/1-1-user-authentication.md)
• If exists → upgrade status to at least ready-for-dev

Preservation rule:

• If existing {status_file} exists and has more advanced status, preserve it
• Never downgrade status (e.g., don't change done to ready-for-dev)

Status Flow Reference:

• Epic: backlog → in-progress → done
• Story: backlog → ready-for-dev → in-progress → review → done
• Retrospective: optional ↔ done

Create or update {status_file} with:

File Structure:

# generated: {date}
# last_updated: {date}
# project: {project_name}
# project_key: {project_key}
# tracking_system: {tracking_system}
# story_location: {story_location}

# STATUS DEFINITIONS:
# ==================
# Epic Status:
#   - backlog: Epic not yet started
#   - in-progress: Epic actively being worked on
#   - done: All stories in epic completed
#
# Epic Status Transitions:
#   - backlog → in-progress: Automatically when first story is created (via create-story)
#   - in-progress → done: Manually when all stories reach 'done' status
#
# Story Status:
#   - backlog: Story only exists in epic file
#   - ready-for-dev: Story file created in stories folder
#   - in-progress: Developer actively working on implementation
#   - review: Ready for code review (via Dev's code-review workflow)
#   - done: Story completed
#
# Retrospective Status:
#   - optional: Can be completed but not required
#   - done: Retrospective has been completed
#
# WORKFLOW NOTES:
# ===============
# - Epic transitions to 'in-progress' automatically when first story is created
# - Stories can be worked in parallel if team capacity allows
# - Developer typically creates next story after previous one is 'done' to incorporate learnings
# - Dev moves story to 'review', then runs code-review (fresh context, different LLM recommended)

generated: { date }
last_updated: { date }
 {  }
 {  }
 {  }
 {  }


  

Write the complete sprint status YAML to {status_file} CRITICAL: Metadata appears TWICE - once as comments (#) for documentation, once as YAML key:value fields for parsing Ensure all items are ordered: epic, its stories, its retrospective, next epic...

Perform validation checks:

• Every epic in epic files appears in {status_file}
• Every story in epic files appears in {status_file}
• Every epic has a corresponding retrospective entry
• No items in {status_file} that don't exist in epic files
• All status values are legal (match state machine definitions)
• File is valid YAML syntax

Count totals:

• Total epics: {{epic_count}}
• Total stories: {{story_count}}
• Epics in-progress: {{in_progress_count}}
• Stories done: {{done_count}}

Display the completion summary in the user's language:

Sprint Status Generated Successfully

• File Location: {status_file}
• Total Epics: {{epic_count}}
• Total Stories: {{story_count}}
• Epics In Progress: {{in_progress_count}}
• Stories Completed: {{done_count}}

Next Steps:

1. Review the generated {status_file}
2. Use this file to track development progress
3. Agents will update statuses as they work
4. Re-run this workflow to refresh auto-detected statuses

Additional Documentation

Status State Machine

Epic Status Flow:

backlog → in-progress → done

• backlog: Epic not yet started
• in-progress: Epic actively being worked on (stories being created/implemented)
• done: All stories in epic completed

Story Status Flow:

backlog → ready-for-dev → in-progress → review → done

• backlog: Story only exists in epic file
• ready-for-dev: Story file created (e.g., stories/1-3-plant-naming.md)
• in-progress: Developer actively working
• review: Ready for code review (via Dev's code-review workflow)
• done: Completed

Retrospective Status:

optional ↔ done

• optional: Ready to be conducted but not required
• done: Finished

Guidelines

1. Epic Activation: Mark epic as in-progress when starting work on its first story
2. Sequential Default: Stories are typically worked in order, but parallel work is supported
3. Parallel Work Supported: Multiple stories can be in-progress if team capacity allows
4. Review Before Done: Stories should pass through review before done
5. Learning Transfer: Developer typically creates next story after previous one is done to incorporate learnings