> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bmad-code-org/BMAD-METHOD/llms.txt
> Use this file to discover all available pages before exploring further.

# Phase 4: Implementation

> Execute sprints, implement stories, and conduct reviews

# Phase 4: Implementation Workflows

The Implementation phase executes your planned work through structured sprints. These workflows manage sprint planning, story development, code review, and continuous improvement.

## Available Workflows

<CardGroup cols={2}>
  <Card title="Sprint Planning" icon="calendar-days" href="#sprint-planning-workflow">
    Generate sprint status tracking from epics
  </Card>

  <Card title="Create Story" icon="file-plus" href="#create-story-workflow">
    Create detailed story specification files
  </Card>

  <Card title="Dev Story" icon="code" href="#dev-story-workflow">
    Implement stories following specifications
  </Card>

  <Card title="Code Review" icon="magnifying-glass-chart" href="#code-review-workflow">
    Perform adversarial code reviews
  </Card>

  <Card title="Sprint Status" icon="chart-line" href="#sprint-status-workflow">
    Track sprint progress and story states
  </Card>

  <Card title="Correct Course" icon="route" href="#correct-course-workflow">
    Manage sprint changes and course corrections
  </Card>

  <Card title="Retrospective" icon="comments" href="#retrospective-workflow">
    Conduct epic retrospectives
  </Card>
</CardGroup>

***

## Sprint Planning Workflow

### Purpose

Generate comprehensive sprint status tracking from epic files. This workflow creates a YAML file that tracks the status of all epics, stories, and retrospectives throughout development.

### Trigger Commands

```bash theme={null}
"Run sprint planning"
"Generate sprint plan"
"Create sprint status"
```

### How It Works

The workflow:

1. Discovers all epic files (whole or sharded)
2. Extracts all epics and stories
3. Creates status tracking entries
4. Detects existing story files to set initial status
5. Generates sprint-status.yaml

### Status Definitions

**Epic Status Flow**:

```
backlog → in-progress → done
```

* `backlog`: Epic not yet started
* `in-progress`: Epic actively being worked on
* `done`: All stories in epic completed

**Story Status Flow**:

```
backlog → ready-for-dev → in-progress → review → done
```

* `backlog`: Story only exists in epic file
* `ready-for-dev`: Story file created in stories folder
* `in-progress`: Developer actively working
* `review`: Ready for code review
* `done`: Completed

**Retrospective Status**:

```
optional ↔ done
```

* `optional`: Can be completed but not required
* `done`: Finished

### Inputs

* Epic files from `{planning_artifacts}/epic*.md`
* Project context (if exists)
* Configuration from `config.yaml`

### Outputs

**File Location**: `{implementation_artifacts}/sprint-status.yaml`

**File Structure**:

```yaml theme={null}
# Sprint Status - Auto-generated
generated: 2026-03-04
project: my-project
project_key: NOKEY
tracking_system: file-system
story_location: ./stories

development_status:
  epic-1: backlog
  1-1-user-authentication: backlog
  1-2-account-management: ready-for-dev  # Story file exists
  1-3-profile-settings: backlog
  epic-1-retrospective: optional
  
  epic-2: backlog
  2-1-content-creation: backlog
  2-2-content-editing: backlog
  epic-2-retrospective: optional
```

### Example Invocation

```text theme={null}
User: "Run sprint planning"

AI: "Starting sprint planning...

Discovering epic files...
✓ Found: {planning_artifacts}/epics.md

Parsing epics and stories...
✓ Epic 1: User Management (3 stories)
✓ Epic 2: Content Management (5 stories)
✓ Epic 3: Search & Discovery (4 stories)

Total: 3 epics, 12 stories

Detecting story files...
✓ Found story file: 1-2-account-management.md
  Status upgraded: backlog → ready-for-dev

Generating sprint status file...
✓ Created: {implementation_artifacts}/sprint-status.yaml

**Summary**:
- Total Epics: 3
- Total Stories: 12
- Stories Ready: 1
- Stories Backlog: 11"
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/sprint-planning/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/sprint-planning/instructions.md`
* Template: `src/bmm/workflows/4-implementation/sprint-planning/sprint-status-template.yaml`

***

## Create Story Workflow

### Purpose

Create detailed story specification files from epic stories. This workflow generates implementation-ready story files with full context, technical notes, and acceptance criteria.

### Trigger Commands

```bash theme={null}
"Create story [story-id]"
"Generate story 1-2-account-management"
"Prepare story for development"
```

### Workflow Process

