fix: add updated web builds
This commit is contained in:
Brian Madison
411
dist/agents/analyst.txt
vendored
411
dist/agents/analyst.txt
vendored
@@ -54,7 +54,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -82,6 +82,7 @@ commands:
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -89,6 +90,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
@@ -817,6 +819,326 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
|
||||
[[LLM: Acknowledge the user's choice to finalize the current work, accept the AI's last output as is, or move on to the next step without selecting another action from this list. Prepare to proceed accordingly.]]
|
||||
==================== END: tasks#advanced-elicitation ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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:
|
||||
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- 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]]
|
||||
|
||||
### 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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
**Document Structure**:
|
||||
|
||||
# [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] |
|
||||
|
||||
## 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **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...] |
|
||||
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
## Source Tree and Module Organization
|
||||
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#project-brief-tmpl ====================
|
||||
# Project Brief: {{Project Name}}
|
||||
|
||||
@@ -2013,10 +2335,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -2120,25 +2448,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
|
||||
594
dist/agents/architect.txt
vendored
594
dist/agents/architect.txt
vendored
@@ -494,7 +494,39 @@ Generate comprehensive documentation for existing projects optimized for AI deve
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
[[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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
@@ -509,370 +541,266 @@ Ask the user these elicitation questions to better understand their needs:
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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. Core Documentation Generation
|
||||
### 2. Deep Codebase Analysis
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- Document workarounds and technical debt
|
||||
- Note areas that differ from standard patterns
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
### 3. Core Documentation Generation
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
**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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
**Document Structure**:
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
# [Project Name] Brownfield Architecture Document
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
## 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.
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
### Document Scope
|
||||
[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
|
||||
[If no PRD: "Comprehensive documentation of entire system"]
|
||||
|
||||
### 3. Document Structure Template
|
||||
### Change Log
|
||||
| Date | Version | Description | Author |
|
||||
|------|---------|-------------|--------|
|
||||
| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
## Quick Reference - Key Files and Entry Points
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
### 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **Key Algorithms**: [List specific files with complex logic]
|
||||
|
||||
## Overview
|
||||
### If PRD Provided - Enhancement Impact Areas
|
||||
[Highlight which files/modules will be affected by the planned enhancement]
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
## High Level Architecture
|
||||
|
||||
## Quick Reference
|
||||
### Technical Summary
|
||||
[Real assessment of architecture - mention if it's well-structured or has issues]
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
### 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...] |
|
||||
|
||||
## Detailed Information
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
## Source Tree and Module Organization
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: tasks#execute-checklist ====================
|
||||
|
||||
681
dist/agents/bmad-master.txt
vendored
681
dist/agents/bmad-master.txt
vendored
@@ -1333,7 +1333,39 @@ Generate comprehensive documentation for existing projects optimized for AI deve
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
[[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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
@@ -1348,370 +1380,266 @@ Ask the user these elicitation questions to better understand their needs:
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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. Core Documentation Generation
|
||||
### 2. Deep Codebase Analysis
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- Document workarounds and technical debt
|
||||
- Note areas that differ from standard patterns
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
### 3. Core Documentation Generation
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
**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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
**Document Structure**:
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
# [Project Name] Brownfield Architecture Document
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
## 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.
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
### Document Scope
|
||||
[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
|
||||
[If no PRD: "Comprehensive documentation of entire system"]
|
||||
|
||||
### 3. Document Structure Template
|
||||
### Change Log
|
||||
| Date | Version | Description | Author |
|
||||
|------|---------|-------------|--------|
|
||||
| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
## Quick Reference - Key Files and Entry Points
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
### 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **Key Algorithms**: [List specific files with complex logic]
|
||||
|
||||
## Overview
|
||||
### If PRD Provided - Enhancement Impact Areas
|
||||
[Highlight which files/modules will be affected by the planned enhancement]
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
## High Level Architecture
|
||||
|
||||
## Quick Reference
|
||||
### Technical Summary
|
||||
[Real assessment of architecture - mention if it's well-structured or has issues]
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
### 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...] |
|
||||
|
||||
## Detailed Information
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
## Source Tree and Module Organization
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: tasks#create-next-story ====================
|
||||
@@ -8874,10 +8802,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -8981,25 +8915,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
|
||||
87
dist/agents/bmad-orchestrator.txt
vendored
87
dist/agents/bmad-orchestrator.txt
vendored
@@ -811,10 +811,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -918,25 +924,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
|
||||
@@ -70,7 +70,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -98,6 +98,7 @@ commands:
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -105,6 +106,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
@@ -1161,6 +1163,326 @@ The questions and perspectives offered should always consider:
|
||||
- Game development best practices and common pitfalls
|
||||
==================== END: tasks#advanced-elicitation ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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:
|
||||
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- 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]]
|
||||
|
||||
### 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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
**Document Structure**:
|
||||
|
||||
# [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] |
|
||||
|
||||
## 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **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...] |
|
||||
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
## Source Tree and Module Organization
|
||||
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#project-brief-tmpl ====================
|
||||
# Project Brief: {{Project Name}}
|
||||
|
||||
|
||||
803
dist/teams/team-all.txt
vendored
803
dist/teams/team-all.txt
vendored
@@ -196,7 +196,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -224,6 +224,7 @@ commands:
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -231,6 +232,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
@@ -1301,10 +1303,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -1408,25 +1416,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -2397,6 +2450,326 @@ Present these numbered options to the user:
|
||||
- Plan for iterative refinement based on initial findings
|
||||
==================== END: tasks#create-deep-research-prompt ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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:
|
||||
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- 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]]
|
||||
|
||||
### 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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
**Document Structure**:
|
||||
|
||||
# [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] |
|
||||
|
||||
## 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **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...] |
|
||||
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
## Source Tree and Module Organization
|
||||
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#project-brief-tmpl ====================
|
||||
# Project Brief: {{Project Name}}
|
||||
|
||||
@@ -3190,398 +3563,6 @@ These replace the standard elicitation options when working on market research d
|
||||
These replace the standard elicitation options when working on competitive analysis documents.]]
|
||||
==================== END: templates#competitor-analysis-tmpl ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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)
|
||||
]]
|
||||
|
||||
### 2. Core Documentation Generation
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
|
||||
### 3. Document Structure Template
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
|
||||
## Overview
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
|
||||
## Quick Reference
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
|
||||
## Detailed Information
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: tasks#execute-checklist ====================
|
||||
# Checklist Validation Task
|
||||
|
||||
|
||||
803
dist/teams/team-fullstack.txt
vendored
803
dist/teams/team-fullstack.txt
vendored
@@ -200,7 +200,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -228,6 +228,7 @@ commands:
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -235,6 +236,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
@@ -1145,10 +1147,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -1252,25 +1260,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -2241,6 +2294,326 @@ Present these numbered options to the user:
|
||||
- Plan for iterative refinement based on initial findings
|
||||
==================== END: tasks#create-deep-research-prompt ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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:
|
||||
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- 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]]
|
||||
|
||||
### 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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
**Document Structure**:
|
||||
|
||||
# [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] |
|
||||
|
||||
## 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **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...] |
|
||||
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
## Source Tree and Module Organization
|
||||
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#project-brief-tmpl ====================
|
||||
# Project Brief: {{Project Name}}
|
||||
|
||||
@@ -5206,398 +5579,6 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
|
||||
[[LLM: If a UI/UX checklist exists, run it against this document and report results here.]]
|
||||
==================== END: templates#front-end-spec-tmpl ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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)
|
||||
]]
|
||||
|
||||
### 2. Core Documentation Generation
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
|
||||
### 3. Document Structure Template
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
|
||||
## Overview
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
|
||||
## Quick Reference
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
|
||||
## Detailed Information
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#architecture-tmpl ====================
|
||||
# {{Project Name}} Architecture Document
|
||||
|
||||
|
||||
87
dist/teams/team-ide-minimal.txt
vendored
87
dist/teams/team-ide-minimal.txt
vendored
@@ -1047,10 +1047,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -1154,25 +1160,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
|
||||
803
dist/teams/team-no-ui.txt
vendored
803
dist/teams/team-no-ui.txt
vendored
@@ -195,7 +195,7 @@ agent:
|
||||
id: analyst
|
||||
title: Business Analyst
|
||||
icon: 📊
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
|
||||
whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
|
||||
customization: null
|
||||
persona:
|
||||
role: Insightful Analyst & Strategic Ideation Partner
|
||||
@@ -223,6 +223,7 @@ commands:
|
||||
- brainstorm {topic}: Facilitate structured brainstorming session
|
||||
- research {topic}: Generate deep research prompt for investigation
|
||||
- elicit: Run advanced elicitation to clarify requirements
|
||||
- document-project: Analyze and document existing project structure comprehensively
|
||||
- exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
|
||||
dependencies:
|
||||
tasks:
|
||||
@@ -230,6 +231,7 @@ dependencies:
|
||||
- create-deep-research-prompt
|
||||
- create-doc
|
||||
- advanced-elicitation
|
||||
- document-project
|
||||
templates:
|
||||
- project-brief-tmpl
|
||||
- market-research-tmpl
|
||||
@@ -1077,10 +1079,16 @@ This architecture enables seamless operation across environments while maintaini
|
||||
|
||||
## Complete Development Workflow
|
||||
|
||||
### Planning Phase (Web UI Recommended)
|
||||
### Planning Phase (Web UI Recommended - Especially Gemini!)
|
||||
|
||||
**Ideal for cost efficiency, especially with Gemini:**
|
||||
**Ideal for cost efficiency with Gemini's massive context:**
|
||||
|
||||
**For Brownfield Projects - Start Here!**:
|
||||
1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Document existing system**: `/analyst` → `*document-project`
|
||||
3. **Creates comprehensive docs** from entire codebase analysis
|
||||
|
||||
**For All Projects**:
|
||||
1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
|
||||
2. **Project Brief**: Create foundation document (Analyst or user)
|
||||
3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
|
||||
@@ -1184,25 +1192,70 @@ Each status change requires user verification and approval before proceeding.
|
||||
|
||||
#### Brownfield Enhancement (Existing Projects)
|
||||
|
||||
**Key Concept**: Brownfield development requires generating good documentation for agents to understand your existing project.
|
||||
**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
|
||||
|
||||
**Recommended Approach**:
|
||||
1. **Analysis Phase**: Use Gemini Web or AI Studio with their 1M+ context windows
|
||||
2. **Document Generation**: Ask Architect agent to analyze your project and run `document-project` task
|
||||
3. **PRD Creation**: Even brownfield projects typically need a PRD unless:
|
||||
- Very small, focused changes
|
||||
- Using `brownfield-create-epic` for single epic without full PRD
|
||||
4. **Architecture Assessment**: Use brownfield-specific templates for complex enhancements
|
||||
**Complete Brownfield Workflow Options**:
|
||||
|
||||
**Brownfield Templates Available**:
|
||||
- `brownfield-prd-tmpl.md`: For substantial enhancements requiring multiple stories
|
||||
- `brownfield-architecture-tmpl.md`: For complex changes impacting system architecture
|
||||
- Both templates emphasize compatibility and integration with existing systems
|
||||
**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
|
||||
1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
|
||||
2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
|
||||
3. **Focused documentation**: `@analyst` → `*document-project`
|
||||
- Analyst asks for focus if no PRD provided
|
||||
- Choose "single document" format for Web UI
|
||||
- Uses PRD to document ONLY relevant areas
|
||||
- Creates one comprehensive markdown file
|
||||
- Avoids bloating docs with unused code
|
||||
|
||||
**When to Skip PRD**:
|
||||
- For focused, single-epic work, use `brownfield-create-epic` task with detailed guidance
|
||||
- For one-off stories without larger context
|
||||
- Note: These tasks will evolve to require some documentation (potentially from `document-project`)
|
||||
**Option 2: Document-First (Good for Smaller Projects)**:
|
||||
1. **Upload project to Gemini Web**
|
||||
2. **Document everything**: `@analyst` → `*document-project`
|
||||
3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
|
||||
- More thorough but can create excessive documentation
|
||||
|
||||
2. **Requirements Gathering**:
|
||||
- **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
|
||||
- **Analyzes**: Existing system, constraints, integration points
|
||||
- **Defines**: Enhancement scope, compatibility requirements, risk assessment
|
||||
- **Creates**: Epic and story structure for changes
|
||||
|
||||
3. **Architecture Planning**:
|
||||
- **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
|
||||
- **Integration Strategy**: How new features integrate with existing system
|
||||
- **Migration Planning**: Gradual rollout and backwards compatibility
|
||||
- **Risk Mitigation**: Addressing potential breaking changes
|
||||
|
||||
**Brownfield-Specific Resources**:
|
||||
|
||||
**Templates**:
|
||||
- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
|
||||
- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
|
||||
|
||||
**Tasks**:
|
||||
- `document-project`: Generates comprehensive documentation from existing codebase
|
||||
- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
|
||||
- `brownfield-create-story`: Creates individual story for small, isolated changes
|
||||
|
||||
**When to Use Each Approach**:
|
||||
|
||||
**Full Brownfield Workflow** (Recommended for):
|
||||
- Major feature additions
|
||||
- System modernization
|
||||
- Complex integrations
|
||||
- Multiple related changes
|
||||
|
||||
**Quick Epic/Story Creation** (Use when):
|
||||
- Single, focused enhancement
|
||||
- Isolated bug fixes
|
||||
- Small feature additions
|
||||
- Well-documented existing system
|
||||
|
||||
**Critical Success Factors**:
|
||||
1. **Documentation First**: Always run `document-project` if docs are outdated/missing
|
||||
2. **Context Matters**: Provide agents access to relevant code sections
|
||||
3. **Integration Focus**: Emphasize compatibility and non-breaking changes
|
||||
4. **Incremental Approach**: Plan for gradual rollout and testing
|
||||
|
||||
**For detailed guide**: See `docs/working-in-the-brownfield.md`
|
||||
|
||||
## Document Creation Best Practices
|
||||
|
||||
@@ -2173,6 +2226,326 @@ Present these numbered options to the user:
|
||||
- Plan for iterative refinement based on initial findings
|
||||
==================== END: tasks#create-deep-research-prompt ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 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.
|
||||
|
||||
**IF PRD EXISTS**:
|
||||
|
||||
- Review the PRD to understand what enhancement/feature is planned
|
||||
- Identify which modules, services, or areas will be affected
|
||||
- Focus documentation ONLY on these relevant areas
|
||||
- Skip unrelated parts of the codebase to keep docs lean
|
||||
|
||||
**IF NO PRD EXISTS**:
|
||||
Ask the user:
|
||||
|
||||
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
|
||||
|
||||
1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
|
||||
|
||||
2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
|
||||
|
||||
3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
|
||||
- 'Adding payment processing to the user service'
|
||||
- 'Refactoring the authentication module'
|
||||
- 'Integrating with a new third-party API'
|
||||
|
||||
4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
|
||||
|
||||
Please let me know your preference, or I can proceed with full documentation if you prefer."
|
||||
|
||||
Based on their response:
|
||||
|
||||
- If they choose option 1-3: Use that context to focus documentation
|
||||
- If they choose option 4 or decline: Proceed with comprehensive analysis below
|
||||
|
||||
Begin by conducting analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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:
|
||||
|
||||
1. **Explore Key Areas**:
|
||||
- Entry points (main files, index files, app initializers)
|
||||
- Configuration files and environment setup
|
||||
- Package dependencies and versions
|
||||
- Build and deployment configurations
|
||||
- Test suites and coverage
|
||||
|
||||
2. **Ask Clarifying Questions**:
|
||||
- "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
|
||||
- "What are the most critical/complex parts of this system that developers struggle with?"
|
||||
- "Are there any undocumented 'tribal knowledge' areas I should capture?"
|
||||
- "What technical debt or known issues should I document?"
|
||||
- "Which parts of the codebase change most frequently?"
|
||||
|
||||
3. **Map the Reality**:
|
||||
- Identify ACTUAL patterns used (not theoretical best practices)
|
||||
- Find where key business logic lives
|
||||
- Locate integration points and external dependencies
|
||||
- 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]]
|
||||
|
||||
### 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
|
||||
- Integration constraints
|
||||
- Performance bottlenecks
|
||||
|
||||
**Document Structure**:
|
||||
|
||||
# [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] |
|
||||
|
||||
## 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/`
|
||||
- **API Definitions**: `src/routes/` or link to OpenAPI spec
|
||||
- **Database Models**: `src/models/` or link to schema files
|
||||
- **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...] |
|
||||
|
||||
### Repository Structure Reality Check
|
||||
- Type: [Monorepo/Polyrepo/Hybrid]
|
||||
- Package Manager: [npm/yarn/pnpm]
|
||||
- Notable: [Any unusual structure decisions]
|
||||
|
||||
## Source Tree and Module Organization
|
||||
|
||||
### Project Structure (Actual)
|
||||
```
|
||||
project-root/
|
||||
├── src/
|
||||
│ ├── controllers/ # HTTP request handlers
|
||||
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
|
||||
│ ├── models/ # Database models (Sequelize)
|
||||
│ ├── utils/ # Mixed bag - needs refactoring
|
||||
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
|
||||
├── tests/ # Jest tests (60% coverage)
|
||||
├── scripts/ # Build and deployment scripts
|
||||
└── config/ # Environment configs
|
||||
```
|
||||
|
||||
### 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
|
||||
- **[List other key modules with their actual files]**
|
||||
|
||||
## 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]
|
||||
|
||||
## 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]**
|
||||
|
||||
## 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...] |
|
||||
|
||||
### Internal Integration Points
|
||||
- **Frontend Communication**: REST API on port 3000, expects specific headers
|
||||
- **Background Jobs**: Redis queue, see `src/workers/`
|
||||
- **[Other integrations]**
|
||||
|
||||
## 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/`)
|
||||
|
||||
## 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)
|
||||
```
|
||||
|
||||
## 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
|
||||
- `src/routes/userRoutes.js` - New endpoints
|
||||
- [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]
|
||||
|
||||
## Appendix - Useful Commands and Scripts
|
||||
|
||||
### Frequently Used Commands
|
||||
```bash
|
||||
npm run dev # Start development server
|
||||
npm run build # Production build
|
||||
npm run migrate # Run database migrations
|
||||
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`
|
||||
- Mention it can be sharded later in IDE if needed
|
||||
|
||||
2. **In IDE Environment**:
|
||||
- Create the document as `docs/brownfield-architecture.md`
|
||||
- Inform user this single document contains all architectural information
|
||||
- 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
|
||||
- What constraints must be respected
|
||||
- If PRD provided: What needs to change for the enhancement]]
|
||||
|
||||
### 5. Quality Assurance
|
||||
|
||||
[[LLM: 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
|
||||
3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
|
||||
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.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Single comprehensive brownfield architecture document created
|
||||
- Document reflects REALITY including technical debt and workarounds
|
||||
- Key files and modules are referenced with actual paths
|
||||
- Models/APIs reference source files rather than duplicating content
|
||||
- If PRD provided: Clear impact analysis showing what needs to change
|
||||
- Document enables AI agents to navigate and understand the actual codebase
|
||||
- Technical constraints and "gotchas" are clearly documented
|
||||
|
||||
## Notes
|
||||
|
||||
- This task creates ONE document that captures the TRUE state of the system
|
||||
- References actual files rather than duplicating content when possible
|
||||
- Documents technical debt, workarounds, and constraints honestly
|
||||
- For brownfield projects with PRD: Provides clear enhancement impact analysis
|
||||
- The goal is PRACTICAL documentation for AI agents doing real work
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#project-brief-tmpl ====================
|
||||
# Project Brief: {{Project Name}}
|
||||
|
||||
@@ -4668,398 +5041,6 @@ Keep it action-oriented and forward-looking.]]
|
||||
None Listed
|
||||
==================== END: data#technical-preferences ====================
|
||||
|
||||
==================== START: tasks#document-project ====================
|
||||
# Document an Existing Project
|
||||
|
||||
## Purpose
|
||||
|
||||
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
|
||||
|
||||
## Task Instructions
|
||||
|
||||
### 1. Initial Project Analysis
|
||||
|
||||
[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
|
||||
|
||||
1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
|
||||
2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
|
||||
3. **Build System Analysis**: Find build scripts, CI/CD configurations, and development commands
|
||||
4. **Existing Documentation Review**: Check for README files, docs folders, and any existing documentation
|
||||
5. **Code Pattern Analysis**: Sample key files to understand coding patterns, naming conventions, and architectural approaches
|
||||
|
||||
Ask the user these elicitation questions to better understand their needs:
|
||||
|
||||
- What is the primary purpose of this project?
|
||||
- Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
|
||||
- What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
|
||||
- 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)
|
||||
]]
|
||||
|
||||
### 2. Core Documentation Generation
|
||||
|
||||
[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
|
||||
|
||||
**Core Documents (always generate):**
|
||||
|
||||
1. **docs/index.md** - Master documentation index
|
||||
2. **docs/architecture/index.md** - Architecture documentation index
|
||||
3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
|
||||
4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
|
||||
5. **docs/architecture/unified-project-structure.md** - Project structure and organization
|
||||
6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
|
||||
|
||||
**Backend Documents (generate for backend/full-stack projects):**
|
||||
|
||||
7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
|
||||
8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
|
||||
9. **docs/architecture/data-models.md** - Data structures and validation rules
|
||||
10. **docs/architecture/database-schema.md** - Database design and relationships
|
||||
11. **docs/architecture/external-apis.md** - Third-party integrations
|
||||
|
||||
**Frontend Documents (generate for frontend/full-stack projects):**
|
||||
|
||||
12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
|
||||
13. **docs/architecture/components.md** - UI component specifications
|
||||
14. **docs/architecture/core-workflows.md** - User interaction flows
|
||||
15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
|
||||
|
||||
**Additional Documents (generate if applicable):**
|
||||
|
||||
16. **docs/prd.md** - Product requirements document (if not exists)
|
||||
17. **docs/architecture/deployment-guide.md** - Deployment and operations info
|
||||
18. **docs/architecture/security-considerations.md** - Security patterns and requirements
|
||||
19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
|
||||
|
||||
**Optional Enhancement Documents:**
|
||||
|
||||
20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
|
||||
21. **docs/architecture/changelog-conventions.md** - Change management practices
|
||||
22. **docs/architecture/code-review-checklist.md** - Review standards and practices
|
||||
|
||||
Present each document section by section, using the advanced elicitation task after each major section.]]
|
||||
|
||||
### 3. Document Structure Template
|
||||
|
||||
[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
|
||||
|
||||
```markdown
|
||||
# {{Document Title}}
|
||||
|
||||
## Overview
|
||||
|
||||
{{Brief description of what this document covers and why it's important for AI agents}}
|
||||
|
||||
## Quick Reference
|
||||
|
||||
{{Key points, commands, or patterns that agents need most frequently}}
|
||||
|
||||
## Detailed Information
|
||||
|
||||
{{Comprehensive information organized into logical sections}}
|
||||
|
||||
## Examples
|
||||
|
||||
{{Concrete examples showing proper usage or implementation}}
|
||||
|
||||
## Common Patterns
|
||||
|
||||
{{Recurring patterns agents should recognize and follow}}
|
||||
|
||||
## Things to Avoid
|
||||
|
||||
{{Anti-patterns, deprecated approaches, or common mistakes}}
|
||||
|
||||
## Related Resources
|
||||
|
||||
{{Links to other relevant documentation or external resources}}
|
||||
```
|
||||
|
||||
Each document should be:
|
||||
|
||||
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
|
||||
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
|
||||
- **Example-rich** - Include specific code examples and real file references
|
||||
- **Context-aware** - Reference actual project files, folders, and conventions
|
||||
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
|
||||
]]
|
||||
|
||||
### 4. Content Guidelines for Each Document Type
|
||||
|
||||
#### Core Architecture Documents
|
||||
|
||||
##### docs/architecture/index.md
|
||||
|
||||
[[LLM: Create a comprehensive index of all architecture documentation:
|
||||
|
||||
- List all architecture documents with brief descriptions
|
||||
- Group documents by category (backend, frontend, shared)
|
||||
- Include quick links to key sections
|
||||
- Provide reading order recommendations for different use cases]]
|
||||
|
||||
##### docs/architecture/unified-project-structure.md
|
||||
|
||||
[[LLM: Document the complete project structure:
|
||||
|
||||
- Root-level directory structure with explanations
|
||||
- Where each type of code belongs (backend, frontend, tests, etc.)
|
||||
- File naming conventions and patterns
|
||||
- Module/package organization
|
||||
- Generated vs. source file locations
|
||||
- Build output locations]]
|
||||
|
||||
##### docs/architecture/coding-standards.md
|
||||
|
||||
[[LLM: Capture project-wide coding conventions:
|
||||
|
||||
- Language-specific style guidelines
|
||||
- Naming conventions (variables, functions, classes, files)
|
||||
- Code organization within files
|
||||
- Import/export patterns
|
||||
- Comment and documentation standards
|
||||
- Linting and formatting tool configurations
|
||||
- Git commit message conventions]]
|
||||
|
||||
##### docs/architecture/tech-stack.md
|
||||
|
||||
[[LLM: Document all technologies and versions:
|
||||
|
||||
- Primary languages and versions
|
||||
- Frameworks and major libraries with versions
|
||||
- Development tools and their versions
|
||||
- Database systems and versions
|
||||
- External services and APIs used
|
||||
- Browser/runtime requirements]]
|
||||
|
||||
##### docs/architecture/testing-strategy.md
|
||||
|
||||
[[LLM: Define testing approaches and requirements:
|
||||
|
||||
- Test file locations and naming conventions
|
||||
- Unit testing patterns and frameworks
|
||||
- Integration testing approaches
|
||||
- E2E testing setup (if applicable)
|
||||
- Test coverage requirements
|
||||
- Mocking strategies
|
||||
- Test data management]]
|
||||
|
||||
#### Backend Architecture Documents
|
||||
|
||||
##### docs/architecture/backend-architecture.md
|
||||
|
||||
[[LLM: Document backend service structure:
|
||||
|
||||
- Service layer organization
|
||||
- Controller/route patterns
|
||||
- Middleware architecture
|
||||
- Authentication/authorization patterns
|
||||
- Request/response flow
|
||||
- Background job processing
|
||||
- Service communication patterns]]
|
||||
|
||||
##### docs/architecture/rest-api-spec.md
|
||||
|
||||
[[LLM: Specify all API endpoints:
|
||||
|
||||
- Base URL and versioning strategy
|
||||
- Authentication methods
|
||||
- Common headers and parameters
|
||||
- Each endpoint with:
|
||||
- HTTP method and path
|
||||
- Request parameters/body
|
||||
- Response format and status codes
|
||||
- Error responses
|
||||
- Rate limiting and quotas]]
|
||||
|
||||
##### docs/architecture/data-models.md
|
||||
|
||||
[[LLM: Define data structures and validation:
|
||||
|
||||
- Core business entities
|
||||
- Data validation rules
|
||||
- Relationships between entities
|
||||
- Computed fields and derivations
|
||||
- Data transformation patterns
|
||||
- Serialization formats]]
|
||||
|
||||
##### docs/architecture/database-schema.md
|
||||
|
||||
[[LLM: Document database design:
|
||||
|
||||
- Database type and version
|
||||
- Table/collection structures
|
||||
- Indexes and constraints
|
||||
- Relationships and foreign keys
|
||||
- Migration patterns
|
||||
- Seed data requirements
|
||||
- Backup and recovery procedures]]
|
||||
|
||||
##### docs/architecture/external-apis.md
|
||||
|
||||
[[LLM: Document third-party integrations:
|
||||
|
||||
- List of external services used
|
||||
- Authentication methods for each
|
||||
- API endpoints and usage patterns
|
||||
- Rate limits and quotas
|
||||
- Error handling strategies
|
||||
- Webhook configurations
|
||||
- Data synchronization patterns]]
|
||||
|
||||
#### Frontend Architecture Documents
|
||||
|
||||
##### docs/architecture/frontend-architecture.md
|
||||
|
||||
[[LLM: Document frontend application structure:
|
||||
|
||||
- Component hierarchy and organization
|
||||
- State management patterns
|
||||
- Routing architecture
|
||||
- Data fetching patterns
|
||||
- Authentication flow
|
||||
- Error boundary strategies
|
||||
- Performance optimization patterns]]
|
||||
|
||||
##### docs/architecture/components.md
|
||||
|
||||
[[LLM: Specify UI components:
|
||||
|
||||
- Component library/design system used
|
||||
- Custom component specifications
|
||||
- Props and state for each component
|
||||
- Component composition patterns
|
||||
- Styling approaches
|
||||
- Accessibility requirements
|
||||
- Component testing patterns]]
|
||||
|
||||
##### docs/architecture/core-workflows.md
|
||||
|
||||
[[LLM: Document user interaction flows:
|
||||
|
||||
- Major user journeys
|
||||
- Screen flow diagrams
|
||||
- Form handling patterns
|
||||
- Navigation patterns
|
||||
- Data flow through workflows
|
||||
- Error states and recovery
|
||||
- Loading and transition states]]
|
||||
|
||||
##### docs/architecture/ui-ux-spec.md
|
||||
|
||||
[[LLM: Define UI/UX guidelines:
|
||||
|
||||
- Design system specifications
|
||||
- Color palette and typography
|
||||
- Spacing and layout grids
|
||||
- Responsive breakpoints
|
||||
- Animation and transition guidelines
|
||||
- Accessibility standards
|
||||
- Browser compatibility requirements]]
|
||||
|
||||
### 5. Adaptive Content Strategy
|
||||
|
||||
[[LLM: Adapt your documentation approach based on project characteristics:
|
||||
|
||||
**For Web Applications:**
|
||||
|
||||
- Focus on component patterns, routing, state management
|
||||
- Include build processes, asset handling, and deployment
|
||||
- Cover API integration patterns and data fetching
|
||||
|
||||
**For Backend Services:**
|
||||
|
||||
- Emphasize service architecture, data models, and API design
|
||||
- Include database interaction patterns and migration strategies
|
||||
- Cover authentication, authorization, and security patterns
|
||||
|
||||
**For CLI Tools:**
|
||||
|
||||
- Focus on command structure, argument parsing, and output formatting
|
||||
- Include plugin/extension patterns if applicable
|
||||
- Cover configuration file handling and user interaction patterns
|
||||
|
||||
**For Libraries/Frameworks:**
|
||||
|
||||
- Emphasize public API design and usage patterns
|
||||
- Include extension points and customization approaches
|
||||
- Cover versioning, compatibility, and migration strategies
|
||||
|
||||
**For Mobile Applications:**
|
||||
|
||||
- Focus on platform-specific patterns and navigation
|
||||
- Include state management and data persistence approaches
|
||||
- Cover platform integration and native feature usage
|
||||
|
||||
**For Data Science/ML Projects:**
|
||||
|
||||
- Emphasize data pipeline patterns and model organization
|
||||
- Include experiment tracking and reproducibility approaches
|
||||
- Cover data validation and model deployment patterns
|
||||
]]
|
||||
|
||||
### 6. Quality Assurance
|
||||
|
||||
[[LLM: Before completing each document:
|
||||
|
||||
1. **Accuracy Check**: Verify all file paths, commands, and code examples work
|
||||
2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
|
||||
3. **Clarity Assessment**: Check that explanations are clear and actionable
|
||||
4. **Consistency Verification**: Ensure terminology and patterns align across all documents
|
||||
5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
|
||||
|
||||
Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
|
||||
|
||||
### 7. Final Integration
|
||||
|
||||
[[LLM: After all documents are completed:
|
||||
|
||||
1. Ensure all documents are created in the proper BMAD-expected locations:
|
||||
|
||||
- Core docs in `docs/` (index.md, prd.md)
|
||||
- Architecture shards in `docs/architecture/` subdirectory
|
||||
- Create the `docs/architecture/` directory if it doesn't exist
|
||||
|
||||
2. Create/update the master index documents:
|
||||
|
||||
- Update `docs/index.md` to reference all documentation
|
||||
- Create `docs/architecture/index.md` listing all architecture shards
|
||||
|
||||
3. Verify document cross-references:
|
||||
|
||||
- Ensure all documents link to related documentation
|
||||
- Check that file paths match the actual project structure
|
||||
- Validate that examples reference real files in the project
|
||||
|
||||
4. Provide maintenance guidance:
|
||||
|
||||
- Document update triggers (when to update each doc)
|
||||
- Create a simple checklist for keeping docs current
|
||||
- Suggest automated validation approaches
|
||||
|
||||
5. Summary report including:
|
||||
- List of all documents created with their paths
|
||||
- Any gaps or areas needing human review
|
||||
- Recommendations for project-specific additions
|
||||
- Next steps for maintaining documentation accuracy
|
||||
|
||||
Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- Documentation enables AI agents to understand project context without additional explanation
|
||||
- All major architectural patterns and coding conventions are captured
|
||||
- Examples reference actual project files and demonstrate real usage
|
||||
- Documentation is structured consistently and easy to navigate
|
||||
- Content is actionable and focuses on what agents need to do, not just understand
|
||||
|
||||
## Notes
|
||||
|
||||
- This task is designed to work with any project type, language, or framework
|
||||
- The documentation should reflect the project as it actually is, not as it should be
|
||||
- Focus on patterns that agents can recognize and replicate consistently
|
||||
- Include both positive examples (what to do) and negative examples (what to avoid)
|
||||
==================== END: tasks#document-project ====================
|
||||
|
||||
==================== START: templates#architecture-tmpl ====================
|
||||
# {{Project Name}} Architecture Document
|
||||
|
||||
|
||||
Reference in New Issue
Block a user