# 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:** ```yaml 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:** 1. Story 1.1 (P0, no deps) → Start here 2. Story 1.2 (P0, deps: 1.1) 3. Story 1.3 (P0, deps: 1.2) 4. Story 2.1 (P0, no deps) → Can parallelize with 1.x ... ### Related Workflows - **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:** 1. Epic Overview 2. Relevant Architecture Decisions - ADRs applicable to this epic - Technology selections 3. Directory Structure - Files to create/modify - Module organization 4. Code Patterns - Epic-specific patterns - Code examples 5. Integration Points - APIs to create/consume - Database interactions - Third-party services 6. Testing Strategy - Test levels for epic (E2E, API, Unit) - Test fixtures needed - Mock strategies 7. Configuration - Environment variables - Feature flags - Constants ### Example: Epic 1 Tech Context (Authentication) ```markdown # 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= SENDGRID_API_KEY=SG.xxx ``` **Constants:** ```typescript // /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 ```` ### Example: Story 1.2 - User Can Login ```markdown # 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 ``` ### Related Workflows - **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:** ```xml User can enter email and password on login page Valid credentials redirect to dashboard
``` ### Example: Story 1.2 Context Assembly **Story 1.2: User Can Login** **Context Assembled:** 1. **Product Context** (from PRD): - Authentication requirements section (2 pages) - User personas: Primary user is buyer 2. **Architecture Context** (from architecture.md): - ADR-001: Use NextAuth.js (full ADR) - Authentication Architecture section (1 page) 3. **Epic Context** (from epic-1-tech-context.md): - Code patterns for login - Integration points (NextAuth.js config) - Testing strategy 4. **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) 5. **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. ### Related Workflows - **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) ### Example: Implementing Story 1.2 (Login) **Phase 1: Planning** Tasks identified: 1. Create /pages/login.tsx (UI) 2. Configure NextAuth credentials provider 3. Implement password verification logic 4. Write E2E test: Valid login 5. Write E2E test: Invalid login 6. 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** ```bash npm run test:e2e npm run test:api npm run test:unit ``` All tests pass ✅ **Phase 4: Verification** - [x] AC-1: Login page exists with email/password inputs - [x] AC-2: Valid credentials → Dashboard - [x] AC-3: Invalid credentials → Error message - [x] AC-4: Error message generic (security) - [x] AC-5: Session persists across page refreshes **Phase 5: Documentation** Update story file: ```markdown ## 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 ``` ### Related Workflows - **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:** ````markdown --- ## 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):** 1. /pages/login.tsx:42 - Consider extracting form validation to custom hook 2. Add JSDoc comments to public functions in /lib/auth/password.ts **Low Priority (Nice to Have):** 1. 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 ```` ### Related Workflows - **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:** 1. Loads sprint-status.yaml 2. Determines current phase 3. Identifies next workflow to run 4. 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](../workflows/workflow-status/README.md) --- ### document-project **Purpose:** Analyze and document brownfield projects by scanning codebase, architecture, and patterns. **Agent:** Analyst **Duration:** 1-3 hours **When to Use:** Brownfield projects without documentation **How It Works:** 1. Scans codebase structure 2. Identifies architecture patterns 3. Documents technology stack 4. Creates reference documentation 5. Generates PRD-like document from existing code **Output:** `project-documentation-{date}.md` **When to Run:** - Before starting work on legacy project - When inheriting undocumented codebase - Creating onboarding documentation See: [document-project README](../workflows/document-project/README.md) --- ## Story Lifecycle Visualization ``` ┌─────────────────────────────────────────────────────────────┐ │ PHASE 4: IMPLEMENTATION (Iterative Story Lifecycle) │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────┐ │ Sprint Planning │ → Creates sprint-status.yaml └────────┬────────┘ Defines story queue │ ├──────────────────────────────────────────┐ │ │ ▼ │ ┌─────────────────────┐ │ │ Epic Tech Context │ → Optional per epic │ │ (Once per epic) │ Provides technical │ └─────────────────────┘ guidance │ │ │ ▼ │ ┌─────────────────────────────────────────────────┤ │ FOR EACH STORY IN QUEUE: │ ├─────────────────────────────────────────────────┤ │ │ ▼ │ ┌─────────────────┐ │ │ Create Story │ → Generates story file │ │ (TODO → IN PROGRESS) │ └────────┬────────┘ │ │ │ ▼ │ ┌─────────────────┐ │ │ Story Context │ → Assembles focused context │ └────────┬────────┘ │ │ │ ▼ │ ┌─────────────────┐ │ │ Dev Story │ → Implements + tests │ │ (IN PROGRESS) │ │ └────────┬────────┘ │ │ │ ▼ │ ┌─────────────────┐ │ │ Code Review │ → Senior dev review │ │ (IN PROGRESS → │ │ │ READY FOR REVIEW) │ └────────┬────────┘ │ │ │ ┌────┴────┐ │ │ Result? │ │ └────┬────┘ │ │ │ ┌────┼────────────────────┐ │ │ │ │ │ ▼ ▼ ▼ │ APPROVED APPROVED REQUEST │ WITH COMMENTS CHANGES │ │ │ │ │ └─────────┴───────────────────┘ │ │ │ ▼ │ ┌─────────────────┐ │ │ Story Done │ → READY FOR REVIEW → DONE│ └────────┬────────┘ │ │ │ ├─────────────────────────────────────┘ │ More stories? │ ▼ ┌────────────────┐ │ Epic Complete? │ └────────┬───────┘ │ ┌────┼────┐ │ │ Yes No │ └──> Continue to next story │ ▼ ┌─────────────────┐ │ Retrospective │ → Review epic, lessons learned └─────────────────┘ │ ▼ All epics done? │ Yes → PROJECT COMPLETE ``` --- ## 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](./workflows-testing.md)