46 KiB

Raw Blame History

BMM Implementation Workflows (Phase 4)

Reading Time: ~20 minutes

Overview

Phase 4 (Implementation) workflows manage the iterative sprint-based development cycle. This phase uses a story-centric workflow where each story moves through a defined lifecycle from creation to completion.

Key principle: One story at a time, move it through the entire lifecycle before starting the next.

Quick Reference

Workflow	Agent	Duration	Purpose
sprint-planning	SM	30-60 min	Initialize sprint tracking file
epic-tech-context	SM	15-30 min/epic	Epic-specific technical guidance
create-story	SM	10-20 min	Create next story from epics
story-context	PM	10-15 min	Assemble dynamic story context
dev-story	DEV	2-8 hours	Implement story with tests
code-review	DEV	30-60 min	Senior dev review of completed story
correct-course	SM	30-90 min	Handle mid-sprint changes
retrospective	SM	60-90 min	Post-epic review and lessons
workflow-status	All	2-5 min	Check "what should I do now?"
document-project	Analyst	1-3 hours	Document brownfield projects

Understanding the Implementation Phase

Story Lifecycle

Every story moves through this lifecycle:

1. TODO (Not Started)
   ↓ [sprint-planning creates status file]

2. IN PROGRESS (Being Implemented)
   ↓ [create-story generates story file]
   ↓ [story-context assembles context]
   ↓ [dev-story implements with tests]

3. READY FOR REVIEW (Implementation Complete)
   ↓ [code-review validates quality]

4. DONE (Accepted)
   ↓ [story-done marks complete]
   ↓ [Repeat for next story]

Sprint-Based Development Model

Sprint Structure:

Sprint 0 (Planning): Phases 1-3 complete
Sprint 1: Epic 1 stories (P0/P1)
Sprint 2: Epic 2 stories (P0/P1)
Sprint 3: Epic 3+ stories (P0/P1)
Sprint N: P2/P3 stories, polish

Typical Sprint Timeline:

Week 1-2: Epic 1 implementation
Week 3-4: Epic 2 implementation
Week 5-6: Epic 3 implementation
Week 7+: Refinement, P2/P3, polish

Multi-Agent Workflow

Phase 4 involves coordination between agents:

Agent	Primary Workflows	Role
SM	sprint-planning, epic-tech-context, create-story, correct-course, retrospective	Orchestration, tracking
PM	story-context	Context assembly
DEV	dev-story, code-review	Implementation, quality
Analyst	document-project	Documentation (brownfield)

sprint-planning

Purpose

Generate and manage the sprint status tracking file for Phase 4 implementation, extracting all epics and stories from epic files and tracking their status through the development lifecycle.

Agent: SM (Scrum Master) Phase: 4 (Implementation) Required: Yes (first step of Phase 4) Typical Duration: 30-60 minutes

When to Use

Run once at the start of Phase 4 after solutioning-gate-check passes (or after PRD for Level 0-2).

Trigger Points:

solutioning-gate-check PASS (Level 3-4)
PRD complete (Level 2)
tech-spec complete (Level 0-1)

Purpose of Sprint Planning

Creates:

Sprint status tracking file (sprint-status.yaml)
Story queue (ordered by priority and dependencies)
Epic-level tracking
Sprint assignments

Enables:

workflow-status to answer "what's next?"
Progress tracking throughout implementation
Dependency management
Velocity measurement

Process Overview

Phase 1: Context Loading (Step 1)

Load epics.md
Load individual epic files
Load architecture.md (if exists)
Extract all stories

Phase 2: Story Extraction (Steps 2-3)

Parse stories from epic files
Extract acceptance criteria
Identify priorities (P0/P1/P2/P3)
Extract dependencies

Phase 3: Sprint Assignment (Steps 4-5)

Group stories by epic
Sequence by priority and dependencies
Assign to sprints (Sprint 1, 2, 3, etc.)
Calculate sprint capacity estimates

Phase 4: Status File Creation (Step 6)

Generate sprint-status.yaml
Initialize all stories as TODO
Document sprint plan
Save to output folder

Inputs

Required:

epics.md
Epic files (epic-1-.md, epic-2-.md, etc.)

Optional:

architecture.md (for technical dependencies)
Team velocity data (for sprint sizing)

Outputs

Primary Output: sprint-status.yaml

File Structure:

metadata:
  project_name: 'E-Commerce Platform'
  total_epics: 3
  total_stories: 24
  current_sprint: 1
  sprint_start_date: '2025-11-02'

sprints:
  sprint_1:
    name: 'Epic 1: Authentication'
    start_date: '2025-11-02'
    end_date: '2025-11-15'
    capacity_points: 40
    stories:
      - id: '1.1'
        title: 'User can register with email'
        status: 'TODO'
        priority: 'P0'
        epic: 1
        estimated_hours: 8
        assigned_to: null
        dependencies: []
      - id: '1.2'
        title: 'User can login with email'
        status: 'TODO'
        priority: 'P0'
        epic: 1
        estimated_hours: 6
        assigned_to: null
        dependencies: ['1.1']

  sprint_2:
    name: 'Epic 2: Product Catalog'
    # ...

