bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/validation-criteria.yaml

@@ -0,0 +1,189 @@
+# Implementation Readiness Validation Criteria
+# Defines systematic validation rules by project level
+
+validation_rules:
+  # Level 0-1 Projects (Simple, minimal planning)
+  level_0_1:
+    required_documents:
+      - tech_spec
+      - stories_or_tasks
+
+    validations:
+      - name: "Tech Spec Completeness"
+        checks:
+          - "All features defined with implementation approach"
+          - "Technical dependencies identified"
+          - "API contracts defined if applicable"
+          - "Data models specified"
+
+      - name: "Story Coverage"
+        checks:
+          - "All tech spec features have corresponding stories"
+          - "Stories are sequenced logically"
+          - "Technical tasks are defined"
+          - "No critical gaps in coverage"
+
+  # Level 2 Projects (PRD + Tech Spec, no separate architecture)
+  level_2:
+    required_documents:
+      - prd
+      - tech_spec # Includes architecture decisions
+      - epics_and_stories
+
+    validations:
+      - name: "PRD to Tech Spec Alignment"
+        checks:
+          - "All PRD requirements addressed in tech spec"
+          - "Architecture embedded in tech spec covers PRD needs"
+          - "Non-functional requirements are specified"
+          - "Technical approach supports business goals"
+
+      - name: "Story Coverage and Alignment"
+        checks:
+          - "Every PRD requirement has story coverage"
+          - "Stories align with tech spec approach"
+          - "Epic breakdown is complete"
+          - "Acceptance criteria match PRD success criteria"
+
+      - name: "Sequencing Validation"
+        checks:
+          - "Foundation stories come first"
+          - "Dependencies are properly ordered"
+          - "Iterative delivery is possible"
+          - "No circular dependencies"
+
+  # Level 3-4 Projects (Full planning with separate architecture)
+  level_3_4:
+    required_documents:
+      - prd
+      - architecture
+      - epics_and_stories
+
+    validations:
+      - name: "PRD Completeness"
+        checks:
+          - "User requirements fully documented"
+          - "Success criteria are measurable"
+          - "Scope boundaries clearly defined"
+          - "Priorities are assigned"
+
+      - name: "Architecture Coverage"
+        checks:
+          - "All PRD requirements have architectural support"
+          - "System design is complete"
+          - "Integration points defined"
+          - "Security architecture specified"
+          - "Performance considerations addressed"
+          - "If architecture.md: Implementation patterns defined"
+          - "If architecture.md: Technology versions verified and current"
+          - "If architecture.md: Starter template command documented (if applicable)"
+
+      - name: "PRD-Architecture Alignment"
+        checks:
+          - "No architecture gold-plating beyond PRD"
+          - "NFRs from PRD reflected in architecture"
+          - "Technology choices support requirements"
+          - "Scalability matches expected growth"
+          - "If UX spec exists: Architecture supports UX requirements"
+          - "If UX spec exists: Component library supports interaction patterns"
+
+      - name: "Story Implementation Coverage"
+        checks:
+          - "All architectural components have stories"
+          - "Infrastructure setup stories exist"
+          - "Integration implementation planned"
+          - "Security implementation stories present"
+
+      - name: "Comprehensive Sequencing"
+        checks:
+          - "Infrastructure before features"
+          - "Authentication before protected resources"
+          - "Core features before enhancements"
+          - "Dependencies properly ordered"
+          - "Allows for iterative releases"
+
+# Special validation contexts
+special_contexts:
+  greenfield:
+    additional_checks:
+      - "Project initialization stories exist"
+      - "If using architecture.md: First story is starter template initialization"
+      - "Development environment setup documented"
+      - "CI/CD pipeline stories included"
+      - "Initial data/schema setup planned"
+      - "Deployment infrastructure stories present"
+
+  ux_workflow_active:
+    additional_checks:
+      - "UX requirements in PRD"
+      - "UX implementation stories exist"
+      - "Accessibility requirements covered"
+      - "Responsive design addressed"
+      - "User flow continuity maintained"
+
+  api_heavy:
+    additional_checks:
+      - "API contracts fully defined"
+      - "Versioning strategy documented"
+      - "Authentication/authorization specified"
+      - "Rate limiting considered"
+      - "API documentation stories included"
+
+# Severity definitions
+severity_levels:
+  critical:
+    description: "Must be resolved before implementation"
+    examples:
+      - "Missing stories for core requirements"
+      - "Conflicting technical approaches"
+      - "No infrastructure setup for greenfield"
+      - "Security requirements not addressed"
+
+  high:
+    description: "Should be addressed to reduce risk"
+    examples:
+      - "Incomplete acceptance criteria"
+      - "Unclear story dependencies"
+      - "Missing error handling coverage"
+      - "Performance requirements not validated"
+
+  medium:
+    description: "Consider addressing for smoother implementation"
+    examples:
+      - "Documentation gaps"
+      - "Test strategy not defined"
+      - "Monitoring approach unclear"
+      - "Minor sequencing improvements possible"
+
+  low:
+    description: "Minor improvements for consideration"
+    examples:
+      - "Formatting inconsistencies"
+      - "Optional enhancements identified"
+      - "Style guide compliance"
+      - "Nice-to-have features noted"
+
+# Readiness decision criteria
+readiness_decisions:
+  ready:
+    criteria:
+      - "No critical issues found"
+      - "All required documents present"
+      - "Core alignments validated"
+      - "Story sequencing logical"
+      - "Team can begin implementation"
+
+  ready_with_conditions:
+    criteria:
+      - "Only high/medium issues found"
+      - "Mitigation plans identified"
+      - "Core path to MVP clear"
+      - "Issues won't block initial stories"
+
+  not_ready:
+    criteria:
+      - "Critical issues identified"
+      - "Major gaps in coverage"
+      - "Conflicting approaches found"
+      - "Required documents missing"
+      - "Blocking dependencies unresolved"

