BMAD-METHOD/expansion-packs/bmad-prp-integration/data/prp-methodology.md

PRP Methodology for BMad Integration

Overview

This document outlines the PRP (Product Requirement Prompt) methodology as implemented in PRPs-agentic-eng and how it integrates with BMad-Method's structured planning approach.

PRP Core Principles

1. Context is King

• Comprehensive Context: Every PRP must contain ALL necessary documentation, examples, and caveats
• Information Density: Use keywords and patterns from the codebase
• Context Completeness: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"

2. Validation Loops

• Executable Validation: Provide executable tests/lints the AI can run and fix
• Progressive Success: Start simple, validate, then enhance
• Quality Gates: Multiple validation levels (syntax → tests → integration)

3. One-Pass Implementation

• Complete Context: All implementation details included in PRP
• Clear Requirements: Specific, measurable success criteria
• Actionable Tasks: Detailed implementation blueprint with dependencies

PRP Structure

Goal Section

**Feature Goal**: [Specific, measurable end state]
**Deliverable**: [Concrete artifact - API endpoint, service class, etc.]
**Success Definition**: [How you'll know this is complete and working]

Why Section

• Business value and user impact
• Integration with existing features
• Problems this solves and for whom

What Section

• User-visible behavior and technical requirements
• Success criteria with specific measurable outcomes

All Needed Context Section

### Context Completeness Check
_Before writing this PRP, validate: "If someone knew nothing about this codebase, would they have everything needed to implement this successfully?"_

### Documentation & References
- url: [Complete URL with section anchor]
  why: [Specific methods/concepts needed for implementation]
  critical: [Key insights that prevent common implementation errors]

- file: [exact/path/to/pattern/file.py]
  why: [Specific pattern to follow - class structure, error handling, etc.]
  pattern: [Brief description of what pattern to extract]
  gotcha: [Known constraints or limitations to avoid]

### Known Gotchas
# CRITICAL: [Library name] requires [specific setup]
# Example: FastAPI requires async functions for endpoints

Implementation Blueprint Section

### Data models and structure
Create the core data models, we ensure type safety and consistency.

### Implementation Tasks (ordered by dependencies)
Task 1: CREATE src/models/{domain}_models.py
Task 2: IMPLEMENT src/services/{domain}_service.py
Task 3: ADD src/api/{domain}_endpoints.py

Validation Loop Section

### Level 1: Syntax & Style
ruff check src/ --fix
mypy src/

### Level 2: Unit Tests
uv run pytest tests/test_{domain}.py -v

### Level 3: Integration Test
curl -X POST http://localhost:8000/{domain}/create \
 -H "Content-Type: application/json" \
 -d '{"field": "value"}'

Integration with BMad-Method

Story to PRP Conversion

Mapping BMad Story Components

• Story Statement → Goal Section
• Acceptance Criteria → Success Criteria
• Dev Notes → All Needed Context
• Tasks/Subtasks → Implementation Blueprint
• Testing Requirements → Validation Loop

Context Preservation

• Architecture Documents: Map BMad architecture context to PRP format
• Technical Constraints: Preserve all technical constraints and gotchas
• Implementation Patterns: Maintain existing code patterns and conventions
• Testing Standards: Convert BMad testing requirements to PRP validation

PRP to Story Conversion

Mapping PRP Results to BMad

• Implementation Results → Dev Agent Record
• Validation Results → QA Review
• Generated Artifacts → Story Completion Notes
• Performance Metrics → Story Validation Results

Quality Assurance

• Code Quality: Validate against BMad coding standards
• Test Coverage: Ensure test coverage meets BMad requirements
• Integration Testing: Verify integration with existing BMad workflow
• Documentation: Update BMad story documentation with results

Best Practices

PRP Creation

1. Start with BMad Story: Use BMad story as foundation
2. Enhance Context: Add comprehensive context and examples
3. Validate Completeness: Ensure context completeness check passes
4. Test Validation Loops: Verify validation loops are executable
5. Maintain Traceability: Keep links to original BMad story

PRP Execution

1. Environment Setup: Ensure proper execution environment
2. Context Validation: Verify all context is available
3. Progressive Validation: Run validation loops progressively
4. Error Handling: Handle errors and provide recovery options
5. Result Collection: Collect and validate execution results

Result Integration

1. Quality Validation: Validate results against BMad standards
2. Context Mapping: Map results back to BMad story format
3. Documentation Update: Update story with execution results
4. Workflow Continuation: Prepare for next BMad workflow phase

Validation Standards

Context Completeness

• All necessary documentation included
• Code examples and patterns provided
• Technical constraints documented
• Validation loops executable
• Information density sufficient

Implementation Quality

• Code follows project patterns
• Tests cover all requirements
• Performance meets standards
• Security requirements met
• Documentation complete

Integration Consistency

• BMad story requirements preserved
• Architecture context maintained
• Testing standards followed
• Quality gates passed
• Traceability maintained

Error Handling

Context Issues

• Missing Documentation: Request additional documentation
• Incomplete Context: Enhance context with examples
• Outdated Information: Update context with current information

Execution Issues

• Environment Problems: Fix execution environment
• Dependency Issues: Resolve missing dependencies
• Validation Failures: Address validation issues

Integration Issues

• Format Mismatches: Handle format conversion issues
• Context Loss: Preserve context during conversion
• Quality Issues: Address quality and compliance issues

Success Metrics

Conversion Quality

• Context Preservation: 95%+ context preserved during conversion
• Format Compliance: 100% PRP format compliance
• Validation Completeness: All validation loops executable
• Traceability: Full traceability between frameworks

Execution Success

• Success Rate: 90%+ successful PRP executions
• Quality Compliance: 95%+ quality standards met
• Performance: <10% overhead on execution time
• Error Recovery: 80%+ error recovery success rate

Integration Effectiveness

• Workflow Continuity: Seamless workflow integration
• Quality Maintenance: Maintained quality standards
• User Experience: Improved development experience
• Productivity: Increased development productivity