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

Sprint Planning

Generate sprint status tracking from epics

Create Story

Create detailed story specification files

Dev Story

Implement stories following specifications

Code Review

Perform adversarial code reviews

Sprint Status

Track sprint progress and story states

Correct Course

Manage sprint changes and course corrections

Retrospective

Conduct epic retrospectives

---

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

"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:

# 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

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

"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:

---
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

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

"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

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

"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

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

"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

**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

"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

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

"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

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 - For small changes during implementation
• Document Project - Generate project documentation