1. **Story Selection** - Identify story from epic
2. **Context Gathering** - Load PRD, Architecture, UX
3. **Technical Planning** - Add implementation details
4. **File Generation** - Create story markdown file
5. **Status Update** - Update sprint-status.yaml

### Inputs

* Story from epic file
* PRD (requirements context)
* Architecture (technical decisions)
* UX Design (for UI stories)
* Project context

### Outputs

**File Location**: `{implementation_artifacts}/{story-key}.md`

Example: `stories/1-2-account-management.md`

**Story File Structure**:

```markdown theme={null}
---
epic: 1
story: 1.2
title: Account Management
status: ready-for-dev
estimated_points: 5
---

# Story 1.2: Account Management

**As a** registered user
**I want** to manage my account settings
**So that** I can control my profile and preferences

## Acceptance Criteria

- Given I am logged in
  When I navigate to account settings
  Then I see my current profile information
  
- Given I am on account settings
  When I update my email address
  Then the system validates and saves the new email

## Technical Implementation Notes

**Files to Modify/Create**:
- `src/pages/account-settings.tsx` - Account settings page
- `src/components/ProfileForm.tsx` - Profile edit form
- `src/api/users.ts` - User update API calls

**Architecture References**:
- [ADR-003: State Management] - Use React Context for user state
- [ADR-007: API Design] - Follow REST conventions

**Dependencies**:
- Story 1.1 (User Authentication) must be complete
- Backend API endpoint: PUT /api/users/:id

## UX References

- See UX Design Section 4.2: Account Settings Flow
- Wireframe: Account Settings Page (page 12)

## Test Cases

1. Successful profile update
2. Email validation errors
3. Concurrent update conflicts
4. Permission checks
```

### Example Invocation

```text theme={null}
User: "Create story 1-2-account-management"

AI: "Creating story specification for 1.2: Account Management

Loading context...
✓ PRD: User account requirements
✓ Architecture: State management, API design decisions
✓ UX Design: Account settings wireframes

Generating implementation plan...

Story file created: {implementation_artifacts}/1-2-account-management.md

Updated sprint-status.yaml:
  1-2-account-management: ready-for-dev ← backlog

This story is now ready for development!
Run: 'dev this story 1-2-account-management' to begin implementation."
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/create-story/workflow.yaml`
* Template: `src/bmm/workflows/4-implementation/create-story/template.md`
* Checklist: `src/bmm/workflows/4-implementation/create-story/checklist.md`

***

## Dev Story Workflow

### Purpose

Execute story implementation following the detailed story specification file. This workflow implements features with full context from PRD, Architecture, and UX design.

### Trigger Commands

```bash theme={null}
"Dev this story [story-file]"
"Implement the next story in the sprint plan"
"Dev story 1-2-account-management"
```

### Workflow Process

1. **Story Discovery** - Load story file or auto-discover next story
2. **Context Loading** - Load all relevant planning documents
3. **Implementation** - Write code following specifications
4. **Testing** - Verify acceptance criteria
5. **Status Update** - Mark story as in-progress/review/done

### Auto-Discovery

If no story file specified, the workflow:

1. Reads sprint-status.yaml
2. Finds next story with status `ready-for-dev`
3. Loads that story automatically

### Inputs

* Story specification file
* PRD (business requirements)
* Architecture (technical decisions)
* UX Design (design specs)
* Project context (patterns, conventions)

### Implementation Guidelines

The AI developer:

* Follows architecture decisions strictly
* Implements according to acceptance criteria
* Adheres to project patterns and conventions
* Writes tests to verify acceptance criteria
* Updates story status as work progresses

### Outputs

* Implemented code (files created/modified)
* Tests for acceptance criteria
* Updated sprint-status.yaml
* Implementation notes (if needed)

### Example Invocation

```text theme={null}
User: "Dev story 1-2-account-management"

AI: "Loading story 1.2: Account Management

Context loaded:
✓ Story spec: {implementation_artifacts}/1-2-account-management.md
✓ Architecture decisions (12 ADRs)
✓ UX Design (Account settings flow)
✓ Project context (React patterns, API conventions)

Updating sprint status: ready-for-dev → in-progress

Implementing story...

1. Creating account settings page
   ✓ src/pages/account-settings.tsx
   
2. Building profile form component
   ✓ src/components/ProfileForm.tsx
   
3. Adding API integration
   ✓ src/api/users.ts
   
4. Writing tests
   ✓ tests/account-settings.test.tsx
   ✓ All acceptance criteria verified

Story implementation complete!
Updating sprint status: in-progress → review

Next step: Run code review"
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/dev-story/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/dev-story/instructions.xml`
* Checklist: `src/bmm/workflows/4-implementation/dev-story/checklist.md`

