diff --git a/.bmad-core/agents/architect.md b/.bmad-core/agents/architect.md index 1da8bb88..0fd22a59 100644 --- a/.bmad-core/agents/architect.md +++ b/.bmad-core/agents/architect.md @@ -2,27 +2,24 @@ CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode: -```yml +```yaml activation-instructions: - - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER! - - Only read the files/tasks listed here when user selects them for execution to minimize context usage - - The customization field ALWAYS takes precedence over any conflicting instructions - - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute - + - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER! + - Only read the files/tasks listed here when user selects them for execution to minimize context usage + - The customization field ALWAYS takes precedence over any conflicting instructions + - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute agent: name: Winston id: architect title: Architect icon: 🏗️ - whenToUse: "Use for system design, architecture documents, technology selection, API design, and infrastructure planning" - customization: - + whenToUse: Use for system design, architecture documents, technology selection, API design, and infrastructure planning + customization: null persona: role: Holistic System Architect & Full-Stack Technical Leader style: Comprehensive, pragmatic, user-centric, technically deep yet accessible identity: Master of holistic application design who bridges frontend, backend, infrastructure, and everything in between focus: Complete systems architecture, cross-stack optimization, pragmatic technology selection - core_principles: - Holistic System Thinking - View every component as part of a larger system - User Experience Drives Architecture - Start with user journeys and work backward @@ -34,24 +31,22 @@ persona: - Data-Centric Design - Let data requirements drive architecture - Cost-Conscious Engineering - Balance technical ideals with financial reality - Living Architecture - Design for change and adaptation - startup: - Greet the user with your name and role, and inform of the *help command. - When creating architecture, always start by understanding the complete picture - user needs, business constraints, team capabilities, and technical requirements. - commands: - - "*help" - Show: numbered list of the following commands to allow selection - - "*chat-mode" - (Default) Architect consultation with advanced-elicitation for complex system design - - "*create-doc {template}" - Create doc (no template = show available templates) - - "*execute-checklist {checklist}" - Run architectural validation checklist - - "*research {topic}" - Generate deep research prompt for architectural decisions - - "*exit" - Say goodbye as the Architect, and then abandon inhabiting this persona - + - '*help" - Show: numbered list of the following commands to allow selection' + - '*chat-mode" - (Default) Architect consultation with advanced-elicitation for complex system design' + - '*create-doc {template}" - Create doc (no template = show available templates)' + - '*execute-checklist {checklist}" - Run architectural validation checklist' + - '*research {topic}" - Generate deep research prompt for architectural decisions' + - '*exit" - Say goodbye as the Architect, and then abandon inhabiting this persona' dependencies: tasks: - create-doc - - execute-checklist - create-deep-research-prompt + - document-project + - execute-checklist templates: - architecture-tmpl - front-end-architecture-tmpl diff --git a/.bmad-core/agents/bmad-master.md b/.bmad-core/agents/bmad-master.md index 1bddae89..8ef7413b 100644 --- a/.bmad-core/agents/bmad-master.md +++ b/.bmad-core/agents/bmad-master.md @@ -55,6 +55,7 @@ dependencies: - correct-course - create-deep-research-prompt - create-doc + - document-project - create-expansion-pack - create-agent - create-next-story diff --git a/.bmad-core/bmad-core-config.yml b/.bmad-core/bmad-core-config.yml new file mode 100644 index 00000000..0e680011 --- /dev/null +++ b/.bmad-core/bmad-core-config.yml @@ -0,0 +1,60 @@ +agent_file_references: + core_docs: + - docs/index.md + - docs/prd.md + - docs/architecture.md + - docs/architecture/index.md + - 'docs/architecture/coding-standards.md # Required by DEV at startup' + - 'docs/architecture/tech-stack.md # Technology stack reference' + - 'docs/architecture/unified-project-structure.md # Project structure guide' + - 'docs/architecture/testing-strategy.md # Testing requirements' + story_files: + - 'docs/stories/ # Stories directory (pattern: {epicNum}.{storyNum}.story.md)' + epic_locations: + primary: docs/ + secondary: docs/prd/ + architecture_shards: + backend: + - 'docs/architecture/backend-architecture.md # Backend service patterns' + - 'docs/architecture/rest-api-spec.md # API endpoint specifications' + - 'docs/architecture/data-models.md # Data structures and validation' + - 'docs/architecture/database-schema.md # Database design' + - 'docs/architecture/external-apis.md # Third-party integrations' + frontend: + - 'docs/architecture/frontend-architecture.md # Frontend patterns' + - docs/architecture/components.md + - 'docs/architecture/core-workflows.md # User interaction flows' + - 'docs/architecture/ui-ux-spec.md # UI/UX specifications' + shared: + - 'docs/architecture/tech-stack.md # Technology constraints' + - 'docs/architecture/unified-project-structure.md # Code organization' + - 'docs/architecture/coding-standards.md # Project conventions' + - 'docs/architecture/testing-strategy.md # Testing requirements' + additional_docs: + - 'docs/tech-stack.md # Technology stack (if separate)' + - 'docs/data-models.md # Data models (if separate)' + - 'docs/api-reference.md # API reference (if separate)' + - 'docs/frontend-architecture.md # Frontend arch (if separate)' +bmad_core_dependencies: + tasks: + - .bmad-core/tasks/create-next-story.md + - .bmad-core/tasks/execute-checklist.md + - .bmad-core/tasks/correct-course.md + - .bmad-core/tasks/shard-doc.md + - .bmad-core/tasks/index-docs.md + templates: + - .bmad-core/templates/story-tmpl.md + checklists: + - .bmad-core/checklists/story-draft-checklist.md + - .bmad-core/checklists/story-dod-checklist.md + utils: + - .bmad-core/utils/template-format.md +file_patterns: + story_files: '{epicNum}.{storyNum}.story.md' + epic_files: epic-{n}-{description}.md +story_statuses: + - Draft + - Approved + - In Progress + - Review + - Done diff --git a/.bmad-core/tasks/document-project.md b/.bmad-core/tasks/document-project.md new file mode 100644 index 00000000..b2947ef1 --- /dev/null +++ b/.bmad-core/tasks/document-project.md @@ -0,0 +1,389 @@ +# 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) diff --git a/README.md b/README.md index b7ae3a19..99a35a12 100644 --- a/README.md +++ b/README.md @@ -256,6 +256,11 @@ npm install ## Documentation & Guides +### Architecture & Technical + +- 🏗️ [Core Architecture](docs/core-architecture.md) - Complete technical architecture and system design +- 📖 [User Guide](docs/user-guide.md) - Comprehensive guide to using BMAD-METHOD effectively + ### Workflow Guides - 📚 [Universal BMAD Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs @@ -277,7 +282,7 @@ MIT License - see [LICENSE](LICENSE) for details. ## Version History -- **Current**: [v4.0.0](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs +- **Current**: [v4](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs - **Previous Versions**: - [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3) - Introduced the unified BMAD Agent and Gemini optimization - [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2) - Added web agents and template separation diff --git a/docs/core-architecture.md b/docs/core-architecture.md new file mode 100644 index 00000000..f3e698ea --- /dev/null +++ b/docs/core-architecture.md @@ -0,0 +1,213 @@ +# BMAD Method: Core Architecture + +This document serves as the definitive source of truth for the BMAD-Method's architecture. It is designed to be understood by both human developers and the AI agents that operate within the framework. + +## 1. Overview + +The BMAD-Method is an AI-Powered Agile Development Framework designed to transform software development by providing specialized AI agents for every role in a complete Agile team. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex software development tasks in a predictable, high-quality manner. + +The system facilitates a full development lifecycle: + +1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs. +2. **Architecture & Design**: Defining system architecture and UI/UX specifications. +3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects. + +## 2. System Architecture Diagram + +The entire BMAD-Method ecosystem is designed around the `.bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments. + +```mermaid +graph TD + subgraph BMAD Method Project + subgraph Core Framework + A["bmad-core"] + A --> B["agents"] + A --> C["agent-teams"] + A --> D["workflows"] + A --> E["templates"] + A --> F["tasks"] + A --> G["checklists"] + A --> H["data (KB)"] + end + + subgraph Tooling + I["tools/builders/web-builder.js"] + end + + subgraph Outputs + J[".bmad-core/web-bundles"] + end + + B -- defines dependencies for --> E + B -- defines dependencies for --> F + B -- defines dependencies for --> G + B -- defines dependencies for --> H + + C -- bundles --> B + I -- reads from --> A + I -- creates --> J + end + + subgraph Target Environments + K["IDE (Cursor, VS Code, etc.)"] + L["Web UI (Gemini, ChatGPT)"] + end + + B --> K + J --> L + + style A fill:#1a73e8,color:#fff + style I fill:#f9ab00,color:#fff + style J fill:#34a853,color:#fff +```text + +## 3. Core Components + +The `.bmad-core` directory contains all the definitions and resources that give the agents their capabilities. + +### 3.1. Agents (`.bmad-core/agents/`) + +- **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent. +- **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use. +- **Startup Instructions**: Agents can include startup sequences that load project-specific documentation from the `docs/` folder, such as coding standards, API specifications, or project structure documents. This provides immediate project context upon activation. +- **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context. +- **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities. + +### 3.2. Agent Teams (`.bmad-core/agent-teams/`) + +- **Purpose**: Team files (e.g., `team-all.yml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments. +- **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`. + +### 3.3. Workflows (`.bmad-core/workflows/`) + +- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent. +- **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization. + +### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`) + +- **Purpose**: These folders house the modular components that are dynamically loaded by agents based on their dependencies. + - **`templates/`**: Contains markdown templates for common documents like PRDs, architecture specifications, and user stories. + - **`tasks/`**: Defines the instructions for carrying out specific, repeatable actions like "shard-doc" or "create-next-story". + - **`checklists/`**: Provides quality assurance checklists for agents like the Product Owner (`po`) or Architect. + - **`data/`**: Contains the core knowledge base (`bmad-kb.md`), technical preferences (`technical-preferences.md`), and other key data files. + +#### 3.4.1. Template Processing System + +A key architectural principle of BMAD is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic. + +The BMAD framework employs a sophisticated template processing system orchestrated by three key components: + +- **`template-format.md`** (`.bmad-core/utils/`): Defines the foundational markup language used throughout all BMAD templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system. + +- **`create-doc.md`** (`.bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system. + +- **`advanced-elicitation.md`** (`.bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality. + +The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves. + +#### 3.4.2. Technical Preferences System + +BMAD includes a personalization layer through the `technical-preferences.md` file in `.bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects. + +**Purpose and Benefits:** +- **Consistency**: Ensures all agents reference the same technical preferences +- **Efficiency**: Eliminates the need to repeatedly specify preferred technologies +- **Personalization**: Agents provide recommendations aligned with user preferences +- **Learning**: Captures lessons learned and preferences that evolve over time + +**Content Structure:** +The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions. + +**Integration Points:** +- Templates can reference technical preferences during document generation +- Agents suggest preferred technologies when appropriate for project requirements +- When preferences don't fit project needs, agents explain alternatives +- Web bundles can include preferences content for consistent behavior across platforms + +**Evolution Over Time:** +Users are encouraged to continuously update this file with discoveries from projects, adding both positive preferences and technologies to avoid, creating a personalized knowledge base that improves agent recommendations over time. + +## 4. The Build & Delivery Process + +The framework is designed for two primary environments: local IDEs and web-based AI chat interfaces. The `web-builder.js` script is the key to supporting the latter. + +### 4.1. Web Builder (`tools/builders/web-builder.js`) + +- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `.bmad-core/web-bundles/`. +- **Process**: + 1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file. + 2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs. + 3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section. + 4. **Outputs Bundle**: The final `.txt` file is saved in the `web-bundles` directory, ready to be uploaded to a web UI. + +### 4.2. Environment-Specific Usage + +- **For IDEs**: Users interact with the agents directly via their markdown files in `.bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents. +- **For Web UIs**: Users upload a pre-built bundle from `.bmad-core/web-bundles/`. This single file provides the AI with the context of the entire team and all their required tools and knowledge. + +## 5. BMAD Workflows + +### 5.1. The Planning Workflow + +Before development begins, BMAD follows a structured planning workflow that establishes the foundation for successful project execution: + +```mermaid +graph TD + A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"} + B -->|Yes| C["Analyst: Market Research & Analysis"] + B -->|No| D["Create Project Brief"] + C --> D["Analyst: Create Project Brief"] + D --> E["PM: Create PRD from Brief"] + E --> F["Architect: Create Architecture from PRD"] + F --> G["PO: Run Master Checklist"] + G --> H{"Documents Aligned?"} + H -->|Yes| I["Planning Complete"] + H -->|No| J["PO: Update Epics & Stories"] + J --> K["Update PRD/Architecture as needed"] + K --> G + I --> L["📁 Switch to IDE"] + L --> M["PO: Shard Documents"] + M --> N["Ready for SM/Dev Cycle"] + + style I fill:#34a853,color:#fff + style G fill:#f9ab00,color:#fff + style L fill:#1a73e8,color:#fff + style N fill:#34a853,color:#fff +``` + +**Key Planning Phases:** + +1. **Optional Analysis**: Analyst conducts market research and competitive analysis +2. **Project Brief**: Foundation document created by Analyst or user +3. **PRD Creation**: PM transforms brief into comprehensive product requirements +4. **Architecture Design**: Architect creates technical foundation based on PRD +5. **Validation & Alignment**: PO ensures all documents are consistent and complete +6. **Refinement**: Updates to epics, stories, and documents as needed +7. **Environment Transition**: Critical switch from web UI to IDE for development workflow +8. **Document Preparation**: PO shards large documents for development consumption + +**Workflow Orchestration**: The `bmad-orchestrator` agent uses these workflow definitions to guide users through the complete process, ensuring proper transitions between planning (web UI) and development (IDE) phases. + +### 5.2. The Core Development Cycle + +Once the initial planning and architecture phases are complete, the project moves into a cyclical development workflow, as detailed in the `bmad-kb.md`. This ensures a steady, sequential, and quality-controlled implementation process. + +```mermaid +graph TD + A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"] + B --> C["PO: Shard Arch"] + C --> D["Development Phase"] + D --> E["Scrum Master: Drafts next story from sharded epic"] + E --> F{"User Approval"} + F -->|Approved| G["Dev: Implement Story"] + F -->|Needs Changes| E + G --> H["Dev: Complete story Tasks"] + H --> I{"User Verification"} + I -->|Verified Complete| J["Mark Story as Done"] + I -->|Needs Fixes| G + J --> E + + style J fill:#34a853,color:#fff +``` + +This cycle continues, with the Scrum Master and Developer agents working in tandem, until all stories in the epic are completed. diff --git a/docs/user-guide.md b/docs/user-guide.md new file mode 100644 index 00000000..05d91e86 --- /dev/null +++ b/docs/user-guide.md @@ -0,0 +1,1007 @@ +# BMAD-METHOD User Guide + +This comprehensive guide will help you understand and effectively use the BMAD-METHOD framework for AI-assisted software development. + +## Table of Contents + +1. [Understanding BMAD](#understanding-bmad) +2. [Getting Started](#getting-started) +3. [Agent System](#agent-system) +4. [Templates and Document Creation](#templates-and-document-creation) +5. [Development Workflow](#development-workflow) +6. [Team Configurations](#team-configurations) +7. [IDE Integration](#ide-integration) +8. [Web UI Usage](#web-ui-usage) +9. [Advanced Features](#advanced-features) +10. [Troubleshooting](#troubleshooting) +11. [Best Practices](#best-practices) + +## Understanding BMAD + +### What is BMAD-METHOD? + +BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is an AI agent orchestration framework that provides specialized AI agents for every role in a complete Agile development team. Unlike generic AI assistants, each BMAD agent has deep expertise in their specific domain and can collaborate to deliver complete software projects. + +### Core Principles + +1. **Specialized Expertise**: Each agent focuses on a specific role (PM, Architect, Developer, QA, etc.) +2. **True Agile Workflow**: Follows real Agile methodologies with proper story management +3. **Self-Contained Templates**: Documents embed both output and processing instructions +4. **Dynamic Dependencies**: Agents only load resources they need +5. **Platform Agnostic**: Works with any AI platform or IDE + +### When to Use BMAD + +- **New Projects (Greenfield)**: Complete end-to-end development +- **Existing Projects (Brownfield)**: Feature additions and enhancements +- **Team Collaboration**: Multiple roles working together +- **Quality Assurance**: Structured testing and validation +- **Documentation**: Professional PRDs, architecture docs, user stories + +## Getting Started + +### Installation Options + +#### Option 1: Web UI (Fastest - 2 minutes) + +Best for: ChatGPT, Claude, Gemini users + +1. Navigate to `.bmad-core/web-bundles/teams/` +2. Copy `team-fullstack.txt` content +3. Create new Gemini Gem or CustomGPT +4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed" +5. Type `/help` to see available commands + +#### Option 2: IDE Integration (5 minutes) + +Best for: Cursor, Claude Code, Windsurf, VS Code users + +```bash +# Interactive installation (recommended) +npx bmad-method install + +# Command line installation +npx bmad-method install --full --directory ./my-project --ide cursor +```text + +### First Steps + +1. **Choose Your Environment**: Web UI or IDE +2. **Select Agent/Team**: Individual agent or full team +3. **Initialize Project**: Run `/help` or `*help` to see capabilities +4. **Start Development**: Begin with planning or jump into coding + +## Agent System + +### Core Development Team + +| Agent | Role | Primary Functions | When to Use | +| ----------- | ------------------ | --------------------------------------- | -------------------------------------- | +| `analyst` | Business Analyst | Market research, requirements gathering | Project planning, competitive analysis | +| `pm` | Product Manager | PRD creation, feature prioritization | Strategic planning, roadmaps | +| `architect` | Solution Architect | System design, technical architecture | Complex systems, scalability planning | +| `dev` | Developer | Code implementation, debugging | All development tasks | +| `qa` | QA Specialist | Test planning, quality assurance | Testing strategies, bug validation | +| `ux-expert` | UX Designer | UI/UX design, prototypes | User experience, interface design | +| `po` | Product Owner | Backlog management, story validation | Story refinement, acceptance criteria | +| `sm` | Scrum Master | Sprint planning, story creation | Project management, workflow | + +### Meta Agents + +| Agent | Role | Primary Functions | When to Use | +| ------------------- | ---------------- | ------------------------------------- | --------------------------------- | +| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching | Complex multi-role tasks | +| `bmad-master` | Universal Expert | All capabilities without switching | Single-session comprehensive work | + +### How Agents Work + +#### Dependencies System + +Each agent has a YAML header defining its dependencies: + +```yaml +dependencies: + templates: + - prd-template.md + - user-story-template.md + tasks: + - create-doc.md + - shard-doc.md + data: + - bmad-kb.md +``` + +**Key Points:** + +- Agents only load resources they need (lean context) +- Dependencies are automatically resolved during bundling +- Resources are shared across agents to maintain consistency + +#### Agent Interaction + +**In IDE:** + +```bash +# Cursor or Windsurf (manual rules - loaded with @) +@pm Create a PRD for a task management app +@architect Design the system architecture +@dev Implement the user authentication + +# Claude Code (files in commands folder - loaded with /) +/pm Create user stories +/dev Fix the login bug +```text + +**In Web UI:** + +```text +/pm create-doc prd +/architect review system design +/dev implement story 1.2 +``` + +## Templates and Document Creation + +### Understanding Templates + +BMAD templates are **self-contained and interactive** - they embed both the desired document output and the LLM instructions needed to work with users. This means no separate task is needed for most document creation. + +#### Template Structure + +Templates follow the `template-format.md` specification: + +- `{{placeholders}}` for variable substitution +- `[[LLM: instructions]]` for AI-only processing directives +- Conditional logic blocks +- Examples and guidance sections + +#### Template Processing Flow + +1. **User Request**: "Create a PRD" +2. **Agent Selection**: PM agent loads PRD template +3. **Interactive Processing**: Template guides conversation +4. **Content Generation**: AI follows embedded instructions +5. **User Refinement**: Built-in elicitation processes +6. **Final Output**: Complete, professional document + +### Document Types + +#### Product Requirements Document (PRD) + +- **Template**: `prd-template.md` +- **Agent**: PM +- **Use Case**: Feature specification, project planning +- **Command**: `/pm create-doc prd` +- **💡 Cost-Saving Tip**: For Gemini users, create PRDs in the web UI to avoid high IDE token costs. Copy the final markdown output to `docs/prd.md` in your project. + +#### Architecture Documents + +- **Template**: `architecture-template.md` +- **Agent**: Architect +- **Use Case**: System design, technical planning +- **Command**: `/architect create-doc architecture` +- **💡 Cost-Saving Tip**: For Gemini users, create architecture docs in the web UI to avoid high IDE token costs. Copy the final markdown output to `docs/architecture.md` in your project. + +#### User Stories + +- **Template**: `user-story-template.md` +- **Agent**: SM (Scrum Master) +- **Use Case**: Development planning, sprint preparation +- **Command**: `/sm create-doc user-story` + +### Document Creation Best Practices + +#### Web UI to IDE Workflow (Recommended for Gemini) + +For cost efficiency, especially with Gemini: + +1. **Create Large Documents in Web UI**: Use web bundles for PRD and architecture creation +2. **Copy to Project**: Save the final markdown output to your project's `docs/` folder +3. **Standard Naming**: Use `prd.md` and `architecture.md` for consistency +4. **Continue in IDE**: Use IDE agents for development tasks and smaller documents + +#### File Naming Conventions + +**Required Names for Framework Integration:** +- `docs/prd.md` - Product Requirements Document +- `docs/architecture.md` - System Architecture Document + +**Why These Names Matter:** +- Agents automatically reference these files during development +- Sharding tasks expect these specific filenames +- Workflow automation depends on standard naming + +#### IDE Document Creation + +When working directly in IDEs: +- Agents should create documents in `docs/` folder automatically +- If agents name files differently (e.g., `product-requirements.md`), rename to `prd.md` +- Verify document location matches `docs/prd.md` and `docs/architecture.md` + +### Advanced Template Features + +#### Embedded Elicitation + +Templates can include `advanced-elicitation.md` for enhanced interaction: + +```markdown +[[LLM: Use advanced-elicitation actions 0-3 to refine requirements]] +```text + +This provides 10 structured brainstorming actions: + +- 0-3: Analysis and brainstorming +- 4-6: Refinement and validation +- 7-9: Review and finalization + +#### Interactive Modes + +- **Incremental Mode**: Step-by-step with user input +- **YOLO Mode**: Rapid generation with minimal interaction + +## Development Workflow + +### The Planning Workflow (Web UI) + +Before development begins, BMAD follows a structured planning workflow that's ideally done in web UI for cost efficiency: + +```mermaid +graph TD + A["Start: Project Idea"] --> B{"Optional: Analyst Brainstorming"} + B -->|Yes| C["Analyst: Market Research & Analysis"] + B -->|No| D["Create Project Brief"] + C --> D["Analyst: Create Project Brief"] + D --> E["PM: Create PRD from Brief"] + E --> F["Architect: Create Architecture from PRD"] + F --> G["PO: Run Master Checklist"] + G --> H{"Documents Aligned?"} + H -->|Yes| I["Planning Complete"] + H -->|No| J["PO: Update Epics & Stories"] + J --> K["Update PRD/Architecture as needed"] + K --> G + I --> L["📁 Switch to IDE"] + L --> M["PO: Shard Documents"] + M --> N["Ready for SM/Dev Cycle"] + + style I fill:#34a853,color:#fff + style G fill:#f9ab00,color:#fff + style L fill:#1a73e8,color:#fff + style N fill:#34a853,color:#fff +``` + +#### Web UI to IDE Transition + +**Critical Transition Point**: Once the PO confirms document alignment, you must switch from web UI to IDE to begin the development workflow: + +1. **Copy Documents to Project**: Ensure `docs/prd.md` and `docs/architecture.md` are in your project +2. **Switch to IDE**: Open your project in your preferred IDE (Cursor, Claude Code, Windsurf) +3. **Document Sharding**: Use PO agent to shard large documents into manageable pieces +4. **Begin Development**: Start the SM/Dev cycle for implementation + +### The Core Development Cycle (IDE) + +Once planning is complete and documents are sharded, BMAD follows a structured development workflow: + +```mermaid +graph TD + A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"] + B --> C["PO: Shard Arch"] + C --> D["Development Phase"] + D --> E["Scrum Master: Drafts next story from sharded epic"] + E --> F{"User Approval"} + F -->|Approved| G["Dev: Implement Story"] + F -->|Needs Changes| E + G --> H["Dev: Complete story Tasks"] + H --> I{"User Verification"} + I -->|Verified Complete| J["Mark Story as Done"] + I -->|Needs Fixes| G + J --> E + + style J fill:#34a853,color:#fff +```text + +### Workflow Phases + +#### 1. Planning Phase + +- **Analyst**: Market research, competitive analysis +- **PM**: Create PRD, define features +- **Architect**: System design, technical architecture +- **UX Expert**: User experience design + +#### 2. Preparation Phase + +- **PO**: Shard epics into manageable stories +- **PO**: Shard architecture into implementation tasks +- **SM**: Prepare initial story backlog + +#### 3. Development Phase (Cyclical) + +- **SM**: Draft next story from sharded epic +- **User**: Review and approve story +- **Dev**: Implement all story tasks +- **User**: Verify implementation +- **Repeat**: Until all stories complete + +#### 4. Quality Assurance + +- **QA**: Test planning and execution +- **Dev**: Bug fixes and refinements +- **PO**: Acceptance criteria validation + +### Workflow Types + +#### Greenfield Development + +For new projects: + +1. Business analysis and market research +2. Product requirements and feature definition +3. System architecture and design +4. Development execution +5. Testing and deployment + +#### Brownfield Enhancement + +For existing projects: + +1. Current system analysis +2. Enhancement planning +3. Impact assessment +4. Incremental development +5. Integration testing + +## Team Configurations + +### Pre-Built Teams + +#### Team All + +- **Includes**: All 10 agents + orchestrator +- **Use Case**: Complete projects requiring all roles +- **Bundle**: `team-all.txt` + +#### Team Fullstack + +- **Includes**: PM, Architect, Developer, QA, UX Expert +- **Use Case**: End-to-end web/mobile development +- **Bundle**: `team-fullstack.txt` + +#### Team No-UI + +- **Includes**: PM, Architect, Developer, QA (no UX Expert) +- **Use Case**: Backend services, APIs, system development +- **Bundle**: `team-no-ui.txt` + +### Custom Team Configuration + +Create custom teams by modifying `.bmad-core/agent-teams/`: + +```yaml +name: Custom Development Team +description: Specialized team for specific needs +agents: + - pm + - architect + - dev + - qa +workflows: + - greenfield-fullstack +``` + +## IDE Integration + +### Supported IDEs + +#### Cursor IDE + +- **Commands**: `@agent-name task` (manual rules) +- **Example**: `@pm Create a PRD for user management` +- **Features**: Inline suggestions, context awareness +- **Integration**: Agents loaded as manual rules + +#### Claude Code + +- **Commands**: `/agent-name task` (command files) +- **Example**: `/architect Design microservices architecture` +- **Features**: File integration, project context +- **Integration**: Agents installed as files in commands folder + +#### Windsurf + +- **Commands**: `@agent-name task` (manual rules) +- **Example**: `@dev Implement authentication` +- **Features**: Multi-file editing, project awareness +- **Integration**: Agents loaded as manual rules + +#### VS Code (Generic) + +- **Setup**: Manual installation +- **Usage**: Copy agent content to chat +- **Features**: Basic integration + +### IDE Setup Process + +1. **Install CLI**: `npx bmad-method install` +2. **Select IDE**: Choose during installation +3. **Configure Integration**: Automatic setup for supported IDEs +4. **Verify Installation**: Test with `@agent-name help` + +### IDE Best Practices + +- **Context Management**: Keep relevant files open +- **Agent Selection**: Use appropriate agent for task +- **Iterative Development**: Work in small, focused tasks +- **File Organization**: Maintain clean project structure + +## Web UI Usage + +**Important**: Web UI is primarily designed for planning and documentation phases, not development. Use IDE integration for coding tasks. + +### Platform Setup + +#### ChatGPT Custom GPT + +1. Create new Custom GPT +2. Upload team bundle as knowledge +3. Set instructions: "Your critical operating instructions are attached, do not break character as directed" +4. Configure capabilities as needed + +#### Claude Projects + +1. Create new project +2. Add team bundle to project knowledge +3. Set project instructions with agent behavior +4. Start conversation with `/help` + +#### Gemini Gems + +1. Create new Gem +2. Upload bundle as instruction file +3. Set system instructions for agent behavior +4. Initialize with `/help` command + +### Web UI Commands + +#### Universal Commands + +- `/help` - Show available commands +- `/status` - Current agent status +- `/switch agent-name` - Change active agent (if orchestrator available) + +#### Document Commands + +- `/create-doc type` - Create document of specified type +- `/review-doc` - Review current document +- `/refine-doc` - Improve document quality + +#### Planning Commands + +- `/pm create-doc prd` - Create Product Requirements Document +- `/architect create-doc architecture` - Create system architecture +- `/analyst create-doc project-brief` - Create project brief +- `/po run-checklist` - Validate document alignment + +### Web UI Agent Interaction + +Web UI agents focus on planning and documentation. Here's how to interact with each: + +#### Agent Switching and Conversation +- **Switch Agents**: Use `/pm`, `/architect`, `/analyst`, `/po` to switch between roles +- **Agent Consultation**: Each agent offers their specialized options and capabilities +- **Natural Conversation**: Agents guide you through their processes with questions and suggestions + +#### Planning Phase Agents +- **Analyst**: `/analyst` - Brainstorming, market research, competitive analysis +- **PM**: `/pm` - Product requirements, feature definition, roadmaps +- **Architect**: `/architect` - System design, technical architecture +- **PO**: `/po` - Document validation, epic management, story alignment + +### Web UI Best Practices + +- **Clear Instructions**: Be specific about requirements +- **Context Sharing**: Provide relevant background +- **Iterative Refinement**: Use built-in elicitation features +- **Document Management**: Keep generated docs organized +- **Stay in Planning**: Use web UI for documentation, switch to IDE for development + +#### Cost-Effective Document Creation + +**Recommended Workflow for Large Documents:** + +1. **Use Web UI for PRD and Architecture**: These are token-heavy documents, especially in Gemini +2. **Copy Final Output**: Save complete markdown to your project +3. **Standard File Names**: + - Save PRD as `docs/prd.md` + - Save Architecture as `docs/architecture.md` +4. **IDE for Development**: Switch to IDE agents for implementation tasks + +**Why This Saves Money:** +- Web UI pricing is typically more cost-effective for large context windows +- PRD and architecture creation involves extensive back-and-forth refinement +- IDE token costs can accumulate quickly with large document generation + +## Advanced Features + +### Dynamic Resource Loading + +BMAD's dependency system ensures agents only load necessary resources: + +- **Templates**: Only relevant document templates +- **Tasks**: Only required automation tasks +- **Data**: Only pertinent knowledge base sections +- **Checklists**: Only applicable quality checks + +### Custom Templates + +Create custom templates following `template-format.md`: + +```markdown +--- +title: Custom Template +description: Your custom document type +dependencies: + - advanced-elicitation.md +--- + +# {{document_title}} + +[[LLM: Guide user through custom process]] + +## Section 1 + +{{section_1_content}} + +[[LLM: Use elicitation action 2 for refinement]] + +## Section 2 + +{{section_2_content}} +```text + +### Workflow Customization + +Modify workflows in `.bmad-core/workflows/`: + +```yaml +name: Custom Workflow +type: development +phases: + planning: + agents: + - analyst + - pm + deliverables: + - market-research + - prd + architecture: + agents: + - architect + deliverables: + - system-design + development: + agents: + - dev + - qa + deliverables: + - implementation + - tests +``` + +### Creating Custom Templates + +Templates are self-contained documents that embed both output structure and processing instructions. Follow these patterns from existing templates: + +#### Template Structure + +```markdown +# {{Project Name}} Document Title + +[[LLM: Opening instruction for AI processing]] + +## Level 2 Section (Shardable) + +[[LLM: Section-specific instructions with embedded tasks]] + +### Level 3 Subsection + +[[LLM: Detailed processing instructions]] +{{placeholder_variable}} + +@{example: Example content for AI guidance} + +^^CONDITION: condition_name^^ +## Conditional Section +[[LLM: Only include if condition is met]] +^^/CONDITION^^ +```text + +#### Key Template Patterns + +**Variable Substitution:** +- `{{Project Name}}` - Dynamic project name +- `{{document_title}}` - Document-specific title +- `{{section_content}}` - Placeholder for generated content + +**AI Processing Instructions:** +- `[[LLM: Instructions for AI behavior]]` - AI-only processing directives +- `@{example: Sample content}` - Guidance examples (not output) +- `tasks#advanced-elicitation` - Reference to embedded tasks + +**Conditional Content:** +```markdown +^^CONDITION: has_ui^^ +## User Interface Section +[[LLM: Only include for UI projects]] +^^/CONDITION^^ +``` + +#### Document Sharding + +Level 2 headings (`##`) in templates can be automatically sharded into separate documents: + +**Original PRD:** +```markdown +## Goals and Background Context +## Requirements +## User Interface Design Goals +## Success Metrics +```text + +**After Sharding:** +- `docs/prd/goals-and-background-context.md` +- `docs/prd/requirements.md` +- `docs/prd/user-interface-design-goals.md` +- `docs/prd/success-metrics.md` + +Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sharding. + +### Creating Custom Tasks + +Tasks are reusable automation instructions that agents can execute. They follow a structured format: + +#### Task Structure + +```markdown +# Task Name + +## Purpose + +- Clear description of what the task accomplishes +- When to use this task + +## Instructions + +### 1. Step One +- Detailed instructions for the agent +- Specific behaviors and outputs expected + +### 2. Step Two +- Additional processing steps +- Integration with other resources + +## Examples + +@{example: Concrete usage examples} +``` + +#### Task Patterns + +**Resource Integration:** +```markdown +[[LLM: Check if docs/coding-standards.md exists and reference it]] +[[LLM: Load docs/openapi-spec.yaml for API context]] +```text + +**Advanced Elicitation:** +```markdown +[[LLM: Apply tasks#advanced-elicitation protocol after completion]] +``` + +**Conditional Logic:** +```markdown +[[LLM: If project has UI components, also check frontend standards]] +```text + +### Creating Custom Agents + +Custom agents combine persona, capabilities, and dependencies into specialized roles: + +#### Agent Structure + +```yaml +agent: + name: Custom Agent Name + id: custom-agent + title: Specialized Role Title + icon: 🎯 + whenToUse: Specific use case description +persona: + role: Primary role definition + style: Communication style and approach + identity: Core identity and expertise + focus: Primary areas of concentration +startup: + - Announcement message + - Initial context loading instructions + - User guidance +commands: + - Available slash commands + - Command descriptions +dependencies: + templates: + - custom-template.md + tasks: + - custom-task.md + data: + - domain-knowledge.md +``` + +#### Agent Startup Instructions + +Agents can load project-specific documents and provide custom context: + +```yaml +startup: + - Load docs/coding-standards.md if available + - Review docs/project-structure.md for context + - Check for docs/third-party-apis/ folder + - Announce specialized capabilities +```text + +#### Loading Project Documents + +Agents can reference and load documents from the `docs/` folder: + +- **Coding Standards**: `docs/coding-standards.md` +- **API Specifications**: `docs/openapi-spec.yaml` +- **Project Structure**: `docs/project-structure.md` +- **Third-party APIs**: `docs/third-party-apis/` +- **Architecture Decisions**: `docs/architecture-decisions/` + +#### Context Integration + +```markdown +[[LLM: Before beginning, check for and load relevant context: +- docs/coding-standards.md for development standards +- docs/brand-guidelines.md for design consistency +- docs/third-party-apis/ for integration requirements +- Any project-specific documentation in docs/ folder]] +``` + +### Technical Preferences System + +BMAD includes a powerful personalization system through the `technical-preferences.md` file located in `.bmad-core/data/`. + +#### What is technical-preferences.md? + +This file allows you to define your preferred technologies, patterns, and standards once, then have agents automatically consider them across all projects. It acts as your personal technical profile that travels with your agent bundles. + +#### What to Include + +**Technology Stack Preferences:** +```markdown +## Preferred Technologies + +### Frontend +- React with TypeScript +- Tailwind CSS for styling +- Next.js for full-stack applications + +### Backend +- Node.js with Express +- PostgreSQL for relational data +- Redis for caching + +### Deployment +- Vercel for frontend +- Railway for backend services +```text + +**Design Patterns & Standards:** +```markdown +## Code Standards +- Use functional programming patterns where possible +- Prefer composition over inheritance +- Always include comprehensive error handling +- Write tests for all business logic + +## Architecture Preferences +- Microservices for complex applications +- RESTful APIs with OpenAPI documentation +- Event-driven architecture for real-time features +``` + +**External Services & APIs:** +```markdown +## Preferred External Services +- Auth0 for authentication +- Stripe for payments +- SendGrid for email +- Cloudinary for image processing + +## APIs to Avoid +- Legacy SOAP services +- Services without proper documentation +```text + +#### How Agents Use This File + +**Automatic Suggestions**: Agents will suggest your preferred technologies when appropriate for the project requirements. + +**Informed Alternatives**: If your preferences don't fit the project, agents explain why and suggest alternatives. + +**Consistency**: All agents reference the same preferences, ensuring consistent recommendations across planning and development. + +#### Building Your Preferences Over Time + +**Learning and Evolution**: As you work on projects, add discoveries to your preferences file: + +```markdown +## Lessons Learned +- Avoid using Library X for large datasets (performance issues) +- Pattern Y works well for real-time features +- Service Z has excellent documentation and support + +## Future Exploration +- Want to try Framework A on next appropriate project +- Interested in Pattern B for microservices +- Consider Service C for better performance +``` + +#### Using with Web Bundles + +When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation. + +### Extension Packs + +Add specialized capabilities: + +- **DevOps Pack**: CI/CD, deployment automation +- **Mobile Pack**: iOS/Android development +- **Data Pack**: Analytics, ML integration +- **Security Pack**: Security analysis, compliance + +## Troubleshooting + +### Common Issues + +#### Agent Not Responding + +- **Cause**: Incorrect agent name or command +- **Solution**: Check available agents with `/help` +- **Prevention**: Use tab completion in supported IDEs + +#### Template Errors + +- **Cause**: Malformed template syntax +- **Solution**: Validate against `template-format.md` +- **Prevention**: Use provided templates as starting point + +#### Context Overload + +- **Cause**: Too many dependencies loaded +- **Solution**: Use specific agents instead of `bmad-master` +- **Prevention**: Choose appropriate team size + +#### Installation Issues + +- **Cause**: Node.js version, permissions +- **Solution**: Update Node.js, check permissions +- **Prevention**: Use recommended Node.js version (14+) + +### Debugging Steps + +1. **Check Installation**: `npx bmad-method status` +2. **Verify Agent**: Test with simple command +3. **Review Dependencies**: Ensure required files exist +4. **Clear Cache**: Restart IDE/browser +5. **Reinstall**: `npx bmad-method install --force` + +### Getting Help + +- **Discord Community**: [Join Discord](https://discord.gg/g6ypHytrCB) +- **GitHub Issues**: [Report bugs](https://github.com/bmadcode/bmad-method/issues) +- **Documentation**: [Browse docs](https://github.com/bmadcode/bmad-method/tree/main/docs) +- **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode) + +## Best Practices + +### Project Organization + +#### Folder Structure + +```text +project/ +├── .bmad-core/ # BMAD agents and resources +├── docs/ # Generated documentation +│ ├── prd.md +│ ├── architecture.md +│ └── stories/ +├── src/ # Source code +└── tests/ # Test files +``` + +#### Document Management + +- Keep generated docs in `docs/` folder +- Version control all BMAD-generated content +- Regular backups of `.bmad-core/` customizations + +### Development Workflow + +#### Planning Phase + +1. **Start with Analysis**: Use analyst for market research +2. **Create PRD**: PM agent for comprehensive requirements +3. **Design Architecture**: Architect for technical foundation +4. **Plan UX**: UX Expert for user experience + +#### Development Phase + +1. **Shard Work**: PO to break down epics +2. **Story Development**: SM for manageable tasks +3. **Implementation**: Dev for coding +4. **Quality Assurance**: QA for testing + +#### Review Process + +1. **Code Review**: Dev agent for code quality +2. **Functional Testing**: QA for feature validation +3. **User Acceptance**: PO for business requirements +4. **Documentation**: Update docs as needed + +### Quality Assurance + +#### Code Quality + +- Use dev agent for code reviews +- Implement suggested improvements +- Follow established coding standards +- Regular refactoring sessions + +#### Documentation Standards + +- Keep docs updated with changes +- Use templates for consistency +- Regular doc reviews with PO +- Clear, actionable user stories + +#### Process Quality + +- Follow Agile ceremonies +- Regular retrospectives +- Continuous improvement +- Stakeholder feedback integration + +### Performance Optimization + +#### Context Management + +- Use specific agents vs. bmad-master +- Minimal team configurations +- Regular dependency cleanup +- Archive completed projects + +#### Resource Efficiency + +- Appropriate bundle sizes +- Selective agent usage +- Efficient template design +- Regular cache clearing + +## Conclusion + +BMAD-METHOD provides a comprehensive framework for AI-assisted software development. By following this guide, you'll be able to: + +- Effectively use specialized AI agents +- Create professional documentation +- Follow structured development workflows +- Integrate with your preferred tools +- Maintain high quality standards + +Remember: BMAD is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details. + +--- + +For additional support, join our [Discord community](https://discord.gg/g6ypHytrCB) or check out the [YouTube channel](https://www.youtube.com/@BMadCode) for video tutorials and walkthroughs.