diff --git a/bmad-core/agents/dev.md b/bmad-core/agents/dev.md index 6362a303..e066ec54 100644 --- a/bmad-core/agents/dev.md +++ b/bmad-core/agents/dev.md @@ -38,14 +38,14 @@ agent: id: dev title: Full Stack Developer icon: 💻 - whenToUse: 'Use for code implementation, debugging, refactoring, and development best practices' + whenToUse: 'Use for code implementation, debugging, refactoring, Test-Driven Development (TDD) Green/Refactor phases, and development best practices' customization: persona: role: Expert Senior Software Engineer & Implementation Specialist style: Extremely concise, pragmatic, detail-oriented, solution-focused - identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing - focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead + identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing. Practices Test-Driven Development when enabled. + focus: Executing story tasks with precision, TDD Green/Refactor phase execution, updating Dev Agent Record sections only, maintaining minimal context overhead core_principles: - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user. @@ -53,19 +53,39 @@ core_principles: - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log) - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story - Numbered Options - Always use numbered lists when presenting choices to the user + - TDD Discipline - When TDD enabled, implement minimal code to pass failing tests (Green phase) + - Test-First Validation - Never implement features without corresponding failing tests in TDD mode + - Refactoring Safety - Collaborate with QA during refactor phase, keep all tests green # All commands require * prefix when used (e.g., *help) commands: - help: Show numbered list of the following commands to allow selection + # Traditional Development Commands - develop-story: - order-of-execution: 'Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete' - story-file-updates-ONLY: - CRITICAL: ONLY UPDATE THE STORY FILE WITH UPDATES TO SECTIONS INDICATED BELOW. DO NOT MODIFY ANY OTHER SECTIONS. - CRITICAL: You are ONLY authorized to edit these specific sections of story files - Tasks / Subtasks Checkboxes, Dev Agent Record section and all its subsections, Agent Model Used, Debug Log References, Completion Notes List, File List, Change Log, Status - CRITICAL: DO NOT modify Status, Story, Acceptance Criteria, Dev Notes, Testing sections, or any other sections not listed above - - blocking: 'HALT for: Unapproved deps needed, confirm with user | Ambiguous after story check | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' + - blocking: 'HALT for: Unapproved deps needed, confirm with user | 3 failures attempting to implement or fix something repeatedly | Missing config | Failing regression' - ready-for-review: 'Code matches requirements + All validations pass + Follows standards + File List complete' - completion: "All Tasks and Subtasks marked [x] and have tests→Validations and full regression passes (DON'T BE LAZY, EXECUTE ALL TESTS and CONFIRM)→Ensure File List is Complete→run the task execute-checklist for the checklist story-dod-checklist→set story status: 'Ready for Review'→HALT" + # TDD-Specific Commands (only available when tdd.enabled=true) + - tdd-implement {story}: | + Execute tdd-implement task for TDD Green phase. + Implement minimal code to make failing tests pass. No feature creep. + Prerequisites: Story has failing tests (tdd.status='red'), test runner configured. + Outcome: All tests pass, story tdd.status='green', ready for refactor assessment. + - make-tests-pass {story}: | + Iterative command to run tests and implement fixes until all tests pass. + Focuses on single failing test at a time, minimal implementation approach. + Auto-runs tests after each change, provides fast feedback loop. + - tdd-refactor {story}: | + Collaborate with QA agent on TDD Refactor phase. + Improve code quality while keeping all tests green. + Prerequisites: All tests passing (tdd.status='green'). + Outcome: Improved code quality, tests remain green, tdd.status='refactor' or 'done'. + # Utility Commands - explain: teach me what and why you did whatever you just did in detail so I can learn. Explain to me as if you were training a junior engineer. - review-qa: run task `apply-qa-fixes.md' - run-tests: Execute linting and tests @@ -74,8 +94,17 @@ commands: dependencies: checklists: - story-dod-checklist.md + - tdd-dod-checklist.md tasks: - apply-qa-fixes.md - execute-checklist.md - validate-next-story.md + # TDD-specific tasks + - tdd-implement.md + - tdd-refactor.md + prompts: + - tdd-green.md + - tdd-refactor.md + config: + - test-runners.yaml ``` diff --git a/bmad-core/agents/qa.md b/bmad-core/agents/qa.md index 6d787635..0ba8a05e 100644 --- a/bmad-core/agents/qa.md +++ b/bmad-core/agents/qa.md @@ -37,8 +37,9 @@ agent: icon: 🧪 whenToUse: | Use for comprehensive test architecture review, quality gate decisions, - and code improvement. Provides thorough analysis including requirements - traceability, risk assessment, and test strategy. + Test-Driven Development (TDD) test creation, and code improvement. + Provides thorough analysis including requirements traceability, risk assessment, + test strategy, and TDD Red/Refactor phase execution. Advisory only - teams choose their quality bar. customization: null persona: @@ -57,6 +58,10 @@ persona: - Technical Debt Awareness - Identify and quantify debt with improvement suggestions - LLM Acceleration - Use LLMs to accelerate thorough yet focused analysis - Pragmatic Balance - Distinguish must-fix from nice-to-have improvements + - TDD Test-First - Write failing tests before any implementation (Red phase) + - Test Isolation - Ensure deterministic, fast, independent tests with proper mocking + - Minimal Test Scope - Focus on smallest testable behavior slice, avoid over-testing + - Refactoring Safety - Collaborate on safe code improvements while maintaining green tests story-file-permissions: - CRITICAL: When reviewing stories, you are ONLY authorized to update the "QA Results" section of story files - CRITICAL: DO NOT modify any other sections including Status, Story, Acceptance Criteria, Tasks/Subtasks, Dev Notes, Testing, Dev Agent Record, Change Log, or any other sections @@ -64,6 +69,7 @@ story-file-permissions: # All commands require * prefix when used (e.g., *help) commands: - help: Show numbered list of the following commands to allow selection + # Traditional QA Commands - gate {story}: Execute qa-gate task to write/update quality gate decision in directory from qa.qaLocation/gates/ - nfr-assess {story}: Execute nfr-assess task to validate non-functional requirements - review {story}: | @@ -74,10 +80,26 @@ commands: - risk-profile {story}: Execute risk-profile task to generate risk assessment matrix - test-design {story}: Execute test-design task to create comprehensive test scenarios - trace {story}: Execute trace-requirements task to map requirements to tests using Given-When-Then + # TDD-Specific Commands (only available when tdd.enabled=true) + - tdd-start {story}: | + Initialize TDD process for a story. Sets tdd.status='red', analyzes acceptance criteria, + creates test plan, and prepares for write-failing-tests execution. + Prerequisites: Story status 'ready' or 'inprogress', clear acceptance criteria. + - write-failing-tests {story}: | + Execute write-failing-tests task to implement TDD Red phase. + Creates failing tests that describe expected behavior before implementation. + Auto-detects test runner, creates test files, ensures proper mocking strategy. + Prerequisites: tdd-start completed or story ready for TDD. + - tdd-refactor {story}: | + Participate in TDD Refactor phase with Dev agent. + Validates refactoring safety, ensures tests remain green, improves test maintainability. + Collaborative command - works with Dev agent during refactor phase. - exit: Say goodbye as the Test Architect, and then abandon inhabiting this persona dependencies: data: - technical-preferences.md + - test-levels-framework.md + - test-priorities-matrix.md tasks: - nfr-assess.md - qa-gate.md @@ -85,7 +107,18 @@ dependencies: - risk-profile.md - test-design.md - trace-requirements.md + # TDD-specific tasks + - write-failing-tests.md + - tdd-refactor.md templates: - qa-gate-tmpl.yaml - story-tmpl.yaml + - story-tdd-template.md + checklists: + - tdd-dod-checklist.md + prompts: + - tdd-red.md + - tdd-refactor.md + config: + - test-runners.yaml ``` diff --git a/bmad-core/tasks/test-design.md b/bmad-core/tasks/test-design.md index 6f569d89..58c1c18b 100644 --- a/bmad-core/tasks/test-design.md +++ b/bmad-core/tasks/test-design.md @@ -2,7 +2,7 @@ # test-design -Create comprehensive test scenarios with appropriate test level recommendations for story implementation. +Create comprehensive test scenarios with appropriate test level recommendations for story implementation. Supports both traditional testing and Test-Driven Development (TDD) first approaches. ## Inputs @@ -12,12 +12,17 @@ required: - story_path: '{devStoryLocation}/{epic}.{story}.*.md' # Path from core-config.yaml - story_title: '{title}' # If missing, derive from story file H1 - story_slug: '{slug}' # If missing, derive from title (lowercase, hyphenated) +optional: + - tdd_mode: boolean # If true, design tests for TDD Red phase (before implementation) + - existing_tests: array # List of existing tests to consider for gap analysis ``` ## Purpose Design a complete test strategy that identifies what to test, at which level (unit/integration/e2e), and why. This ensures efficient test coverage without redundancy while maintaining appropriate test boundaries. +**TDD Mode**: When `tdd_mode=true`, design tests that will be written BEFORE implementation (Red phase), focusing on smallest testable behavior slices and proper mocking strategies. + ## Dependencies ```yaml @@ -71,6 +76,46 @@ test_scenario: description: 'What is being tested' justification: 'Why this level was chosen' mitigates_risks: ['RISK-001'] # If risk profile exists + # TDD-specific fields (when tdd_mode=true) + tdd_phase: red|green|refactor # When this test should be written + mocking_strategy: mock|fake|stub|none # How to handle dependencies + test_data_approach: fixed|builder|random # How to generate test data +``` + +### 4a. TDD-Specific Test Design (when tdd_mode=true) + +**Smallest-Next-Test Principle:** + +- Design tests for the absolute smallest behavior increment +- Each test should drive a single, focused implementation change +- Avoid tests that require multiple features to pass + +**Mocking Strategy Selection Matrix:** + +| Dependency Type | Recommended Approach | Justification | +| --------------- | -------------------- | -------------------------------------- | +| External API | Mock | Control responses, avoid network calls | +| Database | Fake | In-memory implementation for speed | +| File System | Stub | Return fixed responses | +| Time/Date | Mock | Deterministic time control | +| Random Numbers | Stub | Predictable test outcomes | +| Other Services | Mock/Fake | Depends on complexity and speed needs | + +**Test Data Strategy:** + +```yaml +test_data_approaches: + fixed_data: + when: 'Simple, predictable scenarios' + example: "const userId = 'test-user-123'" + + builder_pattern: + when: 'Complex objects with variations' + example: "new UserBuilder().withEmail('test@example.com').build()" + + avoid_random: + why: 'Makes tests non-deterministic and hard to debug' + instead: 'Use meaningful, fixed test data' ``` ### 5. Validate Coverage diff --git a/bmad-core/templates/tdd-quality-gates.md b/bmad-core/templates/tdd-quality-gates.md new file mode 100644 index 00000000..3514ccc4 --- /dev/null +++ b/bmad-core/templates/tdd-quality-gates.md @@ -0,0 +1,299 @@ + + +# TDD Quality Gates Template + +Quality gate criteria and checkpoints for Test-Driven Development workflows. + +## Gate Structure + +Each TDD phase has specific quality gates that must be met before progression to the next phase. + +## Red Phase Gates + +### Prerequisites for Red Phase Entry + +- [ ] Story has clear acceptance criteria +- [ ] Test runner detected or configured +- [ ] Story status is 'ready' or 'inprogress' +- [ ] TDD enabled in core-config.yaml + +### Red Phase Completion Gates + +**PASS Criteria:** + +- [ ] At least one test written and failing +- [ ] Tests fail for correct reasons (missing implementation, not syntax errors) +- [ ] All external dependencies properly mocked +- [ ] Test data is deterministic (no random values, current time) +- [ ] Test names clearly describe expected behavior +- [ ] Story TDD metadata updated (status='red', test list populated) +- [ ] Test files follow project naming conventions + +**FAIL Criteria:** + +- [ ] No tests written +- [ ] Tests pass unexpectedly (implementation may already exist) +- [ ] Tests fail due to syntax errors or configuration issues +- [ ] External dependencies not mocked (network calls, file system, etc.) +- [ ] Non-deterministic tests (random data, time-dependent) + +**Gate Decision:** + +```yaml +red_phase_gate: + status: PASS|FAIL + failing_tests_count: { number } + tests_fail_correctly: true|false + mocking_complete: true|false + deterministic_tests: true|false + metadata_updated: true|false + ready_for_green_phase: true|false +``` + +## Green Phase Gates + +### Prerequisites for Green Phase Entry + +- [ ] Red phase gate passed +- [ ] Story tdd.status = 'red' +- [ ] Failing tests exist and documented +- [ ] Test runner confirmed working + +### Green Phase Completion Gates + +**PASS Criteria:** + +- [ ] All previously failing tests now pass +- [ ] No new tests added during implementation +- [ ] Implementation is minimal (only what's needed for tests) +- [ ] No feature creep beyond test requirements +- [ ] All existing tests remain green (no regressions) +- [ ] Code follows basic quality standards +- [ ] Story TDD metadata updated (status='green') + +**CONCERNS Criteria:** + +- [ ] Implementation seems overly complex for test requirements +- [ ] Additional functionality added without corresponding tests +- [ ] Code quality significantly below project standards +- [ ] Performance implications not addressed + +**FAIL Criteria:** + +- [ ] Tests still failing after implementation attempt +- [ ] New regressions introduced (previously passing tests now fail) +- [ ] Implementation missing for some failing tests +- [ ] Significant feature creep detected + +**Gate Decision:** + +```yaml +green_phase_gate: + status: PASS|CONCERNS|FAIL + all_tests_passing: true|false + no_regressions: true|false + minimal_implementation: true|false + feature_creep_detected: false|true + code_quality_acceptable: true|false + ready_for_refactor_phase: true|false +``` + +## Refactor Phase Gates + +### Prerequisites for Refactor Phase Entry + +- [ ] Green phase gate passed +- [ ] Story tdd.status = 'green' +- [ ] All tests consistently passing +- [ ] Code quality issues identified + +### Refactor Phase Completion Gates + +**PASS Criteria:** + +- [ ] All tests remain green throughout refactoring +- [ ] Code quality measurably improved +- [ ] No behavior changes introduced +- [ ] Refactoring changes committed incrementally +- [ ] Technical debt reduced in story scope +- [ ] Story TDD metadata updated (status='refactor' or 'done') + +**CONCERNS Criteria:** + +- [ ] Some code smells remain unaddressed +- [ ] Refactoring introduced minor complexity +- [ ] Test execution time increased significantly +- [ ] Marginal quality improvements + +**FAIL Criteria:** + +- [ ] Tests broken by refactoring changes +- [ ] Behavior changed during refactoring +- [ ] Code quality degraded +- [ ] Large, risky refactoring attempts + +**Gate Decision:** + +```yaml +refactor_phase_gate: + status: PASS|CONCERNS|FAIL + tests_remain_green: true|false + code_quality_improved: true|false + behavior_preserved: true|false + technical_debt_reduced: true|false + safe_incremental_changes: true|false + ready_for_completion: true|false +``` + +## Story Completion Gates + +### TDD Story Completion Criteria + +**Must Have:** + +- [ ] All TDD phases completed (Red → Green → Refactor) +- [ ] Final test suite passes consistently +- [ ] Code quality meets project standards +- [ ] All acceptance criteria covered by tests +- [ ] TDD-specific DoD checklist completed + +**Quality Metrics:** + +- [ ] Test coverage meets story target +- [ ] No obvious code smells remain +- [ ] Test execution time reasonable (< 2x baseline) +- [ ] All TDD artifacts documented in story + +**Documentation:** + +- [ ] TDD cycle progression tracked in story +- [ ] Test-to-requirement traceability clear +- [ ] Refactoring decisions documented +- [ ] Lessons learned captured + +## Gate Failure Recovery + +### Red Phase Recovery + +```yaml +red_phase_failures: + no_failing_tests: + action: 'Review acceptance criteria, create simpler test cases' + escalation: 'Consult SM for requirement clarification' + + tests_pass_unexpectedly: + action: 'Check if implementation already exists, adjust test scope' + escalation: 'Review story scope with PO' + + mocking_issues: + action: 'Review external dependencies, implement proper mocks' + escalation: 'Consult with Dev agent on architecture' +``` + +### Green Phase Recovery + +```yaml +green_phase_failures: + tests_still_failing: + action: 'Break down implementation into smaller steps' + escalation: 'Review test expectations vs implementation approach' + + regressions_introduced: + action: 'Revert changes, identify conflicting logic' + escalation: 'Architectural review with team' + + feature_creep_detected: + action: 'Remove features not covered by tests' + escalation: 'Return to Red phase for additional tests' +``` + +### Refactor Phase Recovery + +```yaml +refactor_phase_failures: + tests_broken: + action: 'Immediately revert breaking changes' + escalation: 'Use smaller refactoring steps' + + behavior_changed: + action: 'Revert and analyze where behavior diverged' + escalation: 'Review refactoring approach with QA agent' + + quality_degraded: + action: 'Revert changes, try different refactoring technique' + escalation: 'Accept current code quality, document technical debt' +``` + +## Quality Metrics Dashboard + +### Per-Phase Metrics + +```yaml +metrics_tracking: + red_phase: + - failing_tests_count + - test_creation_time + - mocking_complexity + + green_phase: + - implementation_time + - lines_of_code_added + - test_pass_rate + + refactor_phase: + - code_quality_delta + - test_execution_time_delta + - refactoring_safety_score +``` + +### Story-Level Metrics + +```yaml +story_metrics: + total_tdd_cycle_time: '{hours}' + cycles_completed: '{count}' + test_to_code_ratio: '{percentage}' + coverage_achieved: '{percentage}' + quality_improvement_score: '{0-100}' +``` + +## Integration with Standard Gates + +### How TDD Gates Extend Standard QA Gates + +- **Standard gates still apply** for final story review +- **TDD gates are additional checkpoints** during development +- **Phase-specific criteria** supplement overall quality assessment +- **Traceability maintained** between TDD progress and story completion + +### Gate Reporting + +```yaml +gate_report_template: + story_id: '{epic}.{story}' + tdd_enabled: true + phases_completed: ['red', 'green', 'refactor'] + + phase_gates: + red: + status: 'PASS' + completed_date: '2025-01-01T10:00:00Z' + criteria_met: 6/6 + + green: + status: 'PASS' + completed_date: '2025-01-01T14:00:00Z' + criteria_met: 7/7 + + refactor: + status: 'PASS' + completed_date: '2025-01-01T16:00:00Z' + criteria_met: 6/6 + + final_assessment: + overall_gate: 'PASS' + quality_score: 92 + recommendations: [] +``` + +This template ensures consistent quality standards across all TDD phases while maintaining compatibility with existing BMAD quality gates.