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

package/src/modules/bmm/docs/workflows-implementation.md

@@ -1,7 +1,5 @@
 # BMM Implementation Workflows (Phase 4)
 
-**Reading Time:** ~8 minutes
-
 ## Overview
 
 Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle using a **story-centric workflow** where each story moves through a defined lifecycle from creation to completion.
@@ -14,117 +12,29 @@ Phase 4 (Implementation) workflows manage the iterative sprint-based development
 
 Phase 4 is the final phase of the BMad Method workflow. To see how implementation fits into the complete methodology:
 
-![BMad Method Workflow - Standard Greenfield](./images/workflow-method-greenfield.svg)
+The BMad Method consists of four phases working in sequence:
 
-_Complete workflow showing Phases 1-4. Phase 4 (Implementation) is the rightmost column, showing the iterative epic and story cycles detailed below._
+1. **Phase 1 (Analysis)** - Optional exploration and discovery workflows
+2. **Phase 2 (Planning)** - Required requirements definition using scale-adaptive system
+3. **Phase 3 (Solutioning)** - Technical architecture and design decisions
+4. **Phase 4 (Implementation)** - Iterative sprint-based development with story-centric workflow
 
----
+Phase 4 focuses on the iterative epic and story cycles where stories are implemented, reviewed, and completed one at a time.
 
-## Phase 4 Workflow Lifecycle
-
-```mermaid
-%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','fontSize':'16px','fontFamily':'arial'}}}%%
-graph TB
-    subgraph Setup["<b>SPRINT SETUP - Run Once</b>"]
-        direction TB
-        SprintPlanning["<b>SM: sprint-planning</b><br/>Initialize sprint status file"]
-    end
-
-    subgraph EpicCycle["<b>EPIC CYCLE - Repeat Per Epic</b>"]
-        direction TB
-        EpicContext["<b>SM: epic-tech-context</b><br/>Generate epic technical guidance"]
-        ValidateEpic["<b>SM: validate-epic-tech-context</b><br/>(Optional validation)"]
-
-        EpicContext -.->|Optional| ValidateEpic
-        ValidateEpic -.-> StoryLoopStart
-        EpicContext --> StoryLoopStart[Start Story Loop]
-    end
-
-    subgraph StoryLoop["<b>STORY LIFECYCLE - Repeat Per Story</b>"]
-        direction TB
-
-        CreateStory["<b>SM: create-story</b><br/>Create next story from queue"]
-        ValidateStory["<b>SM: validate-create-story</b><br/>(Optional validation)"]
-        StoryContext["<b>SM: story-context</b><br/>Assemble dynamic context"]
-        StoryReady["<b>SM: story-ready-for-dev</b><br/>Mark ready without context"]
-        ValidateContext["<b>SM: validate-story-context</b><br/>(Optional validation)"]
-        DevStory["<b>DEV: develop-story</b><br/>Implement with tests"]
-        CodeReview["<b>DEV: code-review</b><br/>Senior dev review"]
-        StoryDone["<b>DEV: story-done</b><br/>Mark complete, advance queue"]
-
-        CreateStory -.->|Optional| ValidateStory
-        ValidateStory -.-> StoryContext
-        CreateStory --> StoryContext
-        CreateStory -.->|Alternative| StoryReady
-        StoryContext -.->|Optional| ValidateContext
-        ValidateContext -.-> DevStory
-        StoryContext --> DevStory
-        StoryReady -.-> DevStory
-        DevStory --> CodeReview
-        CodeReview -.->|Needs fixes| DevStory
-        CodeReview --> StoryDone
-        StoryDone -.->|Next story| CreateStory
-    end
-
-    subgraph EpicClose["<b>EPIC COMPLETION</b>"]
-        direction TB
-        Retrospective["<b>SM: epic-retrospective</b><br/>Post-epic lessons learned"]
-    end
-
-    subgraph Support["<b>SUPPORTING WORKFLOWS</b>"]
-        direction TB
-        CorrectCourse["<b>SM: correct-course</b><br/>Handle mid-sprint changes"]
-        WorkflowStatus["<b>Any Agent: workflow-status</b><br/>Check what's next"]
-    end
-
-    Setup --> EpicCycle
-    EpicCycle --> StoryLoop
-    StoryLoop --> EpicClose
-    EpicClose -.->|Next epic| EpicCycle
-    StoryLoop -.->|If issues arise| CorrectCourse
-    StoryLoop -.->|Anytime| WorkflowStatus
-    EpicCycle -.->|Anytime| WorkflowStatus
-
-    style Setup fill:#e3f2fd,stroke:#1565c0,stroke-width:3px,color:#000
-    style EpicCycle fill:#c5e1a5,stroke:#33691e,stroke-width:3px,color:#000
-    style StoryLoop fill:#f3e5f5,stroke:#6a1b9a,stroke-width:3px,color:#000
-    style EpicClose fill:#ffcc80,stroke:#e65100,stroke-width:3px,color:#000
-    style Support fill:#fff3e0,stroke:#e65100,stroke-width:3px,color:#000
-
-    style SprintPlanning fill:#90caf9,stroke:#0d47a1,stroke-width:2px,color:#000
-    style EpicContext fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
-    style ValidateEpic fill:#c5e1a5,stroke:#33691e,stroke-width:1px,color:#000
-    style CreateStory fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
-    style ValidateStory fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
-    style StoryContext fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
-    style StoryReady fill:#ce93d8,stroke:#4a148c,stroke-width:2px,color:#000
-    style ValidateContext fill:#e1bee7,stroke:#6a1b9a,stroke-width:1px,color:#000
-    style DevStory fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
-    style CodeReview fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
-    style StoryDone fill:#a5d6a7,stroke:#1b5e20,stroke-width:2px,color:#000
-    style Retrospective fill:#ffb74d,stroke:#e65100,stroke-width:2px,color:#000
-```
+For a visual representation of the complete workflow, see: [workflow-method-greenfield.excalidraw](./images/workflow-method-greenfield.excalidraw)
 
 ---
 
 ## Quick Reference
 
