bmad-method 4.30.4 → 4.31.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [4.31.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.30.4...v4.31.0) (2025-07-20)
+
+
+### Bug Fixes
+
+* enhanced user guide with better diagrams ([c445962](https://github.com/bmadcode/BMAD-METHOD/commit/c445962f259cd7d84c47a896e7fda99e83a30c8d))
+
+
+### Features
+
+* Installation includes a getting started user guide with detailed mermaid diagram ([df57d77](https://github.com/bmadcode/BMAD-METHOD/commit/df57d772cac9f9010811e7e86a6433a0fe636a45))
+
 ## [4.30.4](https://github.com/bmadcode/BMAD-METHOD/compare/v4.30.3...v4.30.4) (2025-07-19)
 
 

package/README.md

@@ -23,7 +23,7 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 
 This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why.
 
-**📖 [See the complete workflow in the User Guide](docs/user-guide.md)** - Planning phase, development cycle, and all agent roles
+**📖 [See the complete workflow in the User Guide](bmad-core/user-guide.md)** - Planning phase, development cycle, and all agent roles
 
 ## Quick Navigation
 
@@ -31,15 +31,15 @@ This two-phase approach eliminates both **planning inconsistency** and **context
 
 **Before diving in, review these critical workflow diagrams that explain how BMad works:**
 
-1. **[Planning Workflow (Web UI)](docs/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
-2. **[Core Development Cycle (IDE)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
+1. **[Planning Workflow (Web UI)](bmad-core/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
+2. **[Core Development Cycle (IDE)](bmad-core/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
 
 > ⚠️ **These diagrams explain 90% of BMad Method Agentic Agile flow confusion** - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner!
 
 ### What would you like to do?
 
 - **[Install and Build software with Full Stack Agile AI Team](#quick-start)** → Quick Start Instruction
-- **[Learn how to use BMad](docs/user-guide.md)** → Complete user guide and walkthrough
+- **[Learn how to use BMad](bmad-core/user-guide.md)** → Complete user guide and walkthrough
 - **[See available AI agents](#available-agents)** → Specialized roles for your team
 - **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education
 - **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain
@@ -97,7 +97,7 @@ This single command handles:
 3. **Upload & configure**: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
 4. **Start Ideating and Planning**: Start chatting! Type `*help` to see available commands or pick an agent like `*analyst` to start right in on creating a brief.
 5. **CRITICAL**: Talk to BMad Orchestrator in the web at ANY TIME (#bmad-orchestrator command) and ask it questions about how this all works!
-6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](docs/user-guide.md) for more details
+6. **When to move to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](bmad-core/user-guide.md) for more details
 
 ### Alternative: Clone and Build
 
@@ -114,10 +114,9 @@ BMad's natural language framework works in ANY domain. Expansion packs provide s
 
 ### Essential Guides
 
-- 📖 **[User Guide](docs/user-guide.md)** - Complete walkthrough from project inception to completion
+- 📖 **[User Guide](bmad-core/user-guide.md)** - Complete walkthrough from project inception to completion
 - 🏗️ **[Core Architecture](docs/core-architecture.md)** - Technical deep dive and system design
 - 🚀 **[Expansion Packs Guide](docs/expansion-packs.md)** - Extend BMad to any domain beyond software development
-- [IDE Specific Guides available in this folder](docs/agentic-tools/)
 
 ## Support
 

package/bmad-core/user-guide.md

@@ -0,0 +1,250 @@
+# BMad-Method BMAd Code User Guide
+
+This guide will help you understand and effectively use the BMad Method for agile ai driven planning and development.
+
+## The BMad Plan and Execute Workflow
+
+First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but its suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
+
+If you are going to use the BMad Method with a Brownfield project (an existing project), review [Working in the Brownfield](./working-in-the-brownfield.md)
+
+If you do not see the diagrams that following rendering, you can install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugin's, if you right click on the tab when open, there should be a Open Preview option, or check the IDE documentation.
+
+### The Planning Workflow (Web UI or Powerful IDE Agents)
+
+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 Research"}
+    B -->|Yes| C["Analyst: Brainstorming (Optional)"]
+    B -->|No| G{"Project Brief Available?"}
+    C --> C2["Analyst: Market Research (Optional)"]
+    C2 --> C3["Analyst: Competitor Analysis (Optional)"]
+    C3 --> D["Analyst: Create Project Brief"]
+    D --> G
+    G -->|Yes| E["PM: Create PRD from Brief (Fast Track)"]
+    G -->|No| E2["PM: Interactive PRD Creation (More Questions)"]
+    E --> F["PRD Created with FRs, NFRs, Epics & Stories"]
+    E2 --> F
+    F --> F2{"UX Required?"}
+    F2 -->|Yes| F3["UX Expert: Create Front End Spec"]
+    F2 -->|No| H["Architect: Create Architecture from PRD"]
+    F3 --> F4["UX Expert: Generate UI Prompt for Lovable/V0 (Optional)"]
+    F4 --> H2["Architect: Create Architecture from PRD + UX Spec"]
+    H --> I["PO: Run Master Checklist"]
+    H2 --> I
+    I --> J{"Documents Aligned?"}
+    J -->|Yes| K["Planning Complete"]
+    J -->|No| L["PO: Update Epics & Stories"]
+    L --> M["Update PRD/Architecture as needed"]
+    M --> I
+    K --> N["📁 Switch to IDE (If in a Web Agent Platform)"]
+    N --> O["PO: Shard Documents"]
+    O --> P["Ready for SM/Dev Cycle"]
+
+    style A fill:#f5f5f5,color:#000
+    style B fill:#e3f2fd,color:#000
+    style C fill:#e8f5e9,color:#000
+    style C2 fill:#e8f5e9,color:#000
+    style C3 fill:#e8f5e9,color:#000
+    style D fill:#e8f5e9,color:#000
+    style E fill:#fff3e0,color:#000
+    style E2 fill:#fff3e0,color:#000
+    style F fill:#fff3e0,color:#000
+    style F2 fill:#e3f2fd,color:#000
+    style F3 fill:#e1f5fe,color:#000
+    style F4 fill:#e1f5fe,color:#000
+    style G fill:#e3f2fd,color:#000
+    style H fill:#f3e5f5,color:#000
+    style H2 fill:#f3e5f5,color:#000
+    style I fill:#f9ab00,color:#fff
+    style J fill:#e3f2fd,color:#000
+    style K fill:#34a853,color:#fff
+    style L fill:#f9ab00,color:#fff
+    style M fill:#fff3e0,color:#000
+    style N fill:#1a73e8,color:#fff
+    style O fill:#f9ab00,color:#fff
+    style P 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's docs folder (or a custom location you can specify during installation)
+2. **Switch to IDE**: Open your project in your preferred Agentic IDE
+3. **Document Sharding**: Use the PO agent to shard the PRD and then the Architecture
+4. **Begin Development**: Start the Core Development Cycle that follows
+
+### The Core Development Cycle (IDE)
+
+Once planning is complete and documents are sharded, BMad follows a structured development workflow:
+
+```mermaid
+graph TD
+    A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
+    B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
+    B2 --> B3{"QA: Review Story Draft (Optional)"}
+    B3 -->|Review Requested| B4["QA: Review Story Against Artifacts"]
+    B3 -->|Skip Review| C{"User Approval"}
+    B4 --> C
+    C -->|Approved| D["Dev: Sequential Task Execution"]
+    C -->|Needs Changes| B2
+    D --> E["Dev: Implement Tasks + Tests"]
+    E --> F["Dev: Run All Validations"]
+    F --> G["Dev: Mark Ready for Review + Add Notes"]
+    G --> H{"User Verification"}
+    H -->|Request QA Review| I["QA: Senior Dev Review + Active Refactoring"]
+    H -->|Approve Without QA| M["IMPORTANT: Verify All Regression Tests and Linting are Passing"]
+    I --> J["QA: Review, Refactor Code, Add Tests, Document Notes"]
+    J --> L{"QA Decision"}
+    L -->|Needs Dev Work| D
+    L -->|Approved| M
+    H -->|Needs Fixes| D
+    M --> N["IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!"]
+    N --> K["Mark Story as Done"]
+    K --> B
+
+    style A fill:#f5f5f5,color:#000
+    style B fill:#e8f5e9,color:#000
+    style B2 fill:#e8f5e9,color:#000
+    style B3 fill:#e3f2fd,color:#000
+    style B4 fill:#fce4ec,color:#000
+    style C fill:#e3f2fd,color:#000
+    style D fill:#e3f2fd,color:#000
+    style E fill:#e3f2fd,color:#000
+    style F fill:#e3f2fd,color:#000
+    style G fill:#e3f2fd,color:#000
+    style H fill:#e3f2fd,color:#000
+    style I fill:#f9ab00,color:#fff
+    style J fill:#ffd54f,color:#000
+    style K fill:#34a853,color:#fff
+    style L fill:#e3f2fd,color:#000
+    style M fill:#ff5722,color:#fff
+    style N fill:#d32f2f,color:#fff
+```
+
+## Installation
+
+### Optional
+
+If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
+
+1. Navigate to `dist/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
+
+### IDE Project Setup
+
+```bash
+# Interactive installation (recommended)
+npx bmad-method install
+```
+
+## Special Agents
+
+There are two bmad agents - in the future they will be consolidated into the single bmad-master.
+
+### BMad-Master
+
+This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when in the web by accessing the knowledge base and explaining anything to you about the process.
+
+If you dont want to bother switching between different agents aside from the dev, this is the agent for you.
+
+### BMad-Orchestrator
+
+This agent should NOT be used within the IDE, it is a heavy weight special purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the team's within the web bundles. If you use a web bundle you will be greeted by the BMad Orchestrator.
+
+### How Agents Work
+
+#### Dependencies System
+
+Each agent has a YAML section that defines 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
+# Some Ide's, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
+@pm Create a PRD for a task management app
+@architect Design the system architecture
+@dev Implement the user authentication
+
+# Some, like Claude Code use slash commands instead
+/pm Create user stories
+/dev Fix the login bug
+```
+
+#### Interactive Modes
+
+- **Incremental Mode**: Step-by-step with user input
+- **YOLO Mode**: Rapid generation with minimal interaction
+
+## IDE Integration
+
+### IDE Best Practices
+
+- **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
+
+## Technical Preferences System
+
+BMad includes a personalization system through the `technical-preferences.md` file located in `.bmad-core/data/` - this can help bias the PM and Architect to recommend your preferences for design patterns, technology selection, or anything else you would like to put in here.
+
+### 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.
+
+## Core Configuration
+
+The `bmad-core/core-config.yaml` file is a critical config that enables BMad to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml.
+
+### Developer Context Files
+
+Define which files the dev agent should always load:
+
+```yaml
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/project-structure.md
+```
+
+You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into it's context. These are the rules the agent will follow.
+
+As your project grows and the code starts to build consistent patterns, coding standards should be reduced to just the items that the agent makes mistakes at still - must with the better models, they will look at surrounding code in files and not need a rule from that file to guide them.
+
+## Getting Help
+
+- **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/docs)
+- **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode)
+
+## Conclusion
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.30.4",
+  "version": "4.31.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {

package/tools/installer/lib/installer.js

@@ -891,6 +891,10 @@ class Installer {
       console.log(chalk.yellow.bold("\n⚠️  IMPORTANT: Cursor Custom Modes Update Required"));
       console.log(chalk.yellow("Since agents have been updated, you need to update any custom agent modes configured in the Cursor custom agent GUI per the Cursor docs."));
     }
+
+    // Important notice to read the user guide
+    console.log(chalk.red.bold("\n📖 IMPORTANT: Please read the user guide installed at docs/user-guide.md"));
+    console.log(chalk.red("This guide contains essential information about the BMad workflow and how to use the agents effectively."));
   }
 
   // Legacy method for backward compatibility

package/tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.30.4",
+  "version": "4.31.0",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "main": "lib/installer.js",
   "bin": {

package/docs/agentic-tools/claude-code-guide.md

@@ -1,19 +0,0 @@
-# BMad Method Guide for Claude Code
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-When running `npx bmad-method install`, select **Claude Code** as your IDE. This creates:
-
-- `.bmad-core/` folder with all agents
-- `.claude/commands/BMad` folder with agent command files (`.md`)
-
-## Using BMad Agents in Claude Code
-
-Type `/agent-name` in your chat to activate an agent.
-
-## Tips for Claude Code Users
-
-- Commands are auto-suggested as you type `/`
-- More coming soon...

package/docs/agentic-tools/cline-guide.md

@@ -1,16 +0,0 @@
-# BMad Method Guide for Cline (VS Code)
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-When running `npx bmad-method install`, select **Cline** as your IDE. This creates:
-
-- `.clinerules/` directory with numbered agent rule files (`.md`)
-- Agents ordered by priority (bmad-master first)
-
-## Using BMad Agents in Cline
-
-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

package/docs/agentic-tools/cursor-guide.md

@@ -1,14 +0,0 @@
-# BMad Method Guide for Cursor
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-When running `npx bmad-method install`, select **Cursor** as your IDE. This creates:
-
-- `.bmad-core/` folder with all agents
-- `.cursor/rules/` folder with agent rule files (`.mdc`)
-
-## Using BMad Agents in Cursor
-
-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.

package/docs/agentic-tools/gemini-cli-guide.md

@@ -1,31 +0,0 @@
-# BMad Method Guide for Gemini CLI
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-When running `npx bmad-method install`, select **Gemini CLI** as your IDE. This creates:
-
-- `.gemini/bmad-method/` directory with all agent context in GEMINI.md file
-
-## Using BMad Agents with Gemini CLI
-
-Simply mention the agent in your prompt:
-
-- "As \*dev, implement the login feature"
-- "Acting as \*architect, review this system design"
-- "\*sm, create the next story for our project"
-
-The Gemini CLI automatically loads the appropriate agent context.
-
-## Gemini CLI-Specific Features
-
-- **Context files**: All agents loaded as context in `.gemini/bmad-method/GEMINI.md`
-- **Automatic loading**: GEMINI.md ensures agents are always available
-- **Natural language**: No special syntax needed, just mention the agent
-
-## Tips for Gemini CLI Users
-
-- Be explicit about which agent you're addressing
-- You can switch agents mid-conversation by mentioning a different one
-- The CLI maintains context across your session

package/docs/agentic-tools/github-copilot-guide.md

@@ -1,42 +0,0 @@
-# BMad Method Guide for GitHub Copilot
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-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 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 GitHub Copilot
-
-1.  **Open GitHub Copilot chat** in VS Code (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux).
-2.  Select the agent you want to use from the chat input's participant selector (e.g., `@workspace` > `dev`).
-3.  The agent adopts that persona for the conversation.
-4.  Use `*help` to see the commands available for the selected agent.
-
-## Available Agents
-
-You can switch between agents using the chat participant selector. The following agents are available for GitHub Copilot:
-
-- `bmad-master` - Master Task Executor
-- `dev` - Development expert
-- `qa` - Quality Assurance specialist
-- `ux-expert` - UX specialist
-
-## GitHub Copilot-Specific Features
-
-- **Settings**: Use the `.vscode/settings.json` file to configure Copilot behavior. The installer can configure these for you.
-  - `chat.agent.maxRequests`: Maximum requests per agent session (recommended: 15).
-  - `github.copilot.chat.agent.runTasks`: Allow agents to run workspace tasks (e.g., from `package.json` scripts).
-  - `github.copilot.chat.agent.autoFix`: Enable automatic error detection and fixing in generated code.
-  - `chat.tools.autoApprove`: Auto-approve ALL tools without confirmation (use with caution).
-- **VS Code integration**: Works within VS Code's GitHub Copilot chat panel.
-- **Tool Confirmation**: Copilot will ask for confirmation before running tools that can modify files. You can approve a tool once, for the session, or always.
-
-## Tips for GitHub Copilot Users
-
-- You can use a `.github/copilot-instructions.md` file to provide additional context or instructions for your projects that are not covered by the BMAD framework.
-- BMAD agents can come with a pre-configured set of tools. You can see which tools an agent uses by looking at the `tools` section in its `.github/chatmodes/[agent].chatmode.md` file.

package/docs/agentic-tools/roo-code-guide.md

@@ -1,15 +0,0 @@
-# BMad Method Guide for Roo Code
-
-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:
-
-- `.bmad-core/` folder with all agents
-- `.roomodes` file in project root with custom modes
-
-## Roo Code-Specific Features
-
-- **Mode file**: `.roomodes` in project root
-- **Mode switching**: Use mode selecto

package/docs/agentic-tools/trae-guide.md

@@ -1,14 +0,0 @@
-# BMad Method Guide for Trae
-
-For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
-
-## Installation
-
-When running `npx bmad-method install`, select **Trae** as your IDE. This creates:
-
-- `.bmad-core/` folder with all agents
-- `.trae/rules/` folder with agent rule files (`.md`)
-
-## Using BMad Agents in Trae
-
-Type `@agent-name` in chat to activate an agent.

package/docs/agentic-tools/windsurf-guide.md

@@ -1,14 +0,0 @@
-# BMad Method Guide for Windsurf
-
-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:
-
-- `.bmad-core/` folder with all agents
-- `.windsurf/rules/` folder with agent rule files (`.md`)
-
-## Using BMad Agents in Windsurf
-
-Type `@agent-name` in chat to activate an agent.