1759 lines
46 KiB
Markdown
1759 lines
46 KiB
Markdown
# 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=<generate-random-string>
|
||
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
|
||
<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:**
|
||
|
||
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)
|