-| Workflow                       | Agent | When                             | Purpose                                     |
-| ------------------------------ | ----- | -------------------------------- | ------------------------------------------- |
-| **sprint-planning**            | SM    | Once at Phase 4 start            | Initialize sprint tracking file             |
-| **epic-tech-context**          | SM    | Per epic                         | Generate epic-specific technical guidance   |
-| **validate-epic-tech-context** | SM    | Optional after epic-tech-context | Validate tech spec against checklist        |
-| **create-story**               | SM    | Per story                        | Create next story from epic backlog         |
-| **validate-create-story**      | SM    | Optional after create-story      | Independent validation of story draft       |
-| **story-context**              | SM    | Optional per story               | Assemble dynamic story context XML          |
-| **validate-story-context**     | SM    | Optional after story-context     | Validate story context against checklist    |
-| **story-ready-for-dev**        | SM    | Optional per story               | Mark story ready without generating context |
-| **develop-story**              | DEV   | Per story                        | Implement story with tests                  |
-| **code-review**                | DEV   | Per story                        | Senior dev quality review                   |
-| **story-done**                 | DEV   | Per story                        | Mark complete and advance queue             |
-| **epic-retrospective**         | SM    | After epic complete              | Review lessons and extract insights         |
-| **correct-course**             | SM    | When issues arise                | Handle significant mid-sprint changes       |
-| **workflow-status**            | Any   | Anytime                          | Check "what should I do now?"               |
+| Workflow            | Agent | When                  | Purpose                               |
+| ------------------- | ----- | --------------------- | ------------------------------------- |
+| **sprint-planning** | SM    | Once at Phase 4 start | Initialize sprint tracking file       |
+| **create-story**    | SM    | Per story             | Create next story from epic backlog   |
+| **dev-story**       | DEV   | Per story             | Implement story with tests            |
+| **code-review**     | DEV   | Per story             | Senior dev quality review             |
+| **retrospective**   | SM    | After epic complete   | Review lessons and extract insights   |
+| **correct-course**  | SM    | When issues arise     | Handle significant mid-sprint changes |
 
 ---
 
@@ -132,27 +42,26 @@ graph TB
 
 ### SM (Scrum Master) - Primary Implementation Orchestrator
 
-**Workflows:** sprint-planning, epic-tech-context, validate-epic-tech-context, create-story, validate-create-story, story-context, validate-story-context, story-ready-for-dev, epic-retrospective, correct-course
+**Workflows:** sprint-planning, create-story, retrospective, correct-course
 
 **Responsibilities:**
 
 - Initialize and maintain sprint tracking
-- Generate technical context (epic and story level)
-- Orchestrate story lifecycle with optional validations
-- Mark stories ready for development
-- Handle course corrections
-- Facilitate retrospectives
+- Create stories from epic backlog
+- Handle course corrections when issues arise
+- Facilitate retrospectives after epic completion
+- Orchestrate overall implementation flow
 
 ### DEV (Developer) - Implementation and Quality
 
-**Workflows:** develop-story, code-review, story-done
+**Workflows:** dev-story, code-review
 
 **Responsibilities:**
 
 - Implement stories with tests
 - Perform senior developer code reviews
-- Mark stories complete and advance queue
 - Ensure quality and adherence to standards
