bmad-method 6.0.0-alpha.12 → 6.0.0-alpha.14

package/src/modules/bmm/docs/brownfield-guide.md

@@ -89,7 +89,7 @@ You: "Yes"
 
 ---
 
-## Phase 0: Documentation (Critical First Step)
+## Documentation: Critical First Step
 
 🚨 **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
 
@@ -159,7 +159,7 @@ If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
 | **A**    | No documentation                           | `document-project`         | Only option - generate from scratch     |
 | **B**    | Docs exist but massive/outdated/incomplete | `document-project`         | Safer to regenerate than trust bad docs |
 | **C**    | Good docs but no structure                 | `shard-doc` → `index-docs` | Structure existing content for AI       |
-| **D**    | Confirmed AI-optimized docs with index.md  | Skip Phase 0               | Rare - only if you're 100% confident    |
+| **D**    | Confirmed AI-optimized docs with index.md  | Skip Documentation         | Rare - only if you're 100% confident    |
 
 ### Scenario A: No Documentation (Most Common)
 
@@ -231,7 +231,7 @@ If you have **good, current documentation** but it's in massive files:
 
 ### Scenario D: Confirmed AI-Optimized Documentation (Rare)
 
-**Action: Skip Phase 0**
+**Action: Skip Documentation**
 
 Only skip if ALL conditions met:
 
@@ -250,8 +250,8 @@ Without AI-optimized documentation, workflows fail:
 
 - **tech-spec** (Quick Flow) can't auto-detect stack/patterns → Makes wrong assumptions
 - **PRD** (BMad Method) can't reference existing code → Designs incompatible features
-- **architecture** can't build on existing structure → Suggests conflicting patterns
-- **story-context** can't inject existing patterns → Dev agent rewrites working code
+- **create-architecture** can't build on existing structure → Suggests conflicting patterns
+- **create-story** can't provide existing pattern context → Stories lack integration guidance
 - **dev-story** invents implementations → Breaks existing integrations
 
 ### Key Principle
