bmad-method 6.0.0-alpha.0 → 6.0.0-alpha.1

package/src/modules/bmm/workflows/4-implementation/sprint-planning/README.md

@@ -0,0 +1,156 @@
+# Sprint Planning Workflow
+
+## Overview
+
+The sprint-planning workflow generates and manages the sprint status tracking file that serves as the single source of truth for Phase 4 implementation. It extracts all epics and stories from epic files and tracks their progress through the development lifecycle.
+
+In Agile terminology, this workflow facilitates **Sprint Planning** or **Sprint 0 Kickoff** - the transition from planning/architecture into actual development execution.
+
+## Purpose
+
+This workflow creates a `sprint-status.yaml` file that:
+
+- Lists all epics, stories, and retrospectives in order
+- Tracks the current status of each item
+- Provides a clear view of what needs to be worked on next
+- Ensures only one story is in progress at a time
+- Maintains the development flow from backlog to done
+
+## When to Use
+
+Run this workflow:
+
+1. **Initially** - After Phase 3 (solutioning) is complete and epics are finalized
+2. **After epic context creation** - To update epic status to 'contexted'
+3. **Periodically** - To auto-detect newly created story files
+4. **For status checks** - To see overall project progress
+
+## Status State Machine
+
+### Epic Flow
+
+```
+backlog → contexted
+```
+
+### Story Flow
+
+```
+backlog → drafted → ready-for-dev → in-progress → review → done
+```
+
+### Retrospective Flow
+
+```
+optional ↔ completed
+```
+
+## Key Guidelines
+
+1. **Epic Context Recommended**: Epics should be `contexted` before their stories can be `drafted`
+2. **Flexible Parallelism**: Multiple stories can be `in-progress` based on team capacity
+3. **Sequential Default**: Stories within an epic are typically worked in order, but parallel work is supported
+4. **Review Flow**: Stories should go through `review` before `done`
+5. **Learning Transfer**: SM typically drafts next story after previous is `done`, incorporating learnings
+
+## File Locations
+
+### Input Files
+
+- **Epic Files**: `{output_folder}/epic*.md` or `{output_folder}/epics.md`
+- **Epic Context**: `{output_folder}/epic-{n}-context.md`
+- **Story Files**: `{story_dir}/{epic}-{story}-{title}.md`
+  - Example: `stories/1-1-user-authentication.md`
+- **Story Context**: `{story_dir}/{epic}-{story}-{title}-context.md`
+  - Example: `stories/1-1-user-authentication-context.md`
+
+### Output File
+
+- **Status File**: `{output_folder}/sprint-status.yaml`
+
+## Usage by Agents
+
+### SM (Scrum Master) Agent
+
+```yaml
+Tasks:
+  - Check sprint-status.yaml for stories in 'done' status
+  - Identify next 'backlog' story to draft
+  - Run create-story workflow
+  - Update status to 'drafted'
+  - Create story context
+  - Update status to 'ready-for-dev'
+```
+
+### Developer Agent
+
+```yaml
+Tasks:
+  - Find stories with 'ready-for-dev' status
+  - Update to 'in-progress' when starting
+  - Implement the story
+  - Update to 'review' when complete
+  - Address review feedback
+  - Update to 'done' after review
+```
+
+### Test Architect
+
+```yaml
+Tasks:
+  - Monitor stories entering 'review'
+  - Track epic progress
+  - Identify when retrospectives are needed
+```
+
+## Example Output
+
+```yaml
+# Sprint Status
+# Generated: 2025-01-20
+# Project: MyPlantFamily
+
+development_status:
+  epic-1: contexted
+  1-1-project-foundation: done
+  1-2-app-shell: done
+  1-3-user-authentication: in-progress
+  1-4-plant-data-model: ready-for-dev
+  1-5-add-plant-manual: drafted
+  1-6-photo-identification: backlog
+  epic-1-retrospective: optional
+
+  epic-2: contexted
+  2-1-personality-system: in-progress
+  2-2-chat-interface: drafted
+  2-3-llm-integration: backlog
+  2-4-reminder-system: backlog
+  epic-2-retrospective: optional
+```
+
+## Integration with BMM Workflow
+
+This workflow is part of Phase 4 (Implementation) and integrates with:
+
+1. **epic-tech-context** - Creates technical context for epics
+2. **create-story** - Drafts individual story files
+3. **story-context** - Adds implementation context to stories
+4. **dev-story** - Developer implements the story
+5. **code-review** - SM reviews implementation
+6. **retrospective** - Optional epic retrospective
+
+## Benefits
+
+- **Clear Visibility**: Everyone knows what's being worked on
+- **Flexible Capacity**: Supports both sequential and parallel work patterns
+- **Learning Transfer**: SM can incorporate learnings when drafting next story
+- **Progress Tracking**: Easy to see overall project status
+- **Automation Friendly**: Simple YAML format for agent updates
+
+## Tips
+
+1. **Initial Generation**: Run immediately after epics are finalized
+2. **Regular Updates**: Agents should update status as they work
+3. **Manual Override**: You can manually edit the file if needed
+4. **Backup First**: The workflow backs up existing status before regenerating
+5. **Validation**: The workflow validates legal status transitions