+- Complete story implementation lifecycle
 
 ---
 
@@ -161,7 +70,7 @@ graph TB
 Stories move through these states in the sprint status file:
 
 1. **TODO** - Story identified but not started
-2. **IN PROGRESS** - Story being implemented (create-story → story-context → dev-story)
+2. **IN PROGRESS** - Story being implemented (create-story → dev-story)
 3. **READY FOR REVIEW** - Implementation complete, awaiting code review
 4. **DONE** - Accepted and complete
 
@@ -183,28 +92,24 @@ Stories move through these states in the sprint status file:
 
 **Per Epic:**
 
-1. SM runs `epic-tech-context`
-2. SM optionally runs `validate-epic-tech-context`
+- Epic context and stories are already prepared from Phase 3
 
 **Per Story (repeat until epic complete):**
 
 1. SM runs `create-story`
-2. SM optionally runs `validate-create-story`
-3. SM runs `story-context` OR `story-ready-for-dev` (choose one)
-4. SM optionally runs `validate-story-context` (if story-context was used)
-5. DEV runs `develop-story`
-6. DEV runs `code-review`
-7. If code review passes: DEV runs `story-done`
-8. If code review finds issues: DEV fixes in `develop-story`, then back to code-review
+2. DEV runs `dev-story`
+3. DEV runs `code-review`
+4. If code review fails: DEV fixes issues in `dev-story`, then re-runs `code-review`
 
 **After Epic Complete:**
 
-- SM runs `epic-retrospective`
-- Move to next epic (start with `epic-tech-context` again)
+- SM runs `retrospective`
+- Move to next epic
 
 **As Needed:**
 
-- Run `workflow-status` anytime to check progress
+- Run `sprint-status` anytime in Phase 4 to inspect sprint-status.yaml and get the next implementation command
+- Run `workflow-status` for cross-phase routing and project-level paths
 - Run `correct-course` if significant changes needed
 
 ---
@@ -215,14 +120,6 @@ Stories move through these states in the sprint status file:
 
 Complete each story's full lifecycle before starting the next. This prevents context switching and ensures quality.
 
-### Epic-Level Technical Context
-
-Generate detailed technical guidance per epic (not per story) using `epic-tech-context`. This provides just-in-time architecture without upfront over-planning.
-
-### Story Context (Optional)
-
-Use `story-context` to assemble focused context XML for each story, pulling from PRD, architecture, epic context, and codebase docs. Alternatively, use `story-ready-for-dev` to mark a story ready without generating context XML.
-
 ### Quality Gates
 
 Every story goes through `code-review` before being marked done. No exceptions.
@@ -233,63 +130,181 @@ The `sprint-status.yaml` file is the single source of truth for all implementati
 
 ---
 
