bmad-method 6.0.0-alpha.20 → 6.0.0-alpha.22

package/docs/bmad-core-concepts/installing/index.md

@@ -0,0 +1,77 @@
+# Installation
+
+Get BMAD up and running in your project.
+
+## Upgrading?
+
+If you're upgrading from v4, see the [Upgrade Guide](./upgrading.md).
+
+---
+
+## Quick Install
+
+```bash
+npx bmad-method install
+```
+
+This interactive installer will:
+
+1. Let you choose a location to install to
+2. Let you choose which Agentic LLM Tools you would like to use (Such as Claude Code, Cursor, Windsurf, etc...)
+3. Let you choose which official modules to install (BMad Method, Creative Intelligence suite, BMad Builder)
+4. Let you choose any custom local modules, workflows or agents to install
+5. Let you configure each module or quickly accept the default recommended settings for each selected model
+
+## Requirements
+
+- **Node.js** 20+ (for the installer)
+- **Git** (recommended for version control)
+- An **AI-powered Agent and/or IDE** or access to Claude/ChatGPT/Gemini
+
+## Module Options
+
+During installation, you'll choose which modules to install:
+
+| Module   | Description          | Best For                                              |
+| -------- | -------------------- | ----------------------------------------------------- |
+| **BMM**  | BMAD Method Core     | Software development projects                         |
+| **BMGD** | Game Development     | Game projects with specialized workflows              |
+| **CIS**  | Creative Intel Suite | Creativity Unlocking Suite, not software dev specific |
+| **BMB**  | Builder              | Creating custom agents and workflows                  |
+
+You will also be asked if you would like to install custom content (agents, workflows or modules) you have created with the BMB, or shared from others in the community.
+
+
+## Post-Installation
+
+After installation, your project will have:
+
+```
+your-project/
+├── _bmad/              # BMAD configuration and agents
+│   ├── bmm/            # Method module (if installed)
+│   ├── bmgd/           # Game dev module (if installed)
+│   ├── core/           # Always installed, includes party mode, advanced elicitation, and other core generic utils
+│   ├── {others}/       # etc...
+├── _bmad-output/       # BMAD default output folder - configurable during install
+├── .claude/            # IDE-specific setup (varies by IDE)
+└── ... your code       # maybe nothing else yet if a fresh new folder
+```
+
+## Next Steps
+
+1. **Read the [Quick Start Guide](../../modules/bmm-bmad-method/quick-start)** to build your first feature
+2. **Explore [Workflows](../../modules/bmm-bmad-method/index#-workflow-guides)** to understand the methodology
+3. **Learn about [Agents](../agents.md)** to understand BMAD's core building blocks
+
+## Troubleshooting
+
+### Common Issues
+
+**"Command not found: npx"**
+: Install Node.js 20+ from [nodejs.org](https://nodejs.org)
+
+**"Permission denied"**
+: Run with appropriate permissions or check your npm configuration
+
+For more help, join our [Discord](https://discord.gg/bmad).

package/docs/bmad-core-concepts/installing/upgrading.md

@@ -0,0 +1,144 @@
+# BMad v4 to v6 Upgrade Guide
+
+## Overview
+
+BMad v6 represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate your v4 project to v6.
+
+---
+
+## Automatic V4 Detection
+
+When you run `npm run install:bmad` on a project, the installer automatically detects:
+
+- **Legacy v4 installation folder**: `.bmad-method`
+- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
+
+### What Happens During Detection
+
+1. **Automatic Detection of v4 Modules**
+   1. Installer will suggest removal or backup of your .bmad-method folder. You can choose to exit the installer and handle this cleanup, or allow the install to continue. Technically you can have both v4 and v6 installed, but it is not recommended. All BMad content and modules will be installed under a .bmad folder, fully segregated.
+
+2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
+   - Located in IDE config folders, for example claude: `.claude/commands/BMad/agents`, `.claude/commands/BMad/tasks`, etc.
+   - NOTE: if the upgrade and install of v6 finished, the new commands will be under `.claude/commands/bmad/<module>/agents|workflows`
+   - Note 2: If you accidentally delete the wrong/new bmad commands - you can easily restore them by rerunning the installer, and choose quick update option, and all will be reapplied properly.
+
+## Module Migration
+
+### Deprecated Modules from v4
+
+| v4 Module                     | v6 Status                                      |
+| ----------------------------- | ---------------------------------------------- |
+| `_bmad-2d-phaser-game-dev`    | Integrated into new BMGD Module                |
+| `_bmad-2d-unity-game-dev`     | Integrated into new BMGD Module                |
+| `_bmad-godot-game-dev`        | Integrated into new BMGD Module                |
+| `_bmad-*-game-dev` (any)      | Integrated into new BMGD Module                |
+| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming soon |
+| `_bmad-creative-writing`      | Not adapted - New v6 module coming soon        |
+
+Aside from .bmad-method - if you have any of these others installed also, again its recommended to remove them and use the V6 equivalents, but its also fine if you decide to keep both. But it is not recommended to use both on the same project long term.
+
+## Architecture Changes
+
+### Folder Structure
+
+**v4 "Expansion Packs" Structure:**
+
+```
+your-project/
+├── .bmad-method/         
+├── .bmad-game-dev/       
+├── .bmad-creative-writing/
+└── .bmad-infrastructure-devops/
+```
+
+**v6 Unified Structure:**
+
+```
+your-project/
+└── _bmad/               # Single installation folder is _bmad
+    └── _config/         # Your customizations
+    |  └── agents/       # Agent customization files
+    ├── core/            # Real core framework (applies to all modules)
+    ├── bmm/             # BMad Method (software/game dev)
+    ├── bmb/             # BMad Builder (create agents/workflows)
+    ├── cis/             # Creative Intelligence Suite
+├── _bmad_output         # Default bmad output folder (was doc folder in v4)
+
+```
+
+### Key Concept Changes
+
+- **v4 `_bmad-core and _bmad-method`**: Was actually the BMad Method
+- **v6 `_bmad/core/`**: Is the real universal core framework
+- **v6 `_bmad/bmm/`**: Is the BMad Method module
+- **Module identification**: All modules now have a `config.yaml` file once installed at the root of the modules installed folder
+
+## Project Progress Migration
+
+### If You've Completed Some or all Planning Phases (Brief/PRD/UX/Architecture) with the BMad Method:
+
+After running the v6 installer, if you kept the paths the same as the installation suggested, you will need to move a few files, or run the installer again. It is recommended to stick with these defaults as it will be easier to adapt if things change in the future.
+
+If you have any planning artifacts, put them in a folder called _bmad-output/planning-artifacts at the root of your project, ensuring that:
+PRD has PRD in the file name or folder name if sharded.
+Similar for 'brief', 'architecture', 'ux-design'.
+
+If you have other long term docs that will not be as ephemeral as these project docs, you can put them in the /docs folder, ideally with a index.md file.
+
+HIGHLY RECOMMENDED NOTE: If you are only partway through planning, its highly recommended to restart and do the PRD, UX and ARCHITECTURE steps. You could even use your existing documents as inputs letting the agent know you want to redo them with the new workflows. These optimized v6 progressive discovery workflows that also will utilize web search at key moments, while offering better advanced elicitation and part mode in the IDE will produce superior results. And then once all are complete, an epics with stories is generated after the architecture step now - ensuring it uses input from all planing documents.
+
+### If You're Mid-Development (Stories Created/Implemented)
+
+1. Complete the v6 installation as above
+2. Ensure you have a file called epics.md or epics/epic*.md - these need to be located under the _bmad-output/planning-artifacts folder.
+3. Run the scrum masters `sprint-planning` workflow to generate the implementation tracking plan in _bmad-output/implementation-artifacts.
+4. Inform the SM after the output is complete which epics and stories were completed already and should be parked properly in the file.
+
+## Agent Customization Migration
+
+### v4 Agent Customization
+
+In v4, you may have modified agent files directly in `_bmad-*` folders.
+
+### v6 Agent Customization
+
+**All customizations** now go in `_bmad/_config/agents/` using customize files:
+
+**Example: Renaming an agent and changing communication style**
+
+File: `_bmad/_config/agents/bmm-pm.customize.yaml`
+
+```yaml
+# Customize the PM agent
+persona:
+  name: 'Captain Jack' # Override agent name
+  role: 'Swashbuckling Product Owner'
+  communication_style: |
+    - Talk like a pirate
+    - Use nautical metaphors for software concepts
+    - Always upbeat and adventurous
+```
+
+There is a lot more that is possible with agent customization, which is covered in detail in the [Agent Customization Guide](../bmad-customization/agents.md)
+
+CRITICAL NOTE: After you modify the customization file, you need to run the npx installer against your installed location, and choose the option to rebuild all agents, or just do a quick update again. This always builds agents fresh and applies customizations.
+
+**How it works:**
+
+- Base agent: `_bmad/bmm/agents/pm.md`
+- Customization: `_bmad/_config/agents/bmm-pm.customize.yaml`
+- Rebuild all agents -> Result: Agent uses your custom name and style
+
+## Document Compatibility
+
+### Sharded vs Unsharded Documents
+
+**Good news**: Unlike v4, v6 workflows are **fully flexible** with document structure:
+
+- ✅ Sharded documents (split into multiple files)
+- ✅ Unsharded documents (single file per section)
+- ✅ Custom sections for your project type
+- ✅ Mixed approaches
+
+All workflow files are scanned automatically. No manual configuration needed.

package/docs/bmad-core-concepts/modules.md

@@ -0,0 +1,76 @@
+# Modules
+
+Modules are organized collections of agents and workflows that solve specific problems or address particular domains.
+
+## What is a Module?
+
+A module is a self-contained package that includes:
+
+- **Agents** - Specialized AI assistants
+- **Workflows** - Step-by-step processes
+- **Configuration** - Module-specific settings
+- **Documentation** - Usage guides and reference
+
+## Official Modules
+
+### Core Module
+Always installed, provides shared functionality:
+- Global configuration
+- Core workflows (Party Mode, Advanced Elicitation, Brainstorming)
+- Common tasks (document indexing, sharding, review)
+
+### BMAD Method (BMM)
+Software and game development:
+- Project planning workflows
+- Implementation agents (Dev, PM, QA, Scrum Master)
+- Testing and architecture guidance
+
+### BMAD Builder (BMB)
+Create custom solutions:
+- Agent creation workflows
+- Workflow authoring tools
+- Module scaffolding
+
+### Creative Intelligence Suite (CIS)
+Innovation and creativity:
+- Creative thinking techniques
+- Innovation strategy workflows
+- Storytelling and ideation
+
+### BMAD Game Dev (BMGD)
+Game development specialization:
+- Game design workflows
+- Narrative development
+- Performance testing frameworks
+
+## Module Structure
+
+Installed modules follow this structure:
+
+```
+_bmad/
+├── core/           # Always present
+├── bmm/            # BMAD Method (if installed)
+├── bmb/            # BMAD Builder (if installed)
+├── cis/            # Creative Intelligence (if installed)
+└── bmgd/           # Game Dev (if installed)
+```
+
+## Custom Modules
+
+You can create your own modules containing:
+- Custom agents for your domain
+- Organizational workflows
+- Team-specific configurations
+
+Custom modules are installed the same way as official modules.
+
+## Installing Modules
+
+During BMAD installation, you choose which modules to install. You can also add or remove modules later by re-running the installer.
+
+See [Installation Guide](./installing/) for details.
+
+---
+
+**Next:** Read the [Installation Guide](./installing/) to set up BMAD with the modules you need.

package/docs/bmad-core-concepts/web-bundles/index.md

@@ -0,0 +1,34 @@
+# Web Bundles
+
+Use BMAD agents in Gemini Gems and Custom GPTs.
+
+## Status
+
+> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality.
+
+## What Are Web Bundles?
+
+Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
+
+### What's Included
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- No external files required
+
+### Use Cases
+
+**Perfect for:**
+- Uploading a single file to a Gemini GEM or Custom GPT
+- Using BMAD Method from the Web
+- Cost savings (generally lower cost than local usage)
+- Quick sharing of agent configurations
+
+**Trade-offs:**
+- Some quality reduction vs local usage
+- Less convenient than full local installation
+- Limited to agent capabilities (no workflow file access)
+
+[← Back to Core Concepts](../index.md)

package/docs/bmad-core-concepts/workflows.md

@@ -0,0 +1,89 @@
+# Workflows
+
+Workflows are structured processes that guide agents through complex tasks. Think of them as recipes that ensure consistent, high-quality outcomes.
+
+## What is a Workflow?
+
+A workflow is a step-by-step process that agents follow to accomplish specific objectives. A workflow can be a single file if small enough, but more than likely is comprized of a very small workflow or skill definition file with multiple steps and data files that are loaded as needed on demand. Each step file:
+
+- Defines a clear goal
+- Provides instructions for the agent
+- May include decision points or user interactions
+- Produces specific outputs
+- Progressively at a specific point can load the next proper step.
+
+## How Workflows Work
+
+```
+┌─────────────┐    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
+│   Step 1    │ →  │   Step 2    │ →  │   Step 3    │ →  │  Complete   │
+│  Discover   │    │   Define    │    │   Build     │    │   Output    │
+└─────────────┘    └─────────────┘    └─────────────┘    └─────────────┘
+```
+
+**Key characteristics:**
+- **Progressive** - Each step builds on the previous
+- **Interactive** - Workflows can pause for user input
+- **Reusable** - The same workflow produces consistent results
+- **Composable** - Workflow steps can call other workflow steps, or whole other workflows!
+- **LLM Reinforcement** - Some rules or info is repeated in each step file ensuring certain rules are always top of agent mind, even during context heavy processes or very long workflows!
+
+## Workflow Types
+
+### Planning Workflows
+
+Generate project artifacts like requirements, architecture, and task breakdowns.
+
+**Examples:** Brief creation, PRD authoring, architecture design, sprint planning
+
+### Execution Workflows
+
+Guide implementation of specific tasks or features.
+
+**Examples:** Code implementation, code review, testing, deployment
+
+### Support Workflows
+
+Handle cross-cutting concerns and creative processes.
+
+**Examples:** Brainstorming, retrospectives, root cause analysis
+
+## Progressive Disclosure
+
+BMAD workflows use **progressive disclosure** - each step only knows about its immediate next step and what it is currently meant to do. This:
+
+- Reduces cognitive load on the AI
+- Ensures each step gets full attention
+- Allows for conditional routing based on previous outcomes
+- Makes workflows easier to debug and modify
+
+## Menu-Driven Interaction
+
+Most workflows use interactive menus with standard options:
+
+| Option           | Purpose                                            |
+| ---------------- | -------------------------------------------------- |
+| **[A] Advanced** | Invoke deeper reasoning techniques                 |
+| **[P] Party**    | Get multiple agent perspectives                    |
+| **[C] Continue** | Proceed to next step after all writes are complete |
+
+## Workflow Files
+
+Workflows are markdown files with structured frontmatter - this front matter also allows them to easily work as skills and also slash command loaded:
+
+```yaml
+---
+name: 'my-workflow'
+description: 'What this workflow does and when it should be used or loaded automatically (or call out if it should be requested to run explicitly by the user)'
+---
+```
+
+The content in the workflow file is very minimal, sets up the reinforcement of the agent persona and reminder that it is a facilitator working with a user, lays out rules of processing steps only when told to do a specific step, loads all config file variables needed by the workflow, and then routes to step 1. No other info about other steps should be in this workflow file. Keeping it as small and lean as possible help in compilation as a skill, as overall size of the skill main file (workflow.md) is critical to keep small.
+
+## Creating Custom Workflows
+
+The **BMAD Builder (BMB)** module includes workflows for creating custom workflows. See [BMB Documentation](../modules/bmb-bmad-builder/) for details.
+
+---
+
+**Next:** Learn about [Modules](./modules.md) to see how agents and workflows are organized.

package/docs/index.md

@@ -1,143 +1,111 @@
-# BMad Documentation Index
+# BMAD Documentation
 
-Complete map of all BMad Method v6 documentation with recommended reading paths.
+Complete documentation for the BMAD Method.
 
----
+## Getting Started
 
-## 🎯 Getting Started (Start Here!)
+### New to BMAD?
+Start with the core concepts to understand how BMAD works:
 
-**New users:** Start with one of these based on your situation:
+- **[Core Concepts](./bmad-core-concepts/)** - Agents, workflows, and modules explained
+- **[Installation Guide](./bmad-core-concepts/installing/)** - Set up BMAD in your project
+- **[Quick Start Guide](./modules/bmm-bmad-method/quick-start)** - Build your first feature
 
-| Your Situation         | Start Here                                         | Then Read                                                   |
-| ---------------------- | -------------------------------------------------- | ----------------------------------------------------------- |
-| **Brand new to BMad**  | [Quick Start Guide](./modules/bmm/quick-start)     | [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) |
-| **Upgrading from v4**  | [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)    | [Quick Start Guide](./modules/bmm/quick-start)              |
-| **Brownfield project** | [Brownfield Guide](./modules/bmm/brownfield-guide) | [Quick Start Guide](./modules/bmm/quick-start)              |
+### Upgrading from v4?
+- **[v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md)** - Migration path for v4 users
 
 ---
 
-## 📋 Core Documentation
-
-### Project-Level Docs (Root)
-
-- **[README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md)** - Main project overview, feature summary, and module introductions
-- **[CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)** - How to contribute, pull request guidelines, code style
-- **[CHANGELOG.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)** - Version history and breaking changes
-
-### Installation & Setup
-
-- **[v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md)** - Migration path for v4 users
-- **[Document Sharding Guide](./document-sharding-guide.md)** - Split large documents for 90%+ token savings
-- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - Maintainer guide for bundle auto-publishing
-
----
+## Module Documentation
 
-## 🏗️ Module Documentation
-
-### BMad Method (BMM) - Software & Game Development
+### BMAD Method (BMM) - Software & Game Development
 
 The flagship module for agile AI-driven development.
 
-- **[BMM Module README](./modules/bmm/)** - Module overview, agents, and complete documentation index
-- **[BMM Documentation](./modules/bmm/)** - All BMM-specific guides and references:
-  - [Quick Start Guide](./modules/bmm/quick-start) - Step-by-step guide to building your first project
-  - [Quick Spec Flow](./modules/bmm/quick-spec-flow) - Rapid Level 0-1 development
-  - [Scale Adaptive System](./modules/bmm/scale-adaptive-system) - Understanding the 5-level system
-  - [Brownfield Guide](./modules/bmm/brownfield-guide) - Working with existing codebases
-- **[BMM Workflows Guide](./modules/bmm/index#-workflow-guides)** - **ESSENTIAL READING**
-- **[Test Architect Guide](./modules/bmm/test-architecture)** - Testing strategy and quality assurance
+- **[BMM Module Index](./modules/bmm-bmad-method/index)** - Module overview, agents, and documentation
+  - [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Step-by-step guide
+  - [Quick Spec Flow](./modules/bmm-bmad-method/quick-spec-flow) - Rapid Level 0-1 development
+  - [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Working with existing codebases
+- **[BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides)** - Essential reading
 
-### BMad Builder (BMB) - Create Custom Solutions
+### BMAD Builder (BMB) - Create Custom Solutions
 
 Build your own agents, workflows, and modules.
 
-- **[BMB Module Overview](./modules/bmb/index)** - Module overview and capabilities
-- **[Agent Creation Guide](./modules/bmb/agents/index)** - Design custom agents
+- **[BMB Module Overview](./modules/bmb-bmad-builder/index)** - Module overview and capabilities
+- **[Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md)** - Create custom agents
+- **[Custom Content Installation](./modules/bmb-bmad-builder/custom-content-installation.md)** - Share and install custom creations
 
 ### Creative Intelligence Suite (CIS) - Innovation & Creativity
 
-AI-powered creative thinking and brainstorming.
-
-- **[CIS Module README](./modules/cis/)** - Module overview and workflows
+- **[CIS Documentation](./modules/cis-creative-intelligence-suite/index)**
 
----
+### BMAD Game Dev (BMGD)
 
-## 🖥️ IDE-Specific Guides
+- **[BMGD Documentation](./modules/bmgd-bmad-game-dev/index)** - Game development workflows
 
-Instructions for loading agents and running workflows in your development environment.
+---
 
-**Popular IDEs:**
+## Core Module
 
-- [Claude Code](./ide-info/claude-code.md)
-- [Cursor](./ide-info/cursor.md)
-- [VS Code](./ide-info/windsurf.md)
+### Global Core Entities
 
-**Other Supported IDEs:**
+- **[Core Module Index](./modules/core/index)** - Shared functionality available to all modules
+  - [Global Core Config](./modules/core/global-core-config.md) - Inheritable configuration
+  - [Core Workflows](./modules/core/core-workflows.md) - Domain-agnostic workflows
+    - [Party Mode](./modules/core/party-mode.md) - Multi-agent conversations
+    - [Brainstorming](./modules/core/brainstorming.md) - Structured creative sessions
+    - [Advanced Elicitation](./modules/core/advanced-elicitation.md) - LLM reasoning techniques
+  - [Core Tasks](./modules/core/core-tasks.md) - Common tasks across modules
 
-- [Augment](./ide-info/auggie.md)
-- [Cline](./ide-info/cline.md)
-- [Codex](./ide-info/codex.md)
-- [Crush](./ide-info/crush.md)
-- [Gemini](./ide-info/gemini.md)
-- [GitHub Copilot](./ide-info/github-copilot.md)
-- [IFlow](./ide-info/iflow.md)
-- [Kilo](./ide-info/kilo.md)
-- [OpenCode](./ide-info/opencode.md)
-- [Qwen](./ide-info/qwen.md)
-- [Roo](./ide-info/roo.md)
-- [Rovo Dev](./ide-info/rovo-dev.md)
-- [Trae](./ide-info/trae.md)
+---
 
-**Key concept:** Every reference to "load an agent" or "activate an agent" in the main docs links to the [ide-info](./ide-info/) directory for IDE-specific instructions.
+## Advanced Topics
 
----
+### Customization
 
-## 🔧 Advanced Topics
+- **[BMAD Customization](./bmad-core-concepts/bmad-customization/)** - Modify agents and workflows
 
-### Custom Agents, Workflow and Modules
+### Platform Guides
 
-- **[Custom Content Installation](./custom-content-installation.md)** - Install and personalize agents, workflows and modules with the default bmad-method installer!
-- [Agent Customization Guide](./agent-customization-guide.md) - Customize agent behavior and responses
+- **[Web Bundles](./bmad-core-concepts/web-bundles/)** - Use BMAD in Gemini Gems and Custom GPTs
 
 ---
 
-## 🎓 Recommended Reading Paths
+## Recommended Reading Paths
 
-### Path 1: Brand New to BMad (Software Project)
+### Path 1: Brand New to BMAD (Software Project)
 
-1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
-3. [BMM Module README](./modules/bmm/) - Understand agents
-4. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
-5. [Your IDE guide](./ide-info/) - Optimize your workflow
+1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
+2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
+3. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Get hands-on
+4. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
 
 ### Path 2: Game Development Project
 
-1. [README.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/README.md) - Understand the vision
-2. [Quick Start Guide](./modules/bmm/quick-start) - Get hands-on
-3. [BMM Module README](./modules/bmm/) - Game agents are included
-4. [BMGD Workflows Guide](./modules/bmgd/workflows-guide) - Game-specific workflows
-5. [Your IDE guide](./ide-info/) - Optimize your workflow
+1. [Core Concepts](./bmad-core-concepts/) - Understand agents and workflows
+2. [Installation Guide](./bmad-core-concepts/installing/) - Set up BMAD
+3. [BMGD Workflows Guide](./modules/bmgd-bmad-game-dev/workflows-guide) - Game-specific workflows
 
 ### Path 3: Upgrading from v4
 
-1. [v4 to v6 Upgrade Guide](./v4-to-v6-upgrade.md) - Understand what changed
-2. [Quick Start Guide](./modules/bmm/quick-start) - Reorient yourself
-3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Learn new v6 workflows
+1. [v4 to v6 Upgrade Guide](./bmad-core-concepts/installing/upgrading.md) - Understand what changed
+2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Reorient yourself
+3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Learn new v6 workflows
 
 ### Path 4: Working with Existing Codebase (Brownfield)
 
-1. [Brownfield Guide](./modules/bmm/brownfield-guide) - Approach for legacy code
-2. [Quick Start Guide](./modules/bmm/quick-start) - Follow the process
-3. [BMM Workflows Guide](./modules/bmm/index#-workflow-guides) - Master the methodology
+1. [Brownfield Guide](./modules/bmm-bmad-method/brownfield-guide) - Approach for legacy code
+2. [Quick Start Guide](./modules/bmm-bmad-method/quick-start) - Follow the process
+3. [BMM Workflows Guide](./modules/bmm-bmad-method/index#-workflow-guides) - Master the methodology
 
-### Path 5: Building Custom Solutions
+### Path 5: Building Custom Agents
 
-1. [BMB Module Overview](./modules/bmb/index) - Understand capabilities
-2. [Agent Creation Guide](./modules/bmb/agents/index) - Create agents
-3. [BMB Workflows Guide](./modules/bmb/workflows/) - Understand workflow structure
+1. [Core Concepts: Agents](./bmad-core-concepts/agents.md) - Understand Simple vs Expert
+2. [Agent Creation Guide](./modules/bmb-bmad-builder/agent-creation-guide.md) - Build your first agent
+3. [Agent Architecture](./modules/bmb-bmad-builder/index) - Deep technical details
 
-### Path 6: Contributing to BMad
+### Path 6: Contributing to BMAD
 
 1. [CONTRIBUTING.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md) - Contribution guidelines
 2. Relevant module README - Understand the area you're contributing to