package/src/modules/bmm/workflows/4-implementation/sprint-planning/checklist.md

@@ -0,0 +1,33 @@
+# Sprint Planning Validation Checklist
+
+## Core Validation
+
+### Complete Coverage Check
+
+- [ ] Every epic found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every story found in epic\*.md files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml that don't exist in epic files
+
+### Parsing Verification
+
+Compare epic files against generated sprint-status.yaml:
+
+```
+Epic Files Contains:                Sprint Status Contains:
+✓ Epic 1                            ✓ epic-1: [status]
+  ✓ Story 1.1: User Auth              ✓ 1-1-user-auth: [status]
+  ✓ Story 1.2: Account Mgmt           ✓ 1-2-account-mgmt: [status]
+  ✓ Story 1.3: Plant Naming           ✓ 1-3-plant-naming: [status]
+                                      ✓ epic-1-retrospective: [status]
+✓ Epic 2                            ✓ epic-2: [status]
+  ✓ Story 2.1: Personality Model      ✓ 2-1-personality-model: [status]
+  ✓ Story 2.2: Chat Interface         ✓ 2-2-chat-interface: [status]
+                                      ✓ epic-2-retrospective: [status]
+```
+
+### Final Check
+
+- [ ] Total count of epics matches
+- [ ] Total count of stories matches
+- [ ] All items are in the expected order (epic, stories, retrospective)

package/src/modules/bmm/workflows/4-implementation/sprint-planning/instructions.md

