Development Phase Guide

Complete guide to the development phase of BMad Method. Use this phase to implement features with complete context-engineered stories.

Platform: Desktop IDEs (Cursor, Claude Code, Windsurf, etc.) Duration: Ongoing throughout development Input: Sharded PRD and Architecture from planning phase Output: Implemented code, updated stories, QA validations

Overview

Development phase is entirely story-driven. Stories contain ALL implementation context, eliminating the need to re-read PRD or architecture. SM creates stories, Dev implements, QA reviews - repeat until complete.

Prerequisites

• Planning phase complete with sharded documents
• .bmad-core/ installed in project
• IDE configured (Cursor, Claude Code, or Windsurf)
• Agents loaded in IDE

Phase Structure

SM (Story Creation) → Dev (Implementation) → QA (Review)
                            ↓                     ↓
                      [if QA FAIL/CONCERNS]
                            ↓
                      Dev (Address Feedback)

Development Cycle

Step 1: Load Development Agents

Option A: Load Individual Agents

• Reference .bmad-core/agents/sm.md, .bmad-core/agents/dev.md, .bmad-core/agents/qa.md in IDE

Option B: Load Team

• Load .bmad-core/agent-teams/team-ide-minimal.yaml if IDE supports

Option C: Configure IDE Rules

• Cursor: Reference in .cursorrules
• Claude Code: Configure in .claude/
• Windsurf: Reference in .windsurfrules

Step 2: Create First Story (Scrum Master)

*agent sm
*draft

SM Workflow:

1. Loads Configuration: Reads .bmad-core/core-config.yaml
2. Identifies Next Story: Scans docs/stories/ for completed stories, finds next from PRD
3. Gathers Story Requirements: Reads from sharded PRD (docs/prd/epic-X.md)
4. Gathers Architecture Context:
   • All Stories: tech-stack, unified-project-structure, coding-standards, testing-strategy
   • Backend Stories: data-models, database-schema, backend-architecture, rest-api-spec
   • Frontend Stories: frontend-architecture, components, core-workflows
5. Includes Previous Learnings: Reads last completed story for patterns
6. Creates Story File: Populates story template with complete context

Story Structure:

# Epic 1.1: User Authentication

**Status**: Draft

## Story
As a user, I want to register an account, so that I can access the application.

## Acceptance Criteria
1. User can register with email and password
2. Email validation performed
3. Password strength enforced (min 8 characters, 1 uppercase, 1 number)
4. Confirmation email sent
5. User redirected to dashboard after registration

## Tasks
- [ ] Task 1: Create user model
  - [ ] Subtask 1.1: Define User schema
  - [ ] Subtask 1.2: Add validation rules
  - [ ] Subtask 1.3: Create migration
- [ ] Task 2: Implement registration endpoint
  - [ ] Subtask 2.1: Create POST /api/register route
  - [ ] Subtask 2.2: Add validation middleware
  - [ ] Subtask 2.3: Hash password with bcrypt
- [ ] Task 3: Write tests
  - [ ] Subtask 3.1: Unit tests for User model
  - [ ] Subtask 3.2: Integration tests for registration endpoint

## Dev Notes

