ros/BMAD-METHOD
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

core agents alignment

Browse Source
This commit is contained in:
Brian Madison
2025-07-12 20:16:05 -05:00
parent f32a5fe08a
commit 24a35ff2c4
16 changed files with 82 additions and 814 deletions
Download Patch File Download Diff File Expand all files Collapse all files

50
bmad-core/tasks/document-project.md
View File

@@ -8,9 +8,9 @@ Generate comprehensive documentation for existing projects optimized for AI deve
### 1. Initial Project Analysis
[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
**IF PRD EXISTS**:
**IF PRD EXISTS**:
- Review the PRD to understand what enhancement/feature is planned
- Identify which modules, services, or areas will be affected
@@ -56,11 +56,10 @@ Ask the user these elicitation questions to better understand their needs:
- Are there any existing documentation standards or formats you prefer?
- What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
- Is there a specific feature or enhancement you're planning? (This helps focus documentation)
]]
### 2. Deep Codebase Analysis
[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
1. **Explore Key Areas**:
- Entry points (main files, index files, app initializers)
@@ -83,13 +82,14 @@ Ask the user these elicitation questions to better understand their needs:
- Document workarounds and technical debt
- Note areas that differ from standard patterns
**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement
### 3. Core Documentation Generation
[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
**CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
- Technical debt and workarounds
- Inconsistent patterns between different parts
- Legacy code that can't be changed
@@ -101,13 +101,16 @@ Ask the user these elicitation questions to better understand their needs:
# [Project Name] Brownfield Architecture Document
## Introduction
This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
### Document Scope
[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
[If no PRD: "Comprehensive documentation of entire system"]
### Change Log
| Date | Version | Description | Author |
|------|---------|-------------|--------|
| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
@@ -115,6 +118,7 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
## Quick Reference - Key Files and Entry Points
### Critical Files for Understanding the System
- **Main Entry**: `src/index.js` (or actual entry point)
- **Configuration**: `config/app.config.js`, `.env.example`
- **Core Business Logic**: `src/services/`, `src/domain/`
@@ -123,22 +127,25 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
- **Key Algorithms**: [List specific files with complex logic]
### If PRD Provided - Enhancement Impact Areas
[Highlight which files/modules will be affected by the planned enhancement]
## High Level Architecture
### Technical Summary
[Real assessment of architecture - mention if it's well-structured or has issues]
### Actual Tech Stack (from package.json/requirements.txt)
| Category | Technology | Version | Notes |
|----------|------------|---------|--------|
| Runtime | Node.js | 16.x | [Any constraints] |
| Framework | Express | 4.18.2 | [Custom middleware?] |
| Database | PostgreSQL | 13 | [Connection pooling setup] |
| [etc...] |
etc...
### Repository Structure Reality Check
- Type: [Monorepo/Polyrepo/Hybrid]
- Package Manager: [npm/yarn/pnpm]
- Notable: [Any unusual structure decisions]
@@ -146,7 +153,8 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
## Source Tree and Module Organization
### Project Structure (Actual)
```
```text
project-root/
├── src/
│ ├── controllers/ # HTTP request handlers
@@ -160,6 +168,7 @@ project-root/
```
### Key Modules and Their Purpose
- **User Management**: `src/services/userService.js` - Handles all user operations
- **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
- **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
@@ -168,12 +177,14 @@ project-root/
## Data Models and APIs
### Data Models
Instead of duplicating, reference actual model files:
- **User Model**: See `src/models/User.js`
- **Order Model**: See `src/models/Order.js`
- **Related Types**: TypeScript definitions in `src/types/`
### API Specifications
- **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
- **Postman Collection**: `docs/api/postman-collection.json`
- **Manual Endpoints**: [List any undocumented endpoints discovered]
@@ -181,12 +192,14 @@ Instead of duplicating, reference actual model files:
## Technical Debt and Known Issues
### Critical Technical Debt
1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
2. **User Service**: Different pattern than other services, uses callbacks instead of promises
3. **Database Migrations**: Manually tracked, no proper migration tool
4. **[Other significant debt]**
### Workarounds and Gotchas
- **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
- **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
- **[Other workarounds developers need to know]**
@@ -194,13 +207,16 @@ Instead of duplicating, reference actual model files:
## Integration Points and External Dependencies
### External Services
| Service | Purpose | Integration Type | Key Files |
|---------|---------|------------------|-----------|
| Stripe | Payments | REST API | `src/integrations/stripe/` |
| SendGrid | Emails | SDK | `src/services/emailService.js` |
| [etc...] |
etc...
### Internal Integration Points
- **Frontend Communication**: REST API on port 3000, expects specific headers
- **Background Jobs**: Redis queue, see `src/workers/`
- **[Other integrations]**
@@ -208,11 +224,13 @@ Instead of duplicating, reference actual model files:
## Development and Deployment
### Local Development Setup
1. Actual steps that work (not ideal steps)
2. Known issues with setup
3. Required environment variables (see `.env.example`)
### Build and Deployment Process
- **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
- **Deployment**: Manual deployment via `scripts/deploy.sh`
- **Environments**: Dev, Staging, Prod (see `config/environments/`)
@@ -220,12 +238,14 @@ Instead of duplicating, reference actual model files:
## Testing Reality
### Current Test Coverage
- Unit Tests: 60% coverage (Jest)
- Integration Tests: Minimal, in `tests/integration/`
- E2E Tests: None
- Manual Testing: Primary QA method
### Running Tests
```bash
npm test # Runs unit tests
npm run test:integration # Runs integration tests (requires local DB)
@@ -234,6 +254,7 @@ npm run test:integration # Runs integration tests (requires local DB)
## If Enhancement PRD Provided - Impact Analysis
### Files That Will Need Modification
Based on the enhancement requirements, these files will be affected:
- `src/services/userService.js` - Add new user fields
- `src/models/User.js` - Update schema
@@ -241,11 +262,13 @@ Based on the enhancement requirements, these files will be affected:
- [etc...]
### New Files/Modules Needed
- `src/services/newFeatureService.js` - New business logic
- `src/models/NewFeature.js` - New data model
- [etc...]
### Integration Considerations
- Will need to integrate with existing auth middleware
- Must follow existing response format in `src/utils/responseFormatter.js`
- [Other integration points]
@@ -253,6 +276,7 @@ Based on the enhancement requirements, these files will be affected:
## Appendix - Useful Commands and Scripts
### Frequently Used Commands
```bash
npm run dev # Start development server
npm run build # Production build
@@ -261,14 +285,13 @@ npm run seed # Seed test data
```
### Debugging and Troubleshooting
- **Logs**: Check `logs/app.log` for application logs
- **Debug Mode**: Set `DEBUG=app:*` for verbose logging
- **Common Issues**: See `docs/troubleshooting.md`]]
### 4. Document Delivery
[[LLM: After generating the complete architecture document:
1. **In Web UI (Gemini, ChatGPT, Claude)**:
- Present the entire document in one response (or multiple if too long)
- Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
@@ -280,6 +303,7 @@ npm run seed # Seed test data
- Can be sharded later using PO agent if desired
The document should be comprehensive enough that future agents can understand:
- The actual state of the system (not idealized)
- Where to find key files and logic
- What technical debt exists
@@ -288,7 +312,7 @@ The document should be comprehensive enough that future agents can understand:
### 5. Quality Assurance
[[LLM: Before finalizing the document:
CRITICAL: Before finalizing the document:
1. **Accuracy Check**: Verify all technical details match the actual codebase
2. **Completeness Review**: Ensure all major system components are documented
@@ -296,7 +320,7 @@ The document should be comprehensive enough that future agents can understand:
4. **Clarity Assessment**: Check that explanations are clear for AI agents
5. **Navigation**: Ensure document has clear section structure for easy reference
Apply the advanced elicitation task after major sections to refine based on user feedback.]]
Apply the advanced elicitation task after major sections to refine based on user feedback.
## Success Criteria