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:

Discovers all epic files (whole or sharded)
Extracts all epics and stories
Creates status tracking entries
Detects existing story files to set initial status
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

Story Selection - Identify story from epic
Context Gathering - Load PRD, Architecture, UX
Technical Planning - Add implementation details
File Generation - Create story markdown file
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

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

Auto-Discovery

If no story file specified, the workflow:

Reads sprint-status.yaml
Finds next story with status ready-for-dev
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

Acceptance Criteria - All criteria met?
Architecture Compliance - Follows ADRs?
Code Quality - Clean, maintainable code?
Security - No vulnerabilities?
Performance - Efficient implementation?
Testing - Adequate test coverage?
UX Alignment - Matches design specs?

Review Process

Context Loading - Load story, architecture, PRD, UX
Code Analysis - Review implementation files
Issue Identification - Find problems and risks
Severity Assessment - Categorize findings
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

Change Identification - What needs to change?
Impact Analysis - What’s affected?
Proposal Generation - Document the change
Stakeholder Review - Get approval
Artifact Updates - Update PRD, epics, stories
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:

What went well? - Celebrate successes
What didn’t go well? - Identify problems
What did we learn? - Extract insights
What will we change? - Action items

Workflow Process

Epic Selection - Choose completed epic
Data Gathering - Review epic stories and outcomes
Facilitated Discussion - Guide retrospective conversation
Action Items - Identify concrete improvements
Documentation - Record learnings
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

Sprint Planning - Generate sprint-status.yaml
Story Creation - Create story files as needed
Development - Implement stories
Review - Code review each story
Retrospective - Review epic when done
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

Get Started

Tutorials

Core Concepts

How-To Guides

Workflows

Advanced Topics

​Phase 4: Implementation Workflows

​Available Workflows

Sprint Planning

Create Story

Dev Story

Code Review

Sprint Status

Correct Course

Retrospective

​Sprint Planning Workflow

​Purpose

​Trigger Commands

​How It Works

​Status Definitions

​Inputs

​Outputs

​Example Invocation

​Source Files

​Create Story Workflow

​Purpose

​Trigger Commands

​Workflow Process

​Inputs

​Outputs

​Example Invocation

​Source Files

​Dev Story Workflow

​Purpose

​Trigger Commands

​Workflow Process

​Auto-Discovery

​Inputs

​Implementation Guidelines

​Outputs

​Example Invocation

​Source Files

​Code Review Workflow

​Purpose

​Trigger Commands

​Review Focus Areas

​Review Process

​Issue Severity Levels

​Inputs

​Outputs

​Example Invocation

​Source Files

​Sprint Status Workflow

​Purpose

​Trigger Commands

​Report Contents

​Example Output

​Source Files

​Correct Course Workflow

​Purpose

​Trigger Commands

​When to Use

​Workflow Process

​Inputs

​Outputs

​Example Invocation

​Source Files

​Retrospective Workflow

​Purpose

​Trigger Commands

​Retrospective Format

​Workflow Process

​Inputs

​Outputs

​Example Invocation

​Source Files

​Implementation Best Practices

​Sprint Flow

​Status Management

​Team Collaboration

Phase 4: Implementation Workflows

Available Workflows

Sprint Planning Workflow

Purpose

Trigger Commands

How It Works

Status Definitions

Inputs

Outputs

Example Invocation

Source Files

Create Story Workflow

Purpose

Trigger Commands

Workflow Process

Inputs

Outputs

Example Invocation

Source Files

Dev Story Workflow

Purpose

Trigger Commands

Workflow Process

Auto-Discovery

Inputs

Implementation Guidelines

Outputs

Example Invocation

Source Files

Code Review Workflow

Purpose

Trigger Commands

Review Focus Areas

Review Process

Issue Severity Levels

Inputs

Outputs

Example Invocation

Source Files

Sprint Status Workflow

Purpose

Trigger Commands

Report Contents

Example Output

Source Files

Correct Course Workflow

Purpose

Trigger Commands

When to Use

Workflow Process

Inputs

Outputs

Example Invocation

Source Files

Retrospective Workflow

Purpose

Trigger Commands

Retrospective Format

Workflow Process

Inputs

Outputs

Example Invocation

Source Files

Implementation Best Practices

Sprint Flow

Status Management

Team Collaboration

Next Steps