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.
{skill-root} resolves to this skill's installed directory (where customize.toml lives).
{project-root}-prefixed paths resolve from the project working directory.
{skill-name} resolves to the skill directory's basename.

On Activation

Step 1: Resolve the Workflow Block

Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow

If the script fails, resolve the workflow block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:

{skill-root}/customize.toml — defaults
{project-root}/_bmad/custom/{skill-name}.toml — team overrides
{project-root}/_bmad/custom/{skill-name}.user.toml — personal overrides

Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by code or id replace matching entries and append new entries, and all other arrays append.

Step 2: Execute Prepend Steps

Execute each entry in {workflow.activation_steps_prepend} in order before proceeding.

Step 3: Load Persistent Facts

Treat every entry in {workflow.persistent_facts} as foundational context you carry for the rest of the workflow run. Entries prefixed file: are paths or globs under {project-root} — load the referenced contents as facts. All other entries are facts verbatim.

Step 4: Load Config

Load config from {project-root}/_bmad/bmm/config.yaml and resolve:

project_name, user_name
communication_language, document_output_language
implementation_artifacts
planning_artifacts
date as system-generated current datetime
YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config {communication_language}
Generate all documents in {document_output_language}

Step 5: Greet the User

Greet {user_name}, speaking in {communication_language}.

Step 6: Execute Append Steps

Execute each entry in {workflow.activation_steps_append} in order.

Activation is complete. Begin the workflow below.

Paths

tracking_system = file-system
project_key = NOKEY
story_location = {implementation_artifacts}
story_location_absolute = {implementation_artifacts}
epics_location = {planning_artifacts}
epics_pattern = *epic*.md
status_file = {implementation_artifacts}/sprint-status.yaml

Input Files

Input	Path	Load Strategy
Epics	`{planning_artifacts}/epic.md` (whole) or `{planning_artifacts}/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:

Search for whole document first - Look for epics.md, bmm-epics.md, or any *epic*.md file
Check for sharded version - If whole document not found, look for epics/index.md
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
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.

<workflow> <step n="1" goal="Parse epic files and extract all work items"> <action>Load {project_context} for project-wide patterns and conventions (if exists)</action> <action>Communicate in {communication_language} with {user_name}</action> <action>Look for all files matching `{epics_pattern}` in {epics_location}</action> <action>Could be a single `epics.md` file or multiple `epic-1.md`, `epic-2.md` files</action>

<action>For each epic file found, extract:</action>

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

<action>Build complete inventory of all epics and stories from all epic files</action> </step>

<step n="2" goal="Build sprint status structure"> <action>For each epic found, create entries in this order:</action>

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

Example structure:

yaml

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

</step> <step n="3" goal="Apply intelligent status detection"> <action>For each story, detect current status by checking files:</action>

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 </step>

<step n="4" goal="Generate sprint status file"> <action>Create or update {status_file} with:</action>

File Structure:

yaml

# 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 }
project: { project_name }
project_key: { project_key }
tracking_system: { tracking_system }
story_location: { story_location }

development_status:
  # All epics, stories, and retrospectives in order

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

<step n="5" goal="Validate and report"> <action>Perform validation checks:</action>

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

<action>Count totals:</action>

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

<action>Display completion summary to {user_name} in {communication_language}:</action>

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:

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

<action>Run: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete — if the resolved value is non-empty, follow it as the final terminal instruction before exiting.</action> </step>

</workflow>

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

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