@@ -320,18 +320,14 @@ See the [Workflows section in BMM README](../README.md) for details.
 ```mermaid
 flowchart TD
     SPRINT[sprint-planning<br/>Initialize tracking]
-    EPIC[epic-tech-context<br/>Per epic]
     CREATE[create-story]
-    CONTEXT[story-context]
     DEV[dev-story]
     REVIEW[code-review]
     CHECK{More stories?}
     RETRO[retrospective<br/>Per epic]
 
-    SPRINT --> EPIC
-    EPIC --> CREATE
-    CREATE --> CONTEXT
-    CONTEXT --> DEV
+    SPRINT --> CREATE
+    CREATE --> DEV
     DEV --> REVIEW
     REVIEW --> CHECK
     CHECK -->|Yes| CREATE
@@ -343,7 +339,7 @@ flowchart TD
 
 **Status Progression:**
 
-- Epic: `backlog → contexted`
+- Epic: `backlog → in-progress → done`
 - Story: `backlog → drafted → ready-for-dev → in-progress → review → done`
 
 **Brownfield-Specific Implementation Tips:**
@@ -351,7 +347,6 @@ flowchart TD
 1. **Respect existing patterns** - Follow established conventions
 2. **Test integration thoroughly** - Validate interactions with existing code
 3. **Use feature flags** - Enable gradual rollout
-4. **Context injection matters** - epic-tech-context and story-context reference existing patterns
 
 ---
 
@@ -375,7 +370,7 @@ When workflow-init asks about your work:
 
 ### 4. Respect Existing Patterns
 
-Tech-spec and story-context will detect conventions. Follow them unless explicitly modernizing.
+Tech-spec and create-story workflows will detect conventions from existing documentation. Follow them unless explicitly modernizing.
 
 ### 5. Plan Integration Points Explicitly
 
@@ -405,13 +400,7 @@ Document in tech-spec/architecture:
 - Context epics before drafting stories
 - Update `sprint-status.yaml` as work progresses
 
-### 9. Leverage Context Injection
-
-- Run `epic-tech-context` before story drafting
-- Always create `story-context` before implementation
-- These reference existing patterns for consistency
-
-### 10. Learn Continuously
+### 9. Learn Continuously
 
 - Run `retrospective` after each epic
 - Incorporate learnings into next stories
@@ -457,7 +446,7 @@ Document in tech-spec/architecture:
    - Analyzes existing auth patterns
    - Confirms conventions
    - Creates tech-spec.md + epic + 3-5 stories
-3. **Implement:** Load SM → `sprint-planning` → `create-story` → `story-context`
+3. **Implement:** Load SM → `sprint-planning` → `create-story`
    Load DEV → `dev-story` for each story
 4. **Review:** Load DEV → `code-review`
 
@@ -479,7 +468,7 @@ Document in tech-spec/architecture:
 4. **Solution:** Load Architect → `create-architecture` → `create-epics-and-stories` → `implementation-readiness`
 5. **Implement:** Sprint-based (10-15 stories)
    - Load SM → `sprint-planning`
-   - Per epic: `epic-tech-context` → stories
+   - Load SM → `create-story` per story
    - Load DEV → `dev-story` per story
 6. **Review:** Per story completion
 
@@ -523,12 +512,9 @@ Document in tech-spec/architecture:
    - `product-brief` - Strategic document
 3. **Plan:** Load PM → `prd` (comprehensive FRs/NFRs)
 4. **Solution:**
-   - `create-architecture` - Full system architecture
-   - `integration-planning` - Phased migration strategy
-   - `create-architecture` - Multi-tenancy architecture
-   - `validate-architecture` - External review
+   - `create-architecture` - Full system architecture including multi-tenancy design
    - `create-epics-and-stories` - Create epics and stories
-   - `implementation-readiness` - Executive approval
+   - `implementation-readiness` - Final validation before implementation
 5. **Implement:** Phased sprint-based (50+ stories)
 
 **Time:** 3-6 months
@@ -575,7 +561,7 @@ Document in tech-spec/architecture:
 **Solution:**
 
 1. Ensure `document-project` captured existing architecture
-2. Check `story-context` - should document integration points
+2. Check story files created by `create-story` - should include integration context
 3. In tech-spec/architecture - explicitly document:
    - Which existing modules to modify
    - What APIs/services to integrate with
@@ -608,7 +594,7 @@ Document in tech-spec/architecture:
 
 1. Check convention detection (Quick Spec Flow should detect patterns)
 2. Review documentation - ensure `document-project` captured patterns
-3. Use `story-context` - injects pattern guidance
+3. Use `create-story` workflow - it loads context from existing documentation
 4. Add to code-review checklist: pattern adherence, convention consistency
 5. Run retrospective to identify deviations early
 
@@ -619,7 +605,7 @@ Document in tech-spec/architecture:
 ### Commands by Phase
 
 ```bash
-# Phase 0: Documentation (If Needed)
+# Documentation (If Needed)
 # Analyst agent:
 document-project        # Create comprehensive docs (10-30min)
 # OR load index-docs task for existing docs (2-5min)
@@ -637,16 +623,14 @@ prd                     # BMad Method/Enterprise tracks
 
 # Phase 3: Solutioning (BMad Method/Enterprise)
 # Architect agent:
-create-architecture          # Extend architecture
+create-architecture          # Create/extend architecture
 create-epics-and-stories     # Create epics and stories (after architecture)
-implementation-readiness       # Final validation
+implementation-readiness     # Final validation
 
 # Phase 4: Implementation (All Tracks)
 # SM agent:
 sprint-planning              # Initialize tracking
-epic-tech-context            # Epic context
-create-story                 # Draft story
-story-context                # Story context
+create-story                 # Create story
 
 # DEV agent:
 dev-story                    # Implement
@@ -659,14 +643,14 @@ correct-course               # If issues
 
 ### Key Files
 
-**Phase 0 Output:**
+**Documentation Output:**
 
 - `docs/index.md` - **Master AI entry point (REQUIRED)**
 - `docs/project-overview.md`
 - `docs/architecture.md`
 - `docs/source-tree-analysis.md`
 
-**Phase 1-3 Tracking:**
+**Phase 1-4 Tracking:**
 
 - `docs/bmm-workflow-status.yaml` - Progress tracker
 
@@ -682,6 +666,7 @@ correct-course               # If issues
 **Phase 3 Architecture:**
 
 - `docs/architecture.md` (BMad Method/Enterprise tracks)
