brownfield experimental docs added to templates
This commit is contained in:
Brian Madison
@@ -52,6 +52,13 @@ Document the decision here before proceeding with the architecture design. In no
|
||||
|
||||
After presenting this starter template section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## High Level Architecture
|
||||
|
||||
[[LLM: This section contains multiple subsections that establish the foundation of the architecture. Present all subsections together (Introduction, Technical Summary, High Level Overview, Project Diagram, and Architectural Patterns), then apply `tasks#advanced-elicitation` protocol to the complete High Level Architecture section. The user can choose to refine the entire section or specific subsections.]]
|
||||
@@ -715,16 +722,6 @@ Note: Basic info goes in Coding Standards for dev agent. This detailed section i
|
||||
|
||||
[[LLM: After presenting the security section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
## Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :------- | :------ | :---------------------------- | :--------- |
|
||||
| {{date}} | 1.0.0 | Initial architecture document | {{author}} |
|
||||
|
||||
---
|
||||
|
||||
## Checklist Results Report
|
||||
|
||||
[[LLM: Before running the checklist, offer to output the full architecture document. Once user confirms, execute the `architect-checklist` and populate results here.]]
|
||||
|
||||
542
bmad-core/templates/brownfield-architecture-tmpl.md
Normal file
542
bmad-core/templates/brownfield-architecture-tmpl.md
Normal file
@@ -0,0 +1,542 @@
|
||||
# {{Project Name}} Brownfield Enhancement Architecture
|
||||
|
||||
[[LLM: IMPORTANT - SCOPE AND ASSESSMENT REQUIRED:
|
||||
|
||||
This architecture document is for SIGNIFICANT enhancements to existing projects that require comprehensive architectural planning. Before proceeding:
|
||||
|
||||
1. **Verify Complexity**: Confirm this enhancement requires architectural planning. For simple additions, recommend: "For simpler changes that don't require architectural planning, consider using the brownfield-create-epic or brownfield-create-story task with the Product Owner instead."
|
||||
|
||||
2. **REQUIRED INPUTS**:
|
||||
|
||||
- Completed brownfield-prd.md
|
||||
- Existing project technical documentation (from docs folder or user-provided)
|
||||
- Access to existing project structure (IDE or uploaded files)
|
||||
|
||||
3. **DEEP ANALYSIS MANDATE**: You MUST conduct thorough analysis of the existing codebase, architecture patterns, and technical constraints before making ANY architectural recommendations. Every suggestion must be based on actual project analysis, not assumptions.
|
||||
|
||||
4. **CONTINUOUS VALIDATION**: Throughout this process, explicitly validate your understanding with the user. For every architectural decision, confirm: "Based on my analysis of your existing system, I recommend [decision] because [evidence from actual project]. Does this align with your system's reality?"
|
||||
|
||||
If any required inputs are missing, request them before proceeding.]]
|
||||
|
||||
## Introduction
|
||||
|
||||
[[LLM: This section establishes the document's purpose and scope for brownfield enhancements. Keep the content below but ensure project name and enhancement details are properly substituted.
|
||||
|
||||
After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
This document outlines the architectural approach for enhancing {{Project Name}} with {{Enhancement Description}}. Its primary goal is to serve as the guiding architectural blueprint for AI-driven development of new features while ensuring seamless integration with the existing system.
|
||||
|
||||
**Relationship to Existing Architecture:**
|
||||
This document supplements existing project architecture by defining how new components will integrate with current systems. Where conflicts arise between new and existing patterns, this document provides guidance on maintaining consistency while implementing enhancements.
|
||||
|
||||
### Existing Project Analysis
|
||||
|
||||
[[LLM: Analyze the existing project structure and architecture:
|
||||
|
||||
1. Review existing documentation in docs folder
|
||||
2. Examine current technology stack and versions
|
||||
3. Identify existing architectural patterns and conventions
|
||||
4. Note current deployment and infrastructure setup
|
||||
5. Document any constraints or limitations
|
||||
|
||||
CRITICAL: After your analysis, explicitly validate your findings: "Based on my analysis of your project, I've identified the following about your existing system: [key findings]. Please confirm these observations are accurate before I proceed with architectural recommendations."
|
||||
|
||||
Present findings and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
**Current Project State:**
|
||||
|
||||
- **Primary Purpose:** {{existing_project_purpose}}
|
||||
- **Current Tech Stack:** {{existing_tech_summary}}
|
||||
- **Architecture Style:** {{existing_architecture_style}}
|
||||
- **Deployment Method:** {{existing_deployment_approach}}
|
||||
|
||||
**Available Documentation:**
|
||||
|
||||
- {{existing_docs_summary}}
|
||||
|
||||
**Identified Constraints:**
|
||||
|
||||
- {{constraint_1}}
|
||||
- {{constraint_2}}
|
||||
- {{constraint_3}}
|
||||
|
||||
### Change Log
|
||||
|
||||
| Change | Date | Version | Description | Author |
|
||||
| ------ | ---- | ------- | ----------- | ------ |
|
||||
|
||||
## Enhancement Scope and Integration Strategy
|
||||
|
||||
[[LLM: Define how the enhancement will integrate with the existing system:
|
||||
|
||||
1. Review the brownfield PRD enhancement scope
|
||||
2. Identify integration points with existing code
|
||||
3. Define boundaries between new and existing functionality
|
||||
4. Establish compatibility requirements
|
||||
|
||||
VALIDATION CHECKPOINT: Before presenting the integration strategy, confirm: "Based on my analysis, the integration approach I'm proposing takes into account [specific existing system characteristics]. These integration points and boundaries respect your current architecture patterns. Is this assessment accurate?"
|
||||
|
||||
Present complete integration strategy and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Enhancement Overview
|
||||
|
||||
**Enhancement Type:** {{enhancement_type}}
|
||||
**Scope:** {{enhancement_scope}}
|
||||
**Integration Impact:** {{integration_impact_level}}
|
||||
|
||||
### Integration Approach
|
||||
|
||||
**Code Integration Strategy:** {{code_integration_approach}}
|
||||
**Database Integration:** {{database_integration_approach}}
|
||||
**API Integration:** {{api_integration_approach}}
|
||||
**UI Integration:** {{ui_integration_approach}}
|
||||
|
||||
### Compatibility Requirements
|
||||
|
||||
- **Existing API Compatibility:** {{api_compatibility}}
|
||||
- **Database Schema Compatibility:** {{db_compatibility}}
|
||||
- **UI/UX Consistency:** {{ui_compatibility}}
|
||||
- **Performance Impact:** {{performance_constraints}}
|
||||
|
||||
## Tech Stack Alignment
|
||||
|
||||
[[LLM: Ensure new components align with existing technology choices:
|
||||
|
||||
1. Use existing technology stack as the foundation
|
||||
2. Only introduce new technologies if absolutely necessary
|
||||
3. Justify any new additions with clear rationale
|
||||
4. Ensure version compatibility with existing dependencies
|
||||
|
||||
Present complete tech stack alignment and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Existing Technology Stack
|
||||
|
||||
[[LLM: Document the current stack that must be maintained or integrated with]]
|
||||
|
||||
| Category | Current Technology | Version | Usage in Enhancement | Notes |
|
||||
| :----------------- | :----------------- | :---------- | :------------------- | :-------- |
|
||||
| **Language** | {{language}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Runtime** | {{runtime}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Framework** | {{framework}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Database** | {{database}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **API Style** | {{api_style}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Authentication** | {{auth}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Testing** | {{test_framework}} | {{version}} | {{usage}} | {{notes}} |
|
||||
| **Build Tool** | {{build_tool}} | {{version}} | {{usage}} | {{notes}} |
|
||||
|
||||
### New Technology Additions
|
||||
|
||||
[[LLM: Only include if new technologies are required for the enhancement]]
|
||||
|
||||
^^CONDITION: has_new_tech^^
|
||||
|
||||
| Technology | Version | Purpose | Rationale | Integration Method |
|
||||
| :----------- | :---------- | :---------- | :------------ | :----------------- |
|
||||
| {{new_tech}} | {{version}} | {{purpose}} | {{rationale}} | {{integration}} |
|
||||
|
||||
^^/CONDITION: has_new_tech^^
|
||||
|
||||
## Data Models and Schema Changes
|
||||
|
||||
[[LLM: Define new data models and how they integrate with existing schema:
|
||||
|
||||
1. Identify new entities required for the enhancement
|
||||
2. Define relationships with existing data models
|
||||
3. Plan database schema changes (additions, modifications)
|
||||
4. Ensure backward compatibility
|
||||
|
||||
Present data model changes and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### New Data Models
|
||||
|
||||
<<REPEAT: new_data_model>>
|
||||
|
||||
### {{model_name}}
|
||||
|
||||
**Purpose:** {{model_purpose}}
|
||||
**Integration:** {{integration_with_existing}}
|
||||
|
||||
**Key Attributes:**
|
||||
|
||||
- {{attribute_1}}: {{type_1}} - {{description_1}}
|
||||
- {{attribute_2}}: {{type_2}} - {{description_2}}
|
||||
|
||||
**Relationships:**
|
||||
|
||||
- **With Existing:** {{existing_relationships}}
|
||||
- **With New:** {{new_relationships}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Schema Integration Strategy
|
||||
|
||||
**Database Changes Required:**
|
||||
|
||||
- **New Tables:** {{new_tables_list}}
|
||||
- **Modified Tables:** {{modified_tables_list}}
|
||||
- **New Indexes:** {{new_indexes_list}}
|
||||
- **Migration Strategy:** {{migration_approach}}
|
||||
|
||||
**Backward Compatibility:**
|
||||
|
||||
- {{compatibility_measure_1}}
|
||||
- {{compatibility_measure_2}}
|
||||
|
||||
## Component Architecture
|
||||
|
||||
[[LLM: Define new components and their integration with existing architecture:
|
||||
|
||||
1. Identify new components required for the enhancement
|
||||
2. Define interfaces with existing components
|
||||
3. Establish clear boundaries and responsibilities
|
||||
4. Plan integration points and data flow
|
||||
|
||||
MANDATORY VALIDATION: Before presenting component architecture, confirm: "The new components I'm proposing follow the existing architectural patterns I identified in your codebase: [specific patterns]. The integration interfaces respect your current component structure and communication patterns. Does this match your project's reality?"
|
||||
|
||||
Present component architecture and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### New Components
|
||||
|
||||
<<REPEAT: new_component>>
|
||||
|
||||
### {{component_name}}
|
||||
|
||||
**Responsibility:** {{component_description}}
|
||||
**Integration Points:** {{integration_points}}
|
||||
|
||||
**Key Interfaces:**
|
||||
|
||||
- {{interface_1}}
|
||||
- {{interface_2}}
|
||||
|
||||
**Dependencies:**
|
||||
|
||||
- **Existing Components:** {{existing_dependencies}}
|
||||
- **New Components:** {{new_dependencies}}
|
||||
|
||||
**Technology Stack:** {{component_tech_details}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Component Interaction Diagram
|
||||
|
||||
[[LLM: Create Mermaid diagram showing how new components interact with existing ones]]
|
||||
|
||||
```mermaid
|
||||
{{component_interaction_diagram}}
|
||||
```
|
||||
|
||||
## API Design and Integration
|
||||
|
||||
[[LLM: Define new API endpoints and integration with existing APIs:
|
||||
|
||||
1. Plan new API endpoints required for the enhancement
|
||||
2. Ensure consistency with existing API patterns
|
||||
3. Define authentication and authorization integration
|
||||
4. Plan versioning strategy if needed
|
||||
|
||||
Present API design and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### New API Endpoints
|
||||
|
||||
^^CONDITION: has_new_api^^
|
||||
|
||||
**API Integration Strategy:** {{api_integration_strategy}}
|
||||
**Authentication:** {{auth_integration}}
|
||||
**Versioning:** {{versioning_approach}}
|
||||
|
||||
<<REPEAT: new_endpoint>>
|
||||
|
||||
#### {{endpoint_name}}
|
||||
|
||||
- **Method:** {{http_method}}
|
||||
- **Endpoint:** {{endpoint_path}}
|
||||
- **Purpose:** {{endpoint_purpose}}
|
||||
- **Integration:** {{integration_with_existing}}
|
||||
|
||||
**Request:**
|
||||
|
||||
```json
|
||||
{{request_schema}}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
|
||||
```json
|
||||
{{response_schema}}
|
||||
```
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
^^/CONDITION: has_new_api^^
|
||||
|
||||
## External API Integration
|
||||
|
||||
[[LLM: Document new external API integrations required for the enhancement]]
|
||||
|
||||
^^CONDITION: has_new_external_apis^^
|
||||
|
||||
<<REPEAT: external_api>>
|
||||
|
||||
### {{api_name}} API
|
||||
|
||||
- **Purpose:** {{api_purpose}}
|
||||
- **Documentation:** {{api_docs_url}}
|
||||
- **Base URL:** {{api_base_url}}
|
||||
- **Authentication:** {{auth_method}}
|
||||
- **Integration Method:** {{integration_approach}}
|
||||
|
||||
**Key Endpoints Used:**
|
||||
|
||||
- `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}
|
||||
|
||||
**Error Handling:** {{error_handling_strategy}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
^^/CONDITION: has_new_external_apis^^
|
||||
|
||||
## Source Tree Integration
|
||||
|
||||
[[LLM: Define how new code will integrate with existing project structure:
|
||||
|
||||
1. Follow existing project organization patterns
|
||||
2. Identify where new files/folders will be placed
|
||||
3. Ensure consistency with existing naming conventions
|
||||
4. Plan for minimal disruption to existing structure
|
||||
|
||||
Present integration plan and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Existing Project Structure
|
||||
|
||||
[[LLM: Document relevant parts of current structure]]
|
||||
|
||||
```plaintext
|
||||
{{existing_structure_relevant_parts}}
|
||||
```
|
||||
|
||||
### New File Organization
|
||||
|
||||
[[LLM: Show only new additions to existing structure]]
|
||||
|
||||
```plaintext
|
||||
{{project-root}}/
|
||||
├── {{existing_structure_context}}
|
||||
│ ├── {{new_folder_1}}/ # {{purpose_1}}
|
||||
│ │ ├── {{new_file_1}}
|
||||
│ │ └── {{new_file_2}}
|
||||
│ ├── {{existing_folder}}/ # Existing folder with additions
|
||||
│ │ ├── {{existing_file}} # Existing file
|
||||
│ │ └── {{new_file_3}} # New addition
|
||||
│ └── {{new_folder_2}}/ # {{purpose_2}}
|
||||
```
|
||||
|
||||
### Integration Guidelines
|
||||
|
||||
- **File Naming:** {{file_naming_consistency}}
|
||||
- **Folder Organization:** {{folder_organization_approach}}
|
||||
- **Import/Export Patterns:** {{import_export_consistency}}
|
||||
|
||||
## Infrastructure and Deployment Integration
|
||||
|
||||
[[LLM: Define how the enhancement will be deployed alongside existing infrastructure:
|
||||
|
||||
1. Use existing deployment pipeline and infrastructure
|
||||
2. Identify any infrastructure changes needed
|
||||
3. Plan deployment strategy to minimize risk
|
||||
4. Define rollback procedures
|
||||
|
||||
Present deployment integration and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Existing Infrastructure
|
||||
|
||||
**Current Deployment:** {{existing_deployment_summary}}
|
||||
**Infrastructure Tools:** {{existing_infrastructure_tools}}
|
||||
**Environments:** {{existing_environments}}
|
||||
|
||||
### Enhancement Deployment Strategy
|
||||
|
||||
**Deployment Approach:** {{deployment_approach}}
|
||||
**Infrastructure Changes:** {{infrastructure_changes}}
|
||||
**Pipeline Integration:** {{pipeline_integration}}
|
||||
|
||||
### Rollback Strategy
|
||||
|
||||
**Rollback Method:** {{rollback_method}}
|
||||
**Risk Mitigation:** {{risk_mitigation}}
|
||||
**Monitoring:** {{monitoring_approach}}
|
||||
|
||||
## Coding Standards and Conventions
|
||||
|
||||
[[LLM: Ensure new code follows existing project conventions:
|
||||
|
||||
1. Document existing coding standards from project analysis
|
||||
2. Identify any enhancement-specific requirements
|
||||
3. Ensure consistency with existing codebase patterns
|
||||
4. Define standards for new code organization
|
||||
|
||||
Present coding standards and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Existing Standards Compliance
|
||||
|
||||
**Code Style:** {{existing_code_style}}
|
||||
**Linting Rules:** {{existing_linting}}
|
||||
**Testing Patterns:** {{existing_test_patterns}}
|
||||
**Documentation Style:** {{existing_doc_style}}
|
||||
|
||||
### Enhancement-Specific Standards
|
||||
|
||||
[[LLM: Only include if new patterns are needed for the enhancement]]
|
||||
|
||||
<<REPEAT: enhancement_standard>>
|
||||
|
||||
- **{{standard_name}}:** {{standard_description}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Critical Integration Rules
|
||||
|
||||
- **Existing API Compatibility:** {{api_compatibility_rule}}
|
||||
- **Database Integration:** {{db_integration_rule}}
|
||||
- **Error Handling:** {{error_handling_integration}}
|
||||
- **Logging Consistency:** {{logging_consistency}}
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
[[LLM: Define testing approach for the enhancement:
|
||||
|
||||
1. Integrate with existing test suite
|
||||
2. Ensure existing functionality remains intact
|
||||
3. Plan for testing new features
|
||||
4. Define integration testing approach
|
||||
|
||||
Present testing strategy and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Integration with Existing Tests
|
||||
|
||||
**Existing Test Framework:** {{existing_test_framework}}
|
||||
**Test Organization:** {{existing_test_organization}}
|
||||
**Coverage Requirements:** {{existing_coverage_requirements}}
|
||||
|
||||
### New Testing Requirements
|
||||
|
||||
#### Unit Tests for New Components
|
||||
|
||||
- **Framework:** {{test_framework}}
|
||||
- **Location:** {{test_location}}
|
||||
- **Coverage Target:** {{coverage_target}}
|
||||
- **Integration with Existing:** {{test_integration}}
|
||||
|
||||
#### Integration Tests
|
||||
|
||||
- **Scope:** {{integration_test_scope}}
|
||||
- **Existing System Verification:** {{existing_system_verification}}
|
||||
- **New Feature Testing:** {{new_feature_testing}}
|
||||
|
||||
#### Regression Testing
|
||||
|
||||
- **Existing Feature Verification:** {{regression_test_approach}}
|
||||
- **Automated Regression Suite:** {{automated_regression}}
|
||||
- **Manual Testing Requirements:** {{manual_testing_requirements}}
|
||||
|
||||
## Security Integration
|
||||
|
||||
[[LLM: Ensure security consistency with existing system:
|
||||
|
||||
1. Follow existing security patterns and tools
|
||||
2. Ensure new features don't introduce vulnerabilities
|
||||
3. Maintain existing security posture
|
||||
4. Define security testing for new components
|
||||
|
||||
Present security integration and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Existing Security Measures
|
||||
|
||||
**Authentication:** {{existing_auth}}
|
||||
**Authorization:** {{existing_authz}}
|
||||
**Data Protection:** {{existing_data_protection}}
|
||||
**Security Tools:** {{existing_security_tools}}
|
||||
|
||||
### Enhancement Security Requirements
|
||||
|
||||
**New Security Measures:** {{new_security_measures}}
|
||||
**Integration Points:** {{security_integration_points}}
|
||||
**Compliance Requirements:** {{compliance_requirements}}
|
||||
|
||||
### Security Testing
|
||||
|
||||
**Existing Security Tests:** {{existing_security_tests}}
|
||||
**New Security Test Requirements:** {{new_security_tests}}
|
||||
**Penetration Testing:** {{pentest_requirements}}
|
||||
|
||||
## Risk Assessment and Mitigation
|
||||
|
||||
[[LLM: Identify and plan for risks specific to brownfield development:
|
||||
|
||||
1. Technical integration risks
|
||||
2. Deployment and operational risks
|
||||
3. User impact and compatibility risks
|
||||
4. Mitigation strategies for each risk
|
||||
|
||||
Present risk assessment and apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Technical Risks
|
||||
|
||||
<<REPEAT: technical_risk>>
|
||||
|
||||
**Risk:** {{risk_description}}
|
||||
**Impact:** {{impact_level}}
|
||||
**Likelihood:** {{likelihood}}
|
||||
**Mitigation:** {{mitigation_strategy}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Operational Risks
|
||||
|
||||
<<REPEAT: operational_risk>>
|
||||
|
||||
**Risk:** {{risk_description}}
|
||||
**Impact:** {{impact_level}}
|
||||
**Likelihood:** {{likelihood}}
|
||||
**Mitigation:** {{mitigation_strategy}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
### Monitoring and Alerting
|
||||
|
||||
**Enhanced Monitoring:** {{monitoring_additions}}
|
||||
**New Alerts:** {{new_alerts}}
|
||||
**Performance Monitoring:** {{performance_monitoring}}
|
||||
|
||||
## Checklist Results Report
|
||||
|
||||
[[LLM: Execute the architect-checklist and populate results here, focusing on brownfield-specific validation]]
|
||||
|
||||
## Next Steps
|
||||
|
||||
[[LLM: After completing the brownfield architecture:
|
||||
|
||||
1. Review integration points with existing system
|
||||
2. Begin story implementation with Dev agent
|
||||
3. Set up deployment pipeline integration
|
||||
4. Plan rollback and monitoring procedures]]
|
||||
|
||||
### Story Manager Handoff
|
||||
|
||||
[[LLM: Create a brief prompt for Story Manager to work with this brownfield enhancement. Include:
|
||||
|
||||
- Reference to this architecture document
|
||||
- Key integration requirements validated with user
|
||||
- Existing system constraints based on actual project analysis
|
||||
- First story to implement with clear integration checkpoints
|
||||
- Emphasis on maintaining existing system integrity throughout implementation]]
|
||||
|
||||
### Developer Handoff
|
||||
|
||||
[[LLM: Create a brief prompt for developers starting implementation. Include:
|
||||
|
||||
- Reference to this architecture and existing coding standards analyzed from actual project
|
||||
- Integration requirements with existing codebase validated with user
|
||||
- Key technical decisions based on real project constraints
|
||||
- Existing system compatibility requirements with specific verification steps
|
||||
- Clear sequencing of implementation to minimize risk to existing functionality]]
|
||||
240
bmad-core/templates/brownfield-prd-tmpl.md
Normal file
240
bmad-core/templates/brownfield-prd-tmpl.md
Normal file
@@ -0,0 +1,240 @@
|
||||
# {{Project Name}} Brownfield Enhancement PRD
|
||||
|
||||
[[LLM: IMPORTANT - SCOPE ASSESSMENT REQUIRED:
|
||||
|
||||
This PRD is for SIGNIFICANT enhancements to existing projects that require comprehensive planning and multiple stories. Before proceeding:
|
||||
|
||||
1. **Assess Enhancement Complexity**: If this is a simple feature addition or bug fix that could be completed in 1-2 focused development sessions, STOP and recommend: "For simpler changes, consider using the brownfield-create-epic or brownfield-create-story task with the Product Owner instead. This full PRD process is designed for substantial enhancements that require architectural planning and multiple coordinated stories."
|
||||
|
||||
2. **Project Context**: Determine if we're working in an IDE with the project already loaded or if the user needs to provide project information. If project files are available, analyze existing documentation in the docs folder. If insufficient documentation exists, recommend running the document-project task first.
|
||||
|
||||
3. **Deep Assessment Requirement**: You MUST thoroughly analyze the existing project structure, patterns, and constraints before making ANY suggestions. Every recommendation must be grounded in actual project analysis, not assumptions.]]
|
||||
|
||||
## Project Analysis and Context
|
||||
|
||||
[[LLM: Gather comprehensive information about the existing project. This section must be completed before proceeding with requirements.
|
||||
|
||||
CRITICAL: Throughout this analysis, explicitly confirm your understanding with the user. For every assumption you make about the existing project, ask: "Based on my analysis, I understand that [assumption]. Is this correct?"
|
||||
|
||||
Do not proceed with any recommendations until the user has validated your understanding of the existing system.]]
|
||||
|
||||
### Existing Project Overview
|
||||
|
||||
[[LLM: If working in IDE with project loaded, analyze the project structure and existing documentation. If working in web interface, request project upload or detailed project information from user.]]
|
||||
|
||||
**Project Location**: [[LLM: Note if this is IDE-based analysis or user-provided information]]
|
||||
|
||||
**Current Project State**: [[LLM: Brief description of what the project currently does and its primary purpose]]
|
||||
|
||||
### Available Documentation Analysis
|
||||
|
||||
[[LLM: Check for existing documentation in docs folder or provided by user. List what documentation is available and assess its completeness. Required documents include:
|
||||
|
||||
- Tech stack documentation
|
||||
- Source tree/architecture overview
|
||||
- Coding standards
|
||||
- API documentation or OpenAPI specs
|
||||
- External API integrations
|
||||
- UX/UI guidelines or existing patterns]]
|
||||
|
||||
**Available Documentation**:
|
||||
|
||||
- [ ] Tech Stack Documentation
|
||||
- [ ] Source Tree/Architecture
|
||||
- [ ] Coding Standards
|
||||
- [ ] API Documentation
|
||||
- [ ] External API Documentation
|
||||
- [ ] UX/UI Guidelines
|
||||
- [ ] Other: \***\*\_\_\_\*\***
|
||||
|
||||
[[LLM: If critical documentation is missing, STOP and recommend: "I recommend running the document-project task first to generate baseline documentation including tech-stack, source-tree, coding-standards, APIs, external-APIs, and UX/UI information. This will provide the foundation needed for a comprehensive brownfield PRD."]]
|
||||
|
||||
### Enhancement Scope Definition
|
||||
|
||||
[[LLM: Work with user to clearly define what type of enhancement this is. This is critical for scoping and approach.]]
|
||||
|
||||
**Enhancement Type**: [[LLM: Determine with user which applies]]
|
||||
|
||||
- [ ] New Feature Addition
|
||||
- [ ] Major Feature Modification
|
||||
- [ ] Integration with New Systems
|
||||
- [ ] Performance/Scalability Improvements
|
||||
- [ ] UI/UX Overhaul
|
||||
- [ ] Technology Stack Upgrade
|
||||
- [ ] Bug Fix and Stability Improvements
|
||||
- [ ] Other: \***\*\_\_\_\*\***
|
||||
|
||||
**Enhancement Description**: [[LLM: 2-3 sentences describing what the user wants to add or change]]
|
||||
|
||||
**Impact Assessment**: [[LLM: Assess the scope of impact on existing codebase]]
|
||||
|
||||
- [ ] Minimal Impact (isolated additions)
|
||||
- [ ] Moderate Impact (some existing code changes)
|
||||
- [ ] Significant Impact (substantial existing code changes)
|
||||
- [ ] Major Impact (architectural changes required)
|
||||
|
||||
### Change Log
|
||||
|
||||
| Change | Date | Version | Description | Author |
|
||||
| ------ | ---- | ------- | ----------- | ------ |
|
||||
|
||||
## Goals and Background Context
|
||||
|
||||
### Goals
|
||||
|
||||
[[LLM: Bullet list of 1-line desired outcomes this enhancement will deliver if successful]]
|
||||
|
||||
### Background Context
|
||||
|
||||
[[LLM: 1-2 short paragraphs explaining why this enhancement is needed, what problem it solves, and how it fits with the existing project]]
|
||||
|
||||
## Requirements
|
||||
|
||||
[[LLM: Draft functional and non-functional requirements based on your validated understanding of the existing project. Before presenting requirements, confirm: "These requirements are based on my understanding of your existing system. Please review carefully and confirm they align with your project's reality." Then immediately execute tasks#advanced-elicitation display]]
|
||||
|
||||
### Functional
|
||||
|
||||
[[LLM: Each Requirement will be a bullet markdown with identifier starting with FR]]
|
||||
@{example: - FR1: The existing Todo List will integrate with the new AI duplicate detection service without breaking current functionality.}
|
||||
|
||||
### Non Functional
|
||||
|
||||
[[LLM: Each Requirement will be a bullet markdown with identifier starting with NFR. Include constraints from existing system]]
|
||||
@{example: - NFR1: Enhancement must maintain existing performance characteristics and not exceed current memory usage by more than 20%.}
|
||||
|
||||
### Compatibility Requirements
|
||||
|
||||
[[LLM: Critical for brownfield - what must remain compatible]]
|
||||
|
||||
- CR1: [[LLM: Existing API compatibility requirements]]
|
||||
- CR2: [[LLM: Database schema compatibility requirements]]
|
||||
- CR3: [[LLM: UI/UX consistency requirements]]
|
||||
- CR4: [[LLM: Integration compatibility requirements]]
|
||||
|
||||
^^CONDITION: has_ui^^
|
||||
|
||||
## User Interface Enhancement Goals
|
||||
|
||||
[[LLM: For UI changes, capture how they will integrate with existing UI patterns and design systems]]
|
||||
|
||||
### Integration with Existing UI
|
||||
|
||||
[[LLM: Describe how new UI elements will fit with existing design patterns, style guides, and component libraries]]
|
||||
|
||||
### Modified/New Screens and Views
|
||||
|
||||
[[LLM: List only the screens/views that will be modified or added]]
|
||||
|
||||
### UI Consistency Requirements
|
||||
|
||||
[[LLM: Specific requirements for maintaining visual and interaction consistency with existing application]]
|
||||
|
||||
^^/CONDITION: has_ui^^
|
||||
|
||||
## Technical Constraints and Integration Requirements
|
||||
|
||||
[[LLM: This section replaces separate architecture documentation. Gather detailed technical constraints from existing project analysis.]]
|
||||
|
||||
### Existing Technology Stack
|
||||
|
||||
[[LLM: Document the current technology stack that must be maintained or integrated with]]
|
||||
|
||||
**Languages**: [[LLM: Current programming languages in use]]
|
||||
**Frameworks**: [[LLM: Current frameworks and their versions]]
|
||||
**Database**: [[LLM: Current database technology and schema considerations]]
|
||||
**Infrastructure**: [[LLM: Current deployment and hosting infrastructure]]
|
||||
**External Dependencies**: [[LLM: Current third-party services and APIs]]
|
||||
|
||||
### Integration Approach
|
||||
|
||||
[[LLM: Define how the enhancement will integrate with existing architecture]]
|
||||
|
||||
**Database Integration Strategy**: [[LLM: How new features will interact with existing database]]
|
||||
**API Integration Strategy**: [[LLM: How new APIs will integrate with existing API structure]]
|
||||
**Frontend Integration Strategy**: [[LLM: How new UI components will integrate with existing frontend]]
|
||||
**Testing Integration Strategy**: [[LLM: How new tests will integrate with existing test suite]]
|
||||
|
||||
### Code Organization and Standards
|
||||
|
||||
[[LLM: Based on existing project analysis, define how new code will fit existing patterns]]
|
||||
|
||||
**File Structure Approach**: [[LLM: How new files will fit existing project structure]]
|
||||
**Naming Conventions**: [[LLM: Existing naming conventions that must be followed]]
|
||||
**Coding Standards**: [[LLM: Existing coding standards and linting rules]]
|
||||
**Documentation Standards**: [[LLM: How new code documentation will match existing patterns]]
|
||||
|
||||
### Deployment and Operations
|
||||
|
||||
[[LLM: How the enhancement fits existing deployment pipeline]]
|
||||
|
||||
**Build Process Integration**: [[LLM: How enhancement builds with existing process]]
|
||||
**Deployment Strategy**: [[LLM: How enhancement will be deployed alongside existing features]]
|
||||
**Monitoring and Logging**: [[LLM: How enhancement will integrate with existing monitoring]]
|
||||
**Configuration Management**: [[LLM: How new configuration will integrate with existing config]]
|
||||
|
||||
### Risk Assessment and Mitigation
|
||||
|
||||
[[LLM: Identify risks specific to working with existing codebase]]
|
||||
|
||||
**Technical Risks**: [[LLM: Risks related to modifying existing code]]
|
||||
**Integration Risks**: [[LLM: Risks in integrating with existing systems]]
|
||||
**Deployment Risks**: [[LLM: Risks in deploying alongside existing features]]
|
||||
**Mitigation Strategies**: [[LLM: Specific strategies to address identified risks]]
|
||||
|
||||
## Epic and Story Structure
|
||||
|
||||
[[LLM: For brownfield projects, favor a single comprehensive epic unless the user is clearly requesting multiple unrelated enhancements. Before presenting the epic structure, confirm: "Based on my analysis of your existing project, I believe this enhancement should be structured as [single epic/multiple epics] because [rationale based on actual project analysis]. Does this align with your understanding of the work required?" Then present the epic structure and immediately execute tasks#advanced-elicitation display.]]
|
||||
|
||||
### Epic Approach
|
||||
|
||||
[[LLM: Explain the rationale for epic structure - typically single epic for brownfield unless multiple unrelated features]]
|
||||
|
||||
**Epic Structure Decision**: [[LLM: Single Epic or Multiple Epics with rationale]]
|
||||
|
||||
## Epic 1: {{enhancement_title}}
|
||||
|
||||
[[LLM: Comprehensive epic that delivers the brownfield enhancement while maintaining existing functionality]]
|
||||
|
||||
**Epic Goal**: [[LLM: 2-3 sentences describing the complete enhancement objective and value]]
|
||||
|
||||
**Integration Requirements**: [[LLM: Key integration points with existing system]]
|
||||
|
||||
[[LLM: CRITICAL STORY SEQUENCING FOR BROWNFIELD:
|
||||
|
||||
- Stories must ensure existing functionality remains intact
|
||||
- Each story should include verification that existing features still work
|
||||
- Stories should be sequenced to minimize risk to existing system
|
||||
- Include rollback considerations for each story
|
||||
- Focus on incremental integration rather than big-bang changes
|
||||
- Size stories for AI agent execution in existing codebase context
|
||||
- MANDATORY: Present the complete story sequence and ask: "This story sequence is designed to minimize risk to your existing system. Does this order make sense given your project's architecture and constraints?"
|
||||
- Stories must be logically sequential with clear dependencies identified
|
||||
- Each story must deliver value while maintaining system integrity]]
|
||||
|
||||
<<REPEAT: story>>
|
||||
|
||||
### Story 1.{{story_number}} {{story_title}}
|
||||
|
||||
As a {{user_type}},
|
||||
I want {{action}},
|
||||
so that {{benefit}}.
|
||||
|
||||
#### Acceptance Criteria
|
||||
|
||||
[[LLM: Define criteria that include both new functionality and existing system integrity]]
|
||||
|
||||
<<REPEAT: criteria>>
|
||||
|
||||
- {{criterion number}}: {{criteria}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
#### Integration Verification
|
||||
|
||||
[[LLM: Specific verification steps to ensure existing functionality remains intact]]
|
||||
|
||||
- IV1: [[LLM: Existing functionality verification requirement]]
|
||||
- IV2: [[LLM: Integration point verification requirement]]
|
||||
- IV3: [[LLM: Performance impact verification requirement]]
|
||||
|
||||
<</REPEAT>>
|
||||
@@ -46,6 +46,13 @@
|
||||
|
||||
Document the starter template decision and any constraints it imposes before proceeding.]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## Frontend Tech Stack
|
||||
|
||||
[[LLM: Extract from main architecture's Technology Stack Table. This section MUST remain synchronized with the main architecture document. After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
@@ -8,7 +8,7 @@
|
||||
|
||||
This document defines the user experience goals, information architecture, user flows, and visual design specifications for {{Project Name}}'s user interface. It serves as the foundation for visual design and frontend development, ensuring a cohesive and user-centered experience.
|
||||
|
||||
## Overall UX Goals & Principles
|
||||
### Overall UX Goals & Principles
|
||||
|
||||
[[LLM: Work with the user to establish and document the following. If not already defined, facilitate a discussion to determine:
|
||||
|
||||
@@ -23,33 +23,43 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
{{persona_descriptions}}
|
||||
|
||||
@{example: personas}
|
||||
|
||||
- **Power User:** Technical professionals who need advanced features and efficiency
|
||||
- **Casual User:** Occasional users who prioritize ease of use and clear guidance
|
||||
- **Administrator:** System managers who need control and oversight capabilities
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
### Usability Goals
|
||||
|
||||
{{usability_goals}}
|
||||
|
||||
@{example: usability_goals}
|
||||
|
||||
- Ease of learning: New users can complete core tasks within 5 minutes
|
||||
- Efficiency of use: Power users can complete frequent tasks with minimal clicks
|
||||
- Error prevention: Clear validation and confirmation for destructive actions
|
||||
- Memorability: Infrequent users can return without relearning
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
### Design Principles
|
||||
|
||||
{{design_principles}}
|
||||
|
||||
@{example: design_principles}
|
||||
|
||||
1. **Clarity over cleverness** - Prioritize clear communication over aesthetic innovation
|
||||
2. **Progressive disclosure** - Show only what's needed, when it's needed
|
||||
3. **Consistent patterns** - Use familiar UI patterns throughout the application
|
||||
4. **Immediate feedback** - Every action should have a clear, immediate response
|
||||
5. **Accessible by default** - Design for all users from the start
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## Information Architecture (IA)
|
||||
|
||||
@@ -69,6 +79,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
```
|
||||
|
||||
@{example: sitemap}
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
A[Homepage] --> B[Dashboard]
|
||||
@@ -83,6 +94,7 @@ graph TD
|
||||
D --> D2[Settings]
|
||||
D --> D3[Billing]
|
||||
```
|
||||
|
||||
@{/example}
|
||||
|
||||
### Navigation Structure
|
||||
@@ -106,6 +118,7 @@ graph TD
|
||||
Create subsections for each major flow. After presenting all flows, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
<<REPEAT: user_flow>>
|
||||
|
||||
### {{flow_name}}
|
||||
|
||||
**User Goal:** {{flow_goal}}
|
||||
@@ -121,6 +134,7 @@ Create subsections for each major flow. After presenting all flows, apply `tasks
|
||||
```
|
||||
|
||||
**Edge Cases & Error Handling:**
|
||||
|
||||
- {{edge_case_1}}
|
||||
- {{edge_case_2}}
|
||||
|
||||
@@ -128,6 +142,7 @@ Create subsections for each major flow. After presenting all flows, apply `tasks
|
||||
<</REPEAT>>
|
||||
|
||||
@{example: user_flow}
|
||||
|
||||
### User Registration
|
||||
|
||||
**User Goal:** Create a new account to access the platform
|
||||
@@ -153,10 +168,11 @@ graph TD
|
||||
```
|
||||
|
||||
**Edge Cases & Error Handling:**
|
||||
|
||||
- Duplicate email: Show inline error with password recovery option
|
||||
- Weak password: Real-time feedback on password strength
|
||||
- Network error: Preserve form data and show retry option
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
## Wireframes & Mockups
|
||||
|
||||
@@ -169,11 +185,13 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
### Key Screen Layouts
|
||||
|
||||
<<REPEAT: screen_layout>>
|
||||
|
||||
#### {{screen_name}}
|
||||
|
||||
**Purpose:** {{screen_purpose}}
|
||||
|
||||
**Key Elements:**
|
||||
|
||||
- {{element_1}}
|
||||
- {{element_2}}
|
||||
- {{element_3}}
|
||||
@@ -194,6 +212,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
### Core Components
|
||||
|
||||
<<REPEAT: component>>
|
||||
|
||||
#### {{component_name}}
|
||||
|
||||
**Purpose:** {{component_purpose}}
|
||||
@@ -206,6 +225,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
<</REPEAT>>
|
||||
|
||||
@{example: component}
|
||||
|
||||
#### Button
|
||||
|
||||
**Purpose:** Primary interaction element for user actions
|
||||
@@ -214,11 +234,12 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
**States:** Default, Hover, Active, Disabled, Loading
|
||||
|
||||
**Usage Guidelines:**
|
||||
**Usage Guidelines:**
|
||||
|
||||
- Use Primary for main CTAs (one per view)
|
||||
- Secondary for supporting actions
|
||||
- Destructive only for permanent deletions with confirmation
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
## Branding & Style Guide
|
||||
|
||||
@@ -232,19 +253,20 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Color Palette
|
||||
|
||||
| Color Type | Hex Code | Usage |
|
||||
|:-----------|:---------|:------|
|
||||
| **Primary** | {{primary_color}} | {{primary_usage}} |
|
||||
| **Secondary** | {{secondary_color}} | {{secondary_usage}} |
|
||||
| **Accent** | {{accent_color}} | {{accent_usage}} |
|
||||
| **Success** | {{success_color}} | Positive feedback, confirmations |
|
||||
| **Warning** | {{warning_color}} | Cautions, important notices |
|
||||
| **Error** | {{error_color}} | Errors, destructive actions |
|
||||
| **Neutral** | {{neutral_colors}} | Text, borders, backgrounds |
|
||||
| Color Type | Hex Code | Usage |
|
||||
| :------------ | :------------------ | :------------------------------- |
|
||||
| **Primary** | {{primary_color}} | {{primary_usage}} |
|
||||
| **Secondary** | {{secondary_color}} | {{secondary_usage}} |
|
||||
| **Accent** | {{accent_color}} | {{accent_usage}} |
|
||||
| **Success** | {{success_color}} | Positive feedback, confirmations |
|
||||
| **Warning** | {{warning_color}} | Cautions, important notices |
|
||||
| **Error** | {{error_color}} | Errors, destructive actions |
|
||||
| **Neutral** | {{neutral_colors}} | Text, borders, backgrounds |
|
||||
|
||||
### Typography
|
||||
|
||||
**Font Families:**
|
||||
|
||||
- **Primary:** {{primary_font}}
|
||||
- **Secondary:** {{secondary_font}}
|
||||
- **Monospace:** {{mono_font}}
|
||||
@@ -283,16 +305,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
### Key Requirements
|
||||
|
||||
**Visual:**
|
||||
|
||||
- Color contrast ratios: {{contrast_requirements}}
|
||||
- Focus indicators: {{focus_requirements}}
|
||||
- Text sizing: {{text_requirements}}
|
||||
|
||||
**Interaction:**
|
||||
|
||||
- Keyboard navigation: {{keyboard_requirements}}
|
||||
- Screen reader support: {{screen_reader_requirements}}
|
||||
- Touch targets: {{touch_requirements}}
|
||||
|
||||
**Content:**
|
||||
|
||||
- Alternative text: {{alt_text_requirements}}
|
||||
- Heading structure: {{heading_requirements}}
|
||||
- Form labels: {{form_requirements}}
|
||||
@@ -309,12 +334,12 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
### Breakpoints
|
||||
|
||||
| Breakpoint | Min Width | Max Width | Target Devices |
|
||||
|:-----------|:----------|:----------|:---------------|
|
||||
| Mobile | {{mobile_min}} | {{mobile_max}} | {{mobile_devices}} |
|
||||
| Tablet | {{tablet_min}} | {{tablet_max}} | {{tablet_devices}} |
|
||||
| Desktop | {{desktop_min}} | {{desktop_max}} | {{desktop_devices}} |
|
||||
| Wide | {{wide_min}} | - | {{wide_devices}} |
|
||||
| Breakpoint | Min Width | Max Width | Target Devices |
|
||||
| :--------- | :-------------- | :-------------- | :------------------ |
|
||||
| Mobile | {{mobile_min}} | {{mobile_max}} | {{mobile_devices}} |
|
||||
| Tablet | {{tablet_min}} | {{tablet_max}} | {{tablet_devices}} |
|
||||
| Desktop | {{desktop_min}} | {{desktop_max}} | {{desktop_devices}} |
|
||||
| Wide | {{wide_min}} | - | {{wide_devices}} |
|
||||
|
||||
### Adaptation Patterns
|
||||
|
||||
@@ -339,8 +364,9 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
### Key Animations
|
||||
|
||||
<<REPEAT: animation>>
|
||||
|
||||
- **{{animation_name}}:** {{animation_description}} (Duration: {{duration}}, Easing: {{easing}})
|
||||
<</REPEAT>>
|
||||
<</REPEAT>>
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
@@ -380,14 +406,6 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
- [ ] Brand guidelines incorporated
|
||||
- [ ] Performance goals established
|
||||
|
||||
## Change Log
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
|:-----|:--------|:------------|:-------|
|
||||
| {{date}} | 1.0.0 | Initial UI/UX specification | {{author}} |
|
||||
|
||||
---
|
||||
|
||||
## Checklist Results
|
||||
|
||||
[[LLM: If a UI/UX checklist exists, run it against this document and report results here.]]
|
||||
[[LLM: If a UI/UX checklist exists, run it against this document and report results here.]]
|
||||
|
||||
@@ -40,6 +40,13 @@ This unified approach combines what would traditionally be separate backend and
|
||||
|
||||
If none, state "N/A - Greenfield project"
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## High Level Architecture
|
||||
|
||||
[[LLM: This section contains multiple subsections that establish the foundation. Present all subsections together, then apply `tasks#advanced-elicitation` protocol to the complete section.]]
|
||||
@@ -221,7 +228,7 @@ After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
|
||||
|
||||
- {{relationship_1}}
|
||||
- {{relationship_2}}
|
||||
<</REPEAT>>
|
||||
<</REPEAT>>
|
||||
|
||||
@{example: data_model}
|
||||
|
||||
@@ -261,7 +268,7 @@ interface UserProfile {
|
||||
|
||||
- Has many Posts (1:n)
|
||||
- Has one Profile (1:1)
|
||||
@{/example}
|
||||
@{/example}
|
||||
|
||||
## REST API Spec
|
||||
|
||||
@@ -988,20 +995,10 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
- Response time
|
||||
- Database query performance
|
||||
|
||||
## Change Log
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :------- | :------ | :----------------------------- | :--------- |
|
||||
| {{date}} | 1.0.0 | Initial fullstack architecture | {{author}} |
|
||||
|
||||
---
|
||||
|
||||
## Checklist Results Report
|
||||
|
||||
[[LLM: Before running the checklist, offer to output the full architecture document. Once user confirms, execute the `architect-checklist` and populate results here.]]
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
[[LLM: Provide specific next steps for implementation.]]
|
||||
|
||||
@@ -1,406 +0,0 @@
|
||||
# {{Project Name}} Infrastructure Architecture
|
||||
|
||||
[[LLM: Initial Setup
|
||||
|
||||
1. Replace {{Project Name}} with the actual project name throughout the document
|
||||
2. Gather and review required inputs:
|
||||
- Product Requirements Document (PRD) - Required for business needs and scale requirements
|
||||
- Main System Architecture - Required for infrastructure dependencies
|
||||
- Technical Preferences/Tech Stack Document - Required for technology choices
|
||||
- PRD Technical Assumptions - Required for cross-referencing repository and service architecture
|
||||
|
||||
If any required documents are missing, ask user: "I need the following documents to create a comprehensive infrastructure architecture: [list missing]. Would you like to proceed with available information or provide the missing documents first?"
|
||||
|
||||
3. <critical_rule>Cross-reference with PRD Technical Assumptions to ensure infrastructure decisions align with repository and service architecture decisions made in the system architecture.</critical_rule>
|
||||
|
||||
Output file location: `docs/infrastructure-architecture.md`]]
|
||||
|
||||
## Infrastructure Overview
|
||||
|
||||
[[LLM: Review the product requirements document to understand business needs and scale requirements. Analyze the main system architecture to identify infrastructure dependencies. Document non-functional requirements (performance, scalability, reliability, security). Cross-reference with PRD Technical Assumptions to ensure alignment with repository and service architecture decisions.]]
|
||||
|
||||
- Cloud Provider(s)
|
||||
- Core Services & Resources
|
||||
- Regional Architecture
|
||||
- Multi-environment Strategy
|
||||
|
||||
@{example: cloud_strategy}
|
||||
|
||||
- **Cloud Provider:** AWS (primary), with multi-cloud capability for critical services
|
||||
- **Core Services:** EKS for container orchestration, RDS for databases, S3 for storage, CloudFront for CDN
|
||||
- **Regional Architecture:** Multi-region active-passive with primary in us-east-1, DR in us-west-2
|
||||
- **Multi-environment Strategy:** Development, Staging, UAT, Production with identical infrastructure patterns
|
||||
|
||||
@{/example}
|
||||
|
||||
[[LLM: Infrastructure Elicitation Options
|
||||
Present user with domain-specific elicitation options:
|
||||
"For the Infrastructure Overview section, I can explore:
|
||||
1. **Multi-Cloud Strategy Analysis** - Evaluate cloud provider options and vendor lock-in considerations
|
||||
2. **Regional Distribution Planning** - Analyze latency requirements and data residency needs
|
||||
3. **Environment Isolation Strategy** - Design security boundaries and resource segregation
|
||||
4. **Scalability Patterns Review** - Assess auto-scaling needs and traffic patterns
|
||||
5. **Compliance Requirements Analysis** - Review regulatory and security compliance needs
|
||||
6. **Cost-Benefit Analysis** - Compare infrastructure options and TCO
|
||||
7. **Proceed to next section**
|
||||
|
||||
Select an option (1-7):"]]
|
||||
|
||||
## Infrastructure as Code (IaC)
|
||||
|
||||
[[LLM: Define IaC approach based on technical preferences and existing patterns. Consider team expertise, tooling ecosystem, and maintenance requirements.]]
|
||||
|
||||
- Tools & Frameworks
|
||||
- Repository Structure
|
||||
- State Management
|
||||
- Dependency Management
|
||||
|
||||
<critical_rule>All infrastructure must be defined as code. No manual resource creation in production environments.</critical_rule>
|
||||
|
||||
## Environment Configuration
|
||||
|
||||
[[LLM: Design environment strategy that supports the development workflow while maintaining security and cost efficiency. Reference the Environment Transition Strategy section for promotion details.]]
|
||||
|
||||
- Environment Promotion Strategy
|
||||
- Configuration Management
|
||||
- Secret Management
|
||||
- Feature Flag Integration
|
||||
|
||||
<<REPEAT: environment>>
|
||||
|
||||
### {{environment_name}} Environment
|
||||
|
||||
- **Purpose:** {{environment_purpose}}
|
||||
- **Resources:** {{environment_resources}}
|
||||
- **Access Control:** {{environment_access}}
|
||||
- **Data Classification:** {{environment_data_class}}
|
||||
|
||||
<</REPEAT>>
|
||||
|
||||
## Environment Transition Strategy
|
||||
|
||||
[[LLM: Detail the complete lifecycle of code and configuration changes from development to production. Include governance, testing gates, and rollback procedures.]]
|
||||
|
||||
- Development to Production Pipeline
|
||||
- Deployment Stages and Gates
|
||||
- Approval Workflows and Authorities
|
||||
- Rollback Procedures
|
||||
- Change Cadence and Release Windows
|
||||
- Environment-Specific Configuration Management
|
||||
|
||||
## Network Architecture
|
||||
|
||||
[[LLM: Design network topology considering security zones, traffic patterns, and compliance requirements. Reference main architecture for service communication patterns.
|
||||
|
||||
Create Mermaid diagram showing:
|
||||
- VPC/Network structure
|
||||
- Security zones and boundaries
|
||||
- Traffic flow patterns
|
||||
- Load balancer placement
|
||||
- Service mesh topology (if applicable)]]
|
||||
|
||||
- VPC/VNET Design
|
||||
- Subnet Strategy
|
||||
- Security Groups & NACLs
|
||||
- Load Balancers & API Gateways
|
||||
- Service Mesh (if applicable)
|
||||
|
||||
```mermaid
|
||||
graph TB
|
||||
subgraph "Production VPC"
|
||||
subgraph "Public Subnets"
|
||||
ALB[Application Load Balancer]
|
||||
end
|
||||
subgraph "Private Subnets"
|
||||
EKS[EKS Cluster]
|
||||
RDS[(RDS Database)]
|
||||
end
|
||||
end
|
||||
Internet((Internet)) --> ALB
|
||||
ALB --> EKS
|
||||
EKS --> RDS
|
||||
```
|
||||
|
||||
^^CONDITION: uses_service_mesh^^
|
||||
|
||||
### Service Mesh Architecture
|
||||
|
||||
- **Mesh Technology:** {{service_mesh_tech}}
|
||||
- **Traffic Management:** {{traffic_policies}}
|
||||
- **Security Policies:** {{mesh_security}}
|
||||
- **Observability Integration:** {{mesh_observability}}
|
||||
|
||||
^^/CONDITION: uses_service_mesh^^
|
||||
|
||||
## Compute Resources
|
||||
|
||||
[[LLM: Select compute strategy based on application architecture (microservices, serverless, monolithic). Consider cost, scalability, and operational complexity.]]
|
||||
|
||||
- Container Strategy
|
||||
- Serverless Architecture
|
||||
- VM/Instance Configuration
|
||||
- Auto-scaling Approach
|
||||
|
||||
^^CONDITION: uses_kubernetes^^
|
||||
|
||||
### Kubernetes Architecture
|
||||
|
||||
- **Cluster Configuration:** {{k8s_cluster_config}}
|
||||
- **Node Groups:** {{k8s_node_groups}}
|
||||
- **Networking:** {{k8s_networking}}
|
||||
- **Storage Classes:** {{k8s_storage}}
|
||||
- **Security Policies:** {{k8s_security}}
|
||||
|
||||
^^/CONDITION: uses_kubernetes^^
|
||||
|
||||
## Data Resources
|
||||
|
||||
[[LLM: Design data infrastructure based on data architecture from main system design. Consider data volumes, access patterns, compliance, and recovery requirements.
|
||||
|
||||
Create data flow diagram showing:
|
||||
- Database topology
|
||||
- Replication patterns
|
||||
- Backup flows
|
||||
- Data migration paths]]
|
||||
|
||||
- Database Deployment Strategy
|
||||
- Backup & Recovery
|
||||
- Replication & Failover
|
||||
- Data Migration Strategy
|
||||
|
||||
## Security Architecture
|
||||
|
||||
[[LLM: Implement defense-in-depth strategy. Reference security requirements from PRD and compliance needs. Consider zero-trust principles where applicable.]]
|
||||
|
||||
- IAM & Authentication
|
||||
- Network Security
|
||||
- Data Encryption
|
||||
- Compliance Controls
|
||||
- Security Scanning & Monitoring
|
||||
|
||||
<critical_rule>Apply principle of least privilege for all access controls. Document all security exceptions with business justification.</critical_rule>
|
||||
|
||||
## Shared Responsibility Model
|
||||
|
||||
[[LLM: Clearly define boundaries between cloud provider, platform team, development team, and security team responsibilities. This is critical for operational success.]]
|
||||
|
||||
- Cloud Provider Responsibilities
|
||||
- Platform Team Responsibilities
|
||||
- Development Team Responsibilities
|
||||
- Security Team Responsibilities
|
||||
- Operational Monitoring Ownership
|
||||
- Incident Response Accountability Matrix
|
||||
|
||||
@{example: responsibility_matrix}
|
||||
|
||||
| Component | Cloud Provider | Platform Team | Dev Team | Security Team |
|
||||
|-----------|---------------|---------------|----------|---------------|
|
||||
| Physical Security | ✓ | - | - | Audit |
|
||||
| Network Security | Partial | ✓ | Config | Audit |
|
||||
| Application Security | - | Tools | ✓ | Review |
|
||||
| Data Encryption | Engine | Config | Implementation | Standards |
|
||||
|
||||
@{/example}
|
||||
|
||||
## Monitoring & Observability
|
||||
|
||||
[[LLM: Design comprehensive observability strategy covering metrics, logs, traces, and business KPIs. Ensure alignment with SLA/SLO requirements.]]
|
||||
|
||||
- Metrics Collection
|
||||
- Logging Strategy
|
||||
- Tracing Implementation
|
||||
- Alerting & Incident Response
|
||||
- Dashboards & Visualization
|
||||
|
||||
## CI/CD Pipeline
|
||||
|
||||
[[LLM: Design deployment pipeline that balances speed with safety. Include progressive deployment strategies and automated quality gates.
|
||||
|
||||
Create pipeline diagram showing:
|
||||
- Build stages
|
||||
- Test gates
|
||||
- Deployment stages
|
||||
- Approval points
|
||||
- Rollback triggers]]
|
||||
|
||||
- Pipeline Architecture
|
||||
- Build Process
|
||||
- Deployment Strategy
|
||||
- Rollback Procedures
|
||||
- Approval Gates
|
||||
|
||||
^^CONDITION: uses_progressive_deployment^^
|
||||
|
||||
### Progressive Deployment Strategy
|
||||
|
||||
- **Canary Deployment:** {{canary_config}}
|
||||
- **Blue-Green Deployment:** {{blue_green_config}}
|
||||
- **Feature Flags:** {{feature_flag_integration}}
|
||||
- **Traffic Splitting:** {{traffic_split_rules}}
|
||||
|
||||
^^/CONDITION: uses_progressive_deployment^^
|
||||
|
||||
## Disaster Recovery
|
||||
|
||||
[[LLM: Design DR strategy based on business continuity requirements. Define clear RTO/RPO targets and ensure they align with business needs.]]
|
||||
|
||||
- Backup Strategy
|
||||
- Recovery Procedures
|
||||
- RTO & RPO Targets
|
||||
- DR Testing Approach
|
||||
|
||||
<critical_rule>DR procedures must be tested at least quarterly. Document test results and improvement actions.</critical_rule>
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
[[LLM: Balance cost efficiency with performance and reliability requirements. Include both immediate optimizations and long-term strategies.]]
|
||||
|
||||
- Resource Sizing Strategy
|
||||
- Reserved Instances/Commitments
|
||||
- Cost Monitoring & Reporting
|
||||
- Optimization Recommendations
|
||||
|
||||
## BMAD Integration Architecture
|
||||
|
||||
[[LLM: Design infrastructure to specifically support other BMAD agents and their workflows. This ensures the infrastructure enables the entire BMAD methodology.]]
|
||||
|
||||
### Development Agent Support
|
||||
- Container platform for development environments
|
||||
- GitOps workflows for application deployment
|
||||
- Service mesh integration for development testing
|
||||
- Developer self-service platform capabilities
|
||||
|
||||
### Product & Architecture Alignment
|
||||
- Infrastructure implementing PRD scalability requirements
|
||||
- Deployment automation supporting product iteration speed
|
||||
- Service reliability meeting product SLAs
|
||||
- Architecture patterns properly implemented in infrastructure
|
||||
|
||||
### Cross-Agent Integration Points
|
||||
- CI/CD pipelines supporting Frontend, Backend, and Full Stack development workflows
|
||||
- Monitoring and observability data accessible to QA and DevOps agents
|
||||
- Infrastructure enabling Design Architect's UI/UX performance requirements
|
||||
- Platform supporting Analyst's data collection and analysis needs
|
||||
|
||||
## DevOps/Platform Feasibility Review
|
||||
|
||||
[[LLM: CRITICAL STEP - Present architectural blueprint summary to DevOps/Platform Engineering Agent for feasibility review. Request specific feedback on:
|
||||
|
||||
- **Operational Complexity:** Are the proposed patterns implementable with current tooling and expertise?
|
||||
- **Resource Constraints:** Do infrastructure requirements align with available resources and budgets?
|
||||
- **Security Implementation:** Are security patterns achievable with current security toolchain?
|
||||
- **Operational Overhead:** Will the proposed architecture create excessive operational burden?
|
||||
- **Technology Constraints:** Are selected technologies compatible with existing infrastructure?
|
||||
|
||||
Document all feasibility feedback and concerns raised. Iterate on architectural decisions based on operational constraints and feedback.
|
||||
|
||||
<critical_rule>Address all critical feasibility concerns before proceeding to final architecture documentation. If critical blockers identified, revise architecture before continuing.</critical_rule>]]
|
||||
|
||||
### Feasibility Assessment Results
|
||||
|
||||
- **Green Light Items:** {{feasible_items}}
|
||||
- **Yellow Light Items:** {{items_needing_adjustment}}
|
||||
- **Red Light Items:** {{items_requiring_redesign}}
|
||||
- **Mitigation Strategies:** {{mitigation_plans}}
|
||||
|
||||
## Infrastructure Verification
|
||||
|
||||
### Validation Framework
|
||||
|
||||
This infrastructure architecture will be validated using the comprehensive `infrastructure-checklist.md`, with particular focus on Section 12: Architecture Documentation Validation. The checklist ensures:
|
||||
|
||||
- Completeness of architecture documentation
|
||||
- Consistency with broader system architecture
|
||||
- Appropriate level of detail for different stakeholders
|
||||
- Clear implementation guidance
|
||||
- Future evolution considerations
|
||||
|
||||
### Validation Process
|
||||
|
||||
The architecture documentation validation should be performed:
|
||||
|
||||
- After initial architecture development
|
||||
- After significant architecture changes
|
||||
- Before major implementation phases
|
||||
- During periodic architecture reviews
|
||||
|
||||
The Platform Engineer should use the infrastructure checklist to systematically validate all aspects of this architecture document.
|
||||
|
||||
## Implementation Handoff
|
||||
|
||||
[[LLM: Create structured handoff documentation for implementation team. This ensures architecture decisions are properly communicated and implemented.]]
|
||||
|
||||
### Architecture Decision Records (ADRs)
|
||||
|
||||
Create ADRs for key infrastructure decisions:
|
||||
- Cloud provider selection rationale
|
||||
- Container orchestration platform choice
|
||||
- Networking architecture decisions
|
||||
- Security implementation choices
|
||||
- Cost optimization trade-offs
|
||||
|
||||
### Implementation Validation Criteria
|
||||
|
||||
Define specific criteria for validating correct implementation:
|
||||
- Infrastructure as Code quality gates
|
||||
- Security compliance checkpoints
|
||||
- Performance benchmarks
|
||||
- Cost targets
|
||||
- Operational readiness criteria
|
||||
|
||||
### Knowledge Transfer Requirements
|
||||
|
||||
- Technical documentation for operations team
|
||||
- Runbook creation requirements
|
||||
- Training needs for platform team
|
||||
- Handoff meeting agenda items
|
||||
|
||||
## Infrastructure Evolution
|
||||
|
||||
[[LLM: Document the long-term vision and evolution path for the infrastructure. Consider technology trends, anticipated growth, and technical debt management.]]
|
||||
|
||||
- Technical Debt Inventory
|
||||
- Planned Upgrades and Migrations
|
||||
- Deprecation Schedule
|
||||
- Technology Roadmap
|
||||
- Capacity Planning
|
||||
- Scalability Considerations
|
||||
|
||||
## Integration with Application Architecture
|
||||
|
||||
[[LLM: Map infrastructure components to application services. Ensure infrastructure design supports application requirements and patterns defined in main architecture.]]
|
||||
|
||||
- Service-to-Infrastructure Mapping
|
||||
- Application Dependency Matrix
|
||||
- Performance Requirements Implementation
|
||||
- Security Requirements Implementation
|
||||
- Data Flow to Infrastructure Correlation
|
||||
- API Gateway and Service Mesh Integration
|
||||
|
||||
## Cross-Team Collaboration
|
||||
|
||||
[[LLM: Define clear interfaces and communication patterns between teams. This section is critical for operational success and should include specific touchpoints and escalation paths.]]
|
||||
|
||||
- Platform Engineer and Developer Touchpoints
|
||||
- Frontend/Backend Integration Requirements
|
||||
- Product Requirements to Infrastructure Mapping
|
||||
- Architecture Decision Impact Analysis
|
||||
- Design Architect UI/UX Infrastructure Requirements
|
||||
- Analyst Research Integration
|
||||
|
||||
## Infrastructure Change Management
|
||||
|
||||
[[LLM: Define structured process for infrastructure changes. Include risk assessment, testing requirements, and rollback procedures.]]
|
||||
|
||||
- Change Request Process
|
||||
- Risk Assessment
|
||||
- Testing Strategy
|
||||
- Validation Procedures
|
||||
|
||||
[[LLM: Final Review - Ensure all sections are complete and consistent. Verify feasibility review was conducted and all concerns addressed. Apply final validation against infrastructure checklist.]]
|
||||
|
||||
---
|
||||
|
||||
*Document Version: 1.0*
|
||||
*Last Updated: {{current_date}}*
|
||||
*Next Review: {{review_date}}*
|
||||
Binary file not shown.
@@ -14,6 +14,13 @@
|
||||
|
||||
[[LLM: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is etc...]]
|
||||
|
||||
### Change Log
|
||||
|
||||
[[LLM: Track document versions and changes]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
## Requirements
|
||||
|
||||
[[LLM: Draft the list of functional and non functional requirements under the two child sections, and immediately execute tasks#advanced-elicitation display]]
|
||||
@@ -178,27 +185,16 @@ so that {{benefit}}.
|
||||
<</REPEAT>>
|
||||
<</REPEAT>>
|
||||
|
||||
## Change Log
|
||||
|
||||
| Change | Date | Version | Description | Author |
|
||||
| ------ | ---- | ------- | ----------- | ------ |
|
||||
|
||||
----- END PRD START CHECKLIST OUTPUT ------
|
||||
|
||||
## Checklist Results Report
|
||||
|
||||
[[LLM: Before running the checklist and drafting the prompts, offer to output the full updated PRD. If outputting it, confirm with the user that you will be proceeding to run the checklist and produce the report. Once the user confirms, execute the `pm-checklist` and populate the results in this section.]]
|
||||
|
||||
----- END Checklist START Design Architect `UI/UX Specification Mode` Prompt ------
|
||||
## Next Steps
|
||||
|
||||
## Design Architect Prompt
|
||||
### Design Architect Prompt
|
||||
|
||||
[[LLM: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.]]
|
||||
|
||||
----- END Design Architect `UI/UX Specification Mode` Prompt START Architect Prompt ------
|
||||
|
||||
## Architect Prompt
|
||||
### Architect Prompt
|
||||
|
||||
[[LLM: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.]]
|
||||
|
||||
----- END Architect Prompt ------
|
||||
|
||||
@@ -43,7 +43,9 @@
|
||||
|
||||
{Link to or summarize findings from any initial research conducted (e.g., `deep-research-report-BA.md`).}
|
||||
|
||||
## PM Prompt
|
||||
## Next Steps
|
||||
|
||||
### PM Prompt
|
||||
|
||||
This Project Brief provides the full context for {Project Name}. Please start in 'PRD Generation Mode', review the brief thoroughly to work with the user to create the PRD section by section as the template indicates, asking for any necessary clarification or suggesting improvements as your mode 1 programming allows.
|
||||
|
||||
|
||||
@@ -1,16 +1,16 @@
|
||||
# Story {EpicNum}.{StoryNum}: {Short Title Copied from Epic File}
|
||||
# Story {{EpicNum}}.{{StoryNum}}: {{Short Title Copied from Epic File}}
|
||||
|
||||
## Status: { Draft | Approved | InProgress | Review | Done }
|
||||
## Status: {{ Draft | Approved | InProgress | Review | Done }}
|
||||
|
||||
## Story
|
||||
|
||||
- As a [role]
|
||||
- I want [action]
|
||||
- so that [benefit]
|
||||
- As a {{role}}
|
||||
- I want {{action}}
|
||||
- so that {{benefit}}
|
||||
|
||||
## Acceptance Criteria (ACs)
|
||||
|
||||
{ Copy the Acceptance Criteria numbered list }
|
||||
{{ Copy the Acceptance Criteria numbered list }}
|
||||
|
||||
## Tasks / Subtasks
|
||||
|
||||
@@ -23,7 +23,7 @@
|
||||
|
||||
## Dev Technical Reference
|
||||
|
||||
-
|
||||
[[LLM: SM Agent populates relevant information, only what was pulled from actual artifacts from docs folder, relevant to this story. Do not invent information. If there were important notes from previous story that is relevant here, also include them here if it will help the dev agent. You do NOT need to repeat anything from coding standards or test standards as the dev agent is already aware of those. The dev agent should NEVER need to read the PRD or architecture documents though to complete this self contained story.]]
|
||||
|
||||
## Dev Agent Record
|
||||
|
||||
@@ -39,4 +39,7 @@
|
||||
|
||||
### Change Log
|
||||
|
||||
{List and requirements or tasks that changed from the original state of the story when development started}
|
||||
[[LLM: Track document versions and changes during development that deviate from story dev start]]
|
||||
|
||||
| Date | Version | Description | Author |
|
||||
| :--- | :------ | :---------- | :----- |
|
||||
|
||||
Reference in New Issue
Block a user