feat: Installation includes a getting started user guide with detailed mermaid diagram

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
+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)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
+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
 

bmad-core/user-guide.md

@@ -1,11 +1,15 @@
-# BMad-Method Agentic Agile Driven Development User Guide
+# BMad-Method BMAd Code User Guide
 
-This comprehensive guide will help you understand and effectively use the BMad Method framework for AI-assisted software development along with many expansion purposes.
+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:

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

@@ -1,20 +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, tasks, templates and other data files
-- `.claude/commands/BMad/agents` folder with agent command files (`.md`)
-- `.claude/commands/BMad/tasks` folder with stand alone task 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...

docs/agentic-tools/cline-guide.md

@@ -1,17 +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:
-
-- `.bmad-core/` folder with all agents, tasks, templates and other data files
-- `.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

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, tasks, templates and other data files
-- `.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.

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

@@ -1,32 +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:
-
-- `.bmad-core/` folder with all agents, tasks, templates and other data files
-- `.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

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:
-
-- `.bmad-core/` folder with all agents, tasks, templates and other data files
-- Creates 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.
-- Creates 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.

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, tasks, templates and other data files
-- `.roomodes` file in project root with custom modes
-
-## Roo Code-Specific Features
-
-- **Mode file**: `.roomodes` in project root
-- **Mode switching**: Use mode selecto

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, tasks, templates and other data files
-- `.trae/rules/` folder with agent rule files (`.md`)
-
-## Using BMad Agents in Trae
-
-Type `@agent-name` in chat to activate an agent.

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, tasks, templates and other data files
-- `.windsurf/rules/` folder with agent rule files (`.md`)
-
-## Using BMad Agents in Windsurf
-
-Type `@agent-name` in chat to activate an agent.

docs/bmad-workflow-guide.md

@@ -1,167 +0,0 @@
-# BMad Method Universal Workflow Guide
-
-This guide outlines the core BMad workflow that applies regardless of which AI-powered IDE you're using.
-
-## Overview
-
-The BMad Method follows a structured approach to AI-assisted software development:
-
-1. **Install BMad** in your project
-2. **Plan with Gemini** using team-fullstack
-3. **Organize with bmad-master** (document sharding)
-4. **Develop iteratively** with SM → Dev cycles
-
-## The Complete Workflow
-
-### Phase 1: Project Setup
-
-1. **Install BMad in your project**:
-
-   ```bash
-   npx bmad-method install
-   ```
-
-   - Choose "Complete installation"
-   - Select your IDE (Cursor, Claude Code, Windsurf, Trae, Roo Code, or GitHub Copilot)
-
-2. **Verify installation**:
-   - `.bmad-core/` folder created with all agents
-   - IDE-specific integration files created
-   - All agent commands/rules/modes available
-
-### Phase 2: Ideation & Planning (Gemini)
-
-Use Google's Gemini for collaborative planning with the full team:
-
-1. **Open [Google Gems](https://gemini.google.com/gems/view)**
-2. **Create a new Gem**:
-   - Give it a title (e.g., "BMad Team Fullstack")
-   - In the description enter:
-3. **Load team-fullstack**:
-   - Copy contents of: `web-bundles/teams/team-fullstack.txt` from your project
-   - Paste this content into the Gem setup to configure the team
-4. **Collaborate with the team**:
-   - Business Analyst: Requirements gathering
-   - Product Manager: Feature prioritization
-   - Solution Architect: Technical design
-   - UX Expert: User experience design
-
-### Example Gemini Sessions:
-
-```text
-"I want to build a [type] application that [core purpose].
-Help me brainstorm features and create a comprehensive PRD."
-
-"Based on this PRD, design a scalable technical architecture
-that can handle [specific requirements]."
-```
-
-5. **Export planning documents**:
-   - Copy the PRD output and save as `docs/prd.md` in your project
-   - Copy the architecture output and save as `docs/architecture.md` in your project
-
-### Phase 3: Document Organization (IDE)
-
-Switch back to your IDE for document management:
-
-1. **Load bmad-master agent** (syntax varies by IDE)
-2. **Shard the PRD**:
-   ```
-   *shard-doc docs/prd.md prd
-   ```
-3. **Shard the architecture**:
-   ```
-   *shard-doc docs/architecture.md architecture
-   ```
-
-**Result**: Organized folder structure:
-
-- `docs/prd/` - Broken down PRD sections
-- `docs/architecture/` - Broken down architecture sections
-
-### Phase 4: Iterative Development
-
-Follow the SM → Dev cycle for systematic story development:
-
-#### Story Creation (Scrum Master)
-
-1. **Start new chat/conversation**
-2. **Load SM agent**
-3. **Execute**: `*create` (runs create-next-story task)
-4. **Review generated story** in `docs/stories/`
-5. **Update status**: Change from "Draft" to "Approved"
-
-#### Story Implementation (Developer)
-
-1. **Start new chat/conversation**
-2. **Load Dev agent**
-3. **Agent asks**: Which story to implement
-4. **Follow development tasks**
-5. **Complete implementation**
-6. **Update status**: Change to "Done"
-
-#### Repeat Until Complete
-
-- **SM**: Create next story → Review → Approve
-- **Dev**: Implement story → Complete → Mark done
-- **Continue**: Until all features implemented
-
-## IDE-Specific Syntax
-
-### Agent Loading Syntax by IDE:
-
-- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
-- **Cursor**: `@agent-name` (e.g., `@bmad-master`)
-- **Gemini CLI**: `*agent-name` (e.g., `*bmad-master`)
-- **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
-- **Trae**: `@agent-name` (e.g., `@bmad-master`)
-- **Roo Code**: Select mode from mode selector (e.g., `bmad-master`)
-- **GitHub Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
-
-### Chat Management:
-
-- **Claude Code, Cursor, Windsurf, Trae**: Start new chats when switching agents
-- **Roo Code**: Switch modes within the same conversation
-
-## Available Agents
-
-### Core Development Agents:
-
-- **bmad-master**: Universal task executor, document management
-- **sm**: Scrum Master for story creation and agile process
-- **dev**: Full-stack developer for implementation
-- **architect**: Solution architect for technical design
-
-### Specialized Agents:
-
-- **pm**: Product manager for planning and prioritization
-- **analyst**: Business analyst for requirements
-- **qa**: QA specialist for testing strategies
-- **po**: Product owner for backlog management
-- **ux-expert**: UX specialist for design
-
-## Key Principles
-
-1. **Agent Specialization**: Each agent has specific expertise and responsibilities
-2. **Clean Handoffs**: Always start fresh when switching between agents
-3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
-4. **Iterative Development**: Complete one story before starting the next
-5. **Documentation First**: Always start with solid PRD and architecture
-
-## Common Commands
-
-Every agent supports these core commands:
-
-- `*help` - Show available commands
-- `*status` - Show current context/progress
-- `*exit` - Exit the agent mode
-
-## Success Tips
-
-- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
-- **Use bmad-master for document organization** - Sharding creates manageable chunks
-- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
-- **Keep conversations focused** - One agent, one task per conversation
-- **Review everything** - Always review and approve before marking complete
-
-This workflow ensures systematic, AI-assisted development following agile principles with clear separation of concerns and consistent progress tracking.

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