@@ -0,0 +1,221 @@
+# Sprint Planning - Sprint Status Generator
+
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmm/workflows/4-implementation/sprint-planning/workflow.yaml</critical>
+
+<workflow>
+
+<step n="1" goal="Parse epic files and extract all work items">
+<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>
+
+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:**
+
+```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 epic, check if tech context file exists:</action>
+
+- Check: `{output_folder}/epic-{num}-context.md`
+- If exists → set epic status to `contexted`
+- Else → keep as `backlog`
+
+<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 `drafted`
+
+**Story context detection:**
+
+- Check: `{story_location_absolute}/{story-key}-context.md` (e.g., `stories/1-1-user-authentication-context.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 `drafted`)
+
+**Status Flow Reference:**
+
+- Epic: `backlog` → `contexted`
+- Story: `backlog` → `drafted` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `completed`
+  </step>
+
+<step n="4" goal="Generate sprint status file">
+<action>Create or update {status_file} with:</action>
+
+**File Structure:**
+
+```yaml
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic exists in epic file but not contexted
+#   - contexted: Epic tech context created (required before drafting stories)
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - drafted: Story file created in stories folder
+#   - ready-for-dev: Draft approved and story context created
+#   - in-progress: Developer actively working on implementation
+#   - review: Under SM review (via code-review workflow)
+#   - done: Story completed
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - completed: Retrospective has been done
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epics should be 'contexted' before stories can be 'drafted'
+# - Stories can be worked in parallel if team capacity allows
+# - SM typically drafts next story after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', SM reviews, then Dev moves to 'done'
+
+generated: { 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: For story_location field, write the variable value EXACTLY as defined in workflow.yaml: "{project-root}/docs/stories"</action>
+<action>CRITICAL: Do NOT resolve {project-root} to an absolute path - keep it as the literal string "{project-root}/docs/stories"</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 sprint-status.yaml
+- [ ] Every story in epic files appears in sprint-status.yaml
+- [ ] Every epic has a corresponding retrospective entry
+- [ ] No items in sprint-status.yaml 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 contexted: {{contexted_count}}
+- Stories 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}}
+- **Contexted Epics:** {{contexted_count}}
+- **Stories In Progress:** {{in_progress_count}}
+- **Stories Completed:** {{done_count}}
+
+**Next Steps:**
+
+1. Review the generated sprint-status.yaml
+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
+
+</step>
+
+</workflow>
+
+## Additional Documentation
+
+### Status State Machine
+
+**Epic Status Flow:**
+
+```
+backlog → contexted
+```
+
+- **backlog**: Epic exists in epic file but tech context not created
+- **contexted**: Epic tech context has been generated (prerequisite for story drafting)
+
+**Story Status Flow:**
+
+```
+backlog → drafted → ready-for-dev → in-progress → review → done
+```
+
+- **backlog**: Story only exists in epic file
+- **drafted**: Story file created (e.g., `stories/1-3-plant-naming.md`)
+- **ready-for-dev**: Draft approved + story context created
+- **in-progress**: Developer actively working
+- **review**: Under SM review (via code-review workflow)
+- **done**: Completed
+
+**Retrospective Status:**
+
+```
+optional ↔ completed
+```
+
+- **optional**: Can be done but not required
+- **completed**: Retrospective has been completed
+
+### Guidelines
+
+1. **Epic Context Recommended**: Epics should be `contexted` before stories can be `drafted`
+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**: SM typically drafts next story after previous one is `done` to incorporate learnings
+
+### Error Handling
+
+- If epic file can't be parsed, report specific file and continue with others
+- If existing status file is malformed, backup and regenerate
+- Log warnings for duplicate story IDs across epics
+- Validate status transitions are legal (can't go from `backlog` to `done`)

package/src/modules/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml

@@ -0,0 +1,55 @@
+# Sprint Status Template
+# This is an EXAMPLE showing the expected format
+# The actual file will be generated with all epics/stories from your epic files
+
+# generated: {date}
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: {tracking_system}
+# story_location: {story_location}
+
+# STATUS DEFINITIONS:
+# ==================
+# Epic Status:
+#   - backlog: Epic exists in epic file but not contexted
+#   - contexted: Next epic tech context created by *epic-tech-context (required)
+#
+# Story Status:
+#   - backlog: Story only exists in epic file
+#   - drafted: Story file created in stories folder by *create-story
+#   - ready-for-dev: Draft approved and story context created by *story-ready
+#   - in-progress: Developer actively working on implementation by *dev-story
+#   - review: Implementation complete, ready for review by *code-review
+#   - done: Story completed by *story-done
+#
+# Retrospective Status:
+#   - optional: Can be completed but not required
+#   - completed: Retrospective has been done by *retrospective
+#
+# WORKFLOW NOTES:
+# ===============
+# - Epics should be 'contexted' before stories can be 'drafted'
+# - SM typically drafts next story ONLY after previous one is 'done' to incorporate learnings
+# - Dev moves story to 'review', dev reviews, then Dev moves to 'done'
+
+# EXAMPLE STRUCTURE (your actual epics/stories will replace these):
+
+generated: 05-06-2-2025 21:30
+project: My Awesome Project
+project_key: jira-1234
+tracking_system: file-system
+story_location: "{project-root}/docs/stories"
+
+development_status:
+  epic-1: contexted
+  1-1-user-authentication: done
+  1-2-account-management: drafted
+  1-3-plant-data-model: backlog
+  1-4-add-plant-manual: backlog
+  epic-1-retrospective: optional
+
+  epic-2: backlog
+  2-1-personality-system: backlog
+  2-2-chat-interface: backlog
+  2-3-llm-integration: backlog
+  epic-2-retrospective: optional

package/src/modules/bmm/workflows/4-implementation/sprint-planning/workflow.yaml

@@ -0,0 +1,41 @@
+name: sprint-planning
+description: "Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle"
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+date: system-generated
+
+# Workflow components
+installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/sprint-planning"
+instructions: "{installed_path}/instructions.md"
+template: "{installed_path}/sprint-status-template.yaml"
+validation: "{installed_path}/checklist.md"
+
+# Variables and inputs
+variables:
+  # Project identification
+  project_name: "{config_source}:project_name"
+  project_key: "{config_source}:project_name" # Future: Jira project key, Linear workspace ID, etc.
+
+  # Tracking system configuration
+  tracking_system: "file-system" # Options: file-system, Future will support other options from config of mcp such as jira, linear, trello
+  story_location: "{project-root}/docs/stories" # Relative path for file-system, Future will support URL for Jira/Linear/Trello
+  story_location_absolute: "{config_source}:dev_story_location" # Absolute path for file operations
+
+  # Source files (file-system only)
+  epics_location: "{output_folder}" # Directory containing epic*.md files
+  epics_pattern: "epic*.md" # Pattern to find epic files
+
+  # Output configuration
+  status_file: "{output_folder}/sprint-status.yaml"
+
+# Output configuration
+default_output_file: "{status_file}"
+
+standalone: true
+
+web_bundle: false

package/src/modules/bmm/workflows/4-implementation/story-context/README.md

@@ -224,7 +224,7 @@ To customize this workflow:
 
 For issues or questions:
 
-- Review the workflow creation guide at `/bmad/bmb/workflows/build-workflow/workflow-creation-guide.md`
+- Review the workflow creation guide at `/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md`
 - Validate output using `checklist.md`
 - Ensure story files follow expected markdown structure
 - Check that repository structure supports automated discovery