From 2018ad07c7d4c68efb3c24d85ac7612942c6df9c Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Fri, 4 Jul 2025 08:35:28 -0500 Subject: [PATCH] fix: documentation updates --- docs/agentic-tools/claude-code-guide.md | 20 +- docs/agentic-tools/cline-guide.md | 22 +- docs/agentic-tools/cursor-guide.md | 27 +- docs/agentic-tools/gemini-cli-guide.md | 16 +- docs/agentic-tools/github-copilot-guide.md | 43 +-- docs/agentic-tools/roo-code-guide.md | 35 +- docs/agentic-tools/windsurf-guide.md | 2 - docs/user-guide.md | 415 +-------------------- docs/working-in-the-brownfield.md | 13 +- 9 files changed, 36 insertions(+), 557 deletions(-) diff --git a/docs/agentic-tools/claude-code-guide.md b/docs/agentic-tools/claude-code-guide.md index 64134c9c..fbf293a6 100644 --- a/docs/agentic-tools/claude-code-guide.md +++ b/docs/agentic-tools/claude-code-guide.md @@ -1,6 +1,6 @@ # BMad Method Guide for Claude Code -This guide covers Claude Code-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). +For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). ## Installation @@ -11,23 +11,7 @@ When running `npx bmad-method install`, select **Claude Code** as your IDE. This ## Using BMad Agents in Claude Code -Type `/agent-name` in your chat to activate an agent: - -- `/bmad-master` - Universal task executor -- `/sm` - Scrum Master -- `/dev` - Full-stack developer -- `/architect` - Solution architect -- `/pm` - Product manager -- `/analyst` - Business analyst -- `/qa` - QA specialist -- `/po` - Product owner -- `/ux-expert` - UX specialist - -## Claude Code-Specific Features - -- **Command files**: Stored in `.claude/commands/` as `.md` files -- **Activation**: Use forward slash `/` prefix for all agents -- **Chat management**: Start new chats when switching agents for clean context +Type `/agent-name` in your chat to activate an agent. ## Tips for Claude Code Users diff --git a/docs/agentic-tools/cline-guide.md b/docs/agentic-tools/cline-guide.md index 8888077d..40760091 100644 --- a/docs/agentic-tools/cline-guide.md +++ b/docs/agentic-tools/cline-guide.md @@ -1,6 +1,6 @@ # BMad Method Guide for Cline (VS Code) -This guide covers Cline-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). +For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). ## Installation @@ -14,23 +14,3 @@ When running `npx bmad-method install`, select **Cline** as your IDE. This creat 1. **Open Cline panel** in VS Code 2. **Type `@agent-name`** in the chat (e.g., `@dev`, `@sm`, `@architect`) 3. The agent adopts that persona for the conversation - -## Available Agents - -All agents use `@` prefix: - -- `@bmad-master` - Universal task executor -- `@sm` - Scrum Master -- `@dev` - Full-stack developer -- `@architect` - Solution architect -- `@pm` - Product manager -- `@analyst` - Business analyst -- `@qa` - QA specialist -- `@po` - Product owner -- `@ux-expert` - UX specialist - -## Cline-Specific Features - -- **Rule files**: Stored as numbered files in `.clinerules/` (e.g., `01-bmad-master.md`) -- **Agent ordering**: Prioritized list with core agents first -- **VS Code integration**: Works within VS Code's Cline extension panel diff --git a/docs/agentic-tools/cursor-guide.md b/docs/agentic-tools/cursor-guide.md index 1f6c349e..21ef11d0 100644 --- a/docs/agentic-tools/cursor-guide.md +++ b/docs/agentic-tools/cursor-guide.md @@ -1,6 +1,6 @@ # BMad Method Guide for Cursor -This guide covers Cursor-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). +For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). ## Installation @@ -11,27 +11,4 @@ When running `npx bmad-method install`, select **Cursor** as your IDE. This crea ## Using BMad Agents in Cursor -Type `@agent-name` in chat (Ctrl+L / Cmd+L) to activate an agent: - -- `@bmad-master` - Universal task executor -- `@sm` - Scrum Master -- `@dev` - Full-stack developer -- `@architect` - Solution architect -- `@pm` - Product manager -- `@analyst` - Business analyst -- `@qa` - QA specialist -- `@po` - Product owner -- `@ux-expert` - UX specialist - -## Cursor-Specific Features - -- **Rule files**: Stored in `.cursor/rules/` as `.mdc` files -- **Auto-completion**: Cursor suggests agents as you type `@` -- **Context awareness**: Agents can see your current file selection -- **Custom agents**: For better performance, copy agent content into Cursor's custom modes - -## Tips for Cursor Users - -- Start new chats when switching agents -- Each agent supports `*help` to see available commands -- Leverage Cursor's file context for more accurate assistance +Type `@agent-name` in chat (Ctrl+L / Cmd+L) to activate an agent. Make sure you select the icon that looks like a small ruler if presented with multiple options in the popup window. diff --git a/docs/agentic-tools/gemini-cli-guide.md b/docs/agentic-tools/gemini-cli-guide.md index d70586f3..8e029459 100644 --- a/docs/agentic-tools/gemini-cli-guide.md +++ b/docs/agentic-tools/gemini-cli-guide.md @@ -1,6 +1,6 @@ # BMad Method Guide for Gemini CLI -This guide covers Gemini CLI-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). +For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). ## Installation @@ -19,20 +19,6 @@ Simply mention the agent in your prompt: The Gemini CLI automatically loads the appropriate agent context. -## Available Agents - -All agents are referenced with `@` in prompts: - -- `@bmad-master` - Universal task executor -- `@sm` - Scrum Master -- `@dev` - Full-stack developer -- `@architect` - Solution architect -- `@pm` - Product manager -- `@analyst` - Business analyst -- `@qa` - QA specialist -- `@po` - Product owner -- `@ux-expert` - UX specialist - ## Gemini CLI-Specific Features - **Context files**: All agents loaded as context in `.gemini/agents/` diff --git a/docs/agentic-tools/github-copilot-guide.md b/docs/agentic-tools/github-copilot-guide.md index 7591222c..7767c98a 100644 --- a/docs/agentic-tools/github-copilot-guide.md +++ b/docs/agentic-tools/github-copilot-guide.md @@ -1,53 +1,22 @@ -# BMad Method Guide for Visual Studio Code +# BMad Method Guide for Github Copilot -This guide covers the setup and usage of the BMad Method in Visual Studio Code. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). +For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). ## Installation -When running `npx bmad-method install`, select **Visual Studio Code** as your IDE. This command will perform the following actions: +When running `npx bmad-method install`, select **Github Copilot** as your IDE. This command will perform the following actions: - Create the `.bmad-core/` directory with all the agent rule files. - -- Create the `.vscode/` directory and add a `settings.json` file with the basic configuration to enable GitHub Copilot's agent mode. +- Create the `.vscode/` directory and add a `settings.json` file if it does not already exist, and add the basic configuration to enable GitHub Copilot's agent mode. +- Create a chatmodes file under your .github folder for each specific agent being added ## Using BMad Agents in VS Code -1. In the GitHub Copilot Chat window, select **Agent** from the chat mode dropdown list (usually located next to the input field). - -2. Once in Agent Mode, type `@` and the agent's name in the chat input to activate it: - -- `@bmad-master` - Universal task executor - -- `@sm` - Scrum Master - -- `@dev` - Full-stack developer - -- `@architect` - Solution architect - -- `@pm` - Product manager - -- `@analyst` - Business analyst - -- `@qa` - QA specialist - -- `@po` - Product owner - -- `@ux-expert` - UX specialist +1. In the GitHub Copilot Chat window, select **Agent** from the chat mode dropdown list. ## VS Code Specific Features - **Dynamic Configuration**: When you first invoke an agent (e.g., `@dev`), VS Code will automatically update `.vscode/settings.json` by adding the configuration for that chat mode. - - **Activation**: Use the `@` prefix in the GitHub Copilot Chat for instant switching between agents. - - **Collaboration**: Fully compatible with **Live Share**, allowing you, your team, and BMad agents to work together in real-time. - - **Project Context**: Agents have full access to your workspace, including open files and the selected code. - -## Tips for VS Code Users - -- Use the `help` command (e.g., `@dev help`) to see the available commands for each agent. - -- Use `@workspace` in the Copilot Chat to ask questions about your entire project. - -- Consider adding `.vscode/` and `.bmad-core/` to your `.gitignore` file in team projects to avoid conflicts with personal settings. diff --git a/docs/agentic-tools/roo-code-guide.md b/docs/agentic-tools/roo-code-guide.md index 21ce0879..3e1c6ab3 100644 --- a/docs/agentic-tools/roo-code-guide.md +++ b/docs/agentic-tools/roo-code-guide.md @@ -1,7 +1,5 @@ # BMad Method Guide for Roo Code -This guide covers Roo Code-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). - ## Installation When running `npx bmad-method install`, select **Roo Code** as your IDE. This creates: @@ -9,38 +7,7 @@ When running `npx bmad-method install`, select **Roo Code** as your IDE. This cr - `.bmad-core/` folder with all agents - `.roomodes` file in project root with custom modes -## Using BMad Agents in Roo Code - -Select mode from the mode selector (usually in status bar): - -- `bmad-bmad-master` - ๐Ÿง™ Universal task executor -- `bmad-sm` - ๐Ÿƒ Scrum Master -- `bmad-dev` - ๐Ÿ’ป Full-stack developer -- `bmad-architect` - ๐Ÿ—๏ธ Solution architect -- `bmad-pm` - ๐Ÿ“‹ Product manager -- `bmad-analyst` - ๐Ÿ“Š Business analyst -- `bmad-qa` - ๐Ÿงช QA specialist -- `bmad-po` - ๐ŸŽฏ Product owner -- `bmad-ux-expert` - ๐ŸŽจ UX specialist - ## Roo Code-Specific Features - **Mode file**: `.roomodes` in project root -- **Mode switching**: Use mode selector instead of starting new chats -- **Context preservation**: Maintains context across mode switches -- **File permissions**: Each agent has specific file access: - -### File Permission Summary - -- **Documentation agents** (analyst, pm, po, sm): `.md`, `.txt` only -- **bmad-architect**: `.md`, `.txt`, `.yaml`, `.yaml`, `.json` -- **bmad-qa**: Test files (`.test.*`, `.spec.*`) and `.md` -- **bmad-ux-expert**: `.md`, `.css`, `.scss`, `.html`, `.jsx`, `.tsx` -- **Full access**: `bmad-dev`, `bmad-bmad-master`, `bmad-orchestrator` - -## Tips for Roo Code Users - -- Switch modes instead of starting new chats -- Each mode supports `*help` to see available commands -- Agents respect file permission boundaries -- Context persists across mode switches +- **Mode switching**: Use mode selecto diff --git a/docs/agentic-tools/windsurf-guide.md b/docs/agentic-tools/windsurf-guide.md index 7502174c..ab982bfd 100644 --- a/docs/agentic-tools/windsurf-guide.md +++ b/docs/agentic-tools/windsurf-guide.md @@ -1,7 +1,5 @@ # BMad Method Guide for Windsurf -This guide covers Windsurf-specific setup and usage with BMad Method. For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md). - ## Installation When running `npx bmad-method install`, select **Windsurf** as your IDE. This creates: diff --git a/docs/user-guide.md b/docs/user-guide.md index 523669d8..a6e36904 100644 --- a/docs/user-guide.md +++ b/docs/user-guide.md @@ -1,6 +1,6 @@ # BMad-Method Agentic Agile Driven Development User Guide -This comprehensive guide will help you understand and effectively use the BMad Method framework for AI-assisted software development. +This comprehensive guide will help you understand and effectively use the BMad Method framework for AI-assisted software development along with many expansion purposes. ## Table of Contents @@ -9,18 +9,15 @@ This comprehensive guide will help you understand and effectively use the BMad M 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) +6. [IDE Integration](#ide-integration) +7. [Web UI Usage](#web-ui-usage) +8. [Advanced Features](#advanced-features) ## 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. +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 with you using advanced elicitation techniques, and guided workflows ### Core Principles @@ -28,7 +25,7 @@ BMad-Method (Breakthrough Method of Agile AI-Driven Development) is an AI agent 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 +5. **Platform Agnostic**: Works with any Project Type or Agentic IDE ### When to Use BMad @@ -44,7 +41,7 @@ BMad-Method (Breakthrough Method of Agile AI-Driven Development) is an AI agent #### Option 1: Web UI (Fastest - 2 minutes) -Best for: ChatGPT, Claude, Gemini users +If you want to do the planning int he Web: 1. Navigate to `dist/teams/` 2. Copy `team-fullstack.txt` content @@ -54,8 +51,6 @@ Best for: ChatGPT, Claude, Gemini users #### Option 2: IDE Integration (5 minutes) -Best for: Cursor, Claude Code, Windsurf, VS Code users - ```bash # Interactive installation (recommended) npx bmad-method install @@ -74,40 +69,6 @@ npx bmad-method install npx bmad-method status ``` -### 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 - -### Upgrading from V3 to V4 - -If you have an existing BMad-Method V3 project, simply run the installer in your project directory: - -```bash -npx bmad-method install -# The installer will automatically detect your V3 installation and offer to upgrade -``` - -The upgrade process will: - -1. Create a backup of your V3 files in `.bmad-v3-backup/` -2. Install the new V4 `.bmad-core/` structure -3. Migrate your documents (PRD, Architecture, Stories, Epics) -4. Set up IDE integration for all V4 agents -5. Create an install manifest for future updates - -After upgrading: - -1. Review your documents in the `docs/` folder - if you had a PRD or architecture in your old project, copy it from the backup to the docs folder if they are not there. -2. Optionally run the `doc-migration-task` to align your documents with V4 templates - you can do this with your agent by saying something like: 'run {drag in task} against {drag prd or arch file from docs} to align with {drag the template from .bmad-core/templates/full-stack-architecture.md}' -3. If you have separate front-end and backend architecture docs you can modify step 2 to merge both into a single full stack architecture or separate Front and Back end. - -The reason #2 and #3 are optional is because now BMad V4 makes sharding optional for the SM. See [Core Configuration](#core-configuration) - -**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/` - you can remove the backup folder versions. - ## Agent System ### Core Development Team @@ -233,8 +194,8 @@ Templates follow the `template-format.md` specification: 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 +2. **Copy to Project**: Save the final markdown output to your project's `docs/` folder (use the ... menu) +3. **Standard Naming**: Use `prd.md` and `architecture.md` for consistent file name 4. **Continue in IDE**: Use IDE agents for development tasks and smaller documents #### File Naming Conventions @@ -468,27 +429,7 @@ When the SM agent executes the `create-next-story` task: #### The Story Template Structure -The story template contains embedded LLM instructions for different agents: - -**SM Agent Instructions**: - -- Populate Dev Notes with specific technical details from architecture -- Include source references for all technical guidance -- Create detailed tasks based on architecture constraints -- Add testing requirements from testing strategy - -**Dev Agent Instructions**: - -- Update Debug Log References during implementation -- Document any deviations in Completion Notes -- Maintain comprehensive File List of all changes -- Track requirement changes in Change Log - -**QA Agent Instructions**: - -- Append review results in QA Results section -- Document refactoring performed with explanations -- Note security and performance considerations +The story template contains embedded LLM instructions for the SM Dev and QA Agent. #### How Agents Pass Information @@ -525,57 +466,6 @@ The QA agent contributes: - **Improvements Checklist**: Items completed (marked [x]) vs. items for Dev to address (marked [ ]) - **Learning Opportunities**: Explanations for junior/mid-level developer growth -#### Example: How Notes Flow Between Stories - -**Story 1.1 Completion**: - -```markdown -### Completion Notes List - -- Discovered that user authentication requires additional session management not specified in architecture -- Created new SessionManager service in services/auth/session-manager.ts -- Recommend updating architecture to include session management patterns -``` - -**Story 1.2 Creation** (SM uses the above notes): - -```markdown -## Dev Notes - -### Previous Story Insights - -- Story 1.1 created SessionManager service for auth (services/auth/session-manager.ts) -- Consider using SessionManager for this story's user profile feature -- Architecture update pending for session management patterns -``` - -This continuous feedback loop ensures each story benefits from lessons learned in previous implementations. - -#### QA Agent Key Principles - -When the QA agent performs the review-story task: - -- **Senior Developer Authority**: Reviews as a senior developer with authority to refactor directly -- **Active Improvement**: Makes code improvements rather than just identifying issues -- **Teaching Focus**: Explains all changes for developer learning and growth -- **Pragmatic Balance**: Focuses on significant improvements, not nitpicks -- **Quality Gates**: Can block story completion if critical issues exist - -**QA Blocking Conditions**: -The QA will stop and request clarification if: - -- Story file is incomplete or missing critical sections -- File List is empty or clearly incomplete -- No tests exist when they were required -- Code changes don't align with story requirements -- Critical architectural issues require discussion - -- **Benefits of QA Review**: - - Code quality improvements and refactoring - - Knowledge transfer through documented explanations - - Catching edge cases and security issues - - Ensuring architectural consistency - ### Workflow Types #### Greenfield Development @@ -598,85 +488,11 @@ For existing projects: 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 +- **Context Management**: Keep relevant files only in context, keep files as lean and focused as necessary - **Agent Selection**: Use appropriate agent for task - **Iterative Development**: Work in small, focused tasks - **File Organization**: Maintain clean project structure @@ -685,92 +501,14 @@ workflows: **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 +type #help when in the Gem or Custom GPT with one of the teams, and the BMad-Orchestrator will give you an up to date list of commands. ### 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 @@ -784,7 +522,7 @@ BMad's dependency system ensures agents only load necessary resources: ### Custom Templates -Create custom templates following `template-format.md`: +Create custom templates following `utils/template-format.md`: ```markdown --- @@ -1384,132 +1122,13 @@ Add specialized capabilities: ## Troubleshooting Guide -### Common Issues +## Getting Help -#### 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) +- **Discord Community**: [Join Discord](https://discord.gg/gk8jAdXWmj) - **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 and Tips - -### 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 - -### Recommended Development Flow - -#### 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: @@ -1521,7 +1140,3 @@ BMad-Method provides a comprehensive framework for AI-assisted software developm - 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. diff --git a/docs/working-in-the-brownfield.md b/docs/working-in-the-brownfield.md index 6e977aa2..81e9dd62 100644 --- a/docs/working-in-the-brownfield.md +++ b/docs/working-in-the-brownfield.md @@ -1,12 +1,11 @@ # Working in the Brownfield: A Complete Guide -> ๐Ÿš€ **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation!** +> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!** > -> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase at once: +> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase or critical sections of it all at once (obviously within reason): > -> - Upload via GitHub URL -> - Upload up to 1000 files -> - Upload zipped project +> - Upload via GitHub URL or use gemini cli in the project folder +> - If in the web: Upload up to 1000 files or the zipped project or just give it the github url ## What is Brownfield Development? @@ -21,6 +20,10 @@ Brownfield development refers to adding features, fixing bugs, or modernizing ex - Fix bugs that require architectural understanding - Document undocumented systems +## When NOT to use a Brownfield Flow + +If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask him to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there. + ## The Complete Brownfield Workflow ### Choose Your Approach