-## Common Patterns
-
-### Level 0-1 (Quick Flow)
-
-```
-tech-spec (PM)
-  → sprint-planning (SM)
-  → story loop (SM/DEV)
-```
-
-### Level 2-4 (BMad Method / Enterprise)
+### (BMad Method / Enterprise)
 
 ```
+<<<<<<< Updated upstream
 PRD (PM) → Architecture (Architect)
   → create-epics-and-stories (PM)  ← V6: After architecture!
   → implementation-readiness (Architect)
   → sprint-planning (SM, once)
   → [Per Epic]:
-      epic-tech-context (SM)
       → story loop (SM/DEV)
-      → epic-retrospective (SM)
+      → retrospective (SM)
   → [Next Epic]
+=======
+Current Phase: 4 (Implementation)
+Current Epic: Epic 1 (Authentication)
+Current Sprint: Sprint 1
+
+Next Story: Story 1.3 (Email Verification)
+Status: TODO
+Dependencies: Story 1.2 (DONE) ✅
+
+**Recommendation:** Run `create-story` to generate Story 1.3
+
+After create-story:
+1. Run story-context
+2. Run dev-story
+3. Run code-review
+4. Run story-done
+```
+
+See: [workflow-status instructions](../workflows/workflow-status/instructions.md)
+
+---
+
+### document-project
+
+**Purpose:** Analyze and document brownfield projects by scanning codebase, architecture, and patterns.
+
+**Agent:** Analyst
+**Duration:** 1-3 hours
+**When to Use:** Brownfield projects without documentation
+
+**How It Works:**
+
+1. Scans codebase structure
+2. Identifies architecture patterns
+3. Documents technology stack
+4. Creates reference documentation
+5. Generates PRD-like document from existing code
+
+**Output:** `project-documentation-{date}.md`
+
+**When to Run:**
+
+- Before starting work on legacy project
+- When inheriting undocumented codebase
+- Creating onboarding documentation
+
+See: [document-project reference](./workflow-document-project-reference.md)
+
+---
+
+## Story Lifecycle Visualization
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ PHASE 4: IMPLEMENTATION (Iterative Story Lifecycle)        │
+└─────────────────────────────────────────────────────────────┘
+
+┌─────────────────┐
+│ Sprint Planning │  → Creates sprint-status.yaml
+└────────┬────────┘     Defines story queue
+         │
+         ├──────────────────────────────────────────┐
+         │                                          │
+         ▼                                          │
+┌─────────────────────┐                            │
+│ Epic Tech Context   │  → Optional per epic       │
+│ (Once per epic)     │     Provides technical     │
+└─────────────────────┘     guidance              │
+         │                                          │
+         ▼                                          │
+┌─────────────────────────────────────────────────┤
+│ FOR EACH STORY IN QUEUE:                        │
+├─────────────────────────────────────────────────┤
+         │                                          │
+         ▼                                          │
+┌─────────────────┐                                │
+│ Create Story    │  → Generates story file        │
+│ (TODO → IN PROGRESS)                            │
+└────────┬────────┘                                │
+         │                                          │
+         ▼                                          │
+┌─────────────────┐                                │
+│ Story Context   │  → Assembles focused context   │
+└────────┬────────┘                                │
+         │                                          │
+         ▼                                          │
+┌─────────────────┐                                │
+│ Dev Story       │  → Implements + tests           │
+│ (IN PROGRESS)   │                                │
+└────────┬────────┘                                │
+         │                                          │
+         ▼                                          │
+┌─────────────────┐                                │
+│ Code Review     │  → Senior dev review            │
+│ (IN PROGRESS →  │                                │
+│  READY FOR REVIEW)                               │
+└────────┬────────┘                                │
+         │                                          │
+    ┌────┴────┐                                    │
+    │ Result? │                                    │
+    └────┬────┘                                    │
+         │                                          │
+    ┌────┼────────────────────┐                   │
+    │    │                    │                   │
+    ▼    ▼                    ▼                   │
+APPROVED  APPROVED           REQUEST              │
+          WITH COMMENTS      CHANGES              │
+    │         │                   │                │
+    └─────────┴───────────────────┘               │
+              │                                    │
+              ▼                                    │
+    ┌─────────────────┐                           │
+    │ Story Done      │  → READY FOR REVIEW → DONE│
+    └────────┬────────┘                           │
+             │                                     │
+             ├─────────────────────────────────────┘
+             │ More stories?
+             │
+             ▼
+    ┌────────────────┐
+    │ Epic Complete? │
+    └────────┬───────┘
+             │
+        ┌────┼────┐
+        │         │
+       Yes       No
+        │         └──> Continue to next story
+        │
+        ▼
+┌─────────────────┐
+│ Retrospective   │  → Review epic, lessons learned
+└─────────────────┘
+        │
+        ▼
+    All epics done?
+        │
+       Yes → PROJECT COMPLETE
+>>>>>>> Stashed changes
 ```
 
 ---
 
 ## Related Documentation
 
+- [Phase 1: Analysis Workflows](./workflows-analysis.md)
 - [Phase 2: Planning Workflows](./workflows-planning.md)
 - [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
-- [Quick Spec Flow](./quick-spec-flow.md) - Level 0-1 fast track
-- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project levels
 
 ---
 
 ## Troubleshooting
 
 **Q: Which workflow should I run next?**
-A: Run `workflow-status` - it reads the sprint status file and tells you exactly what to do.
+A: Run `workflow-status` - it reads the sprint status file and tells you exactly what to do. During implementation (Phase 4) run `sprint-status` (fast check against sprint-status.yaml).
 
 **Q: Story needs significant changes mid-implementation?**
 A: Run `correct-course` to analyze impact and route appropriately.
 
-**Q: Do I run epic-tech-context for every story?**
-A: No! Run once per epic, not per story. Use `story-context` or `story-ready-for-dev` per story instead.
-
-**Q: Do I have to use story-context for every story?**
-A: No, it's optional. You can use `story-ready-for-dev` to mark a story ready without generating context XML.
-
 **Q: Can I work on multiple stories in parallel?**
 A: Not recommended. Complete one story's full lifecycle before starting the next. Prevents context switching and ensures quality.
 
 **Q: What if code review finds issues?**
-A: DEV runs `develop-story` to make fixes, re-runs tests, then runs `code-review` again until it passes.
-
-**Q: When do I run validations?**
-A: Validations are optional quality gates. Use them when you want independent review of epic tech specs, story drafts, or story context before proceeding.
+A: DEV runs `dev-story` to make fixes, re-runs tests, then runs `code-review` again until it passes.
 
 ---