package/src/modules/bmm/workflows/3-solutioning/solutioning-gate-check/workflow.yaml

@@ -0,0 +1,40 @@
+# Implementation Ready Check - Workflow Configuration
+name: solutioning-gate-check
+description: "Systematically validate that all planning and solutioning phases are complete and properly aligned before transitioning to Phase 4 implementation. Ensures PRD, architecture, and stories are cohesive with no gaps or contradictions."
+author: "BMad Builder"
+
+# 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"
+document_output_language: "{config_source}:document_output_language"
+date: system-generated
+
+# Workflow status integration
+workflow_status_workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
+workflow_paths_dir: "{project-root}/bmad/bmm/workflows/workflow-status/paths"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmm/workflows/3-solutioning/solutioning-gate-check"
+template: "{installed_path}/template.md"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+
+# Output configuration
+default_output_file: "{output_folder}/implementation-readiness-report-{{date}}.md"
+
+# Expected input documents (varies by project level)
+recommended_inputs:
+  - prd: "{output_folder}/prd*.md"
+  - architecture: "{output_folder}/architecture*.md or {output_folder}/architecture*.md"
+  - tech_spec: "{output_folder}/tech-spec*.md"
+  - epics_stories: "{output_folder}/epic*.md"
+  - ux_artifacts: "{output_folder}/ux*.md"
+
+# Validation criteria data
+validation_criteria: "{installed_path}/validation-criteria.yaml"
+
+standalone: true
+
+web_bundle: false

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

@@ -0,0 +1,221 @@
+# 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

@@ -0,0 +1,69 @@
+# 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/code-review/backlog_template.md

@@ -0,0 +1,12 @@
+# Engineering Backlog
+
+This backlog collects cross-cutting or future action items that emerge from reviews and planning.
+
+Routing guidance:
+
+- Use this file for non-urgent optimizations, refactors, or follow-ups that span multiple stories/epics.
+- Must-fix items to ship a story belong in that story’s `Tasks / Subtasks`.
+- Same-epic improvements may also be captured under the epic Tech Spec `Post-Review Follow-ups` section.
+
+| Date | Story | Epic | Type | Severity | Owner | Status | Notes |
+| ---- | ----- | ---- | ---- | -------- | ----- | ------ | ----- |

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

@@ -0,0 +1,22 @@
+# Senior Developer Review - Validation Checklist
+
+- [ ] Story file loaded from `{{story_path}}`
+- [ ] Story Status verified as one of: {{allow_status_values}}
+- [ ] Epic and Story IDs resolved ({{epic_num}}.{{story_num}})
+- [ ] Story Context located or warning recorded
+- [ ] Epic Tech Spec located or warning recorded
+- [ ] Architecture/standards docs loaded (as available)
+- [ ] Tech stack detected and documented
+- [ ] MCP doc search performed (or web fallback) and references captured
+- [ ] Acceptance Criteria cross-checked against implementation
+- [ ] File List reviewed and validated for completeness
+- [ ] Tests identified and mapped to ACs; gaps noted
+- [ ] Code quality review performed on changed files
+- [ ] Security review performed on changed files and dependencies
+- [ ] Outcome decided (Approve/Changes Requested/Blocked)
+- [ ] Review notes appended under "Senior Developer Review (AI)"
+- [ ] Change Log updated with review entry
+- [ ] Status updated according to settings (if enabled)
+- [ ] Story saved successfully
+
+_Reviewer: {{user_name}} on {{date}}_