***

## Code Review Workflow

### Purpose

Perform adversarial code review to find specific issues in implementation. This workflow provides fresh-eyes review to catch bugs, security issues, and architectural violations.

### Trigger Commands

```bash theme={null}
"Run code review"
"Review this code"
"Check the implementation"
```

### Review Focus Areas

1. **Acceptance Criteria** - All criteria met?
2. **Architecture Compliance** - Follows ADRs?
3. **Code Quality** - Clean, maintainable code?
4. **Security** - No vulnerabilities?
5. **Performance** - Efficient implementation?
6. **Testing** - Adequate test coverage?
7. **UX Alignment** - Matches design specs?

### Review Process

1. **Context Loading** - Load story, architecture, PRD, UX
2. **Code Analysis** - Review implementation files
3. **Issue Identification** - Find problems and risks
4. **Severity Assessment** - Categorize findings
5. **Report Generation** - Document issues and recommendations

### Issue Severity Levels

* **Critical** - Blocks release (security, data loss, crashes)
* **Major** - Violates requirements or architecture
* **Minor** - Code quality, maintainability issues
* **Suggestion** - Improvements and optimizations

### Inputs

* Implemented code
* Story specification
* Architecture decisions
* PRD requirements
* UX Design (for UI stories)

### Outputs

**Review Report** including:

* Issues found (by severity)
* Architecture compliance check
* Security findings
* Test coverage analysis
* Recommendations
* Overall assessment (Pass/Fail/Conditional)

### Example Invocation

```text theme={null}
User: "Run code review"

AI: "Starting adversarial code review...

Loading context...
✓ Sprint status
✓ Last completed story: 1-2-account-management
✓ Architecture decisions
✓ UX design specs

Reviewing implementation...

**Findings**:

🔴 Critical (1):
- User input not sanitized before database query (SQL injection risk)
  File: src/api/users.ts:45

🟡 Major (2):
- Violates ADR-003: State management not using React Context
  File: src/pages/account-settings.tsx:12
- Missing error handling for API failures
  File: src/components/ProfileForm.tsx:67

🟢 Minor (3):
- Inconsistent naming convention for component props
- Missing TypeScript strict null checks
- Console.log left in production code

**Assessment**: FAIL - Must fix critical and major issues

Updating sprint status: review → in-progress"
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/code-review/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/code-review/instructions.xml`
* Checklist: `src/bmm/workflows/4-implementation/code-review/checklist.md`

***

## Sprint Status Workflow

### Purpose

View current sprint progress and story states. This workflow provides a summary of sprint health and what's in progress.

### Trigger Commands

```bash theme={null}
"Show sprint status"
"What's the sprint progress?"
"Sprint summary"
```

### Report Contents

* Overall sprint progress
* Stories by status
* Epics progress
* Blocked items
* Next recommended actions

### Example Output

```text theme={null}
**Sprint Status Report**
Generated: 2026-03-04 10:30 AM

**Overall Progress**: 42% (5/12 stories done)

**By Status**:
- Done: 5 stories
- In Review: 1 story
- In Progress: 2 stories
- Ready for Dev: 1 story
- Backlog: 3 stories

**Epic Progress**:
- Epic 1 (User Management): 100% (3/3 done)
- Epic 2 (Content Management): 40% (2/5 done)
- Epic 3 (Search & Discovery): 0% (0/4 done)

**Currently In Progress**:
- 2-3-content-editing (Developer: active)
- 2-4-content-preview (Developer: active)

**Next Recommended**:
1. Review story 2-2-content-creation (in review status)
2. Start story 2-5-content-publish (ready-for-dev)
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/sprint-status/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/sprint-status/instructions.md`

***

## Correct Course Workflow

### Purpose

Manage significant changes during sprint execution. This workflow helps handle scope changes, technical pivots, and other course corrections while maintaining alignment.

### Trigger Commands

```bash theme={null}
"Correct course"
"Propose sprint change"
"We need to change direction"
```

### When to Use

Use this workflow when:

* Requirements need significant changes
* Technical approach needs pivoting
* Dependencies change unexpectedly
* Priorities need reordering
* Scope needs adjustment

### Workflow Process

1. **Change Identification** - What needs to change?
2. **Impact Analysis** - What's affected?
3. **Proposal Generation** - Document the change
4. **Stakeholder Review** - Get approval
5. **Artifact Updates** - Update PRD, epics, stories
6. **Sprint Adjustment** - Replan affected work

### Inputs

* Proposed change description
* All planning artifacts (PRD, Architecture, Epics)
* Current sprint status
* Project context

