bmad-method 4.27.5 → 5.0.0

package/bmad-core/tasks/document-project.md

@@ -1,317 +0,0 @@
-# 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

package/bmad-core/tasks/facilitate-brainstorming-session.md

@@ -1,136 +0,0 @@
----
-docOutputLocation: docs/brainstorming-session-results.md
-template: brainstorming-output-tmpl
----
-
-# Facilitate Brainstorming Session Task
-
-Facilitate interactive brainstorming sessions with users. Be creative and adaptive in applying techniques.
-
-## Process
-
-### Step 1: Session Setup
-
-Ask 4 context questions (don't preview what happens next):
-
-1. What are we brainstorming about?
-2. Any constraints or parameters?
-3. Goal: broad exploration or focused ideation?
-4. Do you want a structured document output to reference later? (Y/N)
-
-### Step 2: Present Approach Options
-
-After getting answers to Step 1, present 4 approach options (numbered):
-
-1. User selects specific techniques
-2. Analyst recommends techniques based on context
-3. Random technique selection for creative variety
-4. Progressive technique flow (start broad, narrow down)
-
-### Step 3: Execute Techniques Interactively
-
-**KEY PRINCIPLES:**
-
-- **FACILITATOR ROLE**: Guide user to generate their own ideas through questions, prompts, and examples
-- **CONTINUOUS ENGAGEMENT**: Keep user engaged with chosen technique until they want to switch or are satisfied
-- **CAPTURE OUTPUT**: If document output requested, capture all ideas generated in each technique section
-
-**Technique Selection:**
-If user selects Option 1, present numbered list of techniques from the brainstorming-techniques data file. User can select by number (e.g., "7" for Mind Mapping).
-
-**Technique Execution:**
-
-1. Apply selected technique according to data file description
-2. Keep engaging with technique until user indicates they want to:
-   - Choose a different technique
-   - Apply current ideas to a new technique  
-   - Move to convergent phase
-   - End session
-
-**Output Capture (if requested):**
-For each technique used, capture:
-
-- Technique name and duration
-- Key ideas generated by user
-- Insights and patterns identified
-- User's reflections on the process
-
-### Step 4: Session Flow
-
-1. **Warm-up** (5-10 min) - Build creative confidence
-2. **Divergent** (20-30 min) - Generate quantity over quality
-3. **Convergent** (15-20 min) - Group and categorize ideas
-4. **Synthesis** (10-15 min) - Refine and develop concepts
-
-### Step 5: Document Output (if requested)
-
-Generate structured document with these sections:
-
-**Executive Summary**
-
-- Session topic and goals
-- Techniques used and duration
-- Total ideas generated
-- Key themes and patterns identified
-
-**Technique Sections** (for each technique used)
-
-- Technique name and description
-- Ideas generated (user's own words)
-- Insights discovered
-- Notable connections or patterns
-
-**Idea Categorization**
-
-- **Immediate Opportunities** - Ready to implement now
-- **Future Innovations** - Requires development/research
-- **Moonshots** - Ambitious, transformative concepts
-- **Insights & Learnings** - Key realizations from session
-
-**Action Planning**
-
-- Top 3 priority ideas with rationale
-- Next steps for each priority
-- Resources/research needed
-- Timeline considerations
-
-**Reflection & Follow-up**
-
-- What worked well in this session
-- Areas for further exploration
-- Recommended follow-up techniques
-- Questions that emerged for future sessions
-
-## Key Principles
-
-- **YOU ARE A FACILITATOR**: Guide the user to brainstorm, don't brainstorm for them
-- **INTERACTIVE DIALOGUE**: Ask questions, wait for responses, build on their ideas
-- **ONE TECHNIQUE AT A TIME**: Don't mix multiple techniques in one response
-- **CONTINUOUS ENGAGEMENT**: Stay with one technique until user wants to switch
-- **DRAW IDEAS OUT**: Use prompts and examples to help them generate their own ideas
-- **REAL-TIME ADAPTATION**: Monitor engagement and adjust approach as needed
-- Maintain energy and momentum
-- Defer judgment during generation
-- Quantity leads to quality (aim for 100 ideas in 60 minutes)
-- Build on ideas collaboratively
-- Document everything if output requested
-
-## Advanced Engagement Strategies
-
-**Energy Management**
-
-- Check engagement levels: "How are you feeling about this direction?"
-- Offer breaks or technique switches if energy flags
-- Use encouraging language and celebrate idea generation
-
-**Depth vs. Breadth**
-
-- Ask follow-up questions to deepen ideas: "Tell me more about that..."
-- Use "Yes, and..." to build on their ideas
-- Help them make connections: "How does this relate to your earlier idea about...?"
-
-**Transition Management**
-
-- Always ask before switching techniques: "Ready to try a different approach?"
-- Offer options: "Should we explore this idea deeper or generate more alternatives?"
-- Respect their process and timing

package/bmad-core/tasks/generate-ai-frontend-prompt.md

@@ -1,51 +0,0 @@
-# Create AI Frontend Prompt Task
-
-## Purpose
-
-To generate a masterful, comprehensive, and optimized prompt that can be used with any AI-driven frontend development tool (e.g., Vercel v0, Lovable.ai, or similar) to scaffold or generate significant portions of a frontend application.
-
-## Inputs
-
-- Completed UI/UX Specification (`front-end-spec`)
-- Completed Frontend Architecture Document (`front-end-architecture`) or a full stack combined architecture such as `architecture.md`
-- Main System Architecture Document (`architecture` - for API contracts and tech stack to give further context)
-
-## Key Activities & Instructions
-
-### 1. Core Prompting Principles
-
-Before generating the prompt, you must understand these core principles for interacting with a generative AI for code.
-
-- **Be Explicit and Detailed**: The AI cannot read your mind. Provide as much detail and context as possible. Vague requests lead to generic or incorrect outputs.
-- **Iterate, Don't Expect Perfection**: Generating an entire complex application in one go is rare. The most effective method is to prompt for one component or one section at a time, then build upon the results.
-- **Provide Context First**: Always start by providing the AI with the necessary context, such as the tech stack, existing code snippets, and overall project goals.
-- **Mobile-First Approach**: Frame all UI generation requests with a mobile-first design mindset. Describe the mobile layout first, then provide separate instructions for how it should adapt for tablet and desktop.
-
-### 2. The Structured Prompting Framework
-
-To ensure the highest quality output, you MUST structure every prompt using the following four-part framework.
-
-1. **High-Level Goal**: Start with a clear, concise summary of the overall objective. This orients the AI on the primary task.
-   - _Example: "Create a responsive user registration form with client-side validation and API integration."_
-2. **Detailed, Step-by-Step Instructions**: Provide a granular, numbered list of actions the AI should take. Break down complex tasks into smaller, sequential steps. This is the most critical part of the prompt.
-   - _Example: "1. Create a new file named `RegistrationForm.js`. 2. Use React hooks for state management. 3. Add styled input fields for 'Name', 'Email', and 'Password'. 4. For the email field, ensure it is a valid email format. 5. On submission, call the API endpoint defined below."_
-3. **Code Examples, Data Structures & Constraints**: Include any relevant snippets of existing code, data structures, or API contracts. This gives the AI concrete examples to work with. Crucially, you must also state what _not_ to do.
-   - _Example: "Use this API endpoint: `POST /api/register`. The expected JSON payload is `{ "name": "string", "email": "string", "password": "string" }`. Do NOT include a 'confirm password' field. Use Tailwind CSS for all styling."_
-4. **Define a Strict Scope**: Explicitly define the boundaries of the task. Tell the AI which files it can modify and, more importantly, which files to leave untouched to prevent unintended changes across the codebase.
-   - _Example: "You should only create the `RegistrationForm.js` component and add it to the `pages/register.js` file. Do NOT alter the `Navbar.js` component or any other existing page or component."_
-
-### 3. Assembling the Master Prompt
-
-You will now synthesize the inputs and the above principles into a final, comprehensive prompt.
-
-1. **Gather Foundational Context**:
-   - Start the prompt with a preamble describing the overall project purpose, the full tech stack (e.g., Next.js, TypeScript, Tailwind CSS), and the primary UI component library being used.
-2. **Describe the Visuals**:
-   - If the user has design files (Figma, etc.), instruct them to provide links or screenshots.
-   - If not, describe the visual style: color palette, typography, spacing, and overall aesthetic (e.g., "minimalist", "corporate", "playful").
-3. **Build the Prompt using the Structured Framework**:
-   - Follow the four-part framework from Section 2 to build out the core request, whether it's for a single component or a full page.
-4. **Present and Refine**:
-   - Output the complete, generated prompt in a clear, copy-pasteable format (e.g., a large code block).
-   - Explain the structure of the prompt and why certain information was included, referencing the principles above.
-   - <important_note>Conclude by reminding the user that all AI-generated code will require careful human review, testing, and refinement to be considered production-ready.</important_note>

package/bmad-core/tasks/kb-mode-interaction.md

@@ -1,70 +0,0 @@
-# KB Mode Interaction Task
-
-## Purpose
-Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.
-
-## Instructions
-
-When entering KB mode (*kb-mode), follow these steps:
-
-### 1. Welcome and Guide
-Announce entering KB mode with a brief, friendly introduction:
-
-"I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method."
-
-### 2. Present Topic Areas
-Offer a concise list of main topic areas the user might want to explore:
-
-**What would you like to know more about?**
-
-1. **Setup & Installation** - Getting started with BMad
-2. **Workflows** - Choosing the right workflow for your project
-3. **Web vs IDE** - When to use each environment
-4. **Agents** - Understanding specialized agents and their roles
-5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How BMad implements Agile methodologies
-7. **Configuration** - Customizing BMad for your needs
-8. **Best Practices** - Tips for effective BMad usage
-
-Or ask me about anything else related to BMad-Method!
-
-### 3. Respond Contextually
-- Wait for user's specific question or topic selection
-- Provide focused, relevant information from the knowledge base
-- Offer to dive deeper or explore related topics
-- Keep responses concise unless user asks for detailed explanations
-
-### 4. Interactive Exploration
-- After answering, suggest related topics they might find helpful
-- Maintain conversational flow rather than data dumping
-- Use examples when appropriate
-- Reference specific documentation sections when relevant
-
-### 5. Exit Gracefully
-When user is done or wants to exit KB mode:
-- Summarize key points discussed if helpful
-- Remind them they can return to KB mode anytime with *kb-mode
-- Suggest next steps based on what was discussed
-
-## Example Interaction
-
-**User**: *kb-mode
-
-**Assistant**: I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method.
-
-**What would you like to know more about?**
-
-1. **Setup & Installation** - Getting started with BMad
-2. **Workflows** - Choosing the right workflow for your project
-3. **Web vs IDE** - When to use each environment
-4. **Agents** - Understanding specialized agents and their roles
-5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How BMad implements Agile methodologies
-7. **Configuration** - Customizing BMad for your needs
-8. **Best Practices** - Tips for effective BMad usage
-
-Or ask me about anything else related to BMad-Method!
-
-**User**: Tell me about workflows
-
-**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]