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

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

@@ -1,221 +0,0 @@
-# Phase 4: Implementation
-
-## Overview
-
-Phase 4 is where planning transitions into actual development. This phase manages the iterative implementation of stories defined in the epic files, tracking their progress through a well-defined status workflow.
-
-## Status Definitions
-
-### Epic Status
-
-Epics progress through a simple two-state flow:
-
-| Status        | Description                                                                                                                                     | Next Status |
-| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
-| **backlog**   | Epic exists in epic file but technical context has not been created                                                                             | contexted   |
-| **contexted** | Epic technical context has been created via `epic-tech-context` workflow. This is a prerequisite before any stories in the epic can be drafted. | -           |
-
-**File Indicators:**
-
-- `backlog`: No `epic-{n}-context.md` file exists
-- `contexted`: `{output_folder}/epic-{n}-context.md` file exists
-
-### Story Status
-
-Stories progress through a six-state flow representing their journey from idea to implementation:
-
-| Status            | Description                                                                        | Set By        | Next Status   |
-| ----------------- | ---------------------------------------------------------------------------------- | ------------- | ------------- |
-| **backlog**       | Story only exists in the epic file, no work has begun                              | Initial state | drafted       |
-| **drafted**       | Story file has been created via `create-story` workflow                            | SM Agent      | ready-for-dev |
-| **ready-for-dev** | Story has been drafted, approved, and context created via `story-context` workflow | SM Agent      | in-progress   |
-| **in-progress**   | Developer is actively implementing the story                                       | Dev Agent     | review        |
-| **review**        | Implementation complete, under SM review via `code-review` workflow                | Dev Agent     | done          |
-| **done**          | Story has been reviewed and completed                                              | Dev Agent     | -             |
-
-**File Indicators:**
-
-- `backlog`: No story file exists
-- `drafted`: `{story_dir}/{story-key}.md` file exists (e.g., `1-1-user-auth.md`)
-- `ready-for-dev`: Both story file and context exist (e.g., `1-1-user-auth-context.md`)
-- `in-progress`, `review`, `done`: Manual status updates in sprint-status.yaml
-
-### Retrospective Status
-
-Optional retrospectives can be completed after an epic:
-
-| Status        | Description                                        |
-| ------------- | -------------------------------------------------- |
-| **optional**  | Retrospective can be completed but is not required |
-| **completed** | Retrospective has been completed                   |
-
-## Status Transitions
-
-### Epic Flow
-
-```mermaid
-graph LR
-    backlog --> contexted[contexted via epic-tech-context]
-```
-
-### Story Flow
-
-```mermaid
-graph LR
-    backlog --> drafted[drafted via create-story]
-    drafted --> ready[ready-for-dev via story-context]
-    ready --> progress[in-progress - dev starts]
-    progress --> review[review via code-review]
-    review --> done[done - dev completes]
-```
-
-## Sprint Status Management
-
-The `sprint-status.yaml` file is the single source of truth for tracking all work items. It contains:
-
-- All epics with their current status
-- All stories with their current status
-- Retrospective placeholders for each epic
-- Clear documentation of status definitions
-
-### Example Sprint Status File
-
-```yaml
-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
-  1-7-plant-naming: 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
-```
-
-## Workflows in Phase 4
-
-### Core Workflows
-
-| Workflow              | Purpose                                            | Updates Status                      |
-| --------------------- | -------------------------------------------------- | ----------------------------------- |
-| **sprint-planning**   | Generate/update sprint-status.yaml from epic files | Auto-detects file-based statuses    |
-| **epic-tech-context** | Create technical context for an epic               | epic: backlog → contexted           |
-| **create-story**      | Draft a story from epics/PRD                       | story: backlog → drafted            |
-| **story-context**     | Add implementation context to story                | story: drafted → ready-for-dev      |
-| **dev-story**         | Developer implements the story                     | story: ready-for-dev → in-progress  |
-| **code-review**       | SM reviews implementation                          | story: in-progress → review         |
-| **retrospective**     | Conduct epic retrospective                         | retrospective: optional → completed |
-| **correct-course**    | Course correction when needed                      | Various status updates              |
-
-### Sprint Planning Workflow
-
-The `sprint-planning` workflow is the foundation of Phase 4. It:
-
-1. **Parses all epic files** (`epic*.md` or `epics.md`)
-2. **Extracts all epics and stories** maintaining their order
-3. **Auto-detects current status** based on existing files:
-   - Checks for epic context files
-   - Checks for story files
-   - Checks for story context files
-4. **Generates sprint-status.yaml** with current reality
-5. **Preserves manual status updates** (won't downgrade statuses)
-
-Run this workflow:
-
-- Initially after Phase 3 completion
-- After creating epic contexts
-- Periodically to sync file-based status
-- To verify current project state
-
-### Workflow Guidelines
-
-1. **Epic Context First**: Epics should be contexted before drafting their stories
-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
-4. **Learning Transfer**: SM drafts next story after previous is done, incorporating learnings
-5. **Review Flow**: Dev moves to review, SM reviews, Dev moves to done
-
-## Agent Responsibilities
-
-### SM (Scrum Master) Agent
-
-- Run `sprint-planning` to generate initial status
-- Create epic contexts (`epic-tech-context`)
-- Draft stories (`create-story`)
-- Create story contexts (`story-context`)
-- Review completed work (`code-review`)
-- Update status in sprint-status.yaml
-
-### Developer Agent
-
-- Check sprint-status.yaml for `ready-for-dev` stories
-- Update status to `in-progress` when starting
-- Implement stories (`dev-story`)
-- Move to `review` when complete
-- Address review feedback
-- Update to `done` after approval
-
-### Test Architect
-
-- Monitor stories entering `review` status
-- Track epic progress
-- Identify when retrospectives needed
-- Validate implementation quality
-
-## Best Practices
-
-1. **Always run sprint-planning first** to establish current state
-2. **Update status immediately** as work progresses
-3. **Check sprint-status.yaml** before starting any work
-4. **Preserve learning** by drafting stories sequentially when possible
-5. **Document decisions** in story and context files
-
-## Naming Conventions
-
-### Story File Naming
-
-- Format: `{epic}-{story}-{kebab-title}.md`
-- Example: `1-1-user-authentication.md`
-- Avoids YAML float parsing issues (1.1 vs 1.10)
-- Makes files self-descriptive
-
-### Git Branch Naming
-
-- Format: `feat/{epic}-{story}-{kebab-title}`
-- Example: `feat/1-1-user-authentication`
-- Consistent with story file naming
-- Clean for branch management
-
-## File Structure
-
-```
-{output_folder}/
-├── sprint-status.yaml                      # Sprint status tracking
-├── epic*.md or epics.md                    # Epic definitions
-├── epic-1-context.md                       # Epic technical contexts
-├── epic-2-context.md
-└── stories/
-    ├── 1-1-user-authentication.md          # Story drafts
-    ├── 1-1-user-authentication-context.md  # Story contexts
-    ├── 1-2-account-management.md
-    ├── 1-2-account-management-context.md
-    └── ...
-```
-
-## Next Steps
-
-After Phase 4 implementation, projects typically move to:
-
-- Deployment and release
-- User acceptance testing
-- Production monitoring
-- Maintenance and updates
-
-The sprint-status.yaml file provides a complete audit trail of the development process and can be used for project reporting and retrospectives.

package/src/modules/bmm/workflows/4-implementation/code-review/README.md

@@ -1,69 +0,0 @@
-# Review Story (Senior Developer Code Review)
-
-Perform an AI-driven Senior Developer Code Review on a story flagged "Ready for Review". The workflow ingests the story, its Story Context, and the epic’s Tech Spec, consults local docs, uses enabled MCP servers for up-to-date best practices (with web search fallback), and appends structured review notes to the story.
-
-## What It Does
-
-- Auto-discovers the target story or accepts an explicit `story_path`
-- Verifies the story is in a reviewable state (e.g., Ready for Review/Review)
-- Loads Story Context (from Dev Agent Record → Context Reference or auto-discovery)
-- Locates the epic Tech Spec and relevant architecture/standards docs
-- Uses MCP servers for best-practices and security references; falls back to web search
-- Reviews implementation vs Acceptance Criteria, Tech Spec, and repo standards
-- Evaluates code quality, security, and test coverage
-- Appends a "Senior Developer Review (AI)" section to the story with findings and action items
-- Optionally updates story Status based on outcome
-
-## How to Invoke
-
-- Tell the Dev Agent to perform a \*code-review after loading the dev agent. This is a context intensive operation so this should not be done in the same context as a just completed dev session - clear the context, reload the dev, then run code-review!
-
-## Inputs and Variables
-
-- `story_path` (optional): Explicit path to a story file
-- `story_dir` (from config): `{project-root}/bmad/bmm/config.yaml` → `dev_story_location`
-- `allow_status_values`: Defaults include `Ready for Review`, `Review`
-- `auto_discover_context` (default: true)
-- `auto_discover_tech_spec` (default: true)
-- `tech_spec_glob_template`: `tech-spec-epic-{{epic_num}}*.md`
-- `arch_docs_search_dirs`: Defaults to `docs/` and `outputs/`
-- `enable_mcp_doc_search` (default: true)
-- `enable_web_fallback` (default: true)
-- `update_status_on_result` (default: false)
-
-## Story Updates
-
-- Appends a section titled: `Senior Developer Review (AI)` at the end
-- Adds a Change Log entry: "Senior Developer Review notes appended"
-- If enabled, updates `Status` based on outcome
-
-## Persistence and Backlog
-
-To ensure review findings become actionable work, the workflow can persist action items to multiple targets (configurable):
-
-- Story tasks: Inserts unchecked items under `Tasks / Subtasks` in a "Review Follow-ups (AI)" subsection so `dev-story` can pick them up next.
-- Story review section: Keeps a full list under "Senior Developer Review (AI) → Action Items".
-- Backlog file: Appends normalized rows to `docs/backlog.md` (created if missing) for cross-cutting or longer-term improvements.
-- Epic follow-ups: If an epic Tech Spec is found, appends to its `Post-Review Follow-ups` section.
-
-Configure via `workflow.yaml` variables:
-
-- `persist_action_items` (default: true)
-- `persist_targets`: `story_tasks`, `story_review_section`, `backlog_file`, `epic_followups`
-- `backlog_file` (default: `{project-root}/docs/backlog.md`)
-- `update_epic_followups` (default: true)
-- `epic_followups_section_title` (default: `Post-Review Follow-ups`)
-
-Routing guidance:
-
-- Put must-fix items to ship the story into the story’s tasks.
-- Put same-epic but non-blocking improvements into the epic Tech Spec follow-ups.
-- Put cross-cutting, future, or refactor work into the backlog file.
-
-## Related Workflows
-
-- `dev-story` — Implements tasks/subtasks and can act on review action items
-- `story-context` — Generates Story Context for a single story
-- `tech-spec` — Generates epic Tech Spec documents
-
-_Part of the BMAD Method v6 — Implementation Phase_

package/src/modules/bmm/workflows/4-implementation/correct-course/README.md

@@ -1,73 +0,0 @@
----
-last-redoc-date: 2025-10-01
----
-
-# Correct Course Workflow
-
-The correct-course workflow is v6's adaptive response mechanism for stories that encounter issues during development or review, enabling intelligent course correction without restarting from scratch. Run by the Scrum Master (SM) or Team Lead, this workflow analyzes why a story is blocked or has issues, determines whether the story scope needs adjustment, requirements need clarification, technical approach needs revision, or the story needs to be split or reconsidered. This represents the agile principle of embracing change even late in the development cycle, but doing so in a structured way that captures learning and maintains project coherence.
-
-Unlike simply abandoning failed work or blindly pushing forward, correct-course provides a systematic approach to diagnosing issues and determining appropriate remediation. The workflow examines the original story specification, what was actually implemented, what issues arose during development or review, and the broader epic context to recommend the best path forward. This might involve clarifying requirements, adjusting acceptance criteria, revising technical approach, splitting the story into smaller pieces, or even determining the story should be deprioritized.
-
-The critical value of this workflow is that it prevents thrashing—endless cycles of implementation and rework without clear direction. By stepping back to analyze what went wrong and charting a clear path forward, the correct-course workflow enables teams to learn from difficulties and adapt intelligently rather than stubbornly proceeding with a flawed approach.
-
-## Usage
-
-```bash
-# Analyze issues and recommend course correction
-bmad run correct-course
-```
-
-The workflow should be run when:
-
-- Review identifies critical issues requiring rethinking
-- Developer encounters blocking issues during implementation
-- Acceptance criteria prove infeasible or unclear
-- Technical approach needs significant revision
-- Story scope needs adjustment based on discoveries
-
-## Inputs
-
-**Required Context:**
-
-- **Story Document**: Original story specification
-- **Implementation Attempts**: Code changes and approaches tried
-- **Review Feedback**: Issues and concerns identified
-- **Epic Context**: Overall epic goals and current progress
-- **Technical Constraints**: Architecture decisions and limitations discovered
-
-**Analysis Focus:**
-
-- Root cause of issues or blockages
-- Feasibility of current story scope
-- Clarity of requirements and acceptance criteria
-- Appropriateness of technical approach
-- Whether story should be split or revised
-
-## Outputs
-
-**Primary Deliverable:**
-
-- **Course Correction Report** (`[story-id]-correction.md`): Analysis and recommendations including:
-  - Issue root cause analysis
-  - Impact assessment on epic and project
-  - Recommended corrective actions with rationale
-  - Revised story specification if applicable
-  - Updated acceptance criteria if needed
-  - Technical approach adjustments
-  - Timeline and effort implications
-
-**Possible Outcomes:**
-
-1. **Clarify Requirements**: Update story with clearer acceptance criteria
-2. **Revise Scope**: Adjust story scope to be more achievable
-3. **Split Story**: Break into multiple smaller stories
-4. **Change Approach**: Recommend different technical approach
-5. **Deprioritize**: Determine story should be deferred or cancelled
-6. **Unblock**: Identify and address blocking dependencies
-
-**Artifacts:**
-
-- Updated story document if revision needed
-- New story documents if splitting story
-- Updated epic backlog reflecting changes
-- Lessons learned for retrospective

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

@@ -1,129 +0,0 @@
----
-last-redoc-date: 2025-10-01
----
-
-# Create Story Workflow
-
-The create-story workflow is the entry point for v6's just-in-time story generation approach, run exclusively by the Scrum Master (SM) agent. Unlike batch processing methodologies, this workflow generates exactly ONE story at a time based on the current epic backlog state, ensuring stories are created only when needed and with the most current context. The SM analyzes the epic's progress, identifies what needs to be built next based on epics.md enumeration, and generates a complete story specification including acceptance criteria, technical approach, and implementation guidance pulled directly from tech specs, PRD, and architecture documentation.
-
-This workflow represents a fundamental shift from traditional upfront planning to adaptive story generation. By creating stories one at a time and enforcing strict verification against epics.md, the SM ensures that only planned and approved stories are created. The workflow operates in non-interactive "#yolo" mode by default, minimizing prompts while maintaining quality through rigorous source document grounding. It will HALT if epics.md doesn't explicitly enumerate the next story, forcing proper planning through the correct-course workflow rather than allowing ad-hoc story creation.
-
-The workflow's intelligent document discovery system automatically finds the relevant tech spec for the current epic (using pattern `tech-spec-epic-{epic_num}-*.md`), loads all architecture documents from both docs/ and output folders, and synthesizes requirements from multiple sources in priority order. After story creation, it can optionally trigger the story-context workflow to generate just-in-time technical expertise for the developer.
-
-## Usage
-
-```bash
-# SM initiates story creation for the next piece of work
-bmad sm *create-story
-```
-
-The SM runs this workflow when:
-
-- The current sprint has capacity for new work
-- The previous story status is "Done" or "Approved"
-- The team is ready for the next planned story in the epic
-- Story preparation is needed before development
-
-## Inputs
-
-**Required Context Files:**
-
-- **epics.md**: MANDATORY - Must explicitly enumerate the next story or workflow halts
-- **tech-spec-epic-{N}-\*.md**: Epic-specific technical specification (auto-discovered)
-- **PRD.md**: Product requirements document (fallback for requirements)
-- **Architecture Documents**: Automatically discovered from docs/ and output folders:
-  - tech-stack.md, unified-project-structure.md, coding-standards.md
-  - testing-strategy.md, backend-architecture.md, frontend-architecture.md
-  - data-models.md, database-schema.md, rest-api-spec.md, external-apis.md
-
-**Workflow Variables:**
-
-- `story_dir`: From config `dev_story_location` - where stories are saved
-- `epic_num`: Current epic number (auto-detected from existing stories)
-- `story_num`: Next story number (incremented from last completed story)
-- `auto_run_context`: Default true - runs story-context workflow after creation
-- `non_interactive`: Default true - operates in "#yolo" mode with minimal prompts
-
-## Outputs
-
-**Primary Deliverable:**
-
-- **Story Document** (`{story_dir}/story-{epic_num}.{story_num}.md`): Complete story specification including:
-  - User story statement (role, action, benefit)
-  - Acceptance criteria extracted from tech spec or epics.md
-  - Tasks and subtasks mapped to ACs
-  - Testing requirements per testing strategy
-  - Dev notes with source citations
-  - Status: "Draft" (requires approval before development)
-
-**Validation Safeguards:**
-
-- **Epic Enumeration Check**: If epics.md doesn't list the next story, workflow HALTS with:
-  ```
-  "No planned next story found in epics.md for epic {epic_num}.
-  Please load either PM or SM agent and run *correct-course to add/modify epic stories."
-  ```
-- **Status Check**: Won't create new story if current story isn't Done/Approved
-- **Document Grounding**: All requirements traced to source documents (no invention)
-
-## Key Features
-
-**Strict Planning Enforcement**: The workflow will NOT create stories that aren't explicitly planned in epics.md. This prevents scope creep and ensures all work is properly approved through the planning process.
-
-**Intelligent Document Discovery**: Automatically finds the latest tech spec for the epic using glob patterns, discovers all architecture documents across multiple directories, and builds a prioritized document set for requirement extraction.
-
-**Source Document Grounding**: Every requirement, acceptance criterion, and technical constraint is traced to a specific source document. The workflow explicitly forbids inventing domain facts not present in source materials.
-
-**Non-Interactive by Default**: Operates in "#yolo" mode to minimize interruptions, only prompting when absolutely necessary (like missing critical configuration). This enables smooth automated story preparation.
-
-**Automatic Context Generation**: When `auto_run_context` is true (default), automatically triggers the story-context workflow to generate developer expertise injection for the newly created story.
-
-## Integration with v6 Flow
-
-The create-story workflow is step 1 in the v6 implementation cycle:
-
-1. **SM: create-story** ← You are here
-2. SM: story-context (adds JIT technical expertise)
-3. DEV: dev-story (implements with generated context)
-4. DEV/SR: code-review (validates completion)
-5. If needed: correct-course (adjusts direction)
-6. After epic: retrospective (captures learnings)
-
-This workflow establishes the "what" that needs to be built, strictly based on planned epics. The story-context workflow will later add the "how" through just-in-time technical expertise injection.
-
-## Document Priority Order
-
-The workflow uses this priority for extracting requirements:
-
-1. **tech_spec_file**: Epic-scoped technical specification (highest priority)
-2. **epics_file**: Acceptance criteria and story breakdown
-3. **prd_file**: Business requirements and constraints
-4. **Architecture docs**: Constraints, patterns, and technical guidance
-
-## Workflow Behavior
-
-**Story Number Management:**
-
-- Automatically detects next story number from existing files
-- Won't skip numbers or create duplicates
-- Maintains epic.story numbering convention
-
-**Update vs Create:**
-
-- If latest story status != Done/Approved: Updates existing story
-- If latest story status == Done/Approved: Creates next story (if enumerated in epics.md)
-
-**Epic Advancement:**
-
-- In non-interactive mode: Stays within current epic
-- Interactive mode: Can prompt for new epic number
-
-## Troubleshooting
-
-**"No planned next story found in epics.md"**: The next story isn't enumerated in epics.md. Run SM or PM agent's `*correct-course` to properly plan and add the story to the epic.
-
-**Missing story_dir Configuration**: Ensure `dev_story_location` is set in bmad/bmm/config.yaml
-
-**Tech Spec Not Found**: The workflow looks for `tech-spec-epic-{N}-*.md` pattern. Ensure tech specs follow this naming convention.
-
-**Architecture Documents Missing**: While not fatal, missing architecture docs reduce story context quality. Ensure key docs exist in docs/ or output folder.