### Outputs

**File Location**: `{planning_artifacts}/sprint-change-proposal-{date}.md`

**Proposal Includes**:

* Change description
* Rationale and context
* Impact analysis (stories, epics, architecture)
* Updated requirements
* Revised timeline
* Recommendations

### Example Invocation

```text theme={null}
User: "Correct course - we need to add real-time collaboration features"

AI: "Analyzing change impact for real-time collaboration...

Loading current state...
✓ Sprint status: 5/12 stories done
✓ Current epic: 2 (Content Management)

**Impact Analysis**:

Affected Artifacts:
- PRD: Need to add real-time requirements
- Architecture: Need WebSocket/real-time decision
- Epic 2: Need to add collaboration stories
- Epic 3: Search needs to account for multi-user

Affected Stories:
- 2-3-content-editing (in-progress): Major changes
- 2-4-content-preview (in-progress): Moderate changes
- 3-1-search-index (backlog): Minor changes

Estimated New Work: 3 stories, ~13 points

Generating change proposal...
Created: {planning_artifacts}/sprint-change-proposal-2026-03-04.md

Recommendation: 
- Pause stories 2-3 and 2-4
- Update architecture with real-time decision
- Create new epic: Real-time Collaboration
- Replan sprint with new priorities"
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/correct-course/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/correct-course/instructions.md`
* Checklist: `src/bmm/workflows/4-implementation/correct-course/checklist.md`

***

## Retrospective Workflow

### Purpose

Conduct epic retrospectives to capture learnings and improve processes. This workflow helps teams reflect on completed epics and plan improvements.

### Trigger Commands

```bash theme={null}
"Run retrospective for epic [epic-number]"
"Epic 1 retrospective"
"Retrospective"
```

### Retrospective Format

Follows the classic retrospective structure:

1. **What went well?** - Celebrate successes
2. **What didn't go well?** - Identify problems
3. **What did we learn?** - Extract insights
4. **What will we change?** - Action items

### Workflow Process

1. **Epic Selection** - Choose completed epic
2. **Data Gathering** - Review epic stories and outcomes
3. **Facilitated Discussion** - Guide retrospective conversation
4. **Action Items** - Identify concrete improvements
5. **Documentation** - Record learnings
6. **Status Update** - Mark retrospective as done

### Inputs

* Completed epic and its stories
* Sprint status history
* User's observations and feedback

### Outputs

**File Location**: `{implementation_artifacts}/retrospective-epic-{num}-{date}.md`

**Document Includes**:

* Epic summary
* What went well
* What didn't go well
* Key learnings
* Action items for next epic
* Metrics (velocity, completion time, etc.)

### Example Invocation

```text theme={null}
User: "Run retrospective for epic 1"

AI: "Starting retrospective for Epic 1: User Management

**Epic Summary**:
- Stories Completed: 3/3
- Total Points: 13
- Duration: 5 days
- Status: Done

Let's reflect on this epic.

**What went well?**
What successes should we celebrate?"

User: "Authentication was smoother than expected, good architecture decisions"

AI: "Great! 

**What didn't go well?**
What challenges did we face?"

User: "Profile settings took longer than estimated, unclear requirements"

AI: "I see. 

**What did we learn?**
What insights can we apply to future epics?"

User: "Need better UX specs for form-heavy features"

AI: "Excellent insight.

**Action Items**:
Based on learnings, I recommend:
1. Add detailed form specs to UX design before starting Epic 2
2. Allocate 20% buffer for form-heavy stories
3. Review acceptance criteria completeness in story creation

Shall I document these action items? [Y/n]"
```

### Source Files

* Workflow: `src/bmm/workflows/4-implementation/retrospective/workflow.yaml`
* Instructions: `src/bmm/workflows/4-implementation/retrospective/instructions.md`

***

## Implementation Best Practices

### Sprint Flow

1. **Sprint Planning** - Generate sprint-status.yaml
2. **Story Creation** - Create story files as needed
3. **Development** - Implement stories
4. **Review** - Code review each story
5. **Retrospective** - Review epic when done
6. **Repeat** - Continue through epics

### Status Management

* Let workflows manage status automatically
* Re-run sprint planning to refresh status detection
* Use correct course for significant changes
* Keep sprint-status.yaml as single source of truth

### Team Collaboration

* Fresh AI context recommended for code review
* Use different LLM for reviewer vs. developer
* Document learnings in retrospectives
* Apply action items to next epic

## Next Steps

* [Quick Flow](/workflows/quick-flow) - For small changes during implementation
* [Document Project](/workflows/document-project) - Generate project documentation