story_queue:
  - '1.1' # No dependencies, P0
  - '1.2' # Depends on 1.1, P0
  - '1.3' # Depends on 1.2, P0
  # ...

epics:
  - id: 1
    name: 'Authentication'
    total_stories: 8
    completed_stories: 0
    status: 'IN_PROGRESS'
  - id: 2
    name: 'Product Catalog'
    total_stories: 10
    completed_stories: 0
    status: 'TODO'
  - id: 3
    name: 'Shopping Cart'
    total_stories: 6
    completed_stories: 0
    status: 'TODO'

Example Scenario

Input: 3 epics with 24 total stories

Output:

Sprint 1: Epic 1 (8 stories, 2 weeks)
Sprint 2: Epic 2 (10 stories, 2 weeks)
Sprint 3: Epic 3 (6 stories, 1 week)

Story Queue:

Story 1.1 (P0, no deps) → Start here
Story 1.2 (P0, deps: 1.1)
Story 1.3 (P0, deps: 1.2)
Story 2.1 (P0, no deps) → Can parallelize with 1.x ...

solutioning-gate-check (Phase 3) - Must PASS before sprint-planning
workflow-status - Uses sprint-status.yaml to answer "what's next?"
create-story - Uses story_queue to determine next story

epic-tech-context

Purpose

Generate epic-specific technical context document that provides implementation guidance, patterns, and technical decisions for a single epic. Bridges architecture and story implementation.

Agent: SM (Scrum Master) Phase: 4 (Implementation) Required: Optional (recommended for Level 3-4) Typical Duration: 15-30 minutes per epic

When to Use

Run once per epic before starting epic stories.

Trigger Points:

Before implementing first story of an epic
When starting a new epic in a sprint
When architecture guidance is needed

Skip if:

Level 0-1 (no epics)
Level 2 (simple epics, architecture is straightforward)

Purpose of Epic Tech Context

Provides:

Epic-specific technical guidance
Code patterns and examples
Integration points
Testing strategy for epic
Epic-level architectural decisions

Prevents:

Re-reading entire architecture.md for each story
Inconsistent implementations within epic
Missing epic-level integration patterns

Process Overview

Phase 1: Context Loading (Step 1)

Load architecture.md
Load epic file (epic-X-*.md)
Load sprint-status.yaml
Identify epic stories

Phase 2: Technical Extraction (Steps 2-4)

Extract relevant architecture sections for epic
Identify epic-specific ADRs
Determine code patterns
Identify integration points

Phase 3: Implementation Guidance (Steps 5-7)

Define directory structure for epic
Specify testing approach
Provide code examples
Document epic-level constants/config

Phase 4: Documentation (Step 8)

Generate epic-tech-context.md
Save to output folder
Update sprint-status.yaml with context path

Inputs

Required:

architecture.md
epic-X-*.md (specific epic file)
sprint-status.yaml

Outputs

Primary Output: epic-{N}-tech-context.md

Document Structure:

Epic Overview
Relevant Architecture Decisions
- ADRs applicable to this epic
- Technology selections
Directory Structure
- Files to create/modify
- Module organization
Code Patterns
- Epic-specific patterns
- Code examples
Integration Points
- APIs to create/consume
- Database interactions
- Third-party services
Testing Strategy
- Test levels for epic (E2E, API, Unit)
- Test fixtures needed
- Mock strategies
Configuration
- Environment variables
- Feature flags
- Constants

Example: Epic 1 Tech Context (Authentication)

# Epic 1 Tech Context: Authentication

## Architecture Decisions

**ADR-001: Use NextAuth.js**

- All stories in this epic use NextAuth.js
- Database adapter: PostgreSQL (via Prisma)
- Session strategy: Database sessions (not JWT)

**ADR-003: Password Security**

- Use bcrypt with 12 rounds
- Minimum password length: 8 characters
- Require: uppercase, lowercase, number

## Directory Structure

/pages/api/auth/ [...nextauth].ts # Story 1.1 register.ts # Story 1.2 verify-email.ts # Story 1.3

/lib/auth/ validation.ts # Story 1.2 email-service.ts # Story 1.3

/prisma/schema.prisma User model # Story 1.1 Session model # Story 1.1


## Code Patterns