[Source: docs/architecture/tech-stack.md#backend-framework]
Use Express.js for API routes. Use bcrypt for password hashing.

[Source: docs/architecture/data-models.md#user-model]
User model should include: id, email, password (hashed), createdAt, updatedAt.

[Source: docs/architecture/rest-api-spec.md#authentication]
POST /api/register expects { email: string, password: string }
Returns { user: User, token: string }

[Source: docs/stories/1.0.setup.md#lessons-learned]
Database connection already configured in config/database.js.

### Testing
Location: tests/integration/auth.test.js
Framework: Jest with Supertest
Requirements: Test successful registration, invalid email, weak password, duplicate email

## Dev Agent Record
*(Dev updates this section only)*

## QA Review
*(QA updates this section only)*

Output: docs/stories/1.1.user-authentication.md with complete context

Step 3: Implement Story (Developer)

*agent dev
*develop-story

Dev Workflow:

1. Loads Story: Reads story file (contains ALL needed context)
2. Reads First Task: Identifies first unchecked task
3. Implements Task and Subtasks: Writes code for task
4. Writes Tests: Creates test coverage
5. Runs Validations: Executes linter, tests, standards check
6. Updates Checkboxes: Marks [x] when ALL validations pass
7. Updates File List: Adds created/modified files to story
8. Repeats: Moves to next task until all complete
9. Updates Dev Agent Record: Documents implementation approach

Critical Dev Rules:

• ✅ Story contains ALL info - never load PRD/architecture directly
• ✅ ONLY update Dev Agent Record section
• ✅ Never modify: Status, Story, Acceptance Criteria, Dev Notes, Testing
• ✅ Update: Task checkboxes, Dev Agent Record, File List, Change Log
• ✅ Follow develop-story workflow exactly

Dev Agent Record Updates:

## Dev Agent Record

**Agent Model Used**: claude-sonnet-4

**Debug Log**: .ai/debug-log.md#story-1.1

**Completion Notes**:
- Implemented User model with Sequelize ORM
- Added bcrypt hashing with salt rounds = 10
- Created registration endpoint with validation middleware
- Implemented email validation using validator.js
- Added comprehensive test suite with 85% coverage

**File List**:
- Created: src/models/User.js
- Created: src/routes/auth.js
- Created: src/middleware/validation.js
- Created: tests/integration/auth.test.js
- Modified: src/app.js (added auth routes)

**Change Log**:
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| 2024-01-15 | 1.0 | Initial implementation | Dev Agent |

Step 4: QA Review (QA Engineer)

*agent qa
*review

QA Workflow:

1. Loads Story: Reads story file
2. Reviews Implementation: Checks all tasks completed
3. Verifies Acceptance Criteria: Each criterion met
4. Reviews Code Quality: Against architecture coding standards
5. Checks Test Coverage: Adequate coverage (target: 80%+)
6. Validates Architecture: Follows architecture patterns
7. Assesses NFRs: Performance, security, maintainability

Optional QA Tasks:

*test-design              # Design test scenarios
*trace                    # Requirements traceability
*risk-profile             # Risk assessment
*nfr-assess               # Non-functional requirements validation

Step 5: Quality Gate Decision

*agent qa
*gate

Gate Decisions:

PASS: All quality criteria met, ready for production

## QA Review

**Gate Decision**: PASS

**Rationale**:
- All acceptance criteria satisfied
- Test coverage: 85% (target: 80%)
- Code quality standards met
- No security vulnerabilities found
- Performance requirements met

**Status Update**: Done

CONCERNS: Issues found but not blocking

## QA Review

**Gate Decision**: CONCERNS

**Rationale**:
- Missing input validation on optional email field
- Test coverage: 75% (target: 80%)
- Can proceed with monitoring

**Issues**:
1. Add validation for optional profile email field
2. Increase test coverage to 80%

**Status Update**: Review (for minor fixes)

FAIL: Critical issues, must address

## QA Review

**Gate Decision**: FAIL

**Rationale**:
- Security vulnerability: Password stored in plain text
- Missing authentication middleware
- No error handling for failed registration

**Critical Issues**:
1. **SECURITY**: Passwords must be hashed with bcrypt (not done)
2. **MISSING**: Authentication middleware not implemented
3. **ERROR HANDLING**: No try-catch blocks, app crashes on errors

**Status Update**: InProgress (Dev must fix)

WAIVED: Issues waived by stakeholder

## QA Review

**Gate Decision**: WAIVED

**Rationale**:
- Performance slightly below target (220ms vs 200ms)
- Stakeholder decision: Acceptable for MVP
- Documented for future improvement

**Waived Issues**:
1. Registration response time: 220ms (target: 200ms)

**Status Update**: Done (with waiver)

Output: docs/qa/1.1-user-authentication-qa-gate.md

Step 6: Address QA Feedback (if needed)

If gate decision is FAIL or CONCERNS:

*agent dev
*review-qa

Dev Addresses Feedback:

1. Reads QA feedback in story file
2. Prioritizes issues (Critical → Major → Minor)
3. Applies fixes systematically
4. Runs tests to verify
5. Updates Dev Agent Record with resolutions
6. Updates story status to Review

QA Re-reviews: Repeat Step 4-5 until PASS

Step 7: Repeat for Next Story

*agent sm
*draft

SM creates next story (2.1, 2.2, etc.) and cycle repeats.

Development Patterns

Sequential Task Execution

Dev implements tasks in order, one at a time:

1. Read task
2. Implement all subtasks
3. Write tests
4. Run validations
5. Update checkbox ONLY if ALL pass
6. Move to next task

Story-Driven Context

Stories contain complete context - no re-reading needed:

• Requirements from PRD
• Architecture context (selective)
• Previous story learnings
• Source references
• Technical specifications

Quality-First Approach

Every story goes through QA gate:

• Ensures quality standards met
• Prevents technical debt
• Validates architecture compliance
• Documents decisions

Troubleshooting Development Phase

Problem: Story creation fails - missing architecture Solution: Ensure architecture is sharded (*agent po → *shard-doc)

Problem: Dev can't find required files Solution: Check devLoadAlwaysFiles in core-config.yaml

Problem: QA gate always FAIL Solution: Review architecture coding standards, adjust expectations

Problem: Story too large Solution: SM should break into smaller stories (< 8 tasks)

Best Practices

1. One Story at a Time: Complete before starting next
2. Sequential Tasks: Dev implements in order
3. Complete Context in Stories: SM includes all needed context
4. Quality Gates: Every story gets QA review
5. Document Learnings: Add to Dev Agent Record for future stories
6. Keep Stories Small: 3-8 tasks per story ideal

Next Steps

• Review Error Recovery Guide for common issues
• Consult Agent Reference for detailed agent capabilities
• Check Task Reference for available tasks

Related Documentation

• Planning Phase Guide
• Brownfield Guide
• Agent Reference
• Task Reference