bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

package/docs/how-to/installation/upgrade-to-v6.md

@@ -0,0 +1,147 @@
+---
+title: "Upgrading from Previous Versions"
+---
+
+
+## Overview
+
+The latest version of BMad represents a complete ground-up rewrite with significant architectural changes. This guide will help you migrate from version 4.
+
+---
+
+## 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](/docs/how-to/customization/customize-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/{src/modules/bmgd/docs/troubleshooting.md → docs/how-to/troubleshooting/bmgd-troubleshooting.md}

@@ -1,4 +1,7 @@
-# BMGD Troubleshooting
+---
+title: "BMGD Troubleshooting"
+---
+
 
 Common issues and solutions when using BMGD workflows.
 
@@ -26,7 +29,6 @@ Common issues and solutions when using BMGD workflows.
 Check for `_bmad/bmgd/config.yaml` in your project. If missing, create it:
 
 ```yaml
-# BMGD Configuration
 output_folder: '{project-root}/docs/game-design'
 user_name: 'Your Name'
 communication_language: 'English'
@@ -254,6 +256,6 @@ When reporting issues, include:
 
 ## Next Steps
 
-- **[Quick Start Guide](./quick-start.md)** - Getting started
-- **[Workflows Guide](./workflows-guide.md)** - Workflow reference
-- **[Glossary](./glossary.md)** - Terminology
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started
+- **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference
+- **[Glossary](/docs/reference/glossary/index.md)** - Terminology

package/{src/modules/bmgd/docs/quick-flow-guide.md → docs/how-to/workflows/bmgd-quick-flow.md}

@@ -1,4 +1,7 @@
-# BMGD Quick-Flow Guide
+---
+title: "BMGD Quick-Flow Guide"
+---
+
 
 Fast-track workflows for rapid game prototyping and flexible development.
 
@@ -14,7 +17,7 @@ The Game Solo Dev agent includes:
 
 - `quick-prototype` - Rapid mechanic testing
 - `quick-dev` - Flexible feature implementation
-- `create-tech-spec` - Create implementation-ready specs
+- `quick-spec` - Create implementation-ready specs
 - `code-review` - Quality checks
 - `test-framework` - Automated testing setup
 
@@ -283,6 +286,6 @@ If quick-dev keeps expanding scope, stop and create proper stories.
 
 ## Next Steps
 
-- **[Workflows Guide](./workflows-guide.md)** - Full workflow reference
-- **[Agents Guide](./agents-guide.md)** - Agent capabilities
-- **[Quick Start Guide](./quick-start.md)** - Getting started with BMGD
+- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - Full workflow reference
+- **[Agents Guide](/docs/explanation/game-dev/agents.md)** - Agent capabilities
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Getting started with BMGD

package/docs/how-to/workflows/conduct-research.md

@@ -0,0 +1,130 @@
+---
+title: "How to Conduct Research"
+description: How to conduct market, technical, and competitive research using BMad Method
+---
+
+
+Use the `research` workflow to perform comprehensive multi-type research for validating ideas, understanding markets, and making informed decisions.
+
+---
+
+## When to Use This
+
+- Need market viability validation
+- Choosing frameworks or platforms
+- Understanding competitive landscape
+- Need user understanding
+- Understanding domain or industry
+- Need deeper AI-assisted research
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Analyst agent available
+
+---
+
+## Steps
+
+### 1. Load the Analyst Agent
+
+Start a fresh chat and load the Analyst agent.
+
+### 2. Run the Research Workflow
+
+```
+*research
+```
+
+### 3. Choose Research Type
+
+Select the type of research you need:
+
+| Type            | Purpose                                                | Use When                            |
+| --------------- | ------------------------------------------------------ | ----------------------------------- |
+| **market**      | TAM/SAM/SOM, competitive analysis                      | Need market viability validation    |
+| **technical**   | Technology evaluation, ADRs                            | Choosing frameworks/platforms       |
+| **competitive** | Deep competitor analysis                               | Understanding competitive landscape |
+| **user**        | Customer insights, personas, JTBD                      | Need user understanding             |
+| **domain**      | Industry deep dives, trends                            | Understanding domain/industry       |
+| **deep_prompt** | Generate AI research prompts (ChatGPT, Claude, Gemini) | Need deeper AI-assisted research    |
+
+### 4. Provide Context
+
+Give the agent details about what you're researching:
+
+- "SaaS project management tool"
+- "React vs Vue for our dashboard"
+- "Fintech compliance requirements"
+
+### 5. Set Research Depth
+
+Choose your depth level:
+
+- **Quick** - Fast overview
+- **Standard** - Balanced depth
+- **Comprehensive** - Deep analysis
+
+---
+
+## What You Get
+
+### Market Research Example
+
+```
+TAM: $50B
+SAM: $5B
+SOM: $50M
+
+Top Competitors:
+- Asana
+- Monday
+- etc.
+
+Positioning Recommendation: ...
+```
+
+### Technical Research Example
+
+Technology evaluation with:
+- Comparison matrix
+- Trade-off analysis
+- Recommendations with rationale
+
+---
+
+## Key Features
+
+- Real-time web research
+- Multiple analytical frameworks (Porter's Five Forces, SWOT, Technology Adoption Lifecycle)
+- Platform-specific optimization for deep_prompt type
+- Configurable research depth
+
+---
+
+## Next Steps
+
+After research:
+
+1. **Product Brief** - Capture strategic vision informed by research
+2. **PRD** - Use findings as context for requirements
+3. **Architecture** - Use technical research in ADRs
+
+---
+
+## Tips
+
+- Use market research early for new products
+- Technical research helps with architecture decisions
+- Competitive research informs positioning
+- Domain research is valuable for specialized industries
+
+---
+
+## Related
+
+- [Run Brainstorming Session](/docs/how-to/workflows/run-brainstorming-session.md) - Explore ideas before research
+- [Create Product Brief](/docs/how-to/workflows/create-product-brief.md) - Capture strategic vision
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Move to formal planning

package/docs/how-to/workflows/create-architecture.md

@@ -0,0 +1,147 @@
+---
+title: "How to Create Architecture"
+description: How to create system architecture using the BMad Method
+---
+
+
+Use the `architecture` workflow to make technical decisions explicit and prevent agent conflicts during implementation.
+
+---
+
+## When to Use This
+
+- Multi-epic projects (BMad Method, Enterprise)
+- Cross-cutting technical concerns
+- Multiple agents implementing different parts
+- Integration complexity exists
+- Technology choices need alignment
+
+---
+
+## When to Skip This
+
+- Quick Flow (simple changes)
+- BMad Method Simple with straightforward tech stack
+- Single epic with clear technical approach
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- Architect agent available
+- PRD completed
+
+---
+
+## Steps
+
+### 1. Load the Architect Agent
+
+Start a fresh chat and load the Architect agent.
+
+### 2. Run the Architecture Workflow
+
+```
+*create-architecture
+```
+
+### 3. Engage in Discovery
+
+This is NOT a template filler. The architecture workflow:
+
+1. **Discovers** technical needs through conversation
+2. **Proposes** architectural options with trade-offs
+3. **Documents** decisions that prevent agent conflicts
+4. **Focuses** on decision points, not exhaustive documentation
+
+### 4. Document Key Decisions
+
+Work with the agent to create Architecture Decision Records (ADRs) for significant choices.
+
+### 5. Review the Architecture
+
+The agent produces a decision-focused architecture document.
+
+---
+
+## What You Get
+
+An `architecture.md` document containing:
+
+1. **Architecture Overview** - System context, principles, style
+2. **System Architecture** - High-level diagram, component interactions
+3. **Data Architecture** - Database design, state management, caching
+4. **API Architecture** - API style (REST/GraphQL/gRPC), auth, versioning
+5. **Frontend Architecture** - Framework, state management, components
+6. **Integration Architecture** - Third-party integrations, messaging
+7. **Security Architecture** - Auth/authorization, data protection
+8. **Deployment Architecture** - CI/CD, environments, monitoring
+9. **ADRs** - Key decisions with context, options, rationale
+10. **FR/NFR-Specific Guidance** - Technical approach per requirement
+11. **Standards and Conventions** - Directory structure, naming, testing
+
+---
+
+## ADR Format
+
+```markdown
+## ADR-001: Use GraphQL for All APIs
+
+**Status:** Accepted | **Date:** 2025-11-02
+
+**Context:** PRD requires flexible querying across multiple epics
+
+**Decision:** Use GraphQL for all client-server communication
+
+**Options Considered:**
+1. REST - Familiar but requires multiple endpoints
+2. GraphQL - Flexible querying, learning curve
+3. gRPC - High performance, poor browser support
+
+**Rationale:**
+- PRD requires flexible data fetching (Epic 1, 3)
+- Mobile app needs bandwidth optimization (Epic 2)
+- Team has GraphQL experience
+
+**Consequences:**
+- Positive: Flexible querying, reduced versioning
+- Negative: Caching complexity, N+1 query risk
+- Mitigation: Use DataLoader for batching
+```
+
+---
+
+## Example
+
+E-commerce platform produces:
+- Monolith + PostgreSQL + Redis + Next.js + GraphQL
+- ADRs explaining each choice
+- FR/NFR-specific implementation guidance
+
+---
+
+## Tips
+
+- Focus on decisions that prevent agent conflicts
+- Use ADRs for every significant technology choice
+- Keep it practical - don't over-architect
+- Architecture is living - update as you learn
+
+---
+
+## Next Steps
+
+After architecture:
+
+1. **Create Epics and Stories** - Work breakdown informed by architecture
+2. **Implementation Readiness** - Gate check before Phase 4
+
+---
+
+## Related
+
+- [Create PRD](/docs/how-to/workflows/create-prd.md) - Requirements before architecture
+- [Create Epics and Stories](/docs/how-to/workflows/create-epics-and-stories.md) - Next step
+- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check
+- [Why Solutioning Matters](/docs/explanation/architecture/why-solutioning-matters.md)

package/docs/how-to/workflows/create-epics-and-stories.md

@@ -0,0 +1,136 @@
+---
+title: "How to Create Epics and Stories"
+description: How to break PRD requirements into epics and stories using BMad Method
+---
+
+
+Use the `create-epics-and-stories` workflow to transform PRD requirements into bite-sized stories organized into deliverable epics.
+
+---
+
+## When to Use This
+
+- After architecture workflow completes
+- When PRD contains FRs/NFRs ready for implementation breakdown
+- Before implementation-readiness gate check
+
+---
+
+## Prerequisites
+
+- BMad Method installed
+- PM agent available
+- PRD completed
+- Architecture completed
+
+---
+
+## Why After Architecture?
+
+This workflow runs AFTER architecture because:
+
+1. **Informed Story Sizing** - Architecture decisions affect story complexity
+2. **Dependency Awareness** - Architecture reveals technical dependencies
+3. **Technical Feasibility** - Stories can be properly scoped knowing the tech stack
+4. **Consistency** - All stories align with documented architectural patterns
+
+---
+
+## Steps
+
+### 1. Load the PM Agent
+
+Start a fresh chat and load the PM agent.
+
+### 2. Run the Workflow
+
+```
+*create-epics-and-stories
+```
+
+### 3. Provide Context
+
+Point the agent to:
+- Your PRD (FRs/NFRs)
+- Your architecture document
+- Optional: UX design artifacts
+
+### 4. Review Epic Breakdown
+
+The agent organizes requirements into logical epics with user stories.
+
+### 5. Validate Story Quality
+
+Ensure each story has:
+- Clear acceptance criteria
+- Appropriate priority
+- Identified dependencies
+- Technical notes from architecture
+
+---
+
+## What You Get
+
+Epic files (one per epic) containing:
+
+1. **Epic objective and scope**
+2. **User stories with acceptance criteria**
+3. **Story priorities** (P0/P1/P2/P3)
+4. **Dependencies between stories**
+5. **Technical notes** referencing architecture decisions
+
+---
+
+## Example
+
+E-commerce PRD with FR-001 (User Registration), FR-002 (Product Catalog) produces:
+
+- **Epic 1: User Management** (3 stories)
+  - Story 1.1: User registration form
+  - Story 1.2: Email verification
+  - Story 1.3: Login/logout
+
+- **Epic 2: Product Display** (4 stories)
+  - Story 2.1: Product listing page
+  - Story 2.2: Product detail page
+  - Story 2.3: Search functionality
+  - Story 2.4: Category filtering
+
+Each story references relevant ADRs from architecture.
+
+---
+
+## Story Priority Levels
+
+| Priority | Meaning |
+|----------|---------|
+| **P0** | Critical - Must have for MVP |
+| **P1** | High - Important for release |
+| **P2** | Medium - Nice to have |
+| **P3** | Low - Future consideration |
+
+---
+
+## Tips
+
+- Keep stories small enough to complete in a session
+- Ensure acceptance criteria are testable
+- Document dependencies clearly
+- Reference architecture decisions in technical notes
+
+---
+
+## Next Steps
+
+After creating epics and stories:
+
+1. **Implementation Readiness** - Validate alignment before Phase 4
+2. **Sprint Planning** - Organize work for implementation
+
+---
+
+## Related
+
+- [Create Architecture](/docs/how-to/workflows/create-architecture.md) - Do this first
+- [Run Implementation Readiness](/docs/how-to/workflows/run-implementation-readiness.md) - Gate check
+- [Run Sprint Planning](/docs/how-to/workflows/run-sprint-planning.md) - Start implementation