**User Registration (Story 1.2):**
```typescript
// /lib/auth/validation.ts
export const validatePassword = (password: string) => {
  const minLength = 8;
  const hasUppercase = /[A-Z]/.test(password);
  const hasLowercase = /[a-z]/.test(password);
  const hasNumber = /\d/.test(password);

  if (password.length < minLength) {
    throw new Error('Password too short');
  }
  // ...
};

Integration Points

Database:

Create User table with Prisma migration (Story 1.1)
Create Session table with Prisma migration (Story 1.1)

Third-Party Services:

SendGrid for email verification (Story 1.3)
- API Key: SENDGRID_API_KEY env variable
- From email: no-reply@example.com

Testing Strategy

E2E Tests:

Story 1.1: Full registration flow
Story 1.2: Login flow
Story 1.3: Email verification flow

API Tests:

All /api/auth/* endpoints
Error cases: duplicate email, invalid password

Unit Tests:

validation.ts functions
email-service.ts functions

Test Fixtures:

Create tests/fixtures/auth.fixture.ts
Provide: createTestUser(), loginTestUser(), cleanupTestUser()

Configuration

Environment Variables:

DATABASE_URL=postgresql://...
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=<generate-random-string>
SENDGRID_API_KEY=SG.xxx

Constants:

// /lib/auth/constants.ts
export const PASSWORD_MIN_LENGTH = 8;
export const BCRYPT_ROUNDS = 12;
export const EMAIL_VERIFICATION_EXPIRY_HOURS = 24;


### Related Workflows
- **architecture** (Phase 3) - Source of technical guidance
- **story-context** - Uses epic-tech-context as input
- **dev-story** - References epic-tech-context during implementation

---

## create-story

### Purpose
Create the next user story markdown from epics/PRD and architecture, using a standard template and saving to the stories folder.

**Agent:** SM (Scrum Master)
**Phase:** 4 (Implementation)
**Required:** Yes (for each story)
**Typical Duration:** 10-20 minutes per story

### When to Use
Run **before implementing each story** to generate story file.

**Trigger Points:**
- Before starting work on a new story
- When story_queue identifies next story
- After completing previous story

### Process Overview

**Phase 1: Story Selection (Step 1)**
- Load sprint-status.yaml
- Read story_queue
- Select next story (first in queue with dependencies met)

**Phase 2: Story Extraction (Steps 2-3)**
- Load epic file for selected story
- Extract story details
- Extract acceptance criteria
- Extract dependencies

**Phase 3: Context Gathering (Steps 4-5)**
- Load PRD/GDD for product context
- Load architecture for technical context
- Load epic-tech-context (if exists)

**Phase 4: Story File Creation (Step 6)**
- Generate story markdown using template
- Include acceptance criteria
- Include technical notes
- Save to stories/ folder

**Phase 5: Status Update (Step 7)**
- Update sprint-status.yaml
- Move story from TODO → IN PROGRESS
- Update workflow-status.md

### Inputs
Required:
- sprint-status.yaml (story queue)
- epic-X-*.md (for story details)
- PRD.md or GDD.md

Optional:
- architecture.md
- epic-tech-context.md

### Outputs

**Primary Output:** `story-{epic}.{num}-{title}.md`

**Story File Structure:**
```markdown
# Story {Epic}.{Num}: {Title}

**Epic:** {Epic Name}
**Priority:** P0/P1/P2/P3
**Status:** IN PROGRESS
**Estimated Hours:** {Hours}
**Dependencies:** {Story IDs or "None"}

## User Story

As a {user type},
I want to {action},
So that {benefit}.

## Acceptance Criteria

- [ ] AC-1: {Criterion}
- [ ] AC-2: {Criterion}
- [ ] AC-3: {Criterion}

## Technical Notes

{From architecture/epic-tech-context}

## Implementation Checklist

- [ ] Read story-context.xml for dynamic context
- [ ] Implement feature code
- [ ] Write tests (unit, integration, E2E as needed)
- [ ] Update documentation
- [ ] Run tests locally
- [ ] Verify acceptance criteria
- [ ] Mark story as READY FOR REVIEW

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Tests written and passing
- [ ] Code reviewed
- [ ] Documentation updated
- [ ] No regressions in existing features

# Story 1.2: User Can Login with Email

**Epic:** Epic 1 - Authentication
**Priority:** P0
**Status:** IN PROGRESS
**Estimated Hours:** 6
**Dependencies:** Story 1.1 (User Registration)

## User Story

As a registered user,
I want to login with my email and password,
So that I can access my account.

## Acceptance Criteria

- [ ] AC-1: User can enter email and password on login page
- [ ] AC-2: Valid credentials redirect to dashboard
- [ ] AC-3: Invalid credentials show error message
- [ ] AC-4: Error message does not reveal if email exists (security)
- [ ] AC-5: Login creates session that persists across page refreshes

## Technical Notes

**From Architecture (ADR-001):**

- Use NextAuth.js with database session strategy
- Session stored in PostgreSQL via Prisma

**From Epic Tech Context:**