+- `docs/epics.md` + epic folders (from create-epics-and-stories)
 
 **Phase 4 Implementation:**
 
@@ -740,6 +725,7 @@ flowchart TD
 - **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
 - **[Glossary](./glossary.md)** - Key terminology
 - **[FAQ](./faq.md)** - Common questions
+- **[Troubleshooting](./troubleshooting.md)** - Problem resolution
 - **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference
 
 ---
@@ -754,7 +740,7 @@ flowchart TD
 
 **Documentation:**
 
-- [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
+- **[Test Architect Guide](./test-architecture.md)** - Comprehensive testing strategy
 - [BMM Module README](../README.md) - Complete module and workflow reference
 
 ---

package/src/modules/bmm/docs/enterprise-agentic-development.md

@@ -240,7 +240,7 @@ Continuous deployment to production
 **UX Designer Workflow:**
 
 ```bash
-bmad ux *create-design
+bmad ux *create-ux-design
 ```
 
 **BMad produces:**
@@ -288,8 +288,8 @@ bmad ux *create-design
 
 **BMad ensures:**
 
-- AI agents follow architectural patterns consistently (via story-context)
-- Code standards applied uniformly (via epic-tech-context)
+- AI agents follow architectural patterns consistently
+- Code standards applied uniformly
 - PRD traceability throughout implementation (via acceptance criteria)
 - No "telephone game" between PM, design, and dev
 

package/src/modules/bmm/docs/faq.md

@@ -90,7 +90,7 @@ When in doubt, start smaller. You can always run create-prd later if needed.
 
 ### Q: Do I always need architecture for Level 2?
 
-**A:** No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD + epic-tech-context created during implementation.
+**A:** No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD created during planning.
 
 ### Q: What's the difference between Level 1 and Level 2?
 
@@ -147,7 +147,7 @@ If status file exists, use workflow-status. If not, use workflow-init.
 
 ### Q: How do I know when Phase 3 is complete and I can start Phase 4?
 
-**A:** For Level 3-4, run the implementation-readiness workflow. It validates that PRD (FRs/NFRs), architecture, epics+stories, and UX (if applicable) are cohesive before implementation. Pass the gate check = ready for Phase 4.
+**A:** For Level 3-4, run the implementation-readiness workflow. It validates PRD + Architecture + Epics + UX (optional) are aligned before implementation. Pass the gate check = ready for Phase 4.
 
 ### Q: Can I run workflows in parallel or do they have to be sequential?
 
@@ -162,15 +162,6 @@ If status file exists, use workflow-status. If not, use workflow-init.
 
 ## Planning Documents
 
-### Q: What's the difference between tech-spec and epic-tech-context?
-
-**A:**
-
-- **Tech-spec (Level 0-1):** Created upfront in Planning Phase, serves as primary/only planning document, a combination of enough technical and planning information to drive a single or multiple files
-- **Epic-tech-context (Level 2-4):** Created during Implementation Phase per epic, supplements PRD + Architecture
-
-Think of it as: tech-spec is for small projects (replaces PRD and architecture), epic-tech-context is for large projects (supplements PRD).
-
 ### Q: Why no tech-spec at Level 2+?
 
 **A:** Level 2+ projects need product-level planning (PRD) and system-level design (Architecture), which tech-spec doesn't provide. Tech-spec is too narrow for coordinating multiple features. Instead, Level 2-4 uses:
@@ -178,13 +169,6 @@ Think of it as: tech-spec is for small projects (replaces PRD and architecture),
 - PRD (product vision, functional requirements, non-functional requirements)
 - Architecture (system design)
 - Epics+Stories (created AFTER architecture is complete)
-- Epic-tech-context (detailed implementation per epic, created just-in-time)
-
-### Q: When do I create epic-tech-context?
-
-**A:** In Phase 4, right before implementing each epic. Don't create all epic-tech-context upfront - that's over-planning. Create them just-in-time using the epic-tech-context workflow as you're about to start working on that epic.
-
-**Why just-in-time?** You'll learn from earlier epics, and those learnings improve later epic-tech-context.
 
 ### Q: Do I need a PRD for a bug fix?
 
@@ -209,26 +193,9 @@ PRDs are for Level 2-4 projects with multiple features requiring product-level c
 
 ## Implementation
 
-### Q: Do I need story-context for every story?
-
-**A:** Technically no, but it's recommended. story-context provides implementation-specific guidance, references existing patterns, and injects expertise. Skip it only if:
-
-- Very simple story (self-explanatory)
-- You're already expert in the area
-- Time is extremely limited
-
-For Level 0-1 using tech-spec, story-context is less critical because tech-spec is already comprehensive.
-
-### Q: What if I don't create epic-tech-context before drafting stories?
-
-**A:** You can proceed without it, but you'll miss:
-
-- Epic-level technical direction
-- Architecture guidance for this epic
-- Integration strategy with other epics
-- Common patterns to follow across stories
+### Q: Does create-story include implementation context?
 
-epic-tech-context helps ensure stories within an epic are cohesive.
+**A:** Yes! The create-story workflow generates story files that include implementation-specific guidance, references existing patterns from your documentation, and provides technical context. The workflow loads your architecture, PRD, and existing project documentation to create comprehensive stories. For Quick Flow projects using tech-spec, the tech-spec itself is already comprehensive, so stories can be simpler.
 
 ### Q: How do I mark a story as done?
 
@@ -271,7 +238,7 @@ The story-done workflow is faster and ensures proper status file updates.
 - What went well
 - What could improve
 - Technical insights
-- Input for next epic-tech-context
+- Learnings for future epics
 
 Don't wait until project end - run after each epic for continuous improvement.
 
@@ -565,7 +532,7 @@ Trust your expertise - BMM supports your decisions.
 
 ### Q: How do I report a bug or request a feature?
 
-**A:** Open a GitHub issue at: https://github.com/bmad-code-org/BMAD-METHOD/issues
+**A:** Open a GitHub issue at: <https://github.com/bmad-code-org/BMAD-METHOD/issues>
 
 Please include:
 

package/src/modules/bmm/docs/glossary.md

@@ -69,12 +69,6 @@ The methodology path (Quick Flow, BMad Method, or Enterprise Method) chosen for
 
 **Quick Flow track only.** Comprehensive technical plan created upfront that serves as the primary planning document for small changes or features. Contains problem statement, solution approach, file-level changes, stack detection (brownfield), testing strategy, and developer resources.
 
-### Epic-Tech-Context (Epic Technical Context)
-
-**BMad Method/Enterprise tracks only.** Detailed technical planning document created during implementation (just-in-time) for each epic. Supplements PRD + Architecture with epic-specific implementation details, code-level design decisions, and integration points.
-
-**Key Difference:** Tech-spec (Quick Flow) is created upfront and is the only planning doc. Epic-tech-context (BMad Method/Enterprise) is created per epic during implementation and supplements PRD + Architecture.
-
 ### PRD (Product Requirements Document)
 
 **BMad Method/Enterprise tracks.** Product-level planning document containing vision, goals, Functional Requirements (FRs), Non-Functional Requirements (NFRs), success criteria, and UX considerations. Replaces tech-spec for larger projects that need product planning. **V6 Note:** PRD focuses on WHAT to build (requirements). Epic+Stories are created separately AFTER architecture via create-epics-and-stories workflow.
@@ -119,19 +113,15 @@ Architecture design phase. Required for BMad Method and Enterprise Method tracks
 
 ### Phase 4: Implementation (Required)
 
-Sprint-based development through story-by-story iteration. Uses sprint-planning, epic-tech-context, create-story, story-context, dev-story, code-review, and retrospective workflows.
+Sprint-based development through story-by-story iteration. Uses sprint-planning, create-story, dev-story, code-review, and retrospective workflows.
 
-### Quick Spec Flow
-
-Fast-track workflow system for Quick Flow track projects that goes straight from idea to tech-spec to implementation, bypassing heavy planning. Designed for bug fixes, small features, and rapid prototyping.
+### Documentation (Prerequisite for Brownfield)
 
-### Just-In-Time Design
+**Conditional prerequisite for brownfield projects.** Creates comprehensive codebase documentation before planning. Only required if existing documentation is insufficient for AI agents. Uses the `document-project` workflow.
 
-Pattern where epic-tech-context is created during implementation (Phase 4) right before working on each epic, rather than all upfront. Enables learning and adaptation.
-
-### Context Injection
+### Quick Spec Flow
 
-Dynamic technical guidance generated for each story via epic-tech-context and story-context workflows, providing exact expertise when needed without upfront over-planning.
+Fast-track workflow system for Quick Flow track projects that goes straight from idea to tech-spec to implementation, bypassing heavy planning. Designed for bug fixes, small features, and rapid prototyping.
 
 ---
 
@@ -201,7 +191,7 @@ backlog → drafted → ready-for-dev → in-progress → review → done
 
 - **backlog** - Story exists in epic but not yet drafted
 - **drafted** - Story file created by SM via create-story
-- **ready-for-dev** - Story has context, ready for DEV via story-context
+- **ready-for-dev** - Story drafted and reviewed, ready for DEV
 - **in-progress** - DEV is implementing via dev-story
 - **review** - Implementation complete, awaiting code-review
 - **done** - Completed with DoD met
@@ -209,11 +199,12 @@ backlog → drafted → ready-for-dev → in-progress → review → done
 ### Epic Status Progression
 
 ```
-backlog → contexted
+backlog → in-progress → done
 ```
 
-- **backlog** - Epic exists in planning docs but no context yet
-- **contexted** - Epic has technical context via epic-tech-context
+- **backlog** - Epic not yet started
+- **in-progress** - Epic actively being worked on
+- **done** - All stories in epic completed
 
 ### Retrospective
 
@@ -251,11 +242,7 @@ Markdown file containing story details: description, acceptance criteria, techni
 
 ### Story Context
 
-Technical guidance document created via story-context workflow that provides implementation-specific context, references existing patterns, suggests approaches, and injects expertise for the specific story.
-
-### Epic Context
-
-Technical planning document created via epic-tech-context workflow before drafting stories within an epic. Provides epic-level technical direction, architecture notes, and implementation strategy.
+Implementation guidance embedded within story files during the create-story workflow. Provides implementation-specific context, references existing patterns, suggests approaches, and helps maintain consistency with established codebase conventions.
 
 ### Sprint Planning
 
@@ -263,7 +250,7 @@ Workflow that initializes Phase 4 implementation by creating sprint-status.yaml,
 
 ### Gate Check
 
-Validation workflow (implementation-readiness) run before Phase 4 to ensure PRD, architecture, and UX documents are cohesive with no gaps or contradictions. Required for BMad Method and Enterprise Method tracks.
+Validation workflow (implementation-readiness) run before Phase 4 to ensure PRD + Architecture + Epics + UX (optional) are aligned with no gaps or contradictions. Required for BMad Method and Enterprise Method tracks.
 
 ### DoD (Definition of Done)
 

package/src/modules/bmm/docs/images/README.md

@@ -0,0 +1,37 @@
+# Workflow Diagram Maintenance
+
+## Regenerating SVG from Excalidraw
+
+When you edit `workflow-method-greenfield.excalidraw`, regenerate the SVG:
+
+1. Open <https://excalidraw.com/>
+2. Load the `.excalidraw` file
+3. Click menu (☰) → Export image → SVG
+4. **Set "Scale" to 1x** (default is 2x)
+5. Click "Export"
+6. Save as `workflow-method-greenfield.svg`
+7. **Validate the changes** (see below)
+8. Commit both files together
+
+**Important:**
+
+- Always use **1x scale** to maintain consistent dimensions
+- Automated export tools (`excalidraw-to-svg`) are broken - use manual export only
+
+## Visual Validation
+
+After regenerating the SVG, validate that it renders correctly:
+
+```bash
+./tools/validate-svg-changes.sh src/modules/bmm/docs/images/workflow-method-greenfield.svg
+```
+
+This script:
+
+- Checks for required dependencies (Playwright, ImageMagick)
+- Installs Playwright locally if needed (no package.json pollution)
+- Renders old vs new SVG using browser-accurate rendering
+- Compares pixel-by-pixel and generates a diff image
+- Outputs a prompt for AI visual analysis (paste into Gemini/Claude)
+
+**Threshold**: <0.01% difference is acceptable (anti-aliasing variations)