- Implement /pages/api/auth/[...nextauth].ts
- Use bcrypt.compare() for password validation
- Return generic error for security (don't reveal "email not found" vs "wrong password")

## Implementation Checklist

- [ ] Read story-context.xml
- [ ] Create /pages/login.tsx
- [ ] Configure NextAuth.js credentials provider
- [ ] Implement password comparison logic
- [ ] Write E2E test: Valid login → Dashboard
- [ ] Write E2E test: Invalid login → Error
- [ ] Write API test: POST /api/auth/callback/credentials
- [ ] Verify AC-1 through AC-5
- [ ] Mark READY FOR REVIEW

## Definition of Done

- [ ] Login page exists and is styled
- [ ] Valid credentials authenticate successfully
- [ ] Invalid credentials show error
- [ ] Session persists across page loads
- [ ] Tests pass (2 E2E, 3 API)
- [ ] Code reviewed

sprint-planning - Creates story_queue
story-context - Run after create-story
dev-story - Implements the story

story-context

Purpose

Assemble dynamic story context XML by pulling latest documentation and existing code/library artifacts relevant to a drafted story.

Agent: PM (Project Manager) Phase: 4 (Implementation) Required: Yes (before implementing story) Typical Duration: 10-15 minutes per story

When to Use

Run after create-story and before dev-story for each story.

Trigger Points:

Immediately after create-story generates story file
Before DEV agent starts implementation

Purpose of Story Context

Problem Without Context:

DEV agent re-reads entire PRD, architecture, epic files (100+ pages)
Slow context loading
Irrelevant information clutters thinking

Solution With Context:

PM assembles only relevant context for this story
DEV agent receives focused, story-specific information
Fast, targeted implementation

Process Overview

Phase 1: Story Loading (Step 1)

Load story file (story-{epic}.{num}-{title}.md)
Extract story ID, epic, dependencies
Extract acceptance criteria

Phase 2: Documentation Context (Steps 2-4)

Load relevant PRD/GDD sections
Load relevant architecture sections
Load epic-tech-context (if exists)
Load dependent story files

Phase 3: Code Context (Steps 5-6)

Identify existing code files related to story
Load relevant library code (models, services, utils)
Load related test files

Phase 4: Context Assembly (Step 7)

Generate story-context.xml
Organize context by type (docs, code, tests)
Include only relevant sections
Save to output folder

Inputs

Required:

story-{epic}.{num}-{title}.md

Optional (loaded as needed):

PRD.md or GDD.md
architecture.md
epic-tech-context.md
Existing codebase files

Outputs

Primary Output: story-{epic}.{num}-context.xml

XML Structure:

<story-context>
  <story id="1.2" epic="1" title="User Can Login">
    <acceptance-criteria>
      <criterion id="AC-1">User can enter email and password on login page</criterion>
      <criterion id="AC-2">Valid credentials redirect to dashboard</criterion>
      <!-- ... -->
    </acceptance-criteria>
  </story>

  <product-context>
    <section source="PRD.md" name="Authentication Requirements">
      <!-- Relevant PRD excerpt -->
    </section>
  </product-context>

  <architecture-context>
    <adr id="ADR-001" title="Use NextAuth.js">
      <!-- Full ADR content -->
    </adr>
    <section source="architecture.md" name="Authentication Architecture">
      <!-- Relevant architecture excerpt -->
    </section>
  </architecture-context>

  <epic-context>
    <section source="epic-1-tech-context.md">
      <!-- Epic-specific technical guidance -->
    </section>
  </epic-context>

  <code-context>
    <file path="/prisma/schema.prisma">
      <!-- Existing User model -->
    </file>
    <file path="/lib/auth/validation.ts">
      <!-- Existing validation functions -->
    </file>
  </code-context>

  <dependency-context>
    <story id="1.1" title="User Can Register">
      <!-- Story 1.1 summary for context -->
    </story>
  </dependency-context>
</story-context>

Example: Story 1.2 Context Assembly

Story 1.2: User Can Login

Context Assembled:

Product Context (from PRD):
- Authentication requirements section (2 pages)
- User personas: Primary user is buyer
Architecture Context (from architecture.md):
- ADR-001: Use NextAuth.js (full ADR)
- Authentication Architecture section (1 page)
Epic Context (from epic-1-tech-context.md):
- Code patterns for login
- Integration points (NextAuth.js config)
- Testing strategy
Code Context (existing files):
- /prisma/schema.prisma - User and Session models
- /lib/auth/validation.ts - Password validation (from Story 1.1)
- /pages/api/auth/[...nextauth].ts - Auth config (created in Story 1.1)
Dependency Context (Story 1.1):
- Summary: User registration creates User in DB
- Dependency: User table must exist

Result: DEV agent receives 8-10 pages of focused context instead of 100+ pages of full documentation.

create-story - Creates story file that story-context uses
dev-story - Consumes story-context.xml

dev-story

Purpose

Execute a story by implementing tasks/subtasks, writing tests, validating, and updating the story file per acceptance criteria.

Agent: DEV (Developer) Phase: 4 (Implementation) Required: Yes (for each story) Typical Duration: 2-8 hours per story (varies by complexity)

When to Use

Run after story-context to implement the story.

Trigger Points:

After story-context.xml is generated
When story status is IN PROGRESS
For each story in story_queue

Process Overview

Phase 1: Context Loading (Step 1)

Load story file
Load story-context.xml
Review acceptance criteria
Review technical notes

Phase 2: Implementation Planning (Steps 2-3)

Break story into tasks
Identify files to create/modify
Plan test strategy
Estimate implementation approach

Phase 3: Implementation (Steps 4-6)

Write code to satisfy acceptance criteria
Follow architecture decisions
Apply code patterns from epic-tech-context
Write tests (unit, integration, E2E as needed)

Phase 4: Validation (Steps 7-8)

Run tests locally
Verify all acceptance criteria met
Check for regressions
Ensure code quality

Phase 5: Documentation (Step 9)

Update story file (check off AC items)
Document any deviations
Mark story as READY FOR REVIEW
Update sprint-status.yaml

Inputs

Required:

story-{epic}.{num}-{title}.md
story-{epic}.{num}-context.xml

Outputs

Implementation code (multiple files)
Test files
Updated story file (AC checked off)
Updated sprint-status.yaml (status: READY FOR REVIEW)

Phase 1: Planning Tasks identified:

Create /pages/login.tsx (UI)
Configure NextAuth credentials provider
Implement password verification logic
Write E2E test: Valid login
Write E2E test: Invalid login
Write API test: /api/auth/callback/credentials

Phase 2: Implementation Files created/modified:

/pages/login.tsx (new)
/pages/api/auth/[...nextauth].ts (modified - add credentials provider)
/lib/auth/password.ts (new - password verification)
/tests/e2e/auth-login.spec.ts (new)
/tests/api/auth-api.spec.ts (modified - add login tests)

Phase 3: Testing

npm run test:e2e
npm run test:api
npm run test:unit

All tests pass ✅

Phase 4: Verification

AC-1: Login page exists with email/password inputs
AC-2: Valid credentials → Dashboard
AC-3: Invalid credentials → Error message
AC-4: Error message generic (security)
AC-5: Session persists across page refreshes

Phase 5: Documentation Update story file:

## Acceptance Criteria

- [x] AC-1: User can enter email and password on login page
- [x] AC-2: Valid credentials redirect to dashboard
- [x] AC-3: Invalid credentials show error message
- [x] AC-4: Error message does not reveal if email exists (security)
- [x] AC-5: Login creates session that persists across page refreshes

## Implementation Summary

Files Created:

- /pages/login.tsx
- /lib/auth/password.ts
- /tests/e2e/auth-login.spec.ts

Files Modified:

- /pages/api/auth/[...nextauth].ts
- /tests/api/auth-api.spec.ts

Tests Added:

- 2 E2E tests (valid/invalid login)
- 3 API tests (credentials endpoint)

**Status:** READY FOR REVIEW

story-context - Provides focused context
code-review - Next step after implementation
correct-course - If changes needed mid-story

code-review

Purpose

Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic-tech-context, repo docs, MCP servers for latest best-practices, and web search as fallback.

Agent: DEV (Senior Developer persona) Phase: 4 (Implementation) Required: Recommended (especially for P0/P1 stories) Typical Duration: 30-60 minutes per story

When to Use

Run after dev-story when story status is READY FOR REVIEW.

Trigger Points:

Story status: READY FOR REVIEW
Before marking story as DONE
For P0/P1 stories (required)
For P2/P3 stories (optional but recommended)

Process Overview

Phase 1: Context Loading (Step 1)

Load story file
Load story-context.xml
Load implementation files
Load test files

Phase 2: Review Criteria (Steps 2-5)

Acceptance Criteria: All AC met?
Architecture Alignment: Follows architecture decisions?
Code Quality: Readable, maintainable, follows conventions?
Test Coverage: Sufficient tests, tests passing?
Best Practices: Uses latest framework patterns?

Phase 3: Knowledge Loading (Steps 6-7)

Load repository documentation (CONTRIBUTING.md, CODE_STYLE.md)
Use MCP servers for framework best practices (if available)
Web search for latest patterns (fallback)

Phase 4: Review Execution (Steps 8-10)

Review each file changed
Identify issues (critical, high, medium, low)
Suggest improvements
Verify tests

Phase 5: Review Report (Step 11)

Generate code-review.md
Append to story file
Update sprint-status.yaml

Review Criteria

Acceptance Criteria Validation:

All AC items checked off in story file
AC validated through tests
AC validated manually (if needed)

Architecture Alignment:

Follows ADRs
Uses specified technology choices
Follows directory structure conventions
Follows code patterns from epic-tech-context

Code Quality:

Readable and maintainable
Follows repository conventions
No code smells (long functions, god classes, etc.)
Appropriate error handling
Security best practices followed

Test Coverage:

Tests exist for all AC
Tests pass locally
Edge cases covered
Tests follow framework best practices
No flaky tests

Best Practices:

Uses latest framework patterns
Avoids deprecated APIs
Performance considerations addressed
Accessibility requirements met (if applicable)

Inputs

Required:

story-{epic}.{num}-{title}.md (with READY FOR REVIEW status)
story-{epic}.{num}-context.xml
Implementation files (code)
Test files

Optional:

Repository documentation (CONTRIBUTING.md, CODE_STYLE.md)
MCP servers for best practices
Web search for latest patterns

Outputs

Primary Output: Code review appended to story file

Review Structure:

---

## Code Review - {Date}

**Reviewer:** DEV (Senior Developer)
**Status:** APPROVED / REQUEST CHANGES / APPROVED WITH COMMENTS

### Summary

{Overall assessment}

### Acceptance Criteria Validation

- [x] AC-1: Validated ✅
- [x] AC-2: Validated ✅
- [x] AC-3: Validated ✅
- [x] AC-4: Validated ✅
- [x] AC-5: Validated ✅

### Architecture Alignment

✅ Follows ADR-001 (NextAuth.js)
✅ Uses database session strategy
✅ Follows epic-tech-context patterns

### Code Quality Issues

**Critical Issues (Must Fix):**
None

**High Priority (Should Fix Before Merge):**

1. /lib/auth/password.ts:15 - Use constant for bcrypt rounds instead of magic number

   ```typescript
   // Current:
   const hash = await bcrypt.hash(password, 12);

   // Suggested:
   import { BCRYPT_ROUNDS } from './constants';
   const hash = await bcrypt.hash(password, BCRYPT_ROUNDS);
   ```

Medium Priority (Address in Follow-up):

/pages/login.tsx:42 - Consider extracting form validation to custom hook
Add JSDoc comments to public functions in /lib/auth/password.ts

Low Priority (Nice to Have):

Consider using react-hook-form for login form (reduces boilerplate)

Test Coverage

✅ E2E tests cover happy and sad paths ✅ API tests cover error cases ⚠️ Consider adding unit test for password validation edge cases

Best Practices

✅ Uses latest Next.js 14 patterns ✅ Follows React best practices ✅ Accessibility: Form has labels and error messages

Recommendation

APPROVED WITH COMMENTS - Address high priority issue #1, then merge.

Medium/low priority items can be addressed in future stories.


### Review Outcomes

**APPROVED** ✅
- All criteria met
- No critical/high issues
- Story can be marked DONE
- **Action**: Run story-done workflow

**APPROVED WITH COMMENTS** ✅⚠️
- Minor issues noted
- Suggestions for improvement
- Story can be marked DONE
- **Action**: Address comments in follow-up (optional)

**REQUEST CHANGES** ❌
- Critical or high-priority issues found
- Changes required before merge
- Story remains READY FOR REVIEW
- **Action**: Fix issues, re-request review

### Related Workflows
- **dev-story** - Implementation that's being reviewed
- **story-done** - Next step if approved
- **correct-course** - If significant changes needed

---

## correct-course

### Purpose
Navigate significant changes during sprint execution by analyzing impact, proposing solutions, and routing for implementation.

**Agent:** SM (Scrum Master)
**Phase:** 4 (Implementation)
**Required:** As needed
**Typical Duration:** 30-90 minutes

### When to Use
Run when **significant changes** occur mid-sprint:

**Trigger Scenarios:**
- New requirements discovered during implementation
- Architecture decision needs revision
- Story dependencies change
- External factors impact sprint (API changes, platform updates)
- Critical bug discovered requiring immediate attention

**Don't Use For:**
- Minor clarifications → Clarify in story file
- Small scope adjustments → Adjust AC in story
- Typical development blockers → Resolve within team

### Process Overview

**Phase 1: Change Analysis (Steps 1-3)**
- Identify change type (requirements, technical, external)
- Assess impact (stories, epics, architecture)
- Determine urgency (blocking, high, medium, low)

**Phase 2: Impact Assessment (Steps 4-6)**
- Stories affected
- Epics affected
- Architecture changes needed
- Timeline impact

**Phase 3: Solution Proposal (Steps 7-9)**
- **Option A**: Adjust scope (remove stories, defer features)
- **Option B**: Adjust architecture (revise decisions)
- **Option C**: Adjust timeline (extend sprint)
- **Option D**: Combination approach

**Phase 4: Decision and Routing (Steps 10-12)**
- Consult stakeholders (if needed)
- Select solution
- Route to appropriate workflow:
  - Requirements change → Update PRD → Re-run create-story
  - Architecture change → Update architecture → Re-run epic-tech-context
  - Story change → Update story file → Continue dev-story
- Update sprint-status.yaml

### Change Types

**Requirements Change:**
- New AC discovered
- AC invalidated by new information
- Feature scope expansion/reduction

**Technical Change:**
- Architecture decision no longer viable
- Technology choice needs revision
- Integration approach changed

**External Change:**
- Third-party API changed
- Platform update breaks implementation
- Regulatory requirement introduced

### Inputs
Required:
- Description of change
- Current story/epic affected
- Current sprint-status.yaml

### Outputs
- Change impact analysis document
- Updated documentation (PRD/architecture/stories)
- Updated sprint-status.yaml
- Routing recommendations

### Example: API Change Mid-Sprint

**Change:** SendGrid deprecated email API, requires migration to new API

**Impact Analysis:**
- **Stories Affected**: Story 1.3 (Email Verification) - IN PROGRESS
- **Epics Affected**: Epic 1 (Authentication)
- **Architecture Impact**: ADR-004 (Email Service) needs revision
- **Timeline Impact**: +1 day (API migration work)

**Solution Options:**

**Option A:** Continue with deprecated API, plan migration for later
- **Pros**: No sprint disruption
- **Cons**: Technical debt, API sunset in 6 months

**Option B:** Migrate to new API now
- **Pros**: No technical debt, future-proof
- **Cons**: +1 day to sprint

**Option C:** Defer email verification to next sprint
- **Pros**: No disruption to current sprint
- **Cons**: Story 1.3 incomplete, Epic 1 not done

**Decision:** Option B (Migrate now)

**Actions:**
1. Update architecture.md (ADR-004: Use SendGrid v4 API)
2. Update epic-1-tech-context.md (new email patterns)
3. Update Story 1.3 acceptance criteria (new API endpoints)
4. Continue dev-story with new approach
5. Extend sprint by 1 day

### Related Workflows
- **architecture** - May need updates
- **create-story** - May need to create new stories
- **sprint-planning** - May need to re-prioritize
- **retrospective** - Document learnings

---

## retrospective

### Purpose
Run after epic completion to review overall success, extract lessons learned, and explore if new information emerged that might impact the next epic.

**Agent:** SM (Scrum Master)
**Phase:** 4 (Implementation)
**Required:** Recommended (after each epic)
**Typical Duration:** 60-90 minutes

### When to Use
Run **after completing an epic** (all stories DONE).

**Trigger Points:**
- Epic status: DONE
- All epic stories completed
- Before starting next epic
- Before final release (after all epics)

### Process Overview

**Phase 1: Data Gathering (Steps 1-3)**
- Load sprint-status.yaml
- Load completed story files
- Load code-review feedback
- Gather metrics (velocity, story cycle time)

**Phase 2: Review Execution (Steps 4-7)**
- **What Went Well**: Successes and wins
- **What Didn't Go Well**: Challenges and issues
- **Lessons Learned**: Actionable insights
- **Process Improvements**: Changes for next epic

**Phase 3: Technical Insights (Steps 8-10)**
- Architecture decisions review
- Technology choices validation
- Code quality assessment
- Test coverage and quality

**Phase 4: Planning Insights (Steps 11-13)**
- Estimation accuracy
- Requirements clarity
- Dependency management
- Scope changes

**Phase 5: Action Items (Step 14)**
- Process changes for next epic
- Architecture updates needed
- Documentation improvements
- Training or knowledge gaps

### Inputs
Required:
- sprint-status.yaml (epic completion data)
- Completed story files
- code-review feedback

Optional:
- Team velocity data
- CI/CD metrics
- Bug reports

### Outputs

**Primary Output:** `retrospective-epic-{N}-{date}.md`

**Document Structure:**
1. Epic Summary
   - Stories completed
   - Time taken
   - Velocity achieved
2. What Went Well
3. What Didn't Go Well
4. Lessons Learned
5. Technical Insights
6. Planning Insights
7. Action Items for Next Epic
8. Process Improvements

### Example: Epic 1 Retrospective

```markdown
# Retrospective: Epic 1 - Authentication

**Date:** 2025-11-15
**Duration:** 2 weeks (planned), 2.5 weeks (actual)
**Stories Completed:** 8/8
**Velocity:** 48 points (target: 60 points)

## What Went Well

✅ **Architecture decisions solid**
- NextAuth.js choice worked well
- Database sessions simpler than JWT

✅ **Test coverage excellent**
- All stories have E2E + API tests
- No critical bugs in production

✅ **Team collaboration strong**
- Code reviews thorough
- Knowledge sharing effective

## What Didn't Go Well

❌ **Estimation inaccurate**
- Stories took 20% longer than estimated
- Story 1.3 (Email Verification) took 2 days instead of 1

❌ **Third-party integration surprise**
- SendGrid API deprecation discovered mid-sprint
- Required correct-course workflow

❌ **Testing setup overhead**
- Test fixtures took longer than expected to set up
- Should have created fixtures earlier

## Lessons Learned

💡 **Buffer time for integrations**
- Add 25% buffer to stories with third-party APIs
- Research API stability before committing

💡 **Test fixtures upfront**
- Create test fixtures in first story of epic
- Reuse across all stories

💡 **Architecture review cadence**
- Mid-epic architecture check-in would have caught issues earlier

## Technical Insights

**Architecture:**
- ADR-001 (NextAuth.js) validated ✅
- ADR-004 (SendGrid) needed revision (v3 → v4)

**Code Quality:**
- Average code-review score: 8.5/10
- No critical issues
- 3 high-priority issues (all addressed)

**Test Coverage:**
- E2E: 95% of critical paths
- API: 100% of endpoints
- Unit: 85% of business logic

## Planning Insights

**Estimation Accuracy:**
- Estimated: 60 points
- Actual: 72 points
- Variance: +20%
- **Adjustment**: Use 1.2× multiplier for next epic

**Requirements Clarity:**
- PRD was clear ✅
- Architecture was thorough ✅
- Story AC needed refinement in 2 stories

**Dependency Management:**
- Story dependencies well-sequenced
- No blocking issues

## Action Items for Epic 2

1. **Create test fixtures first** (Story 2.1)
   - Owner: DEV
   - Timeline: First story of Epic 2

2. **Add 25% buffer to integration stories**
   - Owner: SM
   - Apply in epic-2 estimates

3. **Mid-epic architecture check-in**
   - Owner: Architect
   - Schedule after 50% epic completion

4. **Research third-party API stability**
   - Owner: DEV
   - Before starting stories with external APIs

## Process Improvements

**For Next Epic:**
- ✅ Run architecture review mid-epic
- ✅ Create test fixtures in first story
- ✅ Add buffer time to estimates
- ✅ Document third-party API versions in architecture

**For Future Projects:**
- Document API stability research process
- Create reusable test fixture templates

sprint-planning - Next epic planning
architecture - May need updates from insights
create-story - Apply lessons to story creation

Utility Workflows

workflow-status

Purpose: Check "what should I do now?" for any agent.

Agent: All Duration: 2-5 minutes When to Use: Anytime you're unsure of next step

How It Works:

Loads sprint-status.yaml
Determines current phase
Identifies next workflow to run
Provides clear recommendation

Example Output:

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 README

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:

Scans codebase structure
Identifies architecture patterns
Documents technology stack
Creates reference documentation
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 README

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

Best Practices for Phase 4

1. One Story at a Time

Focus on completing stories fully before starting new ones. Don't parallelize stories unless you have multiple developers.

2. Always Run story-context

Don't skip context assembly. DEV agent performs better with focused, relevant context.

3. Write Tests First (ATDD)

For P0/P1 stories, write failing tests first (acceptance test-driven development), then implement to make them pass.

4. Code Review P0/P1 Stories

Always review critical stories. P2/P3 can be optional reviews.

5. Run Retrospectives

Don't skip retrospectives. They provide valuable insights that improve velocity in subsequent epics.

6. Use workflow-status

When unsure what to do next, run workflow-status. It will guide you.

7. Document Deviations

If you deviate from architecture or PRD, document why in story file.

Common Anti-Patterns

❌ Starting Multiple Stories Simultaneously

"Let's parallelize 5 stories to go faster." → Result: Context switching, incomplete stories, harder to track

❌ Skipping story-context

"The DEV agent can just read the full PRD." → Result: Slow context loading, irrelevant info, slower implementation

❌ No Code Reviews

"Code reviews slow us down, skip them." → Result: Technical debt, inconsistent quality, bugs in production

❌ Skipping Retrospectives

"We're too busy shipping, no time for retros." → Result: Repeat mistakes, no process improvement, lower velocity

✅ Correct Approach

Focus on one story at a time
Always assemble story context
Review P0/P1 stories
Run retrospectives after epics
Use workflow-status for guidance

Summary

Phase 4 Implementation follows a story-centric workflow:

Workflow	Purpose	Frequency
sprint-planning	Initialize tracking	Once at start
epic-tech-context	Technical guidance	Once per epic
create-story	Generate story file	Per story
story-context	Assemble context	Per story
dev-story	Implement story	Per story
code-review	Review quality	Per story (P0/P1)
correct-course	Handle changes	As needed
retrospective	Learn and improve	After each epic

Key Takeaway: Implementation is iterative and incremental. Move one story through its full lifecycle before starting the next. Use retrospectives to continuously improve.

Next: Testing & QA (testarch workflows) run in parallel with implementation.

See: workflows-testing.md

46 KiB Raw Blame History Unescape Escape

BMM Implementation Workflows (Phase 4)

Overview

Quick Reference

Understanding the Implementation Phase

Story Lifecycle

Sprint-Based Development Model

Multi-Agent Workflow

sprint-planning

Purpose

When to Use

Purpose of Sprint Planning

Process Overview

Inputs

Outputs

Example Scenario

Related Workflows

epic-tech-context

Purpose

When to Use

Purpose of Epic Tech Context

Process Overview

Inputs

Outputs

Example: Epic 1 Tech Context (Authentication)

Integration Points

Testing Strategy

Configuration

Example: Story 1.2 - User Can Login

Related Workflows

story-context

Purpose

When to Use

Purpose of Story Context

Process Overview

Inputs

Outputs

Example: Story 1.2 Context Assembly

Related Workflows

dev-story

Purpose

When to Use

Process Overview

Inputs

Outputs

Example: Implementing Story 1.2 (Login)

Related Workflows

code-review

Purpose

When to Use

Process Overview

Review Criteria

Inputs

Outputs

Test Coverage

Best Practices

Recommendation

Related Workflows

Utility Workflows

workflow-status

document-project

Story Lifecycle Visualization

Best Practices for Phase 4

1. One Story at a Time

2. Always Run story-context

3. Write Tests First (ATDD)

4. Code Review P0/P1 Stories

5. Run Retrospectives

6. Use workflow-status

7. Document Deviations

Common Anti-Patterns

❌ Starting Multiple Stories Simultaneously

❌ Skipping story-context

❌ No Code Reviews

❌ Skipping Retrospectives

✅ Correct Approach

Summary

46 KiB

Raw Blame History