mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-29 20:22:03 +00:00
doc cleanup round 1
This commit is contained in:
Brian Madison
1
.vscode/settings.json
vendored
1
.vscode/settings.json
vendored
@@ -57,6 +57,7 @@
|
||||
"tileset",
|
||||
"tmpl",
|
||||
"Trae",
|
||||
"Unsharded",
|
||||
"VNET",
|
||||
"webskip"
|
||||
],
|
||||
|
||||
@@ -81,7 +81,7 @@ Add your own workflows to the agent's menu:
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: my-workflow
|
||||
workflow: '{project-root}/custom/my-workflow.yaml'
|
||||
workflow: '{project-root}/my-custom/workflows/my-workflow.yaml'
|
||||
description: My custom workflow
|
||||
- trigger: deploy
|
||||
action: '#deploy-prompt'
|
||||
|
||||
@@ -26,10 +26,8 @@ To create an installable custom module:
|
||||
- Create a folder with a short, abbreviated name (e.g., `cis` for Creative Intelligence Suite)
|
||||
- The folder name serves as the module code
|
||||
|
||||
2. **Required Files**
|
||||
- Include a `module.yaml` file in the root folder
|
||||
- This file drives the installation process when used by the BMAD installer
|
||||
- Reference existing modules or the BMad Builder for configuration examples
|
||||
2. **Required File**
|
||||
- Include a `module.yaml` file in the root folder (this drives questions for the final generated config.yaml at install target)
|
||||
|
||||
3. **Folder Organization**
|
||||
Follow these conventions for optimal compatibility:
|
||||
@@ -56,8 +54,10 @@ For standalone content that isn't part of a cohesive module collection, follow t
|
||||
|
||||
1. **Module Configuration**
|
||||
- Create a folder with a `module.yaml` file (similar to custom modules)
|
||||
- Add the property `unitary: true` to the module.yaml
|
||||
- The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
|
||||
- Add the property `unitary: true` in the module.yaml
|
||||
- The `unitary: true` property indicates this is a collection of potentially unrelated items that don't depend on each other
|
||||
- Any content you add to this folder should still be nested under workflows and agents - but the key with stand alone content is they do not rely on each other.
|
||||
- Agents do not reference other workflows even if stored in a unitary:true module. But unitary Agents can have their own workflows in their sidecar, or reference workflows as requirements from other modules - with a process known as workflow vendoring. Keep in mind, this will require that the workflow referenced from the other module would need to be available for the end user to install, so its recommended to only vendor workflows from the core module, or official bmm modules (See [Workflow Vendoring, Customization, and Inheritance](workflow-vendoring-customization-inheritance.md)).
|
||||
|
||||
2. **Folder Structure**
|
||||
Organize content in specific named folders:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Custom Content
|
||||
|
||||
BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agent provides workflows and expertise to plan and build any custom content you can imagine.
|
||||
BMAD supports several categories of officially supported custom content that extend the platform's capabilities. Custom content can be created manually or with the recommended assistance of the BMad Builder (BoMB) Module. The BoMB Agents provides workflows and expertise to plan and build any custom content you can imagine.
|
||||
|
||||
This flexibility transforms the platform beyond its current capabilities, enabling:
|
||||
|
||||
@@ -21,7 +21,7 @@ This flexibility transforms the platform beyond its current capabilities, enabli
|
||||
- [Custom Global Modules](#custom-global-modules)
|
||||
- [Custom Agents](#custom-agents)
|
||||
- [BMad Tiny Agents](#bmad-tiny-agents)
|
||||
- [Simple vs Expert Agents](#simple-vs-expert-agents)
|
||||
- [Simple and Expert Agents](#simple-and-expert-agents)
|
||||
- [Custom Workflows](#custom-workflows)
|
||||
|
||||
## Custom Stand Alone Modules
|
||||
@@ -57,7 +57,7 @@ Similar to Custom Stand Alone Modules, but designed to add functionality that ap
|
||||
|
||||
Examples include:
|
||||
|
||||
- The current TTS (Text-to-Speech) functionality for Claude, which will be rebuilt as a global module
|
||||
- The current TTS (Text-to-Speech) functionality for Claude, which will soon be converted to a global module
|
||||
- The core module, which is always installed and provides all agents with party mode and advanced elicitation capabilities
|
||||
- Installation and update tools that work with any BMAD method configuration
|
||||
|
||||
@@ -81,7 +81,7 @@ Personal agents designed for highly specific needs that may not be suitable for
|
||||
|
||||
These are simple, standalone files that can be scoped to focus on specific data or paths when integrated into an information vault or repository.
|
||||
|
||||
### Simple vs Expert Agents
|
||||
### Simple and Expert Agents
|
||||
|
||||
The distinction between simple and expert agents lies in their structure:
|
||||
|
||||
@@ -89,7 +89,6 @@ The distinction between simple and expert agents lies in their structure:
|
||||
|
||||
- Single file containing all prompts and configuration
|
||||
- Self-contained and straightforward
|
||||
- has metadata type: simple
|
||||
|
||||
**Expert Agent:**
|
||||
|
||||
|
||||
@@ -4,13 +4,21 @@ Comprehensive guide to BMad Method's document sharding system for managing large
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [What is Document Sharding?](#what-is-document-sharding)
|
||||
- [When to Use Sharding](#when-to-use-sharding)
|
||||
- [How Sharding Works](#how-sharding-works)
|
||||
- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
|
||||
- [Workflow Support](#workflow-support)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Examples](#examples)
|
||||
- [Document Sharding Guide](#document-sharding-guide)
|
||||
- [Table of Contents](#table-of-contents)
|
||||
- [What is Document Sharding?](#what-is-document-sharding)
|
||||
- [Architecture](#architecture)
|
||||
- [When to Use Sharding](#when-to-use-sharding)
|
||||
- [Ideal Candidates](#ideal-candidates)
|
||||
- [How Sharding Works](#how-sharding-works)
|
||||
- [Sharding Process](#sharding-process)
|
||||
- [Workflow Discovery](#workflow-discovery)
|
||||
- [Using the Shard-Doc Tool](#using-the-shard-doc-tool)
|
||||
- [CLI Command](#cli-command)
|
||||
- [Interactive Process](#interactive-process)
|
||||
- [What Gets Created](#what-gets-created)
|
||||
- [Workflow Support](#workflow-support)
|
||||
- [Universal Support](#universal-support)
|
||||
|
||||
## What is Document Sharding?
|
||||
|
||||
@@ -49,27 +57,6 @@ docs/
|
||||
- Epic files with 4+ epics (especially for Phase 4)
|
||||
- UX design specs covering multiple subsystems
|
||||
|
||||
**Token Thresholds:**
|
||||
|
||||
- **Consider sharding**: Documents > 20k tokens
|
||||
- **Strongly recommended**: Documents > 40k tokens
|
||||
- **Critical for efficiency**: Documents > 60k tokens
|
||||
|
||||
### When NOT to Shard
|
||||
|
||||
**Small Projects:**
|
||||
|
||||
- Single epic projects
|
||||
- Level 0-1 projects (tech-spec only)
|
||||
- Documents under 10k tokens
|
||||
- Quick prototypes
|
||||
|
||||
**Frequently Updated Docs:**
|
||||
|
||||
- Active work-in-progress documents
|
||||
- Documents updated daily
|
||||
- Documents where whole-file context is essential
|
||||
|
||||
## How Sharding Works
|
||||
|
||||
### Sharding Process
|
||||
@@ -85,36 +72,14 @@ BMad workflows use a **dual discovery system**:
|
||||
|
||||
1. **Try whole document first** - Look for `document-name.md`
|
||||
2. **Check for sharded version** - Look for `document-name/index.md`
|
||||
3. **Priority rule** - Whole document takes precedence if both exist
|
||||
|
||||
### Loading Strategies
|
||||
|
||||
**Full Load (Phase 1-3 workflows):**
|
||||
|
||||
```
|
||||
If sharded:
|
||||
- Read index.md
|
||||
- Read ALL section files
|
||||
- Treat as single combined document
|
||||
```
|
||||
|
||||
**Selective Load (Phase 4 workflows):**
|
||||
|
||||
```
|
||||
If sharded epics and working on Epic 3:
|
||||
- Read epics/index.md
|
||||
- Load ONLY epics/epic-3.md
|
||||
- Skip all other epic files
|
||||
- 90%+ token savings!
|
||||
```
|
||||
3. **Priority rule** - Whole document takes precedence if both exist - remove the whole document if you want the sharded to be used instead.
|
||||
|
||||
## Using the Shard-Doc Tool
|
||||
|
||||
### CLI Command
|
||||
|
||||
```bash
|
||||
# Activate bmad-master or analyst agent, then:
|
||||
/shard-doc
|
||||
/bmad:core:tools:shard-doc
|
||||
```
|
||||
|
||||
### Interactive Process
|
||||
@@ -166,284 +131,3 @@ Agent: Sharding PRD.md...
|
||||
- ✅ Sharded documents
|
||||
- ✅ Automatic detection
|
||||
- ✅ Transparent to user
|
||||
|
||||
### Workflow-Specific Patterns
|
||||
|
||||
#### Phase 1-3 (Full Load)
|
||||
|
||||
Workflows load entire sharded documents:
|
||||
|
||||
- `product-brief` - Research, brainstorming docs
|
||||
- `prd` - Product brief, research
|
||||
- `gdd` - Game brief, research
|
||||
- `create-ux-design` - PRD, brief, architecture (if available)
|
||||
- `tech-spec` - Brief, research
|
||||
- `architecture` - PRD, UX design (if available)
|
||||
- `create-epics-and-stories` - PRD, architecture
|
||||
- `implementation-readiness` - All planning docs
|
||||
|
||||
#### Phase 4 (Selective Load)
|
||||
|
||||
Workflows load only needed sections:
|
||||
|
||||
**sprint-planning** (Full Load):
|
||||
|
||||
- Needs ALL epics to build complete status
|
||||
|
||||
**create-story, code-review** (Selective):
|
||||
|
||||
```
|
||||
Working on Epic 3, Story 2:
|
||||
✓ Load epics/epic-3.md only
|
||||
✗ Skip epics/epic-1.md, epic-2.md, epic-4.md, etc.
|
||||
|
||||
Result: 90%+ token reduction for 10-epic projects!
|
||||
```
|
||||
|
||||
### Input File Patterns
|
||||
|
||||
Workflows use standardized patterns:
|
||||
|
||||
```yaml
|
||||
input_file_patterns:
|
||||
prd:
|
||||
whole: '{output_folder}/*prd*.md'
|
||||
sharded: '{output_folder}/*prd*/index.md'
|
||||
|
||||
epics:
|
||||
whole: '{output_folder}/*epic*.md'
|
||||
sharded_index: '{output_folder}/*epic*/index.md'
|
||||
sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Sharding Strategy
|
||||
|
||||
**Do:**
|
||||
|
||||
- ✅ Shard after planning phase complete
|
||||
- ✅ Keep level 2 headings well-organized
|
||||
- ✅ Use descriptive section names
|
||||
- ✅ Shard before Phase 4 implementation
|
||||
- ✅ Keep original file as backup initially
|
||||
|
||||
**Don't:**
|
||||
|
||||
- ❌ Shard work-in-progress documents
|
||||
- ❌ Shard small documents (<20k tokens)
|
||||
- ❌ Mix sharded and whole versions
|
||||
- ❌ Manually edit index.md structure
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
**Good Section Names:**
|
||||
|
||||
```markdown
|
||||
## Epic 1: User Authentication
|
||||
|
||||
## Technical Requirements
|
||||
|
||||
## System Architecture
|
||||
|
||||
## UX Design Principles
|
||||
```
|
||||
|
||||
**Poor Section Names:**
|
||||
|
||||
```markdown
|
||||
## Section 1
|
||||
|
||||
## Part A
|
||||
|
||||
## Details
|
||||
|
||||
## More Info
|
||||
```
|
||||
|
||||
### File Management
|
||||
|
||||
**When to Re-shard:**
|
||||
|
||||
- Significant structural changes to document
|
||||
- Adding/removing major sections
|
||||
- After major refactoring
|
||||
|
||||
**Updating Sharded Docs:**
|
||||
|
||||
1. Edit individual section files directly
|
||||
2. OR edit original, delete sharded folder, re-shard
|
||||
3. Don't manually edit index.md
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Large PRD
|
||||
|
||||
**Scenario:** 15-epic project, PRD is 45k tokens
|
||||
|
||||
**Before Sharding:**
|
||||
|
||||
```
|
||||
Every workflow loads entire 45k token PRD
|
||||
Architecture workflow: 45k tokens
|
||||
UX design workflow: 45k tokens
|
||||
```
|
||||
|
||||
**After Sharding:**
|
||||
|
||||
```bash
|
||||
/shard-doc
|
||||
Source: docs/PRD.md
|
||||
Destination: docs/prd/
|
||||
|
||||
Created:
|
||||
prd/index.md
|
||||
prd/overview.md (3k tokens)
|
||||
prd/functional-requirements.md (8k tokens)
|
||||
prd/non-functional-requirements.md (6k tokens)
|
||||
prd/user-personas.md (4k tokens)
|
||||
...additional FR/NFR sections
|
||||
```
|
||||
|
||||
**Result:**
|
||||
|
||||
```
|
||||
Architecture workflow: Can load specific sections needed
|
||||
UX design workflow: Can load specific sections needed
|
||||
Significant token reduction for large requirement docs!
|
||||
```
|
||||
|
||||
### Example 2: Sharding Epics File
|
||||
|
||||
**Scenario:** 8 epics with detailed stories, 35k tokens total
|
||||
|
||||
```bash
|
||||
/shard-doc
|
||||
Source: docs/bmm-epics.md
|
||||
Destination: docs/epics/
|
||||
|
||||
Created:
|
||||
epics/index.md
|
||||
epics/epic-1.md
|
||||
epics/epic-2.md
|
||||
...
|
||||
epics/epic-8.md
|
||||
```
|
||||
|
||||
**Efficiency Gain:**
|
||||
|
||||
```
|
||||
Working on Epic 5 stories:
|
||||
Old: Load all 8 epics (35k tokens)
|
||||
New: Load epic-5.md only (4k tokens)
|
||||
Savings: 88% reduction
|
||||
```
|
||||
|
||||
### Example 3: Architecture Document
|
||||
|
||||
**Scenario:** Multi-layer system architecture, 28k tokens
|
||||
|
||||
```bash
|
||||
/shard-doc
|
||||
Source: docs/architecture.md
|
||||
Destination: docs/architecture/
|
||||
|
||||
Created:
|
||||
architecture/index.md
|
||||
architecture/system-overview.md
|
||||
architecture/frontend-architecture.md
|
||||
architecture/backend-services.md
|
||||
architecture/data-layer.md
|
||||
architecture/infrastructure.md
|
||||
architecture/security-architecture.md
|
||||
```
|
||||
|
||||
**Benefit:** Code-review workflow can reference specific architectural layers without loading entire architecture doc.
|
||||
|
||||
## Custom Workflow Integration
|
||||
|
||||
### For Workflow Builders
|
||||
|
||||
When creating custom workflows that load large documents:
|
||||
|
||||
**1. Add input_file_patterns to workflow.yaml:**
|
||||
|
||||
```yaml
|
||||
input_file_patterns:
|
||||
your_document:
|
||||
whole: '{output_folder}/*your-doc*.md'
|
||||
sharded: '{output_folder}/*your-doc*/index.md'
|
||||
```
|
||||
|
||||
**2. Add discovery instructions to instructions.md:**
|
||||
|
||||
```markdown
|
||||
## Document Discovery
|
||||
|
||||
1. Search for whole document: _your-doc_.md
|
||||
2. Check for sharded version: _your-doc_/index.md
|
||||
3. If sharded: Read index + ALL sections (or specific sections if selective load)
|
||||
4. Priority: Whole document first
|
||||
```
|
||||
|
||||
**3. Choose loading strategy:**
|
||||
|
||||
- **Full Load**: Read all sections when sharded
|
||||
- **Selective Load**: Read only relevant sections (requires section identification logic)
|
||||
|
||||
### Pattern Templates
|
||||
|
||||
**Full Load Pattern:**
|
||||
|
||||
```xml
|
||||
<action>Search for document: {output_folder}/*doc-name*.md</action>
|
||||
<action>If not found, check for sharded: {output_folder}/*doc-name*/index.md</action>
|
||||
<action if="sharded found">Read index.md to understand structure</action>
|
||||
<action if="sharded found">Read ALL section files listed in index</action>
|
||||
<action if="sharded found">Combine content as single document</action>
|
||||
```
|
||||
|
||||
**Selective Load Pattern (with section ID):**
|
||||
|
||||
```xml
|
||||
<action>Determine section needed (e.g., epic_num = 3)</action>
|
||||
<action>Check for sharded version: {output_folder}/*doc-name*/index.md</action>
|
||||
<action if="sharded found">Read ONLY the specific section file needed</action>
|
||||
<action if="sharded found">Skip all other section files</action>
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**Both whole and sharded exist:**
|
||||
|
||||
- Workflows will use whole document (priority rule)
|
||||
- Delete or archive the one you don't want
|
||||
|
||||
**Index.md out of sync:**
|
||||
|
||||
- Delete sharded folder
|
||||
- Re-run shard-doc on original
|
||||
|
||||
**Workflow can't find document:**
|
||||
|
||||
- Check file naming matches patterns (`*prd*.md`, `*epic*.md`, etc.)
|
||||
- Verify index.md exists in sharded folder
|
||||
- Check output_folder path in config
|
||||
|
||||
**Sections too granular:**
|
||||
|
||||
- Combine sections in original document
|
||||
- Use fewer level 2 headings
|
||||
- Re-shard
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [shard-doc Tool](../src/core/tools/shard-doc.xml) - Tool implementation
|
||||
- [BMM Workflows Guide](./modules/bmm/index.md#-workflow-guides) - Workflow overview
|
||||
- [Workflow Creation Guide](./modules/bmb/workflows/index) - Custom workflow patterns
|
||||
|
||||
---
|
||||
|
||||
**Document sharding is optional but powerful** - use it when efficiency matters for large projects!
|
||||
|
||||
@@ -5,7 +5,7 @@ Get BMAD Method running in your project in under 2 minutes.
|
||||
## Quick Install
|
||||
|
||||
```bash
|
||||
npx bmad-method@alpha install
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
This interactive installer will:
|
||||
@@ -16,19 +16,23 @@ This interactive installer will:
|
||||
|
||||
## Requirements
|
||||
|
||||
- **Node.js** 18+ (for the installer)
|
||||
- **Node.js** 20+ (for the installer)
|
||||
- **Git** (recommended for version control)
|
||||
- An **AI-powered IDE** or access to Claude/ChatGPT/Gemini
|
||||
- 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 |
|
||||
| **BMB** | Builder | Creating custom agents and workflows |
|
||||
| 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
|
||||
|
||||
@@ -39,38 +43,26 @@ your-project/
|
||||
├── _bmad/ # BMAD configuration and agents
|
||||
│ ├── bmm/ # Method module (if installed)
|
||||
│ ├── bmgd/ # Game dev module (if installed)
|
||||
│ └── config.yaml # Your project configuration
|
||||
│ ├── 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
|
||||
└── ... your code # maybe nothing else yet if a fresh new folder
|
||||
```
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Read the [Quick Start Guide](../modules/bmm/quick-start.md)** to build your first feature
|
||||
2. **Check your [IDE Guide](../ide-info/index.md)** for IDE-specific tips
|
||||
3. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
|
||||
|
||||
## Alternative: Web Bundles
|
||||
|
||||
Don't want to install? Use BMAD agents directly in:
|
||||
|
||||
- **Claude Projects** - Upload the web bundle
|
||||
- **ChatGPT** - Use custom GPT bundles
|
||||
- **Gemini** - Import agent prompts
|
||||
|
||||
See the [Web Bundles Guide](../web-bundles-gemini-gpt-guide.md) for details.
|
||||
2. **Explore [Workflows](../modules/bmm/workflows-planning.md)** to understand the methodology
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**"Command not found: npx"**
|
||||
: Install Node.js 18+ from [nodejs.org](https://nodejs.org)
|
||||
: Install Node.js 20+ from [nodejs.org](https://nodejs.org)
|
||||
|
||||
**"Permission denied"**
|
||||
: Run with appropriate permissions or check your npm configuration
|
||||
|
||||
**IDE not detected**
|
||||
: The installer will prompt you to select your IDE manually
|
||||
|
||||
For more help, see [Troubleshooting](../modules/bmm/troubleshooting.md) or join our [Discord](https://discord.gg/bmad).
|
||||
For more help, join our [Discord](https://discord.gg/bmad).
|
||||
|
||||
@@ -1,31 +0,0 @@
|
||||
# BMAD Method - Auggie CLI Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents can be installed in multiple locations based on your setup.
|
||||
|
||||
### Common Locations
|
||||
|
||||
- User Home: `~/.augment/commands/`
|
||||
- Project: `.augment/commands/`
|
||||
- Custom paths you selected
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Type Trigger**: Use `@{agent-name}` in your prompt
|
||||
2. **Activate**: Agent persona activates
|
||||
3. **Tasks**: Use `@task-{task-name}` for tasks
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
@dev - Activate development agent
|
||||
@architect - Activate architect agent
|
||||
@task-setup - Execute setup task
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Agents can be in multiple locations
|
||||
- Check your installation paths
|
||||
- Activation syntax same across all locations
|
||||
@@ -1,25 +0,0 @@
|
||||
# BMAD Method - Claude Code Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as slash commands in `.claude/commands/bmad/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Type Slash Command**: Start with `/` to see available commands
|
||||
2. **Select Agent**: Type `/bmad-{agent-name}` (e.g., `/bmad-dev`)
|
||||
3. **Execute**: Press Enter to activate that agent persona
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
/bmad:bmm:agents:dev - Activate development agent
|
||||
/bmad:bmm:agents:architect - Activate architect agent
|
||||
/bmad:bmm:workflows:dev-story - Execute dev-story workflow
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Commands are autocompleted when you type `/`
|
||||
- Agent remains active for the conversation
|
||||
- Start a new conversation to switch agents
|
||||
@@ -1,31 +0,0 @@
|
||||
# BMAD Method - Cline Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as **toggleable rules** in `.clinerules/` directory.
|
||||
|
||||
### Important: Rules are OFF by default
|
||||
|
||||
- Rules are NOT automatically loaded to avoid context pollution
|
||||
- You must manually enable the agent you want to use
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Rules Panel**: Click the rules icon below the chat input
|
||||
2. **Enable an Agent**: Toggle ON the specific agent rule you need (e.g., `01-core-dev`)
|
||||
3. **Activate in Chat**: Type `@{agent-name}` to activate that persona
|
||||
4. **Disable When Done**: Toggle OFF to free up context
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Only enable 1-2 agents at a time to preserve context
|
||||
- Disable agents when switching tasks
|
||||
- Rules are numbered (01-, 02-) for organization, not priority
|
||||
|
||||
### Example
|
||||
|
||||
```
|
||||
Toggle ON: 01-core-dev.md
|
||||
In chat: "@dev help me refactor this code"
|
||||
When done: Toggle OFF the rule
|
||||
```
|
||||
@@ -1,21 +0,0 @@
|
||||
# BMAD Method - Codex Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents, tasks and workflows are installed as custom prompts in
|
||||
`$CODEX_HOME/prompts/bmad-*.md` files. If `CODEX_HOME` is not set, it
|
||||
defaults to `$HOME/.codex/`.
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
/bmad-bmm-agents-dev - Activate development agent
|
||||
/bmad-bmm-agents-architect - Activate architect agent
|
||||
/bmad-bmm-workflows-dev-story - Execute dev-story workflow
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
Prompts are autocompleted when you type /
|
||||
Agent remains active for the conversation
|
||||
Start a new conversation to switch agents
|
||||
@@ -1,30 +0,0 @@
|
||||
# BMAD Method - Crush Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as commands in `.crush/commands/bmad/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Command Palette**: Use Crush command interface
|
||||
2. **Navigate**: Browse to `_bmad/{module}/agents/`
|
||||
3. **Select Agent**: Choose the agent command
|
||||
4. **Execute**: Run to activate agent persona
|
||||
|
||||
### Command Structure
|
||||
|
||||
```
|
||||
.crush/commands/bmad/
|
||||
├── agents/ # All agents
|
||||
├── tasks/ # All tasks
|
||||
├── core/ # Core module
|
||||
│ ├── agents/
|
||||
│ └── tasks/
|
||||
└── {module}/ # Other modules
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Commands organized by module
|
||||
- Can browse hierarchically
|
||||
- Agent activates for session
|
||||
@@ -1,25 +0,0 @@
|
||||
# BMAD Method - Cursor Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed in `.cursor/rules/bmad/` as MDC rules.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Reference in Chat**: Use `@_bmad/{module}/agents/{agent-name}`
|
||||
2. **Include Entire Module**: Use `@_bmad/{module}`
|
||||
3. **Reference Index**: Use `@_bmad/index` for all available agents
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
@_bmad/core/agents/dev - Activate dev agent
|
||||
@_bmad/bmm/agents/architect - Activate architect agent
|
||||
@_bmad/core - Include all core agents/tasks
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Rules are Manual type - only loaded when explicitly referenced
|
||||
- No automatic context pollution
|
||||
- Can combine multiple agents: `@_bmad/core/agents/dev @_bmad/core/agents/test`
|
||||
@@ -1,25 +0,0 @@
|
||||
# BMAD Method - Gemini CLI Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are concatenated in `.gemini/bmad-method/GEMINI.md`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Type Trigger**: Use `*{agent-name}` in your prompt
|
||||
2. **Activate**: Agent persona activates from the concatenated file
|
||||
3. **Continue**: Agent remains active for conversation
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
*dev - Activate development agent
|
||||
*architect - Activate architect agent
|
||||
*test - Activate test agent
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- All agents loaded from single GEMINI.md file
|
||||
- Triggers with asterisk: `*{agent-name}`
|
||||
- Context includes all agents (may be large)
|
||||
@@ -1,26 +0,0 @@
|
||||
# BMAD Method - GitHub Copilot Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as chat modes in `.github/chatmodes/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Chat View**: Click Copilot icon in VS Code sidebar
|
||||
2. **Select Mode**: Click mode selector (top of chat)
|
||||
3. **Choose Agent**: Select the BMAD agent from dropdown
|
||||
4. **Chat**: Agent is now active for this session
|
||||
|
||||
### VS Code Settings
|
||||
|
||||
Configured in `.vscode/settings.json`:
|
||||
|
||||
- Max requests per session
|
||||
- Auto-fix enabled
|
||||
- MCP discovery enabled
|
||||
|
||||
### Notes
|
||||
|
||||
- Modes persist for the chat session
|
||||
- Switch modes anytime via dropdown
|
||||
- Multiple agents available in mode selector
|
||||
@@ -1,33 +0,0 @@
|
||||
# BMAD Method - iFlow CLI Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as commands in `.iflow/commands/bmad/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Access Commands**: Use iFlow command interface
|
||||
2. **Navigate**: Browse to `_bmad/agents/` or `_bmad/tasks/`
|
||||
3. **Select**: Choose the agent or task command
|
||||
4. **Execute**: Run to activate
|
||||
|
||||
### Command Structure
|
||||
|
||||
```
|
||||
.iflow/commands/bmad/
|
||||
├── agents/ # Agent commands
|
||||
└── tasks/ # Task commands
|
||||
```
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
/_bmad/agents/core-dev - Activate dev agent
|
||||
/_bmad/tasks/core-setup - Execute setup task
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Commands organized by type (agents/tasks)
|
||||
- Agent activates for session
|
||||
- Similar to Crush command structure
|
||||
@@ -1,24 +0,0 @@
|
||||
# IDE Guides
|
||||
|
||||
BMAD Method works with any AI-powered development environment. Choose your IDE below for specific setup instructions and tips.
|
||||
|
||||
## All Supported IDEs
|
||||
|
||||
| IDE | Type | BMAD Support |
|
||||
| ----------------------------------- | ----------------- | --------------------- |
|
||||
| [Claude Code](claude-code.md) | CLI/Terminal | Native slash commands |
|
||||
| [Cursor](cursor.md) | Desktop Editor | Full agent support |
|
||||
| [VS Code / Windsurf](windsurf.md) | Desktop Editor | Extension-based |
|
||||
| [Cline](cline.md) | VS Code Extension | Full support |
|
||||
| [GitHub Copilot](github-copilot.md) | Extension | Workspace agents |
|
||||
| [Augment](auggie.md) | Extension | Agent loading |
|
||||
| [Codex](codex.md) | CLI | Prompt injection |
|
||||
| [Gemini](gemini.md) | Web/API | Web bundles |
|
||||
| [Roo](roo.md) | VS Code Extension | Mode support |
|
||||
| [Kilo](kilo.md) | Extension | Basic support |
|
||||
| [OpenCode](opencode.md) | Open Source | Full support |
|
||||
| [Qwen](qwen.md) | Web/API | Web bundles |
|
||||
| [Trae](trae.md) | Extension | Basic support |
|
||||
| [Crush](crush.md) | Desktop | Agent support |
|
||||
| [iFlow](iflow.md) | Extension | Prompt loading |
|
||||
| [Rovo Dev](rovo-dev.md) | Atlassian | Integration |
|
||||
@@ -1,24 +0,0 @@
|
||||
# BMAD Method - KiloCode Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as custom modes in `.kilocodemodes`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Project**: Modes auto-load when project opens
|
||||
2. **Select Mode**: Use mode selector in KiloCode interface
|
||||
3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
|
||||
4. **Activate**: Mode is now active
|
||||
|
||||
### Mode Format
|
||||
|
||||
- Mode name: `bmad-{module}-{agent}`
|
||||
- Display: `{icon} {title}`
|
||||
- Example: `bmad-core-dev` shows as `🤖 Dev`
|
||||
|
||||
### Notes
|
||||
|
||||
- Modes persist until changed
|
||||
- Similar to Roo Code mode system
|
||||
- Icon shows in mode selector
|
||||
@@ -1,24 +0,0 @@
|
||||
# BMAD Method - OpenCode Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as OpenCode agents in `.opencode/agent/BMAD/{module_name}` and workflow commands in `.opencode/command/BMAD/{module_name}`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Switch Agents**: Press **Tab** to cycle through primary agents or select using the `/agents`
|
||||
2. **Activate Agent**: Once the Agent is selected say `hello` or any prompt to activate that agent persona
|
||||
3. **Execute Commands**: Type `/bmad` to see and execute bmad workflow commands (commands allow for fuzzy matching)
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
/agents - to see a list of agents and switch between them
|
||||
/_bmad/bmm/workflows/workflow-init - Activate the workflow-init command
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Press **Tab** to switch between primary agents (Analyst, Architect, Dev, etc.)
|
||||
- Commands are autocompleted when you type `/` and allow for fuzzy matching
|
||||
- Workflow commands execute in current agent context, make sure you have the right agent activated before running a command
|
||||
@@ -1,25 +0,0 @@
|
||||
# BMAD Method - Qwen Code Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are concatenated in `.qwen/bmad-method/QWEN.md`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Type Trigger**: Use `*{agent-name}` in your prompt
|
||||
2. **Activate**: Agent persona activates from the concatenated file
|
||||
3. **Continue**: Agent remains active for conversation
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
*dev - Activate development agent
|
||||
*architect - Activate architect agent
|
||||
*test - Activate test agent
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- All agents loaded from single QWEN.md file
|
||||
- Triggers with asterisk: `*{agent-name}`
|
||||
- Similar to Gemini CLI setup
|
||||
@@ -1,27 +0,0 @@
|
||||
# BMAD Method - Roo Code Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as custom modes in `.roomodes`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Project**: Modes auto-load when project opens
|
||||
2. **Select Mode**: Use mode selector in Roo interface
|
||||
3. **Choose Agent**: Pick `bmad-{module}-{agent}` mode
|
||||
4. **Activate**: Mode is now active with configured permissions
|
||||
|
||||
### Permission Levels
|
||||
|
||||
Modes are configured with file edit permissions:
|
||||
|
||||
- Development files only
|
||||
- Configuration files only
|
||||
- Documentation files only
|
||||
- All files (if configured)
|
||||
|
||||
### Notes
|
||||
|
||||
- Modes persist until changed
|
||||
- Each mode has specific file access rights
|
||||
- Icon shows in mode selector for easy identification
|
||||
@@ -1,22 +0,0 @@
|
||||
# BMAD Method - Rovo Dev Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as subagents in `.rovodev/subagents/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Project**: Subagents auto-load when project opens
|
||||
2. **Invoke Agent**: Type `@` and select agent (e.g., `@bmad-bmm-dev`, `@bmad-bmm-architect`)
|
||||
3. **Reference Files**: Check `.rovodev/workflows/` and `.rovodev/references/`
|
||||
|
||||
### Directory Structure
|
||||
|
||||
- `.rovodev/subagents/` - BMAD agents
|
||||
- `.rovodev/workflows/` - Workflow guides
|
||||
- `.rovodev/references/` - Tasks and tools
|
||||
|
||||
### Notes
|
||||
|
||||
- Agents are automatically discovered by Rovo Dev
|
||||
- Subagents use YAML frontmatter for configuration
|
||||
@@ -1,25 +0,0 @@
|
||||
# BMAD Method - Trae Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as rules in `.trae/rules/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Type Trigger**: Use `@{agent-name}` in your prompt
|
||||
2. **Activate**: Agent persona activates automatically
|
||||
3. **Continue**: Agent remains active for conversation
|
||||
|
||||
### Examples
|
||||
|
||||
```
|
||||
@dev - Activate development agent
|
||||
@architect - Activate architect agent
|
||||
@task-setup - Execute setup task
|
||||
```
|
||||
|
||||
### Notes
|
||||
|
||||
- Rules auto-load from `.trae/rules/` directory
|
||||
- Multiple agents can be referenced: `@dev and @test`
|
||||
- Agent follows YAML configuration in rule file
|
||||
@@ -1,22 +0,0 @@
|
||||
# BMAD Method - Windsurf Instructions
|
||||
|
||||
## Activating Agents
|
||||
|
||||
BMAD agents are installed as workflows in `.windsurf/workflows/`.
|
||||
|
||||
### How to Use
|
||||
|
||||
1. **Open Workflows**: Access via Windsurf menu or command palette
|
||||
2. **Select Workflow**: Choose the agent/task workflow
|
||||
3. **Execute**: Run to activate that agent persona
|
||||
|
||||
### Workflow Types
|
||||
|
||||
- **Agent workflows**: `{module}-{agent}.md` (auto_execution_mode: 3)
|
||||
- **Task workflows**: `task-{module}-{task}.md` (auto_execution_mode: 2)
|
||||
|
||||
### Notes
|
||||
|
||||
- Agents run with higher autonomy (mode 3)
|
||||
- Tasks run with guided execution (mode 2)
|
||||
- Workflows persist for the session
|
||||
@@ -1,16 +1,12 @@
|
||||
# BMad Documentation Index
|
||||
|
||||
Complete map of all BMad Method v6 documentation with recommended reading paths.
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Getting Started (Start Here!)
|
||||
|
||||
**New users:** Start with one of these based on your situation:
|
||||
|
||||
| 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) |
|
||||
| **Brand new to BMad** | [Quick Start Guide](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) |
|
||||
|
||||
@@ -28,7 +24,7 @@ Complete map of all BMad Method v6 documentation with recommended reading paths.
|
||||
|
||||
- **[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
|
||||
- **[Bundle Distribution Setup](./BUNDLE_DISTRIBUTION_SETUP.md)** - (temporarily non-functional) Maintainer guide for bundle auto-publishing
|
||||
|
||||
---
|
||||
|
||||
@@ -60,38 +56,6 @@ AI-powered creative thinking and brainstorming.
|
||||
|
||||
- **[CIS Module README](./modules/cis/)** - Module overview and workflows
|
||||
|
||||
---
|
||||
|
||||
## 🖥️ IDE-Specific Guides
|
||||
|
||||
Instructions for loading agents and running workflows in your development environment.
|
||||
|
||||
**Popular IDEs:**
|
||||
|
||||
- [Claude Code](./ide-info/claude-code.md)
|
||||
- [Cursor](./ide-info/cursor.md)
|
||||
- [VS Code](./ide-info/windsurf.md)
|
||||
|
||||
**Other Supported IDEs:**
|
||||
|
||||
- [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
|
||||
|
||||
### Custom Agents, Workflow and Modules
|
||||
@@ -109,7 +73,6 @@ Instructions for loading agents and running workflows in your development enviro
|
||||
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
|
||||
|
||||
### Path 2: Game Development Project
|
||||
|
||||
@@ -117,7 +80,6 @@ Instructions for loading agents and running workflows in your development enviro
|
||||
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
|
||||
|
||||
### Path 3: Upgrading from v4
|
||||
|
||||
|
||||
@@ -8,42 +8,36 @@ BMad v6 represents a complete ground-up rewrite with significant architectural c
|
||||
|
||||
## Automatic V4 Detection
|
||||
|
||||
When you run `npm run install:bmad` on a project with v4 installed, the installer automatically detects:
|
||||
When you run `npm run install:bmad` on a project, the installer automatically detects:
|
||||
|
||||
- **Legacy folders**: Any folders starting with `_bmad`, `bmad` (lowercase), or `Bmad`
|
||||
- **Legacy folders**: Any folders starting with `bmad-core` or `bmad-core`
|
||||
- **IDE command artifacts**: Legacy bmad folders in IDE configuration directories (`.claude/commands/`, `.cursor/commands/`, etc.)
|
||||
|
||||
### What Happens During Detection
|
||||
|
||||
1. **Automatic Backup of v4 Modules**: All `_bmad-*` folders are moved to `v4-backup/` in your project root
|
||||
1. **Automatic Backup of v4 Modules**: All `.bmad-core` folders are moved to `v4-backup/` in your project root
|
||||
- If a backup already exists, a timestamp is added to avoid conflicts
|
||||
- Example: `_bmad-core` → `v4-backup/_bmad-core`
|
||||
- Example: `.bmad-core` → `v4-backup/_bmad-core`
|
||||
- Your project files and data are NOT affected
|
||||
|
||||
2. **IDE Command Cleanup Recommended**: Legacy v4 IDE commands should be manually removed
|
||||
- Located in IDE config folders: `.claude/commands/`, `.cursor/commands/`, etc.
|
||||
- These old commands would still reference v4 folder structure if left in place
|
||||
- The installer provides copy/paste terminal commands for your platform
|
||||
- You can proceed without cleanup, but removing them prevents confusion with old v4 commands
|
||||
|
||||
---
|
||||
- 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
|
||||
|
||||
| v4 Module | v6 Status |
|
||||
| ----------------------------- | ------------------------------------------------ |
|
||||
| `_bmad-2d-phaser-game-dev` | Integrated into BMM |
|
||||
| `_bmad-2d-unity-game-dev` | Integrated into BMM |
|
||||
| `_bmad-godot-game-dev` | Integrated into BMM |
|
||||
| `_bmad-*-game-dev` (any) | Integrated into BMM |
|
||||
| `_bmad-infrastructure-devops` | Deprecated - New core devops agent coming in BMM |
|
||||
| `_bmad-creative-writing` | Not adapted - New module releasing soon |
|
||||
| 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 |
|
||||
|
||||
**Game Development**: All game development functionality has been consolidated and expanded within the BMM (BMad Method) module. Game-specific workflows now adapt to your game type and engine.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Changes
|
||||
|
||||
@@ -64,12 +58,13 @@ your-project/
|
||||
```
|
||||
your-project/
|
||||
└── _bmad/ # Single installation folder, default _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
|
||||
└── _config/ # Your customizations
|
||||
└── agents/ # Agent customization files
|
||||
|
||||
```
|
||||
|
||||
### Key Concept Changes
|
||||
@@ -77,34 +72,28 @@ your-project/
|
||||
- **v4 `_bmad-core`**: 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
|
||||
|
||||
---
|
||||
- **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 Planning Phase (PRD/Architecture) with the BMad Method:
|
||||
### If You've Completed Some or all Planning Phases (Brief/PRD/UX/Architecture) with the BMad Method:
|
||||
|
||||
After running the v6 installer:
|
||||
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.
|
||||
|
||||
1. **Run `workflow-init`** workflow to set up the guided workflow system
|
||||
2. **Specify your project level** when prompted:
|
||||
- If you followed v4's full workflow (PRD → Architecture → Stories), select **Level 3 or 4**
|
||||
- This tells v6 you've already completed planning and solutioning phases
|
||||
3. **Document paths**: Keep your existing paths during installation
|
||||
- Default PRD/Architecture location: `docs/`
|
||||
- Default stories location: `docs/sprint-artifacts/`
|
||||
- **Accept these defaults** if you're already using them in v4
|
||||
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'.
|
||||
|
||||
> **Important**: v6 workflows can handle both sharded and unsharded documents. You don't need to restructure your existing PRD or architecture files.
|
||||
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. Run `workflow-init` and specify Level 3 or 4
|
||||
3. When ready to continue development, run the **`sprint-planning`** workflow (Phase 4)
|
||||
|
||||
---
|
||||
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
|
||||
|
||||
@@ -131,13 +120,15 @@ persona:
|
||||
- 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](agent-customization-guide.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`
|
||||
- Result: Agent uses your custom name and style, but updates don't overwrite your changes
|
||||
|
||||
---
|
||||
- Rebuild all agents -> Result: Agent uses your custom name and style
|
||||
|
||||
## Document Compatibility
|
||||
|
||||
@@ -151,77 +142,3 @@ persona:
|
||||
- ✅ Mixed approaches
|
||||
|
||||
All workflow files are scanned automatically. No manual configuration needed.
|
||||
|
||||
---
|
||||
|
||||
## Installation Steps
|
||||
|
||||
### 1. Clone Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/bmad-code-org/BMAD-METHOD
|
||||
cd BMAD-METHOD
|
||||
npm install
|
||||
```
|
||||
|
||||
### 2. Run Installer on Your v4 Project
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
**Enter the full path to your v4 project** when prompted.
|
||||
|
||||
### 3. Follow Interactive Prompts
|
||||
|
||||
The installer will:
|
||||
|
||||
1. Detect v4 installation and offer to backup `_bmad-*` folders
|
||||
2. Prompt for recommended cleanup (you can skip)
|
||||
3. Let you select modules (recommend: BMM for software and or game development)
|
||||
4. Configure core settings (name, language, etc.)
|
||||
5. Configure module-specific options
|
||||
6. Configure IDE integrations
|
||||
|
||||
### 4. Accept Default Paths
|
||||
|
||||
If you're using:
|
||||
|
||||
- `docs/` for PRD and architecture
|
||||
- `docs/sprint-artifacts/` for story files
|
||||
|
||||
**Accept these defaults** during installation.
|
||||
|
||||
### 5. Initialize Workflow
|
||||
|
||||
After installation:
|
||||
|
||||
1. **Load the Analyst agent** - See your IDE-specific instructions in [docs/ide-info](./ide-info/) for how to activate agents:
|
||||
- [Claude Code](./ide-info/claude-code.md)
|
||||
- [Cursor](./ide-info/cursor.md)
|
||||
- [VS Code/Windsurf](./ide-info/) - Check your IDE folder
|
||||
|
||||
2. **Wait for the agent's menu** to appear
|
||||
|
||||
3. **Tell the agent**: `*workflow-init` - v6 supports excellent natural language fuzzy matching, so you could also say "workflow init" or "please init the workflow"
|
||||
|
||||
Since you are migrating an existing project from v4, it's most likely **Level 3 or 4** you will want to suggest when asked - if you've already completed PRD/architecture in v4.
|
||||
|
||||
---
|
||||
|
||||
## Post-Migration Checklist
|
||||
|
||||
- [ ] v4 folders backed up to `v4-backup/`
|
||||
- [ ] v6 installed to `_bmad/` folder
|
||||
- [ ] `workflow-init` run with correct project level selected
|
||||
- [ ] Agent customizations migrated to `_bmad/_config/agents/` if needed
|
||||
- [ ] IDE integration working (test by listing agents)
|
||||
- [ ] For active development: `sprint-planning` workflow executed
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
- **Discord**: [Join the BMad Community](https://discord.gg/gk8jAdXWmj)
|
||||
- **Issues**: [GitHub Issue Tracker](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
- **Docs**: Check `_bmad/docs/` in your installation for IDE-specific instructions
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
## IMPORTANT NOTE
|
||||
|
||||
The Web Bundling Feature is being rebuilt from the ground up, current bundles for v6 may be incomplete or missing functionality and are not optimized. This will be rectified very soon, with a more expansive guide.
|
||||
The Web Bundling Feature is being rebuilt from the ground up, current bundles found for v6 may be incomplete or missing functionality and are not optimized.
|
||||
|
||||
## What Are Web bundles
|
||||
|
||||
Web bundles package BMad agents as self-contained XML files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file.
|
||||
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 Are Web Bundles?
|
||||
|
||||
Web bundles are standalone XML files containing:
|
||||
Web bundles are standalone files containing:
|
||||
|
||||
- Complete agent persona and instructions
|
||||
- All workflows and dependencies
|
||||
|
||||
42
docs/workflow-vendoring-customization-inheritance.md
Normal file
42
docs/workflow-vendoring-customization-inheritance.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Workflow Vendoring, Customization, and Inheritance (Official Support Consing Soon)
|
||||
|
||||
Vendoring and Inheritance of workflows are 2 ways of sharing or reutilizing workflows - but with some key distinctions and use cases.
|
||||
|
||||
## Workflow Vendoring
|
||||
|
||||
Workflow Vendoring allows an agent to have access to a workflow from another module, without having to install said module. At install time, the module workflow being vendored will be cloned and installed into the module that is receiving the vendored workflow the agent needs.
|
||||
|
||||
### How to Vendor
|
||||
|
||||
Lets assume you are building a module, and you do not want to recreate a workflow from the BMad Method, such as workflows/4-implementation/dev-story/workflow.md. Instead of copying all the context to your module, and having to maintain it over time as updates are made, you can instead use the exec-vendor menu item in your agent.
|
||||
|
||||
From your modules agent definition, you would implement the menu item as follows in the agent:
|
||||
|
||||
```yaml
|
||||
- trigger: develop-story
|
||||
exec-vendor: "{project-root}/_bmad/<source-module>/workflows/4-production/dev-story/workflow.md"
|
||||
exec: "{project-root}/_bmad/<my-module>/workflows/dev-story/workflow.md"
|
||||
description: "Execute Dev Story workflow, implementing tasks and tests, or performing updates to the story"
|
||||
```
|
||||
|
||||
At install time, it will clone the workflow and all of its required assets, and the agent that gets built will have an exec to a path installed in its own module. The content gets added to the folder you specify in exec. While it does not have to exactly match the source path, you will want to ensure you are specifying the workflow.md to be in a new location (in other words in this example, dev-story would not already be the path of another custom module workflow that already exists.)
|
||||
|
||||
## Workflow Inheritance (Official Support Coming Post Beta)
|
||||
|
||||
Workflow Inheritance is a different concept, that allows you to modify or extend existing workflow.
|
||||
|
||||
Party Mode from the core is an example of a workflow that is designed with inheritance in mind - customization for specific party needs. While party mode itself is generic - there might be specific agent collaborations you want to create. Without having to reinvent the whole party mode concept, or copy and paste all of its content - you could inherit from party mode to extend it to be specific.
|
||||
|
||||
Some possible examples could be:
|
||||
|
||||
- Retrospective
|
||||
- Sprint Planning
|
||||
- Collaborative Brainstorming Sessions
|
||||
|
||||
## Workflow Customization (Official Support Coming Post Beta)
|
||||
|
||||
Similar to Workflow Inheritance, Workflow Customization will soon be allowed for certain workflows that are meant to be user customized - similar in process to how agents are customized now.
|
||||
|
||||
This will take the shape of workflows with optional hooks, configurable inputs, and the ability to replace whole at install time.
|
||||
|
||||
For example, assume you are using the Create PRD workflow, which is comprised of 11 steps, and you want to always include specifics about your companies domain, technical landscape or something else. While project-context can be helpful with that, you can also through hooks and step overrides, have full replace steps, the key requirement being to ensure your step replace file is an exact file name match of an existing step, follows all conventions, and ends in a similar fashion to either hook back in to call the next existing step, or more custom steps that eventually hook back into the flow.
|
||||
@@ -25,10 +25,6 @@
|
||||
- @/docs/installers-bundlers/ - Tooling-specific documentation directory
|
||||
- @/tools/cli/README.md - CLI usage documentation (comprehensive)
|
||||
|
||||
### IDE-Specific Documentation
|
||||
|
||||
- @/docs/ide-info/ - IDE-specific setup guides (15+ files)
|
||||
|
||||
### Module Documentation
|
||||
|
||||
Each module may have its own docs:
|
||||
@@ -73,7 +69,6 @@ Follow Keep a Changelog format:
|
||||
When code changes, check these docs:
|
||||
|
||||
- CLI changes → tools/cli/README.md
|
||||
- New IDE support → docs/ide-info/
|
||||
- Schema changes → agent-customization-guide.md
|
||||
- Bundle changes → web-bundles-gemini-gpt-guide.md
|
||||
- Installer changes → installers-bundlers/
|
||||
|
||||
@@ -291,4 +291,3 @@ Phase 4 workflows inherit from BMM base and add BMGD-specific overrides.
|
||||
|
||||
- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
|
||||
- **[Game Types Guide](./game-types-guide.md)** - Game genre reference
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
@@ -50,7 +50,6 @@ Understanding how BMGD works:
|
||||
Essential reference materials:
|
||||
|
||||
- **[Glossary](./glossary.md)** - Key game development terminology
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Common issues and solutions
|
||||
|
||||
---
|
||||
|
||||
@@ -148,7 +147,6 @@ BMGD Documentation
|
||||
├── quick-flow-guide.md # Rapid prototyping and development
|
||||
├── game-types-guide.md # Game type templates
|
||||
├── glossary.md # Terminology
|
||||
└── troubleshooting.md # Common issues
|
||||
```
|
||||
|
||||
---
|
||||
@@ -164,9 +162,6 @@ BMGD Documentation
|
||||
### Related Documentation
|
||||
|
||||
- **[BMM Documentation](../../bmm/docs/index.md)** - Core BMad Method documentation
|
||||
- **[IDE Guides](../../ide-info/)** - Configure your development environment
|
||||
|
||||
---
|
||||
|
||||
## Tips for Using This Documentation
|
||||
|
||||
|
||||
@@ -111,10 +111,6 @@ Use party mode to engage all 19+ agents (from BMM, CIS, BMB, custom modules) in
|
||||
- **[Brownfield Guide](./docs/brownfield-guide.md)** - Working with existing codebases
|
||||
- **[Quick Spec Flow](./docs/quick-spec-flow.md)** - Fast-track for Level 0-1 projects
|
||||
- **[Enterprise Agentic Development](./docs/enterprise-agentic-development.md)** - Team collaboration patterns
|
||||
- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
|
||||
- **[IDE Setup Guides](../../../docs/ide-info/)** - Configure Claude Code, Cursor, Windsurf, etc.
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Community
|
||||
|
||||
|
||||
@@ -725,7 +725,6 @@ flowchart TD
|
||||
- **[Quick Start Guide](./quick-start.md)** - Getting started with BMM
|
||||
- **[Glossary](./glossary.md)** - Key terminology
|
||||
- **[FAQ](./faq.md)** - Common questions
|
||||
- **[Troubleshooting](./troubleshooting.md)** - Problem resolution
|
||||
- **[Workflow Documentation](./index.md#-workflow-guides)** - Complete workflow reference
|
||||
|
||||
---
|
||||
|
||||
@@ -1,686 +0,0 @@
|
||||
# Enterprise Agentic Development with BMad Method
|
||||
|
||||
**The paradigm shift: From team-based story parallelism to individual epic ownership**
|
||||
|
||||
**Reading Time:** ~18 minutes
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [The Paradigm Shift](#the-paradigm-shift)
|
||||
- [The Evolving Role of Product Managers and UX Designers](#the-evolving-role-of-product-managers-and-ux-designers)
|
||||
- [How BMad Method Enables PM/UX Technical Evolution](#how-bmad-method-enables-pmux-technical-evolution)
|
||||
- [Team Collaboration Patterns](#team-collaboration-patterns)
|
||||
- [Work Distribution Strategies](#work-distribution-strategies)
|
||||
- [Enterprise Configuration with Git Submodules](#enterprise-configuration-with-git-submodules)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Common Scenarios](#common-scenarios)
|
||||
|
||||
---
|
||||
|
||||
## The Paradigm Shift
|
||||
|
||||
### Traditional Agile: Team-Based Story Parallelism
|
||||
|
||||
- **Epic duration:** 4-12 weeks across multiple sprints
|
||||
- **Story duration:** 2-5 days per developer
|
||||
- **Team size:** 5-9 developers working on same epic
|
||||
- **Parallelization:** Multiple devs on stories within single epic
|
||||
- **Coordination:** Constant - daily standups, merge conflicts, integration overhead
|
||||
|
||||
**Example:** Payment Processing Epic
|
||||
|
||||
- Sprint 1-2: Backend API (Dev A)
|
||||
- Sprint 1-2: Frontend UI (Dev B)
|
||||
- Sprint 2-3: Testing (Dev C)
|
||||
- **Result:** 6-8 weeks, 3 developers, high coordination
|
||||
|
||||
### Agentic Development: Individual Epic Ownership
|
||||
|
||||
- **Epic duration:** Hours to days (not weeks)
|
||||
- **Story duration:** 30 min to 4 hours with AI agent
|
||||
- **Team size:** 1 developer + AI agents completes full epics
|
||||
- **Parallelization:** Developers work on separate epics
|
||||
- **Coordination:** Minimal - epic boundaries, async updates
|
||||
|
||||
**Same Example:** Payment Processing Epic
|
||||
|
||||
- Day 1 AM: Backend API stories (1 dev + agent, 3-4 stories)
|
||||
- Day 1 PM: Frontend UI stories (same dev + agent, 2-3 stories)
|
||||
- Day 2: Testing & deployment (same dev + agent, 2 stories)
|
||||
- **Result:** 1-2 days, 1 developer, minimal coordination
|
||||
|
||||
### The Core Difference
|
||||
|
||||
**What changed:** AI agents collapse story duration from days to hours, making **epic-level ownership** practical.
|
||||
|
||||
**Impact:** Single developer with BMad Method can deliver in 1 day what previously required full team and multiple sprints.
|
||||
|
||||
---
|
||||
|
||||
## The Evolving Role of Product Managers and UX Designers
|
||||
|
||||
### The Future is Now
|
||||
|
||||
Product Managers and UX Designers are undergoing **the most significant transformation since the creation of these disciplines**. The emergence of AI agents is creating a new breed of technical product leaders who translate vision directly into working code.
|
||||
|
||||
### From Spec Writers to Code Orchestrators
|
||||
|
||||
**Traditional PM/UX (Pre-2025):**
|
||||
|
||||
- Write PRDs, hand off to engineering
|
||||
- Wait weeks/months for implementation
|
||||
- Limited validation capabilities
|
||||
- Non-technical role, heavy on process
|
||||
|
||||
**Emerging PM/UX (2025+):**
|
||||
|
||||
- Write AI-optimized PRDs that **feed agentic pipelines directly**
|
||||
- Generate working prototypes in 10-15 minutes
|
||||
- Review pull requests from AI agents
|
||||
- Technical fluency is **table stakes**, not optional
|
||||
- Orchestrate cloud-based AI agent teams
|
||||
|
||||
### Industry Research (November 2025)
|
||||
|
||||
- **56% of product professionals** cite AI/ML as top focus
|
||||
- **AI agents automating** customer discovery, PRD creation, status reporting
|
||||
- **PRD-to-Code automation** enables PMs to build and deploy apps in 10-15 minutes
|
||||
- **By 2026**: Roles converging into "Full-Stack Product Lead" (PM + Design + Engineering)
|
||||
- **Very high salaries** for AI agent PMs who orchestrate autonomous dev systems
|
||||
|
||||
### Required Skills for Modern PMs/UX
|
||||
|
||||
1. **AI Prompt Engineering** - Writing PRDs AI agents can execute autonomously
|
||||
2. **Coding Literacy** - Understanding code structure, APIs, data flows (not production coding)
|
||||
3. **Agentic Workflow Design** - Orchestrating multi-agent systems (planning → design → dev)
|
||||
4. **Technical Architecture** - Reasoning frameworks, memory systems, tool integration
|
||||
5. **Data Literacy** - Interpreting model outputs, spotting trends, identifying gaps
|
||||
6. **Code Review** - Evaluating AI-generated PRs for correctness and vision alignment
|
||||
|
||||
### What Remains Human
|
||||
|
||||
**AI Can't Replace:**
|
||||
|
||||
- Product vision (market dynamics, customer pain, strategic positioning)
|
||||
- Empathy (deep user research, emotional intelligence, stakeholder management)
|
||||
- Creativity (novel problem-solving, disruptive thinking)
|
||||
- Judgment (prioritization decisions, trade-off analysis)
|
||||
- Ethics (responsible AI use, privacy, accessibility)
|
||||
|
||||
**What Changes:**
|
||||
|
||||
- PMs/UX spend **more time on human elements** (AI handles routine execution)
|
||||
- Barrier between "thinking" and "building" collapses
|
||||
- Product leaders become **builder-thinkers**, not just spec writers
|
||||
|
||||
### The Convergence
|
||||
|
||||
- **PMs learning to code** with GitHub Copilot, Cursor, v0
|
||||
- **UX designers generating code** with UXPin Merge, Figma-to-code tools
|
||||
- **Developers becoming orchestrators** reviewing AI output vs writing from scratch
|
||||
|
||||
**The Bottom Line:** By 2026, successful PMs/UX will fluently operate in both vision and execution. **BMad Method provides the structured framework to make this transition.**
|
||||
|
||||
---
|
||||
|
||||
## How BMad Method Enables PM/UX Technical Evolution
|
||||
|
||||
BMad Method is specifically designed to position PMs and UX designers for this future.
|
||||
|
||||
### 1. AI-Executable PRD Generation
|
||||
|
||||
**PM Workflow:**
|
||||
|
||||
```bash
|
||||
bmad pm *create-prd
|
||||
```
|
||||
|
||||
**BMad produces:**
|
||||
|
||||
- Structured, machine-readable requirements
|
||||
- Functional Requirements (FRs) with testable acceptance criteria
|
||||
- Non-Functional Requirements (NFRs) with measurable targets
|
||||
- Technical context for AI agents
|
||||
|
||||
**Why it matters:** Traditional PRDs are human-readable prose. BMad PRDs are **AI-executable requirement specifications**.
|
||||
|
||||
**PM Value:** Clear requirements that feed into architecture decisions, then into story breakdown. No ambiguity.
|
||||
|
||||
### 2. Human-in-the-Loop Architecture
|
||||
|
||||
**Architect/PM Workflow:**
|
||||
|
||||
```bash
|
||||
bmad architect *create-architecture
|
||||
```
|
||||
|
||||
**BMad produces:**
|
||||
|
||||
- System architecture aligned with PRD's FRs/NFRs
|
||||
- Architecture Decision Records (ADRs)
|
||||
- FR/NFR-specific technical guidance
|
||||
- Integration patterns and standards
|
||||
|
||||
**Why it matters:** PMs can **understand and validate** technical decisions. Architecture is conversational, not template-driven.
|
||||
|
||||
**PM Value:** Technical fluency built through guided architecture process. PMs learn while creating.
|
||||
|
||||
### 3. Automated Epic/Story Breakdown (AFTER Architecture)
|
||||
|
||||
**PM Workflow:**
|
||||
|
||||
```bash
|
||||
bmad pm *create-epics-and-stories
|
||||
```
|
||||
|
||||
**V6 Improvement:** Epics and stories are now created AFTER architecture for better quality. The workflow uses both PRD (FRs/NFRs) and Architecture to create technically-informed stories.
|
||||
|
||||
**BMad produces:**
|
||||
|
||||
- Epic files with clear objectives
|
||||
- Story files with acceptance criteria, context, technical guidance
|
||||
- Priority assignments (P0-P3)
|
||||
- Dependency mapping informed by architectural decisions
|
||||
|
||||
**Why it matters:** Stories become **work packages for cloud AI agents**. Each story is self-contained with full context AND aligned with architecture.
|
||||
|
||||
**PM Value:** No more "story refinement sessions" with engineering. Stories are technically grounded from the start.
|
||||
|
||||
### 4. Cloud Agentic Pipeline (Emerging Pattern)
|
||||
|
||||
**Current State (2025):**
|
||||
|
||||
```
|
||||
PM writes BMad PRD (FRs/NFRs)
|
||||
↓
|
||||
Architect creates architecture (technical decisions)
|
||||
↓
|
||||
create-epics-and-stories generates story queue (informed by architecture)
|
||||
↓
|
||||
Stories loaded by human developers + BMad agents
|
||||
↓
|
||||
Developers create PRs
|
||||
↓
|
||||
PM/Team reviews PRs
|
||||
↓
|
||||
Merge and deploy
|
||||
```
|
||||
|
||||
**Near Future (2026):**
|
||||
|
||||
```
|
||||
PM writes BMad PRD (FRs/NFRs)
|
||||
↓
|
||||
Architecture auto-generated with PM approval
|
||||
↓
|
||||
create-epics-and-stories generates story queue (informed by architecture)
|
||||
↓
|
||||
Stories automatically fed to cloud AI agent pool
|
||||
↓
|
||||
AI agents implement stories in parallel
|
||||
↓
|
||||
AI agents create pull requests
|
||||
↓
|
||||
PM/UX/Senior Devs review PRs
|
||||
↓
|
||||
Approved PRs auto-merge
|
||||
↓
|
||||
Continuous deployment to production
|
||||
```
|
||||
|
||||
**Time Savings:**
|
||||
|
||||
- **Traditional:** PM writes spec → 2-4 weeks engineering → review → deploy (6-8 weeks)
|
||||
- **BMad Agentic:** PM writes PRD → AI agents implement → review PRs → deploy (2-5 days)
|
||||
|
||||
### 5. UX Design Integration
|
||||
|
||||
**UX Designer Workflow:**
|
||||
|
||||
```bash
|
||||
bmad ux *create-ux-design
|
||||
```
|
||||
|
||||
**BMad produces:**
|
||||
|
||||
- Component-based design system
|
||||
- Interaction patterns aligned with tech stack
|
||||
- Accessibility guidelines
|
||||
- Responsive design specifications
|
||||
|
||||
**Why it matters:** Design specs become **implementation-ready** for AI agents. No "lost in translation" between design and dev.
|
||||
|
||||
**UX Value:** Designs validated through working prototypes, not static mocks. Technical understanding built through BMad workflows.
|
||||
|
||||
### 6. PM Technical Skills Development
|
||||
|
||||
**BMad teaches PMs technical skills through:**
|
||||
|
||||
- **Conversational workflows** - No pre-requisite knowledge, learn by doing
|
||||
- **Architecture facilitation** - Understand system design through guided questions
|
||||
- **Story context assembly** - See how code patterns inform implementation
|
||||
- **Code review workflows** - Learn to evaluate code quality, patterns, standards
|
||||
|
||||
**Example:** PM runs `create-architecture` workflow:
|
||||
|
||||
- BMad asks about scale, performance, integrations
|
||||
- PM answers business questions
|
||||
- BMad explains technical implications
|
||||
- PM learns architecture concepts while making decisions
|
||||
|
||||
**Result:** PMs gain **working technical knowledge** without formal CS education.
|
||||
|
||||
### 7. Organizational Leverage
|
||||
|
||||
**Traditional Model:**
|
||||
|
||||
- 1 PM → supports 5-9 developers → delivers 1-2 features/quarter
|
||||
|
||||
**BMad Agentic Model:**
|
||||
|
||||
- 1 PM → writes BMad PRD → 20-50 AI agents execute stories in parallel → delivers 5-10 features/quarter
|
||||
|
||||
**Leverage multiplier:** 5-10× with same PM headcount.
|
||||
|
||||
### 8. Quality Consistency
|
||||
|
||||
**BMad ensures:**
|
||||
|
||||
- AI agents follow architectural patterns consistently
|
||||
- Code standards applied uniformly
|
||||
- PRD traceability throughout implementation (via acceptance criteria)
|
||||
- No "telephone game" between PM, design, and dev
|
||||
|
||||
**PM Value:** What gets built **matches what was specified**, drastically reducing rework.
|
||||
|
||||
### 9. Rapid Prototyping for Validation
|
||||
|
||||
**PM Workflow (with BMad + Cursor/v0):**
|
||||
|
||||
1. Use BMad to generate PRD structure and requirements
|
||||
2. Extract key user flow from PRD
|
||||
3. Feed to Cursor/v0 with BMad context
|
||||
4. Working prototype in 10-15 minutes
|
||||
5. Validate with users **before** committing to full development
|
||||
|
||||
**Traditional:** Months of development to validate idea
|
||||
**BMad Agentic:** Hours of development to validate idea
|
||||
|
||||
### 10. Career Path Evolution
|
||||
|
||||
**BMad positions PMs for emerging roles:**
|
||||
|
||||
- **AI Agent Product Manager** - Orchestrate autonomous development systems
|
||||
- **Full-Stack Product Lead** - Oversee product, design, engineering with AI leverage
|
||||
- **Technical Product Strategist** - Bridge business vision and technical execution
|
||||
|
||||
**Hiring advantage:** PMs using BMad demonstrate:
|
||||
|
||||
- Technical fluency (can read architecture, validate tech decisions)
|
||||
- AI-native workflows (structured requirements, agentic orchestration)
|
||||
- Results (ship 5-10× faster than peers)
|
||||
|
||||
---
|
||||
|
||||
## Team Collaboration Patterns
|
||||
|
||||
### Old Pattern: Story Parallelism
|
||||
|
||||
**Traditional Agile:**
|
||||
|
||||
```
|
||||
Epic: User Dashboard (8 weeks)
|
||||
├─ Story 1: Backend API (Dev A, Sprint 1-2)
|
||||
├─ Story 2: Frontend Layout (Dev B, Sprint 1-2)
|
||||
├─ Story 3: Data Viz (Dev C, Sprint 2-3)
|
||||
└─ Story 4: Integration Testing (Team, Sprint 3-4)
|
||||
|
||||
Challenge: Coordination overhead, merge conflicts, integration issues
|
||||
```
|
||||
|
||||
### New Pattern: Epic Ownership
|
||||
|
||||
**Agentic Development:**
|
||||
|
||||
```
|
||||
Project: Analytics Platform (2-3 weeks)
|
||||
|
||||
Developer A:
|
||||
└─ Epic 1: User Dashboard (3 days, 12 stories sequentially with AI)
|
||||
|
||||
Developer B:
|
||||
└─ Epic 2: Admin Panel (4 days, 15 stories sequentially with AI)
|
||||
|
||||
Developer C:
|
||||
└─ Epic 3: Reporting Engine (5 days, 18 stories sequentially with AI)
|
||||
|
||||
Benefit: Minimal coordination, epic-level ownership, clear boundaries
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Work Distribution Strategies
|
||||
|
||||
### Strategy 1: Epic-Based (Recommended)
|
||||
|
||||
**Best for:** 2-10 developers
|
||||
|
||||
**Approach:** Each developer owns complete epics, works sequentially through stories
|
||||
|
||||
**Example:**
|
||||
|
||||
```yaml
|
||||
epics:
|
||||
- id: epic-1
|
||||
title: Payment Processing
|
||||
owner: alice
|
||||
stories: 8
|
||||
estimate: 2 days
|
||||
|
||||
- id: epic-2
|
||||
title: User Dashboard
|
||||
owner: bob
|
||||
stories: 12
|
||||
estimate: 3 days
|
||||
```
|
||||
|
||||
**Benefits:** Clear ownership, minimal conflicts, epic cohesion, reduced coordination
|
||||
|
||||
### Strategy 2: Layer-Based
|
||||
|
||||
**Best for:** Full-stack apps, specialized teams
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Frontend Dev: Epic 1 (Product Catalog UI), Epic 3 (Cart UI)
|
||||
Backend Dev: Epic 2 (Product API), Epic 4 (Cart Service)
|
||||
```
|
||||
|
||||
**Benefits:** Developers in expertise area, true parallel work, clear API contracts
|
||||
|
||||
**Requirements:** Strong architecture phase, clear API contracts upfront
|
||||
|
||||
### Strategy 3: Feature-Based
|
||||
|
||||
**Best for:** Large teams (10+ developers)
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
Team A (2 devs): Payments feature (4 epics)
|
||||
Team B (2 devs): User Management feature (3 epics)
|
||||
Team C (2 devs): Analytics feature (3 epics)
|
||||
```
|
||||
|
||||
**Benefits:** Feature team autonomy, domain expertise, scalable to large orgs
|
||||
|
||||
---
|
||||
|
||||
## Enterprise Configuration with Git Submodules
|
||||
|
||||
### The Challenge
|
||||
|
||||
**Problem:** Teams customize BMad (agents, workflows, configs) but don't want personal tooling in main repo.
|
||||
|
||||
**Anti-pattern:** Adding `_bmad/` to `.gitignore` breaks IDE tools, submodule management.
|
||||
|
||||
### The Solution: Git Submodules
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- BMad exists in project but tracked separately
|
||||
- Each developer controls their own BMad version/config
|
||||
- Optional team config sharing via submodule repo
|
||||
- IDE tools maintain proper context
|
||||
|
||||
### Setup (New Projects)
|
||||
|
||||
**1. Create optional team config repo:**
|
||||
|
||||
```bash
|
||||
git init bmm-config
|
||||
cd bmm-config
|
||||
npx bmad-method install
|
||||
# Customize for team standards
|
||||
git commit -m "Team BMM config"
|
||||
git push origin main
|
||||
```
|
||||
|
||||
**2. Add submodule to project:**
|
||||
|
||||
```bash
|
||||
cd /path/to/your-project
|
||||
git submodule add https://github.com/your-org/bmm-config.git bmad
|
||||
git commit -m "Add BMM as submodule"
|
||||
```
|
||||
|
||||
**3. Team members initialize:**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-org/your-project.git
|
||||
cd your-project
|
||||
git submodule update --init --recursive
|
||||
# Make personal customizations in _bmad/
|
||||
```
|
||||
|
||||
### Daily Workflow
|
||||
|
||||
**Work in main project:**
|
||||
|
||||
```bash
|
||||
cd /path/to/your-project
|
||||
# BMad available at ./_bmad/, load agents normally
|
||||
```
|
||||
|
||||
**Update personal config:**
|
||||
|
||||
```bash
|
||||
cd bmad
|
||||
# Make changes, commit locally, don't push unless sharing
|
||||
```
|
||||
|
||||
**Update to latest team config:**
|
||||
|
||||
```bash
|
||||
cd bmad
|
||||
git pull origin main
|
||||
```
|
||||
|
||||
### Configuration Strategies
|
||||
|
||||
**Option 1: Fully Personal** - No submodule, each dev installs independently, use `.gitignore`
|
||||
|
||||
**Option 2: Team Baseline + Personal** - Submodule has team standards, devs add personal customizations locally
|
||||
|
||||
**Option 3: Full Team Sharing** - All configs in submodule, team collaborates on improvements
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Epic Ownership
|
||||
|
||||
- **Do:** Assign entire epic to one developer (context → implementation → retro)
|
||||
- **Don't:** Split epics across multiple developers (coordination overhead, context loss)
|
||||
|
||||
### 2. Dependency Management
|
||||
|
||||
- **Do:** Identify epic dependencies in planning, document API contracts, complete prerequisites first
|
||||
- **Don't:** Start dependent epic before prerequisite ready, change API contracts without coordination
|
||||
|
||||
### 3. Communication Cadence
|
||||
|
||||
**Traditional:** Daily standups essential
|
||||
**Agentic:** Lighter coordination
|
||||
|
||||
**Recommended:**
|
||||
|
||||
- Daily async updates ("Epic 1, 60% complete, no blockers")
|
||||
- Twice-weekly 15min sync
|
||||
- Epic completion demos
|
||||
- Sprint retro after all epics complete
|
||||
|
||||
### 4. Branch Strategy
|
||||
|
||||
```bash
|
||||
feature/epic-1-payment-processing (Alice)
|
||||
feature/epic-2-user-dashboard (Bob)
|
||||
feature/epic-3-admin-panel (Carol)
|
||||
|
||||
# PR and merge when epic complete
|
||||
```
|
||||
|
||||
### 5. Testing Strategy
|
||||
|
||||
- **Story-level:** Unit tests (DoD requirement, written by agent during dev-story)
|
||||
- **Epic-level:** Integration tests across stories
|
||||
- **Project-level:** E2E tests after multiple epics complete
|
||||
|
||||
### 6. Documentation Updates
|
||||
|
||||
- **Real-time:** `sprint-status.yaml` updated by workflows
|
||||
- **Epic completion:** Update architecture docs, API docs, README if changed
|
||||
- **Sprint completion:** Incorporate retrospective insights
|
||||
|
||||
### 7. Metrics (Different from Traditional)
|
||||
|
||||
**Traditional:** Story points per sprint, burndown charts
|
||||
**Agentic:** Epics per week, stories per day, time to epic completion
|
||||
|
||||
**Example velocity:**
|
||||
|
||||
- Junior dev + AI: 1-2 epics/week (8-15 stories)
|
||||
- Mid-level dev + AI: 2-3 epics/week (15-25 stories)
|
||||
- Senior dev + AI: 3-5 epics/week (25-40 stories)
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Startup (2 Developers)
|
||||
|
||||
**Project:** SaaS MVP (Level 3)
|
||||
|
||||
**Distribution:**
|
||||
|
||||
```
|
||||
Developer A:
|
||||
├─ Epic 1: Authentication (3 days)
|
||||
├─ Epic 3: Payment Integration (2 days)
|
||||
└─ Epic 5: Admin Dashboard (3 days)
|
||||
|
||||
Developer B:
|
||||
├─ Epic 2: Core Product Features (4 days)
|
||||
├─ Epic 4: Analytics (3 days)
|
||||
└─ Epic 6: Notifications (2 days)
|
||||
|
||||
Total: ~2 weeks
|
||||
Traditional estimate: 3-4 months
|
||||
```
|
||||
|
||||
**BMM Setup:** Direct installation, both use Claude Code, minimal customization
|
||||
|
||||
### Scenario 2: Mid-Size Team (8 Developers)
|
||||
|
||||
**Project:** Enterprise Platform (Level 4)
|
||||
|
||||
**Distribution (Layer-Based):**
|
||||
|
||||
```
|
||||
Backend (2 devs): 6 API epics
|
||||
Frontend (2 devs): 6 UI epics
|
||||
Full-stack (2 devs): 4 integration epics
|
||||
DevOps (1 dev): 3 infrastructure epics
|
||||
QA (1 dev): 1 E2E testing epic
|
||||
|
||||
Total: ~3 weeks
|
||||
Traditional estimate: 9-12 months
|
||||
```
|
||||
|
||||
**BMM Setup:** Git submodule, team config repo, mix of Claude Code/Cursor users
|
||||
|
||||
### Scenario 3: Large Enterprise (50+ Developers)
|
||||
|
||||
**Project:** Multi-Product Platform
|
||||
|
||||
**Organization:**
|
||||
|
||||
- 5 product teams (8-10 devs each)
|
||||
- 1 platform team (10 devs - shared services)
|
||||
- 1 infrastructure team (5 devs)
|
||||
|
||||
**Distribution (Feature-Based):**
|
||||
|
||||
```
|
||||
Product Team A: Payments (10 epics, 2 weeks)
|
||||
Product Team B: User Mgmt (12 epics, 2 weeks)
|
||||
Product Team C: Analytics (8 epics, 1.5 weeks)
|
||||
Product Team D: Admin Tools (10 epics, 2 weeks)
|
||||
Product Team E: Mobile (15 epics, 3 weeks)
|
||||
|
||||
Platform Team: Shared Services (continuous)
|
||||
Infrastructure Team: DevOps (continuous)
|
||||
|
||||
Total: 3-4 months
|
||||
Traditional estimate: 2-3 years
|
||||
```
|
||||
|
||||
**BMM Setup:** Each team has own submodule config, org-wide base config, variety of IDE tools
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
### Key Transformation
|
||||
|
||||
**Work Unit Changed:**
|
||||
|
||||
- **Old:** Story = unit of work assignment
|
||||
- **New:** Epic = unit of work assignment
|
||||
|
||||
**Why:** AI agents collapse story duration (days → hours), making epic ownership practical.
|
||||
|
||||
### Velocity Impact
|
||||
|
||||
- **Traditional:** Months for epic delivery, heavy coordination
|
||||
- **Agentic:** Days for epic delivery, minimal coordination
|
||||
- **Result:** 10-50× productivity gains
|
||||
|
||||
### PM/UX Evolution
|
||||
|
||||
**BMad Method enables:**
|
||||
|
||||
- PMs to write AI-executable PRDs
|
||||
- UX designers to validate through working prototypes
|
||||
- Technical fluency without CS degrees
|
||||
- Orchestration of cloud AI agent teams
|
||||
- Career evolution to Full-Stack Product Lead
|
||||
|
||||
### Enterprise Adoption
|
||||
|
||||
**Git submodules:** Best practice for BMM management across teams
|
||||
**Team flexibility:** Mix of tools (Claude Code, Cursor, Windsurf) with shared BMM foundation
|
||||
**Scalable patterns:** Epic-based, layer-based, feature-based distribution strategies
|
||||
|
||||
### The Future (2026)
|
||||
|
||||
PMs write BMad PRDs → Stories auto-fed to cloud AI agents → Parallel implementation → Human review of PRs → Continuous deployment
|
||||
|
||||
**The future isn't AI replacing PMs—it's AI-augmented PMs becoming 10× more powerful.**
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained
|
||||
- [Quick Start Guide](./quick-start.md) - Getting started
|
||||
- [Workflow Documentation](./index.md#-workflow-guides) - Complete workflow reference
|
||||
- [Agents Guide](./agents-guide.md) - Understanding BMad agents
|
||||
|
||||
---
|
||||
|
||||
_BMad Method fundamentally changes how PMs work, how teams structure work, and how products get built. Understanding these patterns is essential for enterprise success in the age of AI agents._
|
||||
@@ -354,8 +354,6 @@ Use them together for best results.
|
||||
|
||||
**Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality.
|
||||
|
||||
See [IDE Setup Guides](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for configuration specifics.
|
||||
|
||||
### Q: Can I customize agents?
|
||||
|
||||
**A:** Yes! Agents are installed as markdown files with XML-style content (optimized for LLMs, readable by any model). Create customization files in `_bmad/_config/agents/[agent-name].customize.yaml` to override default behaviors while keeping core functionality intact. See agent documentation for customization options.
|
||||
|
||||
@@ -22,26 +22,23 @@ Complete guides for the BMad Method Module (BMM) - AI-powered agile development
|
||||
|
||||
## 📖 Core Concepts
|
||||
|
||||
Understanding how BMM adapts to your needs:
|
||||
The BMad Method is meant to be adapted and customized to your specific needs. In this realm there is no one size fits all - your needs are unique, and BMad Method is meant to support this (and if it does not, can be further customized or extended with new modules).
|
||||
|
||||
- **[Scale Adaptive System](./scale-adaptive-system.md)** - How BMM adapts to project size and complexity
|
||||
- Three planning tracks (Quick Flow, BMad Method, Enterprise Method)
|
||||
- Automatic track recommendation
|
||||
- Documentation requirements per track
|
||||
- Planning workflow routing
|
||||
First know there is the full BMad Method Process and then there is a Quick Flow for those quicker smaller efforts.
|
||||
|
||||
- **[Full Adaptive BMad Method](#-workflow-guides)** - Full planning and scope support through extensive development and testing.
|
||||
- Broken down into 4 phases, all of which are comprised of both required and optional phases
|
||||
- Phases 1-3 are all about progressive idea development through planning and preparations to build your project.
|
||||
- Phase 4 is the implementation cycle where you will Just In Time (JIT) produce the contextual stories needed for the dev agent based on the extensive planing completed
|
||||
- All 4 phases have optional steps in them, depending on how rigorous you want to go with planning, research ideation, validation, testing and traceability.
|
||||
- While there is a lot here, know that even this can be distilled down to a simple PRD, Epic and Story list and then jump into the dev cycle. But if that is all you want, you might be better off with the BMad Quick Flow described next
|
||||
|
||||
- **[BMAD Quick Flow](./bmad-quick-flow.md)** - Fast-track development workflow
|
||||
- 3-step process: spec → dev → optional review
|
||||
- Perfect for bug fixes and small features
|
||||
- Rapid prototyping with production quality
|
||||
- Hours to implementation, not days
|
||||
- Barry (Quick Flow Solo Dev) agent owned
|
||||
|
||||
- **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)** - Elite solo developer for rapid development
|
||||
- Barry is an elite developer who thrives on autonomous execution
|
||||
- Lives and breathes the BMAD Quick Flow workflow
|
||||
- Takes projects from concept to deployment with ruthless efficiency
|
||||
- No handoffs, no delays - just pure focused development
|
||||
- Implementation in minutes, not days
|
||||
- Has a specialized single agent that does all of this: **[Quick Flow Solo Dev Agent](./quick-flow-solo-dev.md)**
|
||||
|
||||
## 🤖 Agents and Collaboration
|
||||
|
||||
@@ -78,7 +75,6 @@ Essential reference materials:
|
||||
|
||||
- **[Glossary](./glossary.md)** - Key terminology and concepts
|
||||
- **[FAQ](./faq.md)** - Frequently asked questions across all topics
|
||||
- **[Enterprise Agentic Development](./enterprise-agentic-development.md)** - Team collaboration strategies
|
||||
|
||||
## 🎯 Choose Your Path
|
||||
|
||||
@@ -86,19 +82,14 @@ Essential reference materials:
|
||||
|
||||
**Build something new (greenfield)**
|
||||
→ Start with [Quick Start Guide](./quick-start.md)
|
||||
→ Then review [Scale Adaptive System](./scale-adaptive-system.md) to understand tracks
|
||||
|
||||
**Fix a bug or add small feature**
|
||||
→ Go to [BMAD Quick Flow](./bmad-quick-flow.md) for rapid development
|
||||
→ Or use [Quick Flow Solo Dev](./quick-flow-solo-dev.md) directly
|
||||
→ User the [Quick Flow Solo Dev](./quick-flow-solo-dev.md) directly with its dedicated stand alone [Quick Bmad Spec Flow](./quick-spec-flow.md) process
|
||||
|
||||
**Work with existing codebase (brownfield)**
|
||||
→ Read [Brownfield Development Guide](./brownfield-guide.md)
|
||||
→ Pay special attention to documentation requirements for brownfield projects
|
||||
|
||||
**Understand planning tracks and methodology**
|
||||
→ See [Scale Adaptive System](./scale-adaptive-system.md)
|
||||
|
||||
## 📋 Workflow Guides
|
||||
|
||||
Comprehensive documentation for all BMM workflows organized by phase:
|
||||
@@ -127,35 +118,6 @@ Comprehensive documentation for all BMM workflows organized by phase:
|
||||
- **[Testing & QA Workflows](./test-architecture.md)** - Comprehensive quality assurance (1,420 lines)
|
||||
- Test strategy, automation, quality gates
|
||||
- TEA agent and test healing
|
||||
- BMad-integrated vs standalone modes
|
||||
|
||||
**Total: 34 workflows documented across all phases**
|
||||
|
||||
### Advanced Workflow References
|
||||
|
||||
For detailed technical documentation on specific complex workflows:
|
||||
|
||||
- **[Document Project Workflow Reference](./workflow-document-project-reference.md)** - Technical deep-dive (445 lines)
|
||||
- v1.2.0 context-safe architecture
|
||||
- Scan levels, resumability, write-as-you-go
|
||||
- Multi-part project detection
|
||||
- Deep-dive mode for targeted analysis
|
||||
|
||||
- **[Architecture Workflow Reference](./workflow-architecture-reference.md)** - Decision architecture guide (320 lines)
|
||||
- Starter template intelligence
|
||||
- Novel pattern design
|
||||
- Implementation patterns for agent consistency
|
||||
- Adaptive facilitation approach
|
||||
|
||||
## 🏗️ Module Structure
|
||||
|
||||
Understanding BMM components:
|
||||
|
||||
- **[BMM Module README](../README.md)** - Overview of module structure
|
||||
- Agent roster and roles
|
||||
- Workflow organization
|
||||
- Teams and collaboration
|
||||
- Best practices
|
||||
|
||||
## 🌐 External Resources
|
||||
|
||||
|
||||
@@ -2,13 +2,11 @@
|
||||
|
||||
**Get all your AI agents in one conversation**
|
||||
|
||||
---
|
||||
|
||||
## What is Party Mode?
|
||||
|
||||
Ever wanted to gather your entire AI team in one room and see what happens? That's party mode.
|
||||
|
||||
Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and suddenly you've got **all your AI agents** in one conversation. PM, Architect, DEV, UX Designer, the CIS creative agents - everyone shows up.
|
||||
Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent or at key workflow junctions when asked), and suddenly you've got **all your AI agents** in one conversation. PM, Architect, DEV, UX Designer and more that you can choose from.
|
||||
|
||||
**Why it's useful:**
|
||||
|
||||
@@ -19,8 +17,6 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and su
|
||||
- **Sprint retrospectives** - Party mode powers the retrospective workflow
|
||||
- **Sprint planning** - Multi-agent collaboration for planning sessions
|
||||
|
||||
**Future use:** Advanced elicitation workflows will leverage party mode for sophisticated requirement gathering.
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
@@ -46,6 +42,10 @@ Type `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent), and su
|
||||
# OR from any agent context
|
||||
*party-mode
|
||||
|
||||
# Super Hack
|
||||
|
||||
/bmad:core:workflows:party-mode and include also in the party Santa Clause and Einstein
|
||||
|
||||
# During party
|
||||
Ask questions, respond to agents, direct the conversation
|
||||
|
||||
@@ -103,116 +103,6 @@ _(Ideas cross-pollinate and evolve)_
|
||||
|
||||
_(Multiple perspectives reveal the right answer)_
|
||||
|
||||
---
|
||||
|
||||
## When NOT to Use Party Mode
|
||||
|
||||
**Skip party mode for:**
|
||||
|
||||
- Simple implementation questions → Use DEV agent
|
||||
- Document review → Use Technical Writer
|
||||
- Workflow status checks → Use any agent + `*workflow-status`
|
||||
- Single-domain questions → Use specialist agent
|
||||
|
||||
**Use party mode for:**
|
||||
|
||||
- Multi-perspective decisions
|
||||
- Creative collaboration
|
||||
- Post-mortems and retrospectives
|
||||
- Sprint planning sessions
|
||||
- Complex problem-solving
|
||||
|
||||
---
|
||||
|
||||
## Agent Customization
|
||||
|
||||
Party mode uses agents from `_bmad/[module]/agents/*.md` - these already include any customizations you applied during install.
|
||||
|
||||
**To customize agents for party mode:**
|
||||
|
||||
1. Create customization file: `_bmad/_config/agents/bmm-pm.customize.yaml`
|
||||
2. Run `npx bmad-method install` to rebuild agents
|
||||
3. Customizations now active in party mode
|
||||
|
||||
Example customization:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
persona:
|
||||
principles:
|
||||
- 'HIPAA compliance is non-negotiable'
|
||||
- 'Patient safety over feature velocity'
|
||||
```
|
||||
|
||||
See [Agents Guide](./agents-guide.md#agent-customization) for details.
|
||||
|
||||
---
|
||||
|
||||
## BMM Workflows That Use Party Mode
|
||||
|
||||
**Current:**
|
||||
|
||||
- `epic-retrospective` - Post-epic team retrospective powered by party mode
|
||||
- Sprint planning discussions (informal party mode usage)
|
||||
|
||||
**Future:**
|
||||
|
||||
- Advanced elicitation workflows will officially integrate party mode
|
||||
- Multi-agent requirement validation
|
||||
- Collaborative technical reviews
|
||||
|
||||
---
|
||||
|
||||
## Available Agents
|
||||
|
||||
Party mode can include **19+ agents** from all installed modules:
|
||||
|
||||
**BMM (12 agents):** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Technical Writer, Game Designer, Game Developer, Game Architect
|
||||
|
||||
**CIS (5 agents):** Brainstorming Coach, Creative Problem Solver, Design Thinking Coach, Innovation Strategist, Storyteller
|
||||
|
||||
**BMB (1 agent):** BMad Builder
|
||||
|
||||
**Core (1 agent):** BMad Master (orchestrator)
|
||||
|
||||
**Custom:** Any agents you've created
|
||||
|
||||
---
|
||||
|
||||
## Tips
|
||||
|
||||
**Get better results:**
|
||||
|
||||
- Be specific with your topic/question
|
||||
- Provide context (project type, constraints, goals)
|
||||
- Direct specific agents when you want their expertise
|
||||
- Make decisions - party mode informs, you decide
|
||||
- Time box discussions (15-30 minutes is usually plenty)
|
||||
|
||||
**Examples of good opening questions:**
|
||||
|
||||
- "We need to decide between REST and GraphQL for our mobile API. Project is a B2B SaaS with 50 enterprise clients."
|
||||
- "Our last sprint failed spectacularly. Let's discuss what went wrong with authentication implementation."
|
||||
- "Brainstorm: how can we make our game's tutorial feel rewarding instead of tedious?"
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Same agents responding every time?**
|
||||
Vary your questions or explicitly request other perspectives: "Game Designer, your thoughts?"
|
||||
|
||||
**Discussion going in circles?**
|
||||
BMad Master will summarize and redirect, or you can make a decision and move on.
|
||||
|
||||
**Too many agents talking?**
|
||||
Make your topic more specific - BMad Master picks 2-3 agents based on relevance.
|
||||
|
||||
**Agents not using customizations?**
|
||||
Make sure you ran `npx bmad-method install` after creating customization files.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Agents Guide](./agents-guide.md) - Complete agent reference
|
||||
|
||||
@@ -371,8 +371,6 @@ Checks:
|
||||
|
||||
**Total time:** 1-3 hours (mostly implementation)
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 4 Workflows
|
||||
|
||||
Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
|
||||
@@ -395,8 +393,6 @@ Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
|
||||
- ✅ Uses tech-spec.md as comprehensive context
|
||||
- ✅ Implements following detected conventions
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Quick Spec vs Full BMM
|
||||
|
||||
| Aspect | Quick Flow Track | BMad Method/Enterprise Tracks |
|
||||
@@ -411,7 +407,6 @@ Quick Spec Flow works seamlessly with all Phase 4 implementation workflows:
|
||||
| **Brownfield** | Auto-analyzes and conforms | Manual documentation required |
|
||||
| **Conventions** | Auto-detects and confirms | Document in PRD/Architecture |
|
||||
|
||||
---
|
||||
|
||||
## When to Graduate from Quick Flow to BMad Method
|
||||
|
||||
@@ -426,8 +421,6 @@ Start with Quick Flow, but switch to BMad Method when:
|
||||
|
||||
💡 **Tip:** You can always run `workflow-init` later to transition from Quick Flow to BMad Method!
|
||||
|
||||
---
|
||||
|
||||
## Quick Spec Flow - Key Benefits
|
||||
|
||||
### 🚀 **Speed**
|
||||
@@ -465,8 +458,6 @@ Start with Quick Flow, but switch to BMad Method when:
|
||||
- No scope creep
|
||||
- Fast iteration
|
||||
|
||||
---
|
||||
|
||||
## Getting Started
|
||||
|
||||
### Prerequisites
|
||||
@@ -478,12 +469,12 @@ Start with Quick Flow, but switch to BMad Method when:
|
||||
|
||||
```bash
|
||||
# For a quick bug fix or small change:
|
||||
# 1. Load PM agent
|
||||
# 1. Load Quick Dev Solo agent
|
||||
# 2. Say: "I want to [describe your change]"
|
||||
# 3. PM will ask if you want to run tech-spec
|
||||
# 3. Agent will ask if you want to run tech-spec
|
||||
# 4. Answer questions about your change
|
||||
# 5. Get tech-spec + story
|
||||
# 6. Load DEV agent and implement!
|
||||
# 6. Reload a fresh context with the solo agent and implement!
|
||||
|
||||
# For a small feature with multiple stories:
|
||||
# Same as above, but get epic + 2-3 stories
|
||||
@@ -492,14 +483,7 @@ Start with Quick Flow, but switch to BMad Method when:
|
||||
|
||||
### No workflow-init Required!
|
||||
|
||||
Quick Spec Flow is **fully standalone**:
|
||||
|
||||
- Detects if it's a single change or multi-story feature
|
||||
- Asks for greenfield vs brownfield
|
||||
- Works without status file tracking
|
||||
- Perfect for rapid prototyping
|
||||
|
||||
---
|
||||
Quick Spec Flow is **fully standalone**
|
||||
|
||||
## FAQ
|
||||
|
||||
|
||||
@@ -43,10 +43,7 @@ The interactive installer will guide you through setup and create a `_bmad/` fol
|
||||
|
||||
### Step 1: Initialize Your Workflow
|
||||
|
||||
1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for how to activate agents:
|
||||
- [Claude Code](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/ide-info/claude-code.md)
|
||||
- [VS Code/Cursor/Windsurf](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) - Check your IDE folder
|
||||
- Other IDEs also supported
|
||||
1. **Load the Analyst agent** in your IDE - Generally this is done by typing `/<workflow or agent name - allow autocomplete to find the right command>` - if you are unsure, you can just start with /bmad and see all that is available, sorted by agents and workflows.
|
||||
2. **Wait for the agent's menu** to appear
|
||||
3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
|
||||
|
||||
@@ -113,7 +110,7 @@ The next TRULY REQUIRED step is:
|
||||
|
||||
When an agent tells you to run a workflow (like `prd`):
|
||||
|
||||
1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for your IDE's specific instructions
|
||||
1. **Start a new chat** with the specified agent
|
||||
2. **Wait for the menu** to appear
|
||||
3. **Tell the agent** to run it using any of these formats:
|
||||
- Type the shorthand: `*prd`
|
||||
|
||||
@@ -1,618 +0,0 @@
|
||||
# BMad Method Scale Adaptive System
|
||||
|
||||
**Automatically adapts workflows to project complexity - from quick fixes to enterprise systems**
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The **Scale Adaptive System** intelligently routes projects to the right planning methodology based on complexity, not arbitrary story counts.
|
||||
|
||||
### The Problem
|
||||
|
||||
Traditional methodologies apply the same process to every project:
|
||||
|
||||
- Bug fix requires full design docs
|
||||
- Enterprise system built with minimal planning
|
||||
- One-size-fits-none approach
|
||||
|
||||
### The Solution
|
||||
|
||||
BMad Method adapts to three distinct planning tracks:
|
||||
|
||||
- **Quick Flow**: Tech-spec only, implement immediately
|
||||
- **BMad Method**: PRD + Architecture, structured approach
|
||||
- **Enterprise Method**: Full planning with security/devops/test
|
||||
|
||||
**Result**: Right planning depth for every project.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
### Three Tracks at a Glance
|
||||
|
||||
| Track | Planning Depth | Best For |
|
||||
| --------------------- | --------------------- | ------------------------------------------ |
|
||||
| **Quick Flow** | Tech-spec only | Simple features, bug fixes, clear scope |
|
||||
| **BMad Method** | PRD + Arch + UX | Products, platforms, complex features |
|
||||
| **Enterprise Method** | Method + Test/Sec/Ops | Enterprise needs, compliance, multi-tenant |
|
||||
|
||||
### Decision Tree
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START{Describe your project}
|
||||
|
||||
START -->|Bug fix, simple feature| Q1{Scope crystal clear?}
|
||||
START -->|Product, platform, complex| M[BMad Method<br/>PRD + Architecture]
|
||||
START -->|Enterprise, compliance| E[Enterprise Method<br/>Extended Planning]
|
||||
|
||||
Q1 -->|Yes| QF[Quick Flow<br/>Tech-spec only]
|
||||
Q1 -->|Uncertain| M
|
||||
|
||||
style QF fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
style M fill:#bbf,stroke:#333,stroke-width:2px,color:#000
|
||||
style E fill:#f9f,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
### Quick Keywords
|
||||
|
||||
- **Quick Flow**: fix, bug, simple, add, clear scope
|
||||
- **BMad Method**: product, platform, dashboard, complex, multiple features
|
||||
- **Enterprise Method**: enterprise, multi-tenant, compliance, security, audit
|
||||
|
||||
---
|
||||
|
||||
## How Track Selection Works
|
||||
|
||||
When you run `workflow-init`, it guides you through an educational choice:
|
||||
|
||||
### 1. Description Analysis
|
||||
|
||||
Analyzes your project description for complexity indicators and suggests an appropriate track.
|
||||
|
||||
### 2. Educational Presentation
|
||||
|
||||
Shows all three tracks with:
|
||||
|
||||
- Time investment
|
||||
- Planning approach
|
||||
- Benefits and trade-offs
|
||||
- AI agent support level
|
||||
- Concrete examples
|
||||
|
||||
### 3. Honest Recommendation
|
||||
|
||||
Provides tailored recommendation based on:
|
||||
|
||||
- Complexity keywords
|
||||
- Greenfield vs brownfield
|
||||
- User's description
|
||||
|
||||
### 4. User Choice
|
||||
|
||||
You choose the track that fits your situation. The system guides but never forces.
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
workflow-init: "Based on 'Add user dashboard with analytics', I recommend BMad Method.
|
||||
This involves multiple features and system design. The PRD + Architecture
|
||||
gives AI agents complete context for better code generation."
|
||||
|
||||
You: "Actually, this is simpler than it sounds. Quick Flow."
|
||||
|
||||
workflow-init: "Got it! Using Quick Flow with tech-spec."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Three Tracks
|
||||
|
||||
### Track 1: Quick Flow
|
||||
|
||||
**Definition**: Fast implementation with tech-spec planning.
|
||||
|
||||
**Time**: Hours to 1 day of planning
|
||||
|
||||
**Planning Docs**:
|
||||
|
||||
- Tech-spec.md (implementation-focused)
|
||||
- Story files (1-15 typically, auto-detects epic structure)
|
||||
|
||||
**Workflow Path**:
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
Tech-Spec → Implement
|
||||
```
|
||||
|
||||
**Use For**:
|
||||
|
||||
- Bug fixes
|
||||
- Simple features
|
||||
- Enhancements with clear scope
|
||||
- Quick additions
|
||||
|
||||
**Story Count**: Typically 1-15 stories (guidance, not rule)
|
||||
|
||||
**Example**: "Fix authentication token expiration bug"
|
||||
|
||||
**AI Agent Support**: Basic - minimal context provided
|
||||
|
||||
**Trade-off**: Less planning = higher rework risk if complexity emerges
|
||||
|
||||
---
|
||||
|
||||
### Track 2: BMad Method (RECOMMENDED)
|
||||
|
||||
**Definition**: Full product + system design planning.
|
||||
|
||||
**Time**: 1-3 days of planning
|
||||
|
||||
**Planning Docs**:
|
||||
|
||||
- PRD.md (functional and non-functional requirements)
|
||||
- Architecture.md (system design)
|
||||
- UX Design (if UI components)
|
||||
- Epics and Stories (created after architecture)
|
||||
|
||||
**Workflow Path**:
|
||||
|
||||
```
|
||||
(Brownfield: document-project first if needed)
|
||||
↓
|
||||
(Optional: Analysis phase - brainstorm, research, product brief)
|
||||
↓
|
||||
PRD → (Optional UX) → Architecture → Create Epics and Stories → Implementation Readiness Check → Implement
|
||||
```
|
||||
|
||||
**Complete Workflow Visualization**:
|
||||
|
||||
|
||||
|
||||
_Detailed flowchart showing all phases, workflows, agents (color-coded), and decision points for the BMad Method track. Each colored box represents a different agent role._
|
||||
|
||||
**Use For**:
|
||||
|
||||
**Greenfield**:
|
||||
|
||||
- Products
|
||||
- Platforms
|
||||
- Multi-feature initiatives
|
||||
|
||||
**Brownfield**:
|
||||
|
||||
- Complex additions (new UIs + APIs)
|
||||
- Major refactors
|
||||
- New modules
|
||||
|
||||
**Story Count**: Typically 10-50+ stories (guidance, not rule)
|
||||
|
||||
**Examples**:
|
||||
|
||||
- "User dashboard with analytics and preferences"
|
||||
- "Add real-time collaboration to existing document editor"
|
||||
- "Payment integration system"
|
||||
|
||||
**AI Agent Support**: Exceptional - complete context for coding partnership
|
||||
|
||||
**Why Architecture for Brownfield?**
|
||||
|
||||
Your brownfield documentation might be huge. Architecture workflow distills massive codebase context into a focused solution design specific to YOUR project. This keeps AI agents focused without getting lost in existing code.
|
||||
|
||||
**Benefits**:
|
||||
|
||||
- Complete AI agent context
|
||||
- Prevents architectural drift
|
||||
- Fewer surprises during implementation
|
||||
- Better code quality
|
||||
- Faster overall delivery (planning pays off)
|
||||
|
||||
---
|
||||
|
||||
### Track 3: Enterprise Method
|
||||
|
||||
**Definition**: Extended planning with security, devops, and test strategy.
|
||||
|
||||
**Time**: 3-7 days of planning
|
||||
|
||||
**Planning Docs**:
|
||||
|
||||
- All BMad Method docs PLUS:
|
||||
- Security Architecture
|
||||
- DevOps Strategy
|
||||
- Test Strategy
|
||||
- Compliance documentation
|
||||
|
||||
**Workflow Path**:
|
||||
|
||||
```
|
||||
(Brownfield: document-project nearly mandatory)
|
||||
↓
|
||||
Analysis (recommended/required) → PRD → UX → Architecture
|
||||
↓
|
||||
Create Epics and Stories
|
||||
↓
|
||||
Security Architecture → DevOps Strategy → Test Strategy
|
||||
↓
|
||||
Implementation Readiness Check → Implement
|
||||
```
|
||||
|
||||
**Use For**:
|
||||
|
||||
- Enterprise requirements
|
||||
- Multi-tenant systems
|
||||
- Compliance needs (HIPAA, SOC2, etc.)
|
||||
- Mission-critical systems
|
||||
- Security-sensitive applications
|
||||
|
||||
**Story Count**: Typically 30+ stories (but defined by enterprise needs, not count)
|
||||
|
||||
**Examples**:
|
||||
|
||||
- "Multi-tenant SaaS platform"
|
||||
- "HIPAA-compliant patient portal"
|
||||
- "Add SOC2 audit logging to enterprise app"
|
||||
|
||||
**AI Agent Support**: Elite - comprehensive enterprise planning
|
||||
|
||||
**Critical for Enterprise**:
|
||||
|
||||
- Security architecture and threat modeling
|
||||
- DevOps pipeline planning
|
||||
- Comprehensive test strategy
|
||||
- Risk assessment
|
||||
- Compliance mapping
|
||||
|
||||
---
|
||||
|
||||
## Planning Documents by Track
|
||||
|
||||
### Quick Flow Documents
|
||||
|
||||
**Created**: Upfront in Planning Phase
|
||||
|
||||
**Tech-Spec**:
|
||||
|
||||
- Problem statement and solution
|
||||
- Source tree changes
|
||||
- Technical implementation details
|
||||
- Detected stack and conventions (brownfield)
|
||||
- UX/UI considerations (if user-facing)
|
||||
- Testing strategy
|
||||
|
||||
**Serves as**: Complete planning document (replaces PRD + Architecture)
|
||||
|
||||
---
|
||||
|
||||
### BMad Method Documents
|
||||
|
||||
**Created**: Upfront in Planning and Solutioning Phases
|
||||
|
||||
**PRD (Product Requirements Document)**:
|
||||
|
||||
- Product vision and goals
|
||||
- Functional requirements (FRs)
|
||||
- Non-functional requirements (NFRs)
|
||||
- Success criteria
|
||||
- User experience considerations
|
||||
- Business context
|
||||
|
||||
**Note**: Epics and stories are created AFTER architecture in the create-epics-and-stories workflow
|
||||
|
||||
**Architecture Document**:
|
||||
|
||||
- System components and responsibilities
|
||||
- Data models and schemas
|
||||
- Integration patterns
|
||||
- Security architecture
|
||||
- Performance considerations
|
||||
- Deployment architecture
|
||||
|
||||
**For Brownfield**: Acts as focused "solution design" that distills existing codebase into integration plan
|
||||
|
||||
---
|
||||
|
||||
### Enterprise Method Documents
|
||||
|
||||
**Created**: Extended planning across multiple phases
|
||||
|
||||
Includes all BMad Method documents PLUS:
|
||||
|
||||
**Security Architecture**:
|
||||
|
||||
- Threat modeling
|
||||
- Authentication/authorization design
|
||||
- Data protection strategy
|
||||
- Audit requirements
|
||||
|
||||
**DevOps Strategy**:
|
||||
|
||||
- CI/CD pipeline design
|
||||
- Infrastructure architecture
|
||||
- Monitoring and alerting
|
||||
- Disaster recovery
|
||||
|
||||
**Test Strategy**:
|
||||
|
||||
- Test approach and coverage
|
||||
- Automation strategy
|
||||
- Quality gates
|
||||
- Performance testing
|
||||
|
||||
---
|
||||
|
||||
## Workflow Comparison
|
||||
|
||||
| Track | Analysis | Planning | Architecture | Security/Ops | Typical Stories |
|
||||
| --------------- | ----------- | --------- | ------------ | ------------ | --------------- |
|
||||
| **Quick Flow** | Optional | Tech-spec | None | None | 1-15 |
|
||||
| **BMad Method** | Recommended | PRD + UX | Required | None | 10-50+ |
|
||||
| **Enterprise** | Required | PRD + UX | Required | Required | 30+ |
|
||||
|
||||
**Note**: Story counts are GUIDANCE based on typical usage, NOT definitions of tracks.
|
||||
|
||||
---
|
||||
|
||||
## Brownfield Projects
|
||||
|
||||
### Critical First Step
|
||||
|
||||
For ALL brownfield projects: Run `document-project` BEFORE planning workflows.
|
||||
|
||||
### Why document-project is Critical
|
||||
|
||||
**Quick Flow** uses it for:
|
||||
|
||||
- Auto-detecting existing patterns
|
||||
- Understanding codebase structure
|
||||
- Confirming conventions
|
||||
|
||||
**BMad Method** uses it for:
|
||||
|
||||
- Architecture inputs (existing structure)
|
||||
- Integration design
|
||||
- Pattern consistency
|
||||
|
||||
**Enterprise Method** uses it for:
|
||||
|
||||
- Security analysis
|
||||
- Integration architecture
|
||||
- Risk assessment
|
||||
|
||||
### Brownfield Workflow Pattern
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START([Brownfield Project])
|
||||
CHECK{Has docs/<br/>index.md?}
|
||||
|
||||
START --> CHECK
|
||||
CHECK -->|No| DOC[document-project workflow<br/>10-30 min]
|
||||
CHECK -->|Yes| TRACK[Choose Track]
|
||||
|
||||
DOC --> TRACK
|
||||
TRACK -->|Quick| QF[Tech-Spec]
|
||||
TRACK -->|Method| M[PRD + Arch]
|
||||
TRACK -->|Enterprise| E[PRD + Arch + Sec/Ops]
|
||||
|
||||
style DOC fill:#ffb,stroke:#333,stroke-width:2px,color:#000
|
||||
style TRACK fill:#bfb,stroke:#333,stroke-width:2px,color:#000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Scenarios
|
||||
|
||||
### Scenario 1: Bug Fix (Quick Flow)
|
||||
|
||||
**Input**: "Fix email validation bug in login form"
|
||||
|
||||
**Detection**: Keywords "fix", "bug"
|
||||
|
||||
**Track**: Quick Flow
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. (Optional) Brief analysis
|
||||
2. Tech-spec with single story
|
||||
3. Implement immediately
|
||||
|
||||
**Time**: 2-4 hours total
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: Small Feature (Quick Flow)
|
||||
|
||||
**Input**: "Add OAuth social login (Google, GitHub, Facebook)"
|
||||
|
||||
**Detection**: Keywords "add", "feature", clear scope
|
||||
|
||||
**Track**: Quick Flow
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. (Optional) Research OAuth providers
|
||||
2. Tech-spec with 3 stories
|
||||
3. Implement story-by-story
|
||||
|
||||
**Time**: 1-3 days
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Customer Portal (BMad Method)
|
||||
|
||||
**Input**: "Build customer portal with dashboard, tickets, billing"
|
||||
|
||||
**Detection**: Keywords "portal", "dashboard", multiple features
|
||||
|
||||
**Track**: BMad Method
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. (Recommended) Product Brief
|
||||
2. PRD (FRs/NFRs)
|
||||
3. (If UI) UX Design
|
||||
4. Architecture (system design)
|
||||
5. Create Epics and Stories
|
||||
6. Implementation Readiness Check
|
||||
7. Implement with sprint planning
|
||||
|
||||
**Time**: 1-2 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: E-commerce Platform (BMad Method)
|
||||
|
||||
**Input**: "Build e-commerce platform with products, cart, checkout, admin, analytics"
|
||||
|
||||
**Detection**: Keywords "platform", multiple subsystems
|
||||
|
||||
**Track**: BMad Method
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Research + Product Brief
|
||||
2. Comprehensive PRD (FRs/NFRs)
|
||||
3. UX Design (recommended)
|
||||
4. System Architecture (required)
|
||||
5. Create Epics and Stories
|
||||
6. Implementation Readiness Check
|
||||
7. Implement with phased approach
|
||||
|
||||
**Time**: 3-6 weeks
|
||||
|
||||
---
|
||||
|
||||
### Scenario 5: Brownfield Addition (BMad Method)
|
||||
|
||||
**Input**: "Add search functionality to existing product catalog"
|
||||
|
||||
**Detection**: Brownfield + moderate complexity
|
||||
|
||||
**Track**: BMad Method (not Quick Flow)
|
||||
|
||||
**Critical First Step**:
|
||||
|
||||
1. **Run document-project** to analyze existing codebase
|
||||
|
||||
**Then Workflow**:
|
||||
|
||||
2. PRD for search feature (FRs/NFRs)
|
||||
3. Architecture (integration design - highly recommended)
|
||||
4. Create Epics and Stories
|
||||
5. Implementation Readiness Check
|
||||
6. Implement following existing patterns
|
||||
|
||||
**Time**: 1-2 weeks
|
||||
|
||||
**Why Method not Quick Flow?**: Integration with existing catalog system benefits from architecture planning to ensure consistency.
|
||||
|
||||
---
|
||||
|
||||
### Scenario 6: Multi-tenant Platform (Enterprise Method)
|
||||
|
||||
**Input**: "Add multi-tenancy to existing single-tenant SaaS platform"
|
||||
|
||||
**Detection**: Keywords "multi-tenant", enterprise scale
|
||||
|
||||
**Track**: Enterprise Method
|
||||
|
||||
**Workflow**:
|
||||
|
||||
1. Document-project (mandatory)
|
||||
2. Research (compliance, security)
|
||||
3. PRD (multi-tenancy requirements - FRs/NFRs)
|
||||
4. Architecture (tenant isolation design)
|
||||
5. Create Epics and Stories
|
||||
6. Security Architecture (data isolation, auth)
|
||||
7. DevOps Strategy (tenant provisioning, monitoring)
|
||||
8. Test Strategy (tenant isolation testing)
|
||||
9. Implementation Readiness Check
|
||||
10. Phased implementation
|
||||
|
||||
**Time**: 3-6 months
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Document-Project First for Brownfield
|
||||
|
||||
Always run `document-project` before starting brownfield planning. AI agents need existing codebase context.
|
||||
|
||||
### 2. Trust the Recommendation
|
||||
|
||||
If `workflow-init` suggests BMad Method, there's probably complexity you haven't considered. Review carefully before overriding.
|
||||
|
||||
### 3. Start Smaller if Uncertain
|
||||
|
||||
Uncertain between Quick Flow and Method? Start with Quick Flow. You can create PRD later if needed.
|
||||
|
||||
### 4. Don't Skip Implementation Readiness Check
|
||||
|
||||
For BMad Method and Enterprise, implementation readiness checks prevent costly mistakes. Invest the time.
|
||||
|
||||
### 5. Architecture is Optional but Recommended for Brownfield
|
||||
|
||||
Brownfield BMad Method makes architecture optional, but it's highly recommended. It distills complex codebase into focused solution design.
|
||||
|
||||
### 6. Discovery Phase Based on Need
|
||||
|
||||
Brainstorming and research are offered regardless of track. Use them when you need to think through the problem space.
|
||||
|
||||
### 7. Product Brief for Greenfield Method
|
||||
|
||||
Product Brief is only offered for greenfield BMad Method and Enterprise. It's optional but helps with strategic thinking.
|
||||
|
||||
---
|
||||
|
||||
## Key Differences from Legacy System
|
||||
|
||||
### Old System (Levels 0-4)
|
||||
|
||||
- Arbitrary story count thresholds
|
||||
- Level 2 vs Level 3 based on story count
|
||||
- Confusing overlap zones (5-10 stories, 12-40 stories)
|
||||
- Tech-spec and PRD shown as conflicting options
|
||||
|
||||
### New System (3 Tracks)
|
||||
|
||||
- Methodology-based distinction (not story counts)
|
||||
- Story counts as guidance, not definitions
|
||||
- Clear track purposes:
|
||||
- Quick Flow = Implementation-focused
|
||||
- BMad Method = Product + system design
|
||||
- Enterprise = Extended with security/ops
|
||||
- Mutually exclusive paths chosen upfront
|
||||
- Educational decision-making
|
||||
|
||||
---
|
||||
|
||||
## Migration from Old System
|
||||
|
||||
If you have existing projects using the old level system:
|
||||
|
||||
- **Level 0-1** → Quick Flow
|
||||
- **Level 2-3** → BMad Method
|
||||
- **Level 4** → Enterprise Method
|
||||
|
||||
Run `workflow-init` on existing projects to migrate to new tracking system. It detects existing planning artifacts and creates appropriate workflow tracking.
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- **[Quick Start Guide](./quick-start.md)** - Get started with BMM
|
||||
- **[Quick Spec Flow](./quick-spec-flow.md)** - Details on Quick Flow track
|
||||
- **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
|
||||
- **[Glossary](./glossary.md)** - Complete terminology
|
||||
- **[FAQ](./faq.md)** - Common questions
|
||||
- **[Workflows Guide](./index.md#-workflow-guides)** - Complete workflow reference
|
||||
|
||||
---
|
||||
|
||||
_Scale Adaptive System - Right planning depth for every project._
|
||||
@@ -1,7 +1,3 @@
|
||||
---
|
||||
last-redoc-date: 2025-11-05
|
||||
---
|
||||
|
||||
# Test Architect (TEA) Agent Guide
|
||||
|
||||
## Overview
|
||||
@@ -259,17 +255,17 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
|
||||
- 🔄 Phase 4: `*test-design` - Focus on regression hotspots and brownfield risks
|
||||
- 🔄 Phase 4: Story Review - May include `*nfr-assess` if not done earlier
|
||||
|
||||
| Workflow Stage | Test Architect | Dev / Team | Outputs |
|
||||
| ---------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| **Documentation**: Prerequisite ➕ | - | Analyst `*document-project` (if undocumented) | Comprehensive project documentation |
|
||||
| **Phase 1**: Discovery | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
|
||||
| **Phase 2**: Planning | Run ➕ `*trace` (baseline coverage) | PM `*prd` (creates PRD with FRs/NFRs) | PRD with FRs/NFRs, ➕ coverage baseline |
|
||||
| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline |
|
||||
| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories |
|
||||
| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (regression hotspots) | Review epic scope and brownfield risks | `test-design-epic-N.md` with brownfield risk assessment and mitigation |
|
||||
| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation |
|
||||
| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report |
|
||||
| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, share release notes | Quality audit, Gate YAML + release summary |
|
||||
| Workflow Stage | Test Architect | Dev / Team | Outputs |
|
||||
| --------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
|
||||
| **Documentation**: Prerequisite ➕ | - | Analyst `*document-project` (if undocumented) | Comprehensive project documentation |
|
||||
| **Phase 1**: Discovery | - | Analyst/PM/Architect rerun planning workflows | Updated planning artifacts in `{output_folder}` |
|
||||
| **Phase 2**: Planning | Run ➕ `*trace` (baseline coverage) | PM `*prd` (creates PRD with FRs/NFRs) | PRD with FRs/NFRs, ➕ coverage baseline |
|
||||
| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline |
|
||||
| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint status file with all epics and stories |
|
||||
| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (regression hotspots) | Review epic scope and brownfield risks | `test-design-epic-N.md` with brownfield risk assessment and mitigation |
|
||||
| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation |
|
||||
| **Phase 4**: Story Review | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests | Quality report, refreshed coverage matrix, NFR report |
|
||||
| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, share release notes | Quality audit, Gate YAML + release summary |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
@@ -309,15 +305,15 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
|
||||
- 🔄 Phase 4: `*test-design` - Enterprise focus (compliance, security architecture alignment)
|
||||
- 📦 Release Gate - Archive artifacts and compliance evidence for audits
|
||||
|
||||
| Workflow Stage | Test Architect | Dev / Team | Outputs |
|
||||
| -------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| **Phase 1**: Discovery | - | Analyst ➕ `*research`, `*product-brief` | Domain research, compliance analysis, product brief |
|
||||
| **Phase 2**: Planning | Run ➕ `*nfr-assess` | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design` | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation |
|
||||
| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline |
|
||||
| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint plan with all epics |
|
||||
| Workflow Stage | Test Architect | Dev / Team | Outputs |
|
||||
| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| **Phase 1**: Discovery | - | Analyst ➕ `*research`, `*product-brief` | Domain research, compliance analysis, product brief |
|
||||
| **Phase 2**: Planning | Run ➕ `*nfr-assess` | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design` | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation |
|
||||
| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture and epic creation | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline |
|
||||
| **Phase 4**: Sprint Start | - | SM `*sprint-planning` | Sprint plan with all epics |
|
||||
| **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (compliance focus) | Review epic scope and compliance requirements | `test-design-epic-N.md` with security/performance/compliance focus |
|
||||
| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices |
|
||||
| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | Quality audit, updated assessments, gate YAML, 📦 audit trail |
|
||||
| **Phase 4**: Story Dev | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story | SM `*create-story`, DEV implements | Tests, fixtures, quality reports, coverage matrices |
|
||||
| **Phase 4**: Release Gate | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence | Quality audit, updated assessments, gate YAML, 📦 audit trail |
|
||||
|
||||
<details>
|
||||
<summary>Execution Notes</summary>
|
||||
|
||||
@@ -1,661 +1,3 @@
|
||||
# BMM Troubleshooting Guide
|
||||
|
||||
Common issues and solutions for the BMad Method Module.
|
||||
|
||||
---
|
||||
|
||||
## Quick Diagnosis
|
||||
|
||||
**Use this flowchart to find your issue:**
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
START{What's the problem?}
|
||||
|
||||
START -->|Can't get started| SETUP[Setup & Installation Issues]
|
||||
START -->|Wrong level detected| LEVEL[Level Detection Problems]
|
||||
START -->|Workflow not working| WORKFLOW[Workflow Issues]
|
||||
START -->|Agent lacks context| CONTEXT[Context & Documentation Issues]
|
||||
START -->|Implementation problems| IMPL[Implementation Issues]
|
||||
START -->|Files/paths wrong| FILES[File & Path Issues]
|
||||
|
||||
style START fill:#ffb,stroke:#333,stroke-width:2px
|
||||
style SETUP fill:#bfb,stroke:#333,stroke-width:2px
|
||||
style LEVEL fill:#bbf,stroke:#333,stroke-width:2px
|
||||
style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px
|
||||
style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Setup and Installation Issues](#setup-and-installation-issues)
|
||||
- [Level Detection Problems](#level-detection-problems)
|
||||
- [Workflow Issues](#workflow-issues)
|
||||
- [Context and Documentation Issues](#context-and-documentation-issues)
|
||||
- [Implementation Issues](#implementation-issues)
|
||||
- [File and Path Issues](#file-and-path-issues)
|
||||
- [Agent Behavior Issues](#agent-behavior-issues)
|
||||
- [Integration Issues (Brownfield)](#integration-issues-brownfield)
|
||||
|
||||
---
|
||||
|
||||
## Setup and Installation Issues
|
||||
|
||||
### Problem: BMM not found after installation
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- `bmad` command not recognized
|
||||
- Agent files not accessible
|
||||
- Workflows don't load
|
||||
|
||||
**Solution:**
|
||||
|
||||
```bash
|
||||
# Check if BMM is installed
|
||||
ls bmad/
|
||||
|
||||
# If not present, run installer
|
||||
npx bmad-method@alpha install
|
||||
|
||||
# For fresh install
|
||||
npx bmad-method@alpha install --skip-version-prompt
|
||||
```
|
||||
|
||||
### Problem: Agents don't have menu
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Load agent file but no menu appears
|
||||
- Agent doesn't respond to commands
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md`
|
||||
2. Wait a few seconds for agent to initialize
|
||||
3. Try asking "show menu" or "help"
|
||||
4. Check IDE supports Markdown rendering with context
|
||||
5. For Claude Code: Ensure agent file is open in chat context
|
||||
|
||||
### Problem: Workflows not found
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Agent says workflow doesn't exist
|
||||
- Menu shows workflow but won't run
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check workflow exists: `ls bmad/bmm/workflows/`
|
||||
2. Verify agent has access to workflow (check agent's workflow list)
|
||||
3. Try using menu number instead of workflow name
|
||||
4. Restart chat with agent in fresh session
|
||||
|
||||
---
|
||||
|
||||
## Level Detection Problems
|
||||
|
||||
### Problem: workflow-init suggests wrong level
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Detects Level 3 but you only need Level 1
|
||||
- Suggests Level 1 but project is actually Level 2
|
||||
- Can't figure out appropriate level
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level
|
||||
2. **Be specific in description** - Use level keywords when describing:
|
||||
- "fix bug" → Level 0
|
||||
- "add small feature" → Level 1
|
||||
- "build dashboard" → Level 2
|
||||
3. **Manual override** - You can always switch levels later if needed
|
||||
|
||||
**Example:**
|
||||
|
||||
```
|
||||
workflow-init: "Level 3 project?"
|
||||
You: "No, this is just adding OAuth login - Level 1"
|
||||
workflow-init: "Got it, creating Level 1 workflow"
|
||||
```
|
||||
|
||||
### Problem: Project level unclear
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Between Level 1 and Level 2
|
||||
- Not sure if architecture needed
|
||||
- Story count uncertain
|
||||
|
||||
**Solution:**
|
||||
**When in doubt, start smaller:**
|
||||
|
||||
- Choose Level 1 instead of Level 2
|
||||
- You can always run `create-prd` later if needed
|
||||
- Level 1 is faster, less overhead
|
||||
- Easy to upgrade, hard to downgrade
|
||||
|
||||
**Decision criteria:**
|
||||
|
||||
- Single epic with related stories? → Level 1
|
||||
- Multiple independent epics? → Level 2
|
||||
- Need product-level planning? → Level 2
|
||||
- Just need technical plan? → Level 1
|
||||
|
||||
### Problem: Old planning docs influencing level detection
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Old Level 3 PRD in folder
|
||||
- Working on new Level 0 bug fix
|
||||
- workflow-init suggests Level 3
|
||||
|
||||
**Solution:**
|
||||
workflow-init asks: "Is this work in progress or previous effort?"
|
||||
|
||||
- Answer: "Previous effort"
|
||||
- Then describe your NEW work clearly
|
||||
- System will detect level based on NEW work, not old artifacts
|
||||
|
||||
---
|
||||
|
||||
## Workflow Issues
|
||||
|
||||
### Problem: Workflow fails or hangs
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Workflow starts but doesn't complete
|
||||
- Agent stops responding mid-workflow
|
||||
- Progress stalls
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check context limits** - Start fresh chat for complex workflows
|
||||
2. **Verify prerequisites**:
|
||||
- Phase 2 needs Phase 1 complete (if used)
|
||||
- Phase 3 needs Phase 2 complete
|
||||
- Phase 4 needs Phase 3 complete (if Level 3-4)
|
||||
3. **Restart workflow** - Load agent in new chat and restart
|
||||
4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid
|
||||
|
||||
### Problem: Agent says "workflow not found"
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Request workflow by name
|
||||
- Agent doesn't recognize it
|
||||
- Menu doesn't show workflow
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Check spelling/format - Use exact workflow name or menu shortcut (`*prd` not `*PRD`)
|
||||
2. Verify agent has workflow:
|
||||
- PM agent: prd, tech-spec
|
||||
- Architect agent: create-architecture, validate-architecture
|
||||
- SM agent: sprint-planning, create-story
|
||||
3. Try menu number instead of name
|
||||
4. Check you're using correct agent for workflow
|
||||
|
||||
### Problem: Sprint-planning workflow fails
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Can't create sprint-status.yaml
|
||||
- Epics not extracted from files
|
||||
- Status file empty or incorrect
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Verify epic files exist**:
|
||||
- Level 1: tech-spec with epic
|
||||
- Level 2-4: epics.md or sharded epic files
|
||||
2. **Check file format**:
|
||||
- Epic files should be valid Markdown
|
||||
- Epic headers should be clear (## Epic Name)
|
||||
3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first
|
||||
4. **Check file paths** - Epic files should be in correct output folder
|
||||
|
||||
---
|
||||
|
||||
## Context and Documentation Issues
|
||||
|
||||
### Problem: AI agents lack codebase understanding (Brownfield)
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Suggestions don't align with existing patterns
|
||||
- Ignores available components
|
||||
- Proposes approaches that conflict with architecture
|
||||
- Doesn't reference existing code
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Run document-project** - Critical for brownfield projects
|
||||
```
|
||||
Load Analyst agent → run document-project
|
||||
Choose scan level: Deep (recommended for PRD prep)
|
||||
```
|
||||
2. **Verify docs/index.md exists** - This is master entry point for AI agents
|
||||
3. **Check documentation completeness**:
|
||||
- Review generated docs/index.md
|
||||
- Ensure key systems are documented
|
||||
4. **Run deep-dive on specific areas** if needed
|
||||
|
||||
### Problem: Have documentation but agents can't find it
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- README.md, ARCHITECTURE.md exist
|
||||
- AI agents still ask questions answered in docs
|
||||
- No docs/index.md file
|
||||
|
||||
**Solution:**
|
||||
**Option 1: Quick fix (2-5min)**
|
||||
Run `index-docs` task:
|
||||
|
||||
- Located at `bmad/core/tasks/index-docs.xml`
|
||||
- Scans existing docs and generates index.md
|
||||
- Lightweight, just creates navigation
|
||||
|
||||
**Option 2: Comprehensive (10-30min)**
|
||||
Run document-project workflow:
|
||||
|
||||
- Discovers existing docs in Step 2
|
||||
- Generates NEW AI-friendly documentation from codebase
|
||||
- Creates index.md linking to BOTH existing and new docs
|
||||
|
||||
**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently.
|
||||
|
||||
### Problem: document-project takes too long
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Exhaustive scan running for hours
|
||||
- Impatient to start planning
|
||||
|
||||
**Solution:**
|
||||
**Choose appropriate scan level:**
|
||||
|
||||
- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview
|
||||
- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects**
|
||||
- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding
|
||||
|
||||
For most brownfield projects, **Deep scan is sufficient**.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Issues
|
||||
|
||||
### Problem: Existing tests breaking (Brownfield)
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Regression test failures
|
||||
- Previously working functionality broken
|
||||
- Integration tests failing
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Review changes against existing patterns**:
|
||||
- Check if new code follows existing conventions
|
||||
- Verify API contracts unchanged (unless intentionally versioned)
|
||||
2. **Run test-review workflow** (TEA agent):
|
||||
- Analyzes test coverage
|
||||
- Identifies regression risks
|
||||
- Suggests fixes
|
||||
3. **Add regression testing to DoD**:
|
||||
- All existing tests must pass
|
||||
- Add integration tests for new code
|
||||
4. **Consider feature flags** for gradual rollout
|
||||
|
||||
### Problem: Story takes much longer than estimated
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Story estimated 4 hours, took 12 hours
|
||||
- Acceptance criteria harder than expected
|
||||
- Hidden complexity discovered
|
||||
|
||||
**Solution:**
|
||||
**This is normal!** Estimates are estimates. To handle:
|
||||
|
||||
1. **Continue until DoD met** - Don't compromise quality
|
||||
2. **Document learnings in retrospective**:
|
||||
- What caused the overrun?
|
||||
- What should we watch for next time?
|
||||
3. **Consider splitting story** if it's truly two stories
|
||||
4. **Adjust future estimates** based on this data
|
||||
|
||||
**Don't stress about estimate accuracy** - use them for learning, not judgment.
|
||||
|
||||
### Problem: Integration points unclear
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Not sure how to connect new code to existing
|
||||
- Unsure which files to modify
|
||||
- Multiple possible integration approaches
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **For brownfield**:
|
||||
- Ensure document-project captured existing architecture
|
||||
- Review architecture docs before implementing
|
||||
2. **Check story file** - Should document integration points
|
||||
3. **In tech-spec/architecture** - Explicitly document:
|
||||
- Which existing modules to modify
|
||||
- What APIs/services to integrate with
|
||||
- Data flow between new and existing code
|
||||
4. **Run integration-planning workflow** (Level 3-4):
|
||||
- Architect agent creates integration strategy
|
||||
|
||||
### Problem: Inconsistent patterns being introduced
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- New code style doesn't match existing
|
||||
- Different architectural approach
|
||||
- Not following team conventions
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check convention detection** (Quick Spec Flow):
|
||||
- Should detect existing patterns
|
||||
- Asks for confirmation before proceeding
|
||||
2. **Review documentation** - Ensure document-project captured patterns
|
||||
3. **Use comprehensive story files** - Include pattern guidance in story
|
||||
4. **Add to code-review checklist**:
|
||||
- Pattern adherence
|
||||
- Convention consistency
|
||||
- Style matching
|
||||
5. **Run retrospective** to identify pattern deviations early
|
||||
|
||||
---
|
||||
|
||||
## File and Path Issues
|
||||
|
||||
### Problem: Output files in wrong location
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- PRD created in wrong folder
|
||||
- Story files not where expected
|
||||
- Documentation scattered
|
||||
|
||||
**Solution:**
|
||||
Check `bmad/bmm/config.yaml` for configured paths:
|
||||
|
||||
```yaml
|
||||
output_folder: '{project-root}/docs'
|
||||
dev_story_location: '{project-root}/docs/stories'
|
||||
```
|
||||
|
||||
Default locations:
|
||||
|
||||
- Planning docs (PRD, epics, architecture): `{output_folder}/`
|
||||
- Stories: `{dev_story_location}/`
|
||||
- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml`
|
||||
|
||||
To change locations, edit config.yaml then re-run workflows.
|
||||
|
||||
### Problem: Can't find status file
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- workflow-status says no status file
|
||||
- Can't track progress
|
||||
- Lost place in workflow
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check default location**: `docs/bmm-workflow-status.md`
|
||||
2. **If missing, reinitialize**:
|
||||
```
|
||||
Load Analyst agent → run workflow-init
|
||||
```
|
||||
3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD
|
||||
4. **Search for it**:
|
||||
```bash
|
||||
find . -name "bmm-workflow-status.md"
|
||||
find . -name "sprint-status.yaml"
|
||||
```
|
||||
|
||||
### Problem: Sprint-status.yaml not updating
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Workflows complete but status unchanged
|
||||
- Stories stuck in old status
|
||||
- Epic status not progressing
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Manual update required** - Most status changes are manual:
|
||||
```yaml
|
||||
stories:
|
||||
- id: epic-1-story-1
|
||||
status: done # Change this manually
|
||||
```
|
||||
2. **Some workflows auto-update**:
|
||||
- sprint-planning creates file
|
||||
- create-story changes story to "ready-for-dev"
|
||||
- dev-story may auto-update (check workflow)
|
||||
3. **Re-run sprint-planning** to resync if needed
|
||||
|
||||
---
|
||||
|
||||
## Agent Behavior Issues
|
||||
|
||||
### Problem: Agent provides vague or generic responses
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- "Use appropriate framework"
|
||||
- "Follow best practices"
|
||||
- Generic advice without specifics
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Provide more context** - Be specific in your description:
|
||||
- "Add OAuth using passport.js to Express server"
|
||||
- Not: "Add authentication"
|
||||
2. **For brownfield**:
|
||||
- Ensure document-project was run
|
||||
- Agent needs codebase context for specific advice
|
||||
3. **Reference existing docs**:
|
||||
- "Based on the existing auth system in UserService..."
|
||||
4. **Start fresh chat** - Context overload can cause generic responses
|
||||
|
||||
### Problem: Agent hallucinating or making up information
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- References files that don't exist
|
||||
- Suggests APIs that aren't in your stack
|
||||
- Creates imaginary requirements
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Use fresh chat** - Context overflow main cause of hallucinations
|
||||
2. **Provide concrete constraints**:
|
||||
- "We use Express 4.18.2, not Next.js"
|
||||
- "Our database is PostgreSQL, not MongoDB"
|
||||
3. **For brownfield**:
|
||||
- Document-project provides factual grounding
|
||||
- Agent sees actual code, not assumptions
|
||||
4. **Correct immediately**:
|
||||
- "No, we don't have UserService, we have AuthenticationModule"
|
||||
|
||||
### Problem: Agent won't follow instructions
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Ignores specific requests
|
||||
- Does something different than asked
|
||||
- Doesn't respect constraints
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Be more explicit** - Agents respond to clear, specific instructions:
|
||||
- "Use EXACTLY these three steps..."
|
||||
- "Do NOT include database migrations in this story"
|
||||
2. **Check agent capabilities** - Agent might not have access to requested workflow
|
||||
3. **Try different phrasing** - Rephrase request to be more direct
|
||||
4. **Use menu system** - Numbers are clearer than text commands
|
||||
|
||||
---
|
||||
|
||||
## Integration Issues (Brownfield)
|
||||
|
||||
### Problem: New code conflicts with existing architecture
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Integration approach doesn't fit existing structure
|
||||
- Would require major refactoring
|
||||
- Conflicts with established patterns
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Check if document-project was run** - Agents need architecture context
|
||||
2. **Review existing architecture docs**:
|
||||
- Read docs/architecture.md (from document-project)
|
||||
- Understand current system design
|
||||
3. **For Level 3-4**:
|
||||
- Run validate-architecture workflow before planning
|
||||
- Use integration-planning workflow
|
||||
4. **Explicitly document integration strategy** in architecture:
|
||||
- How new components fit existing structure
|
||||
- What modifications needed to existing code
|
||||
- Migration path if changing patterns
|
||||
|
||||
### Problem: Breaking changes to existing APIs
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Changing API breaks consumers
|
||||
- Downstream services affected
|
||||
- Need backward compatibility
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Identify all API consumers** (document-project should show this)
|
||||
2. **Plan versioning strategy**:
|
||||
- API v1 (existing) + v2 (new)
|
||||
- Deprecation timeline
|
||||
3. **Use feature flags** for gradual rollout
|
||||
4. **Document migration guide** for API consumers
|
||||
5. **Add to testing strategy**:
|
||||
- Existing consumers still work (v1)
|
||||
- New functionality works (v2)
|
||||
|
||||
### Problem: Data migration required
|
||||
|
||||
**Symptoms:**
|
||||
|
||||
- Schema changes needed
|
||||
- Existing data needs transformation
|
||||
- Risk of data loss
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. **Create explicit migration strategy** in architecture:
|
||||
- Forward migration (old → new schema)
|
||||
- Rollback plan (new → old schema)
|
||||
- Data validation approach
|
||||
2. **Test migrations thoroughly**:
|
||||
- On copy of production data
|
||||
- Measure performance impact
|
||||
3. **Plan rollout**:
|
||||
- Staging environment first
|
||||
- Gradual production rollout
|
||||
- Monitoring for issues
|
||||
4. **Document in tech-spec/architecture**:
|
||||
- Migration scripts
|
||||
- Rollback procedures
|
||||
- Expected downtime
|
||||
|
||||
---
|
||||
|
||||
## Still Stuck?
|
||||
|
||||
### Getting More Help
|
||||
|
||||
If your issue isn't covered here:
|
||||
|
||||
1. **Check other documentation**:
|
||||
- [FAQ](./faq.md) - Common questions
|
||||
- [Glossary](./glossary.md) - Terminology
|
||||
- [Quick Start](./quick-start.md) - Basic usage
|
||||
- [Brownfield Guide](./brownfield-guide.md) - Existing codebases
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels
|
||||
|
||||
2. **Community support**:
|
||||
- [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
|
||||
- Active community, fast responses
|
||||
- Share your specific situation
|
||||
|
||||
3. **Report bugs**:
|
||||
- [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
|
||||
- Include version, steps to reproduce, expected vs actual behavior
|
||||
|
||||
4. **Video tutorials**:
|
||||
- [YouTube Channel](https://www.youtube.com/@BMadCode)
|
||||
- Visual walkthroughs of common workflows
|
||||
|
||||
---
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "No workflow status file found"
|
||||
|
||||
**Cause:** Haven't run workflow-init yet
|
||||
**Fix:** Load Analyst agent → run workflow-init
|
||||
|
||||
### "Epic file not found"
|
||||
|
||||
**Cause:** PRD/epics not created, or wrong path
|
||||
**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths
|
||||
|
||||
### "Story not in sprint-status.yaml"
|
||||
|
||||
**Cause:** Sprint-planning not run, or story file not created
|
||||
**Fix:** Run sprint-planning workflow, verify story files exist
|
||||
|
||||
### "Documentation insufficient for brownfield"
|
||||
|
||||
**Cause:** No docs/index.md or document-project not run
|
||||
**Fix:** Run document-project workflow with Deep scan
|
||||
|
||||
### "Level detection failed"
|
||||
|
||||
**Cause:** Ambiguous project description
|
||||
**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.)
|
||||
|
||||
### "Context generation failed"
|
||||
|
||||
**Cause:** Missing prerequisites (story file or docs)
|
||||
**Fix:** Verify story file exists, docs present
|
||||
|
||||
---
|
||||
|
||||
## Prevention Tips
|
||||
|
||||
**Avoid common issues before they happen:**
|
||||
|
||||
1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later
|
||||
2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow
|
||||
3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present
|
||||
4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow
|
||||
5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade
|
||||
6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift
|
||||
7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic
|
||||
8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4)
|
||||
|
||||
---
|
||||
|
||||
**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide!
|
||||
Common issues and solutions for the BMad Method Module will be listed here as needed.
|
||||
@@ -1,366 +0,0 @@
|
||||
# Decision Architecture Workflow - Technical Reference
|
||||
|
||||
**Module:** BMM (BMAD Method Module)
|
||||
**Type:** Solutioning Workflow
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
The Decision Architecture workflow is a complete reimagining of how architectural decisions are made in the BMAD Method. Instead of template-driven documentation, this workflow facilitates an intelligent conversation that produces a **decision-focused architecture document** optimized for preventing AI agent conflicts during implementation.
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
**The Problem**: When multiple AI agents implement different parts of a system, they make conflicting technical decisions leading to incompatible implementations.
|
||||
|
||||
**The Solution**: A "consistency contract" that documents all critical technical decisions upfront, ensuring every agent follows the same patterns and uses the same technologies.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Starter Template Intelligence ⭐ NEW
|
||||
|
||||
- Discovers relevant starter templates (create-next-app, create-t3-app, etc.)
|
||||
- Considers UX requirements when selecting templates (animations, accessibility, etc.)
|
||||
- Searches for current CLI options and defaults
|
||||
- Documents decisions made BY the starter template
|
||||
- Makes remaining architectural decisions around the starter foundation
|
||||
- First implementation story becomes "initialize with starter command"
|
||||
|
||||
### 2. Adaptive Facilitation
|
||||
|
||||
- Adjusts conversation style based on user skill level (beginner/intermediate/expert)
|
||||
- Experts get rapid, technical discussions
|
||||
- Beginners receive education and protection from complexity
|
||||
- Everyone produces the same high-quality output
|
||||
|
||||
### 3. Dynamic Version Verification
|
||||
|
||||
- NEVER trusts hardcoded version numbers
|
||||
- Uses WebSearch to find current stable versions
|
||||
- Verifies versions during the conversation
|
||||
- Documents only verified, current versions
|
||||
|
||||
### 4. Intelligent Discovery
|
||||
|
||||
- No rigid project type templates
|
||||
- Analyzes PRD to identify which decisions matter for THIS project
|
||||
- Uses knowledge base of decisions and patterns
|
||||
- Scales to infinite project types
|
||||
|
||||
### 5. Collaborative Decision Making
|
||||
|
||||
- Facilitates discussion for each critical decision
|
||||
- Presents options with trade-offs
|
||||
- Integrates advanced elicitation for innovative approaches
|
||||
- Ensures decisions are coherent and compatible
|
||||
|
||||
### 6. Consistent Output
|
||||
|
||||
- Structured decision collection during conversation
|
||||
- Strict document generation from collected decisions
|
||||
- Validated against hard requirements
|
||||
- Optimized for AI agent consumption
|
||||
|
||||
---
|
||||
|
||||
## Workflow Structure
|
||||
|
||||
```
|
||||
Step 0: Validate workflow and extract project configuration
|
||||
Step 0.5: Validate workflow sequencing
|
||||
Step 1: Load PRD (with FRs/NFRs) and understand project context
|
||||
Step 2: Discover and evaluate starter templates ⭐ NEW
|
||||
Step 3: Adapt facilitation style and identify remaining decisions
|
||||
Step 4: Facilitate collaborative decision making (with version verification)
|
||||
Step 5: Address cross-cutting concerns
|
||||
Step 6: Define project structure and boundaries
|
||||
Step 7: Design novel architectural patterns (when needed) ⭐ NEW
|
||||
Step 8: Define implementation patterns to prevent agent conflicts
|
||||
Step 9: Validate architectural coherence
|
||||
Step 10: Generate decision architecture document (with initialization commands)
|
||||
Step 11: Validate document completeness
|
||||
Step 12: Final review and update workflow status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files in This Workflow
|
||||
|
||||
- **workflow.yaml** - Configuration and metadata
|
||||
- **instructions.md** - The adaptive facilitation flow
|
||||
- **decision-catalog.yaml** - Knowledge base of all architectural decisions
|
||||
- **architecture-patterns.yaml** - Common patterns identified from requirements
|
||||
- **pattern-categories.csv** - Pattern principles that teach LLM what needs defining
|
||||
- **checklist.md** - Validation requirements for the output document
|
||||
- **architecture-template.md** - Strict format for the final document
|
||||
|
||||
---
|
||||
|
||||
## How It's Different from Old architecture
|
||||
|
||||
| Aspect | Old Workflow | New Workflow |
|
||||
| -------------------- | -------------------------------------------- | ----------------------------------------------- |
|
||||
| **Approach** | Template-driven | Conversation-driven |
|
||||
| **Project Types** | 11 rigid types with 22+ files | Infinite flexibility with intelligent discovery |
|
||||
| **User Interaction** | Output sections with "Continue?" | Collaborative decision facilitation |
|
||||
| **Skill Adaptation** | One-size-fits-all | Adapts to beginner/intermediate/expert |
|
||||
| **Decision Making** | Late in process (Step 5) | Upfront and central focus |
|
||||
| **Output** | Multiple documents including faux tech-specs | Single decision-focused architecture |
|
||||
| **Time** | Confusing and slow | 30-90 minutes depending on skill level |
|
||||
| **Elicitation** | Never used | Integrated at decision points |
|
||||
|
||||
---
|
||||
|
||||
## Expected Inputs
|
||||
|
||||
- **PRD** (Product Requirements Document) with:
|
||||
- Functional Requirements
|
||||
- Non-Functional Requirements
|
||||
- Performance and compliance needs
|
||||
|
||||
- **UX Spec** (Optional but valuable) with:
|
||||
- Interface designs and interaction patterns
|
||||
- Accessibility requirements (WCAG levels)
|
||||
- Animation and transition needs
|
||||
- Platform-specific UI requirements
|
||||
- Performance expectations for interactions
|
||||
|
||||
---
|
||||
|
||||
## Output Document
|
||||
|
||||
A single `architecture.md` file containing:
|
||||
|
||||
- Executive summary (2-3 sentences)
|
||||
- Project initialization command (if using starter template)
|
||||
- Decision summary table with verified versions and epic mapping
|
||||
- Complete project structure
|
||||
- Integration specifications
|
||||
- Consistency rules for AI agents
|
||||
|
||||
---
|
||||
|
||||
## How Novel Pattern Design Works
|
||||
|
||||
Step 7 handles unique or complex patterns that need to be INVENTED:
|
||||
|
||||
### 1. Detection
|
||||
|
||||
The workflow analyzes the PRD for concepts that don't have standard solutions:
|
||||
|
||||
- Novel interaction patterns (e.g., "swipe to match" when Tinder doesn't exist)
|
||||
- Complex multi-epic workflows (e.g., "viral invitation system")
|
||||
- Unique data relationships (e.g., "social graph" before Facebook)
|
||||
- New paradigms (e.g., "ephemeral messages" before Snapchat)
|
||||
|
||||
### 2. Design Collaboration
|
||||
|
||||
Instead of just picking technologies, the workflow helps DESIGN the solution:
|
||||
|
||||
- Identifies the core problem to solve
|
||||
- Explores different approaches with the user
|
||||
- Documents how components interact
|
||||
- Creates sequence diagrams for complex flows
|
||||
- Uses elicitation to find innovative solutions
|
||||
|
||||
### 3. Documentation
|
||||
|
||||
Novel patterns become part of the architecture with:
|
||||
|
||||
- Pattern name and purpose
|
||||
- Component interactions
|
||||
- Data flow diagrams
|
||||
- Which epics/stories are affected
|
||||
- Implementation guidance for agents
|
||||
|
||||
### 4. Example
|
||||
|
||||
```
|
||||
PRD: "Users can create 'circles' of friends with overlapping membership"
|
||||
↓
|
||||
Workflow detects: This is a novel social structure pattern
|
||||
↓
|
||||
Designs with user: Circle membership model, permission cascading, UI patterns
|
||||
↓
|
||||
Documents: "Circle Pattern" with component design and data flow
|
||||
↓
|
||||
All agents understand how to implement circle-related features consistently
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Implementation Patterns Work
|
||||
|
||||
Step 8 prevents agent conflicts by defining patterns for consistency:
|
||||
|
||||
### 1. The Core Principle
|
||||
|
||||
> "Any time multiple agents might make the SAME decision DIFFERENTLY, that's a pattern to capture"
|
||||
|
||||
The LLM asks: "What could an agent encounter where they'd have to guess?"
|
||||
|
||||
### 2. Pattern Categories (principles, not prescriptions)
|
||||
|
||||
- **Naming**: How things are named (APIs, database fields, files)
|
||||
- **Structure**: How things are organized (folders, modules, layers)
|
||||
- **Format**: How data is formatted (JSON structures, responses)
|
||||
- **Communication**: How components talk (events, messages, protocols)
|
||||
- **Lifecycle**: How states change (workflows, transitions)
|
||||
- **Location**: Where things go (URLs, paths, storage)
|
||||
- **Consistency**: Cross-cutting concerns (dates, errors, logs)
|
||||
|
||||
### 3. LLM Intelligence
|
||||
|
||||
- Uses the principle to identify patterns beyond the 7 categories
|
||||
- Figures out what specific patterns matter for chosen tech
|
||||
- Only asks about patterns that could cause conflicts
|
||||
- Skips obvious patterns that the tech choice determines
|
||||
|
||||
### 4. Example
|
||||
|
||||
```
|
||||
Tech chosen: REST API + PostgreSQL + React
|
||||
↓
|
||||
LLM identifies needs:
|
||||
- REST: URL structure, response format, status codes
|
||||
- PostgreSQL: table naming, column naming, FK patterns
|
||||
- React: component structure, state management, test location
|
||||
↓
|
||||
Facilitates each with user
|
||||
↓
|
||||
Documents as Implementation Patterns in architecture
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How Starter Templates Work
|
||||
|
||||
When the workflow detects a project type that has a starter template:
|
||||
|
||||
1. **Discovery**: Searches for relevant starter templates based on PRD
|
||||
2. **Investigation**: Looks up current CLI options and defaults
|
||||
3. **Presentation**: Shows user what the starter provides
|
||||
4. **Integration**: Documents starter decisions as "PROVIDED BY STARTER"
|
||||
5. **Continuation**: Only asks about decisions NOT made by starter
|
||||
6. **Documentation**: Includes exact initialization command in architecture
|
||||
|
||||
### Example Flow
|
||||
|
||||
```
|
||||
PRD says: "Next.js web application with authentication"
|
||||
↓
|
||||
Workflow finds: create-next-app and create-t3-app
|
||||
↓
|
||||
User chooses: create-t3-app (includes auth setup)
|
||||
↓
|
||||
Starter provides: Next.js, TypeScript, tRPC, Prisma, NextAuth, Tailwind
|
||||
↓
|
||||
Workflow only asks about: Database choice, deployment target, additional services
|
||||
↓
|
||||
First story becomes: "npx create t3-app@latest my-app --trpc --nextauth --prisma"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# In your BMAD-enabled project
|
||||
workflow architecture
|
||||
```
|
||||
|
||||
The AI agent will:
|
||||
|
||||
1. Load your PRD (with FRs/NFRs)
|
||||
2. Identify critical decisions needed
|
||||
3. Facilitate discussion on each decision
|
||||
4. Generate a comprehensive architecture document
|
||||
5. Validate completeness
|
||||
|
||||
---
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Facilitation over Prescription** - Guide users to good decisions rather than imposing templates
|
||||
2. **Intelligence over Templates** - Use AI understanding rather than rigid structures
|
||||
3. **Decisions over Details** - Focus on what prevents agent conflicts, not implementation minutiae
|
||||
4. **Adaptation over Uniformity** - Meet users where they are while ensuring quality output
|
||||
5. **Collaboration over Output** - The conversation matters as much as the document
|
||||
|
||||
---
|
||||
|
||||
## For Developers
|
||||
|
||||
This workflow assumes:
|
||||
|
||||
- Single developer + AI agents (not teams)
|
||||
- Speed matters (decisions in minutes, not days)
|
||||
- AI agents need clear constraints to prevent conflicts
|
||||
- The architecture document is for agents, not humans
|
||||
|
||||
---
|
||||
|
||||
## Migration from architecture
|
||||
|
||||
Projects using the old `architecture` workflow should:
|
||||
|
||||
1. Complete any in-progress architecture work
|
||||
2. Use `architecture` for new projects
|
||||
3. The old workflow remains available but is deprecated
|
||||
|
||||
---
|
||||
|
||||
## Version History
|
||||
|
||||
**1.3.2** - UX specification integration and fuzzy file matching
|
||||
|
||||
- Added UX spec as optional input with fuzzy file matching
|
||||
- Updated workflow.yaml with input file references
|
||||
- Starter template selection now considers UX requirements
|
||||
- Added UX alignment validation to checklist
|
||||
- Instructions use variable references for flexible file names
|
||||
|
||||
**1.3.1** - Workflow refinement and standardization
|
||||
|
||||
- Added workflow status checking at start (Steps 0 and 0.5)
|
||||
- Added workflow status updating at end (Step 12)
|
||||
- Reorganized step numbering for clarity (removed fractional steps)
|
||||
- Enhanced with intent-based approach throughout
|
||||
- Improved cohesiveness across all workflow components
|
||||
|
||||
**1.3.0** - Novel pattern design for unique architectures
|
||||
|
||||
- Added novel pattern design (now Step 7, formerly Step 5.3)
|
||||
- Detects novel concepts in PRD that need architectural invention
|
||||
- Facilitates design collaboration with sequence diagrams
|
||||
- Uses elicitation for innovative approaches
|
||||
- Documents custom patterns for multi-epic consistency
|
||||
|
||||
**1.2.0** - Implementation patterns for agent consistency
|
||||
|
||||
- Added implementation patterns (now Step 8, formerly Step 5.5)
|
||||
- Created principle-based pattern-categories.csv (7 principles, not 118 prescriptions)
|
||||
- Core principle: "What could agents decide differently?"
|
||||
- LLM uses principle to identify patterns beyond the categories
|
||||
- Prevents agent conflicts through intelligent pattern discovery
|
||||
|
||||
**1.1.0** - Enhanced with starter template discovery and version verification
|
||||
|
||||
- Added intelligent starter template detection and integration (now Step 2)
|
||||
- Added dynamic version verification via web search
|
||||
- Starter decisions are documented as "PROVIDED BY STARTER"
|
||||
- First implementation story uses starter initialization command
|
||||
|
||||
**1.0.0** - Initial release replacing architecture workflow
|
||||
|
||||
---
|
||||
|
||||
**Related Documentation:**
|
||||
|
||||
- [Solutioning Workflows](./workflows-solutioning.md)
|
||||
- [Planning Workflows](./workflows-planning.md)
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md)
|
||||
@@ -1,54 +1,23 @@
|
||||
# Document Project Workflow - Technical Reference
|
||||
|
||||
**Module:** BMM (BMAD Method Module)
|
||||
**Type:** Action Workflow (Documentation Generator)
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
|
||||
Analyzes and documents brownfield projects by scanning codebase, architecture, and patterns to create comprehensive reference documentation for AI-assisted development. Generates a master index and multiple documentation files tailored to project structure and type.
|
||||
|
||||
**NEW in v1.2.0:** Context-safe architecture with scan levels, resumability, and write-as-you-go pattern to prevent context exhaustion.
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
- **Multi-Project Type Support**: Handles web, backend, mobile, CLI, game, embedded, data, infra, library, desktop, and extension projects
|
||||
- **Multi-Part Detection**: Automatically detects and documents projects with separate client/server or multiple services
|
||||
- **Three Scan Levels** (NEW v1.2.0): Quick (2-5 min), Deep (10-30 min), Exhaustive (30-120 min)
|
||||
- **Resumability** (NEW v1.2.0): Interrupt and resume workflows without losing progress
|
||||
- **Write-as-you-go** (NEW v1.2.0): Documents written immediately to prevent context exhaustion
|
||||
- **Intelligent Batching** (NEW v1.2.0): Subfolder-based processing for deep/exhaustive scans
|
||||
- **Data-Driven Analysis**: Uses CSV-based project type detection and documentation requirements
|
||||
- **Comprehensive Scanning**: Analyzes APIs, data models, UI components, configuration, security patterns, and more
|
||||
- **Architecture Matching**: Matches projects to 170+ architecture templates from the solutioning registry
|
||||
- **Brownfield PRD Ready**: Generates documentation specifically designed for AI agents planning new features
|
||||
|
||||
---
|
||||
|
||||
## How to Invoke
|
||||
|
||||
```bash
|
||||
workflow document-project
|
||||
```
|
||||
|
||||
Or from BMAD CLI:
|
||||
|
||||
```bash
|
||||
/bmad:bmm:workflows:document-project
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scan Levels (NEW in v1.2.0)
|
||||
## Scan Levels
|
||||
|
||||
Choose the right scan depth for your needs:
|
||||
|
||||
### 1. Quick Scan (Default)
|
||||
|
||||
**Duration:** 2-5 minutes
|
||||
**What it does:** Pattern-based analysis without reading source files
|
||||
**Reads:** Config files, package manifests, directory structure, README
|
||||
**Use when:**
|
||||
@@ -61,7 +30,6 @@ Choose the right scan depth for your needs:
|
||||
|
||||
### 2. Deep Scan
|
||||
|
||||
**Duration:** 10-30 minutes
|
||||
**What it does:** Reads files in critical directories based on project type
|
||||
**Reads:** Files in critical paths defined by documentation requirements
|
||||
**Use when:**
|
||||
@@ -74,7 +42,6 @@ Choose the right scan depth for your needs:
|
||||
|
||||
### 3. Exhaustive Scan
|
||||
|
||||
**Duration:** 30-120 minutes
|
||||
**What it does:** Reads ALL source files in project
|
||||
**Reads:** Every source file (excludes node_modules, dist, build, .git)
|
||||
**Use when:**
|
||||
@@ -88,7 +55,7 @@ Choose the right scan depth for your needs:
|
||||
|
||||
---
|
||||
|
||||
## Resumability (NEW in v1.2.0)
|
||||
## Resumability
|
||||
|
||||
The workflow can be interrupted and resumed without losing progress:
|
||||
|
||||
@@ -98,392 +65,7 @@ The workflow can be interrupted and resumed without losing progress:
|
||||
- **Step-by-Step:** Resume from exact step where interrupted
|
||||
- **Archiving:** Old state files automatically archived
|
||||
|
||||
**Example Resume Flow:**
|
||||
|
||||
```
|
||||
> workflow document-project
|
||||
|
||||
I found an in-progress workflow state from 2025-10-11 14:32:15.
|
||||
|
||||
Current Progress:
|
||||
- Mode: initial_scan
|
||||
- Scan Level: deep
|
||||
- Completed Steps: 5/12
|
||||
- Last Step: step_5
|
||||
|
||||
Would you like to:
|
||||
1. Resume from where we left off - Continue from step 6
|
||||
2. Start fresh - Archive old state and begin new scan
|
||||
3. Cancel - Exit without changes
|
||||
|
||||
Your choice [1/2/3]:
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## What It Does
|
||||
|
||||
### Step-by-Step Process
|
||||
|
||||
1. **Detects Project Structure** - Identifies if project is single-part or multi-part (client/server/etc.)
|
||||
2. **Classifies Project Type** - Matches against 12 project types (web, backend, mobile, etc.)
|
||||
3. **Discovers Documentation** - Finds existing README, CONTRIBUTING, ARCHITECTURE files
|
||||
4. **Analyzes Tech Stack** - Parses package files, identifies frameworks, versions, dependencies
|
||||
5. **Conditional Scanning** - Performs targeted analysis based on project type requirements:
|
||||
- API routes and endpoints
|
||||
- Database models and schemas
|
||||
- State management patterns
|
||||
- UI component libraries
|
||||
- Configuration and security
|
||||
- CI/CD and deployment configs
|
||||
6. **Generates Source Tree** - Creates annotated directory structure with critical paths
|
||||
7. **Extracts Dev Instructions** - Documents setup, build, run, and test commands
|
||||
8. **Creates Architecture Docs** - Generates detailed architecture using matched templates
|
||||
9. **Builds Master Index** - Creates comprehensive index.md as primary AI retrieval source
|
||||
10. **Validates Output** - Runs 140+ point checklist to ensure completeness
|
||||
|
||||
### Output Files
|
||||
|
||||
**Single-Part Projects:**
|
||||
|
||||
- `index.md` - Master index
|
||||
- `project-overview.md` - Executive summary
|
||||
- `architecture.md` - Detailed architecture
|
||||
- `source-tree-analysis.md` - Annotated directory tree
|
||||
- `component-inventory.md` - Component catalog (if applicable)
|
||||
- `development-guide.md` - Local dev instructions
|
||||
- `api-contracts.md` - API documentation (if applicable)
|
||||
- `data-models.md` - Database schema (if applicable)
|
||||
- `deployment-guide.md` - Deployment process (optional)
|
||||
- `contribution-guide.md` - Contributing guidelines (optional)
|
||||
- `project-scan-report.json` - State file for resumability (NEW v1.2.0)
|
||||
|
||||
**Multi-Part Projects (e.g., client + server):**
|
||||
|
||||
- `index.md` - Master index with part navigation
|
||||
- `project-overview.md` - Multi-part summary
|
||||
- `architecture-{part_id}.md` - Per-part architecture docs
|
||||
- `source-tree-analysis.md` - Full tree with part annotations
|
||||
- `component-inventory-{part_id}.md` - Per-part components
|
||||
- `development-guide-{part_id}.md` - Per-part dev guides
|
||||
- `integration-architecture.md` - How parts communicate
|
||||
- `project-parts.json` - Machine-readable metadata
|
||||
- `project-scan-report.json` - State file for resumability (NEW v1.2.0)
|
||||
- Additional conditional files per part (API, data models, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Data Files
|
||||
|
||||
The workflow uses a single comprehensive CSV file:
|
||||
|
||||
**documentation-requirements.csv** - Complete project analysis guide
|
||||
|
||||
- Location: `/_bmad/bmm/workflows/document-project/documentation-requirements.csv`
|
||||
- 12 project types (web, mobile, backend, cli, library, desktop, game, data, extension, infra, embedded)
|
||||
- 24 columns combining:
|
||||
- **Detection columns**: `project_type_id`, `key_file_patterns` (identifies project type from codebase)
|
||||
- **Requirement columns**: `requires_api_scan`, `requires_data_models`, `requires_ui_components`, etc.
|
||||
- **Pattern columns**: `critical_directories`, `test_file_patterns`, `config_patterns`, etc.
|
||||
- Self-contained: All project detection AND scanning requirements in one file
|
||||
- Architecture patterns inferred from tech stack (no external registry needed)
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Primary Use Case: Brownfield PRD Creation
|
||||
|
||||
After running this workflow, use the generated `index.md` as input to brownfield PRD workflows:
|
||||
|
||||
```
|
||||
User: "I want to add a new dashboard feature"
|
||||
PRD Workflow: Loads docs/index.md
|
||||
→ Understands existing architecture
|
||||
→ Identifies reusable components
|
||||
→ Plans integration with existing APIs
|
||||
→ Creates contextual PRD with FRs and NFRs
|
||||
Architecture Workflow: Creates architecture design
|
||||
Create-Epics-and-Stories Workflow: Breaks down into epics and stories
|
||||
```
|
||||
|
||||
### Other Use Cases
|
||||
|
||||
- **Onboarding New Developers** - Comprehensive project documentation
|
||||
- **Architecture Review** - Structured analysis of existing system
|
||||
- **Technical Debt Assessment** - Identify patterns and anti-patterns
|
||||
- **Migration Planning** - Understand current state before refactoring
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Recommended Inputs (Optional)
|
||||
|
||||
- Project root directory (defaults to current directory)
|
||||
- README.md or similar docs (auto-discovered if present)
|
||||
- User guidance on key areas to focus (workflow will ask)
|
||||
|
||||
### Tools Used
|
||||
|
||||
- File system scanning (Glob, Read, Grep)
|
||||
- Code analysis
|
||||
- Git repository analysis (optional)
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Default Output Location
|
||||
|
||||
Files are saved to: `{output_folder}` (from config.yaml)
|
||||
|
||||
Default: `/docs/` folder in project root
|
||||
|
||||
### Customization
|
||||
|
||||
- Modify `documentation-requirements.csv` to adjust scanning patterns for project types
|
||||
- Add new project types to `project-types.csv`
|
||||
- Add new architecture templates to `registry.csv`
|
||||
|
||||
---
|
||||
|
||||
## Example: Multi-Part Web App
|
||||
|
||||
**Input:**
|
||||
|
||||
```
|
||||
my-app/
|
||||
├── client/ # React frontend
|
||||
├── server/ # Express backend
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Detection Result:**
|
||||
|
||||
- Repository Type: Monorepo
|
||||
- Part 1: client (web/React)
|
||||
- Part 2: server (backend/Express)
|
||||
|
||||
**Output (10+ files):**
|
||||
|
||||
```
|
||||
docs/
|
||||
├── index.md
|
||||
├── project-overview.md
|
||||
├── architecture-client.md
|
||||
├── architecture-server.md
|
||||
├── source-tree-analysis.md
|
||||
├── component-inventory-client.md
|
||||
├── development-guide-client.md
|
||||
├── development-guide-server.md
|
||||
├── api-contracts-server.md
|
||||
├── data-models-server.md
|
||||
├── integration-architecture.md
|
||||
└── project-parts.json
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example: Simple CLI Tool
|
||||
|
||||
**Input:**
|
||||
|
||||
```
|
||||
hello-cli/
|
||||
├── main.go
|
||||
├── go.mod
|
||||
└── README.md
|
||||
```
|
||||
|
||||
**Detection Result:**
|
||||
|
||||
- Repository Type: Monolith
|
||||
- Part 1: main (cli/Go)
|
||||
|
||||
**Output (4 files):**
|
||||
|
||||
```
|
||||
docs/
|
||||
├── index.md
|
||||
├── project-overview.md
|
||||
├── architecture.md
|
||||
└── source-tree-analysis.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Deep-Dive Mode
|
||||
|
||||
### What is Deep-Dive Mode?
|
||||
|
||||
When you run the workflow on a project that already has documentation, you'll be offered a choice:
|
||||
|
||||
1. **Rescan entire project** - Update all documentation with latest changes
|
||||
2. **Deep-dive into specific area** - Generate EXHAUSTIVE documentation for a particular feature/module/folder
|
||||
3. **Cancel** - Keep existing documentation
|
||||
|
||||
Deep-dive mode performs **comprehensive, file-by-file analysis** of a specific area, reading EVERY file completely and documenting:
|
||||
|
||||
- All exports with complete signatures
|
||||
- All imports and dependencies
|
||||
- Dependency graphs and data flow
|
||||
- Code patterns and implementations
|
||||
- Testing coverage and strategies
|
||||
- Integration points
|
||||
- Reuse opportunities
|
||||
|
||||
### When to Use Deep-Dive Mode
|
||||
|
||||
- **Before implementing a feature** - Deep-dive the area you'll be modifying
|
||||
- **During architecture review** - Deep-dive complex modules
|
||||
- **For code understanding** - Deep-dive unfamiliar parts of codebase
|
||||
- **When creating PRDs** - Deep-dive areas affected by new features
|
||||
|
||||
### Deep-Dive Process
|
||||
|
||||
1. Workflow detects existing `index.md`
|
||||
2. Offers deep-dive option
|
||||
3. Suggests areas based on project structure:
|
||||
- API route groups
|
||||
- Feature modules
|
||||
- UI component areas
|
||||
- Services/business logic
|
||||
4. You select area or specify custom path
|
||||
5. Workflow reads EVERY file in that area
|
||||
6. Generates `deep-dive-{area-name}.md` with complete analysis
|
||||
7. Updates `index.md` with link to deep-dive doc
|
||||
8. Offers to deep-dive another area or finish
|
||||
|
||||
### Deep-Dive Output Example
|
||||
|
||||
**docs/deep-dive-dashboard-feature.md:**
|
||||
|
||||
- Complete file inventory (47 files analyzed)
|
||||
- Every export with signatures
|
||||
- Dependency graph
|
||||
- Data flow analysis
|
||||
- Integration points
|
||||
- Testing coverage
|
||||
- Related code references
|
||||
- Implementation guidance
|
||||
- ~3,000 LOC documented in detail
|
||||
|
||||
### Incremental Deep-Diving
|
||||
|
||||
You can deep-dive multiple areas over time:
|
||||
|
||||
- First run: Scan entire project → generates index.md
|
||||
- Second run: Deep-dive dashboard feature
|
||||
- Third run: Deep-dive API layer
|
||||
- Fourth run: Deep-dive authentication system
|
||||
|
||||
All deep-dive docs are linked from the master index.
|
||||
|
||||
---
|
||||
|
||||
## Validation
|
||||
|
||||
The workflow includes a comprehensive 160+ point checklist covering:
|
||||
|
||||
- Project detection accuracy
|
||||
- Technology stack completeness
|
||||
- Codebase scanning thoroughness
|
||||
- Architecture documentation quality
|
||||
- Multi-part handling (if applicable)
|
||||
- Brownfield PRD readiness
|
||||
- Deep-dive completeness (if applicable)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps After Completion
|
||||
|
||||
1. **Review** `docs/index.md` - Your master documentation index
|
||||
2. **Validate** - Check generated docs for accuracy
|
||||
3. **Use for PRD** - Point brownfield PRD workflow to index.md
|
||||
4. **Maintain** - Re-run workflow when architecture changes significantly
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
document-project/
|
||||
├── workflow.yaml # Workflow configuration
|
||||
├── instructions.md # Step-by-step workflow logic
|
||||
├── checklist.md # Validation criteria
|
||||
├── documentation-requirements.csv # Project type scanning patterns
|
||||
├── templates/ # Output templates
|
||||
│ ├── index-template.md
|
||||
│ ├── project-overview-template.md
|
||||
│ └── source-tree-template.md
|
||||
└── README.md # This file
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Issue: Project type not detected correctly**
|
||||
|
||||
- Solution: Workflow will ask for confirmation; manually select correct type
|
||||
|
||||
**Issue: Missing critical information**
|
||||
|
||||
- Solution: Provide additional context when prompted; re-run specific analysis steps
|
||||
|
||||
**Issue: Multi-part detection missed a part**
|
||||
|
||||
- Solution: When asked to confirm parts, specify the missing part and its path
|
||||
|
||||
**Issue: Architecture template doesn't match well**
|
||||
|
||||
- Solution: Check registry.csv; may need to add new template or adjust matching criteria
|
||||
|
||||
---
|
||||
|
||||
## Architecture Improvements in v1.2.0
|
||||
|
||||
### Context-Safe Design
|
||||
|
||||
The workflow now uses a write-as-you-go architecture:
|
||||
|
||||
- Documents written immediately to disk (not accumulated in memory)
|
||||
- Detailed findings purged after writing (only summaries kept)
|
||||
- State tracking enables resumption from any step
|
||||
- Batching strategy prevents context exhaustion on large projects
|
||||
|
||||
### Batching Strategy
|
||||
|
||||
For deep/exhaustive scans:
|
||||
|
||||
- Process ONE subfolder at a time
|
||||
- Read files → Extract info → Write output → Validate → Purge context
|
||||
- Primary concern is file SIZE (not count)
|
||||
- Track batches in state file for resumability
|
||||
|
||||
### State File Format
|
||||
|
||||
Optimized JSON (no pretty-printing):
|
||||
|
||||
```json
|
||||
{
|
||||
"workflow_version": "1.2.0",
|
||||
"timestamps": {...},
|
||||
"mode": "initial_scan",
|
||||
"scan_level": "deep",
|
||||
"completed_steps": [...],
|
||||
"current_step": "step_6",
|
||||
"findings": {"summary": "only"},
|
||||
"outputs_generated": [...],
|
||||
"resume_instructions": "..."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Related Documentation:**
|
||||
|
||||
- [Brownfield Development Guide](./brownfield-guide.md)
|
||||
- [Implementation Workflows](./workflows-implementation.md)
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md)
|
||||
|
||||
@@ -19,7 +19,6 @@ Phase 1 Analysis consists of three categories of optional workflows:
|
||||
### Discovery & Ideation (Optional)
|
||||
|
||||
- **brainstorm-project** - Multi-track solution exploration for software projects
|
||||
- **brainstorm-game** - Game concept generation (coming soon)
|
||||
|
||||
### Research & Validation (Optional)
|
||||
|
||||
@@ -54,19 +53,10 @@ These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` w
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Unclear technical approach with business objectives
|
||||
- Multiple solution paths need evaluation
|
||||
- Hidden assumptions need discovery
|
||||
- Innovation beyond obvious solutions
|
||||
|
||||
**Key Outputs:**
|
||||
|
||||
- Architecture proposals with trade-off analysis
|
||||
- Value framework (prioritized features)
|
||||
- Risk analysis (dependencies, challenges)
|
||||
- Strategic recommendation with rationale
|
||||
|
||||
**Example:** "We need a customer dashboard" → Options: Monolith SSR (faster), Microservices SPA (scalable), Hybrid (balanced) with recommendation.
|
||||
- Very vague or seed kernal of an idea that needs exploration
|
||||
- Consider alternatives or enhancements to an idea
|
||||
- See your idea from different angles and viewpoints
|
||||
- No idea what you want to build, but want to find some inspiration
|
||||
|
||||
---
|
||||
|
||||
@@ -111,11 +101,6 @@ These workflows feed into Phase 2 (Planning) workflows, particularly the `prd` w
|
||||
- Transitioning from exploration to strategy
|
||||
- Need executive-level product documentation
|
||||
|
||||
**Modes:**
|
||||
|
||||
- **Interactive Mode** (Recommended): Step-by-step collaborative development with probing questions
|
||||
- **YOLO Mode**: AI generates complete draft from context, then iterative refinement
|
||||
|
||||
**Key Outputs:**
|
||||
|
||||
- Executive summary
|
||||
@@ -179,32 +164,6 @@ Analysis outputs feed directly into Planning:
|
||||
|
||||
Planning workflows automatically load these documents if they exist in the output folder.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Don't Over-Invest in Analysis
|
||||
|
||||
Analysis is optional. If requirements are clear, skip to Phase 2 (Planning).
|
||||
|
||||
### 2. Iterate Between Workflows
|
||||
|
||||
Common pattern: brainstorm → research (validate) → brief (synthesize)
|
||||
|
||||
### 3. Document Assumptions
|
||||
|
||||
Analysis surfaces and validates assumptions. Document them explicitly for planning to challenge.
|
||||
|
||||
### 4. Keep It Strategic
|
||||
|
||||
Focus on "what" and "why", not "how". Leave implementation for Planning and Solutioning.
|
||||
|
||||
### 5. Involve Stakeholders
|
||||
|
||||
Use analysis workflows to align stakeholders before committing to detailed planning.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Greenfield Software (Full Analysis)
|
||||
@@ -238,29 +197,3 @@ Use analysis workflows to align stakeholders before committing to detailed plann
|
||||
- [Phase 4: Implementation Workflows](./workflows-implementation.md)
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding project complexity
|
||||
- [Agents Guide](./agents-guide.md) - Complete agent reference
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Q: Do I need to run all analysis workflows?**
|
||||
A: No! Analysis is entirely optional. Use only workflows that help you think through your problem.
|
||||
|
||||
**Q: Which workflow should I start with?**
|
||||
A: If unsure, start with `research` (market type) to validate viability, then move to `product-brief`.
|
||||
|
||||
**Q: Can I skip straight to Planning?**
|
||||
A: Yes! If you know what you're building and why, skip Phase 1 entirely and start with Phase 2 (prd/tech-spec).
|
||||
|
||||
**Q: How long should Analysis take?**
|
||||
A: Typically hours to 1-2 days. If taking longer, you may be over-analyzing. Move to Planning.
|
||||
|
||||
**Q: What if I discover problems during Analysis?**
|
||||
A: That's the point! Analysis helps you fail fast and pivot before heavy planning investment.
|
||||
|
||||
**Q: Should brownfield projects do Analysis?**
|
||||
A: Usually no. Start with `document-project` (Documentation prerequisite), then skip to Planning (Phase 2).
|
||||
|
||||
---
|
||||
|
||||
_Phase 1 Analysis - Optional strategic thinking before commitment._
|
||||
|
||||
@@ -1,183 +1,14 @@
|
||||
# BMM Planning Workflows (Phase 2)
|
||||
|
||||
## Overview
|
||||
|
||||
Phase 2 (Planning) workflows are **required** for all projects. They transform strategic vision into actionable requirements using a **scale-adaptive system** that automatically selects the right planning depth based on project complexity.
|
||||
|
||||
**Key principle:** One unified entry point (`workflow-init`) intelligently routes to the appropriate planning methodology - from quick tech-specs to comprehensive PRDs.
|
||||
|
||||
**When to use:** All projects require planning. The system adapts depth automatically based on complexity.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 Planning Workflow Overview
|
||||
|
||||
Phase 2 Planning uses a scale-adaptive system with three tracks:
|
||||
|
||||
### Quick Flow (Simple Planning)
|
||||
|
||||
- Entry: `workflow-init` routes based on project complexity
|
||||
- Workflow: `tech-spec`
|
||||
- Output: Technical document with story/epic structure
|
||||
- Story count: 1-15 (typical)
|
||||
- Next: Phase 4 (Implementation) - skips Phase 3
|
||||
|
||||
### BMad Method (Recommended)
|
||||
|
||||
- Entry: `workflow-init` routes based on project complexity
|
||||
- Workflows: `prd` → (optional) `create-ux-design`
|
||||
- Output: PRD with FRs/NFRs
|
||||
- Story count: 10-50+ (typical)
|
||||
- Next: Phase 3 (Solutioning) → Phase 4
|
||||
|
||||
### Enterprise Method
|
||||
|
||||
- Planning: Same as BMad Method (`prd` workflow)
|
||||
- Solutioning: Extended Phase 3 workflows (Architecture + Security + DevOps)
|
||||
- Story count: 30+ (typical)
|
||||
- Next: Phase 4
|
||||
|
||||
The `correct-course` workflow can be used anytime for significant requirement changes.
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Workflow | Agent | Track | Purpose | Typical Stories |
|
||||
| -------------------- | ----------- | ----------------------- | ----------------------------------------------- | --------------- |
|
||||
| **workflow-init** | PM/Analyst | All | Entry point: discovery + routing | N/A |
|
||||
| **tech-spec** | PM | Quick Flow | Technical document → Story or Epic+Stories | 1-15 |
|
||||
| **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs (no epic breakdown) | 10-50+ |
|
||||
| **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) | N/A |
|
||||
| **correct-course** | PM/SM | All | Mid-stream requirement changes | N/A |
|
||||
|
||||
**Note:** Story counts are guidance. V6 improvement: Epic+Stories are created AFTER architecture for better quality.
|
||||
|
||||
---
|
||||
|
||||
## Scale-Adaptive Planning System
|
||||
|
||||
BMM uses three distinct planning tracks that adapt to project complexity:
|
||||
|
||||
### Track 1: Quick Flow
|
||||
|
||||
**Best For:** Bug fixes, simple features, clear scope, enhancements
|
||||
|
||||
**Planning:** Tech-spec only → Implementation
|
||||
|
||||
**Time:** Hours to 1 day
|
||||
|
||||
**Story Count:** Typically 1-15 (guidance)
|
||||
|
||||
**Documents:** tech-spec.md + story files
|
||||
|
||||
**Example:** "Fix authentication bug", "Add OAuth social login"
|
||||
|
||||
---
|
||||
|
||||
### Track 2: BMad Method (RECOMMENDED)
|
||||
|
||||
**Best For:** Products, platforms, complex features, multiple epics
|
||||
|
||||
**Planning:** PRD + Architecture → Implementation
|
||||
|
||||
**Time:** 1-3 days
|
||||
|
||||
**Story Count:** Typically 10-50+ (guidance)
|
||||
|
||||
**Documents:** PRD.md (FRs/NFRs) + architecture.md + epics.md + epic files
|
||||
|
||||
**Greenfield:** Product Brief (optional) → PRD (FRs/NFRs) → UX (optional) → Architecture → Epics+Stories → Implementation
|
||||
|
||||
**Brownfield:** document-project → PRD (FRs/NFRs) → Architecture (recommended) → Epics+Stories → Implementation
|
||||
|
||||
**Example:** "Customer dashboard", "E-commerce platform", "Add search to existing app"
|
||||
|
||||
**Why Architecture for Brownfield?** Distills massive codebase context into focused solution design for your specific project.
|
||||
|
||||
---
|
||||
|
||||
### Track 3: Enterprise Method
|
||||
|
||||
**Best For:** Enterprise requirements, multi-tenant, compliance, security-sensitive
|
||||
|
||||
**Planning (Phase 2):** Uses BMad Method planning (PRD with FRs/NFRs)
|
||||
|
||||
**Solutioning (Phase 3):** Extended workflows (Architecture + Security + DevOps + SecOps as optional additions) → Epics+Stories
|
||||
|
||||
**Time:** 3-7 days total (1-3 days planning + 2-4 days extended solutioning)
|
||||
|
||||
**Story Count:** Typically 30+ (but defined by enterprise needs)
|
||||
|
||||
**Documents Phase 2:** PRD.md (FRs/NFRs)
|
||||
|
||||
**Documents Phase 3:** architecture.md + epics.md + epic files + security-architecture.md (optional) + devops-strategy.md (optional) + secops-strategy.md (optional)
|
||||
|
||||
**Example:** "Multi-tenant SaaS", "HIPAA-compliant portal", "Add SOC2 audit logging"
|
||||
|
||||
---
|
||||
|
||||
## How Track Selection Works
|
||||
|
||||
`workflow-init` guides you through educational choice:
|
||||
|
||||
1. **Description Analysis** - Analyzes project description for complexity
|
||||
2. **Educational Presentation** - Shows all three tracks with trade-offs
|
||||
3. **Recommendation** - Suggests track based on keywords and context
|
||||
4. **User Choice** - You select the track that fits
|
||||
|
||||
The system guides but never forces. You can override recommendations.
|
||||
|
||||
---
|
||||
|
||||
## Workflow Descriptions
|
||||
|
||||
### workflow-init (Entry Point)
|
||||
|
||||
**Purpose:** Single unified entry point for all planning. Discovers project needs and intelligently routes to appropriate track.
|
||||
|
||||
**Agent:** PM (orchestrates others as needed)
|
||||
|
||||
**Always Use:** This is your planning starting point. Don't call prd/tech-spec directly unless skipping discovery.
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Discovery (understand context, assess complexity, identify concerns)
|
||||
2. Routing Decision (determine track, explain rationale, confirm)
|
||||
3. Execute Target Workflow (invoke planning workflow, pass context)
|
||||
4. Handoff (document decisions, recommend next phase)
|
||||
|
||||
---
|
||||
|
||||
### tech-spec (Quick Flow)
|
||||
|
||||
**Purpose:** Lightweight technical specification for simple changes (Quick Flow track). Produces technical document and story or epic+stories structure.
|
||||
|
||||
**Agent:** PM
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Bug fixes
|
||||
- Single API endpoint additions
|
||||
- Configuration changes
|
||||
- Small UI component additions
|
||||
- Isolated validation rules
|
||||
|
||||
**Key Outputs:**
|
||||
|
||||
- **tech-spec.md** - Technical document containing:
|
||||
- Problem statement and solution
|
||||
- Source tree changes
|
||||
- Implementation details
|
||||
- Testing strategy
|
||||
- Acceptance criteria
|
||||
- **Story file(s)** - Single story OR epic+stories structure (1-15 stories typically)
|
||||
|
||||
**Skip To Phase:** 4 (Implementation) - no Phase 3 architecture needed
|
||||
|
||||
**Example:** "Fix null pointer when user has no profile image" → Single file change, null check, unit test, no DB migration.
|
||||
|
||||
---
|
||||
| Workflow | Agent | Track | Purpose |
|
||||
| -------------------- | ----------- | ----------------------- | ------------------------------------- |
|
||||
| **prd** | PM | BMad Method, Enterprise | Strategic PRD with FRs/NFRs |
|
||||
| **create-ux-design** | UX Designer | BMad Method, Enterprise | Optional UX specification (after PRD) |
|
||||
|
||||
### prd (Product Requirements Document)
|
||||
|
||||
@@ -245,207 +76,14 @@ The system guides but never forces. You can override recommendations.
|
||||
|
||||
**Example:** Dashboard redesign → Card-based layout with split-pane toggle, 5 card components, 12 color tokens, responsive grid, 3 epics (Layout, Visualization, Accessibility).
|
||||
|
||||
---
|
||||
|
||||
### correct-course
|
||||
|
||||
**Purpose:** Handle significant requirement changes during implementation (all tracks).
|
||||
|
||||
**Agent:** PM, Architect, or SM
|
||||
|
||||
**When to Use:**
|
||||
|
||||
- Priorities change mid-project
|
||||
- New requirements emerge
|
||||
- Scope adjustments needed
|
||||
- Technical blockers require replanning
|
||||
|
||||
**Process:**
|
||||
|
||||
1. Analyze impact of change
|
||||
2. Propose solutions (continue, pivot, pause)
|
||||
3. Update affected documents (PRD, epics, stories)
|
||||
4. Re-route for implementation
|
||||
|
||||
**Integration:** Updates planning artifacts, may trigger architecture review
|
||||
|
||||
---
|
||||
|
||||
## Decision Guide
|
||||
|
||||
### Which Planning Workflow?
|
||||
|
||||
**Use `workflow-init` (Recommended):** Let the system discover needs and route appropriately.
|
||||
|
||||
**Direct Selection (Advanced):**
|
||||
|
||||
- **Bug fix or single change** → `tech-spec` (Quick Flow)
|
||||
- **Software product** → `prd` (BMad Method)
|
||||
- **UX innovation project** → `create-ux-design` + `prd` (BMad Method)
|
||||
- **Enterprise with compliance** → Choose track in `workflow-init` → Enterprise Method
|
||||
|
||||
---
|
||||
|
||||
## Integration with Phase 3 (Solutioning)
|
||||
|
||||
Planning outputs feed into Solutioning:
|
||||
|
||||
| Planning Output | Solutioning Input | Track Decision |
|
||||
| --------------- | ---------------------------------- | ---------------------------- |
|
||||
| tech-spec.md | Skip Phase 3 → Phase 4 directly | Quick Flow (no architecture) |
|
||||
| PRD.md | **architecture** (Level 3-4) | BMad Method (recommended) |
|
||||
| ux-spec.md | **architecture** (frontend design) | BMad Method |
|
||||
| Enterprise docs | **architecture** + security/ops | Enterprise Method (required) |
|
||||
|
||||
**Key Decision Points:**
|
||||
|
||||
- **Quick Flow:** Skip Phase 3 entirely → Phase 4 (Implementation)
|
||||
- **BMad Method:** Optional Phase 3 (simple), Required Phase 3 (complex)
|
||||
- **Enterprise:** Required Phase 3 (architecture + extended planning)
|
||||
|
||||
See: [workflows-solutioning.md](./workflows-solutioning.md)
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Always Start with workflow-init
|
||||
### 1. Do Product Brief from Phase 1 to kickstart the PRD for better results
|
||||
|
||||
Let the entry point guide you. It prevents over-planning simple features or under-planning complex initiatives.
|
||||
|
||||
### 2. Trust the Recommendation
|
||||
|
||||
If `workflow-init` suggests BMad Method, there's likely complexity you haven't considered. Review carefully before overriding.
|
||||
|
||||
### 3. Iterate on Requirements
|
||||
|
||||
Planning documents are living. Refine PRDs as you learn during Solutioning and Implementation.
|
||||
|
||||
### 4. Involve Stakeholders Early
|
||||
|
||||
Review PRDs with stakeholders before Solutioning. Catch misalignment early.
|
||||
|
||||
### 5. Focus on "What" Not "How"
|
||||
### 2. Focus on "What" Not "How"
|
||||
|
||||
Planning defines **what** to build and **why**. Leave **how** (technical design) to Phase 3 (Solutioning).
|
||||
|
||||
### 6. Document-Project First for Brownfield
|
||||
### 3. Document-Project First for Brownfield
|
||||
|
||||
Always run `document-project` before planning brownfield projects. AI agents need existing codebase context.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Greenfield Software (BMad Method)
|
||||
|
||||
```
|
||||
1. (Optional) Analysis: product-brief, research
|
||||
2. workflow-init → routes to prd
|
||||
3. PM: prd workflow
|
||||
4. (Optional) UX Designer: create-ux-design workflow
|
||||
5. → Phase 3: architecture
|
||||
```
|
||||
|
||||
### Brownfield Software (BMad Method)
|
||||
|
||||
```
|
||||
1. Technical Writer or Analyst: document-project
|
||||
2. workflow-init → routes to prd
|
||||
3. PM: prd workflow
|
||||
4. → Phase 3: architecture (recommended for focused solution design)
|
||||
```
|
||||
|
||||
### Bug Fix (Quick Flow)
|
||||
|
||||
```
|
||||
1. workflow-init → routes to tech-spec
|
||||
2. PM: tech-spec workflow
|
||||
3. → Phase 4: Implementation (skip Phase 3)
|
||||
```
|
||||
|
||||
### Enterprise Project (Enterprise Method)
|
||||
|
||||
```
|
||||
1. (Recommended) Analysis: research (compliance, security)
|
||||
2. workflow-init → routes to Enterprise Method
|
||||
3. PM: prd workflow
|
||||
4. (Optional) UX Designer: ux workflow
|
||||
5. PM: create-epics-and-stories
|
||||
6. → Phase 3: architecture + security + devops + test strategy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Anti-Patterns
|
||||
|
||||
### ❌ Skipping Planning
|
||||
|
||||
"We'll just start coding and figure it out."
|
||||
**Result:** Scope creep, rework, missed requirements
|
||||
|
||||
### ❌ Over-Planning Simple Changes
|
||||
|
||||
"Let me write a 20-page PRD for this button color change."
|
||||
**Result:** Wasted time, analysis paralysis
|
||||
|
||||
### ❌ Planning Without Discovery
|
||||
|
||||
"I already know what I want, skip the questions."
|
||||
**Result:** Solving wrong problem, missing opportunities
|
||||
|
||||
### ❌ Treating PRD as Immutable
|
||||
|
||||
"The PRD is locked, no changes allowed."
|
||||
**Result:** Ignoring new information, rigid planning
|
||||
|
||||
### ✅ Correct Approach
|
||||
|
||||
- Use scale-adaptive planning (right depth for complexity)
|
||||
- Involve stakeholders in review
|
||||
- Iterate as you learn
|
||||
- Keep planning docs living and updated
|
||||
- Use `correct-course` for significant changes
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [Phase 1: Analysis Workflows](./workflows-analysis.md) - Optional discovery phase
|
||||
- [Phase 3: Solutioning Workflows](./workflows-solutioning.md) - Next phase
|
||||
- [Phase 4: Implementation Workflows](./workflows-implementation.md)
|
||||
- [Scale Adaptive System](./scale-adaptive-system.md) - Understanding the three tracks
|
||||
- [Quick Spec Flow](./quick-spec-flow.md) - Quick Flow track details
|
||||
- [Agents Guide](./agents-guide.md) - Complete agent reference
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Q: Which workflow should I run first?**
|
||||
A: Run `workflow-init`. It analyzes your project and routes to the right planning workflow.
|
||||
|
||||
**Q: Do I always need a PRD?**
|
||||
A: No. Simple changes use `tech-spec` (Quick Flow). Only BMad Method and Enterprise tracks create PRDs.
|
||||
|
||||
**Q: Can I skip Phase 3 (Solutioning)?**
|
||||
A: Yes for Quick Flow. Optional for BMad Method (simple projects). Required for BMad Method (complex projects) and Enterprise.
|
||||
|
||||
**Q: How do I know which track to choose?**
|
||||
A: Use `workflow-init` - it recommends based on your description. Story counts are guidance, not definitions.
|
||||
|
||||
**Q: What if requirements change mid-project?**
|
||||
A: Run `correct-course` workflow. It analyzes impact and updates planning artifacts.
|
||||
|
||||
**Q: Do brownfield projects need architecture?**
|
||||
A: Recommended! Architecture distills massive codebase into focused solution design for your specific project.
|
||||
|
||||
**Q: When do I run create-epics-and-stories?**
|
||||
A: In Phase 3 (Solutioning), after architecture is complete.
|
||||
|
||||
**Q: Should I use product-brief before PRD?**
|
||||
A: Optional but recommended for greenfield. Helps strategic thinking. `workflow-init` offers it based on context.
|
||||
|
||||
---
|
||||
|
||||
_Phase 2 Planning - Scale-adaptive requirements for every project._
|
||||
Always run `document-project` before planning brownfield projects. AI agents need existing codebase context and will make a large quality difference. If you are adding a small addition to an existing project, you might want to consider instead after using document-project to use the quick flow solo dev process instead.
|
||||
|
||||
@@ -6,11 +6,13 @@
|
||||
startMessage: |
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
|
||||
🎉🎉 Happy Holidays and New Year 🍾🍾
|
||||
If you are looking for Version 4 of BMad Method, please note that you can
|
||||
still install it by using the command `npx bmad-method@latest install`, until v6 reaches beta.
|
||||
|
||||
IMPORTANT Changes with Version Alpha.20 - PLEASE READ THIS if upgrading from earlier Alpha Versions:
|
||||
IMPORTANT Changes with Version Alpha.22 - PLEASE READ THIS if upgrading from earlier Alpha Versions:
|
||||
|
||||
1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs` is meant for long-term artifacts, which you can always decide to move content to.
|
||||
1. The BMad Core default output folder has changed from docs to `_bmad-output`. `docs`
|
||||
is meant for long-term artifacts, which you can always decide to move content to.
|
||||
|
||||
2. If utilizing the BMad Method Module (BMM) please be aware of the following important recent changes:
|
||||
|
||||
@@ -21,8 +23,8 @@ startMessage: |
|
||||
IT IS STRONGLY SUGGESTED to align with these folder conventions instead of dumping all to docs/ - if you are upgrading from a prior
|
||||
version where all output was going to docs or docs/sprint-artifacts, it is suggested to reset configs to these new values.
|
||||
|
||||
If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts, and if you had brainstorming
|
||||
content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts.
|
||||
If you have anything in progress, you can move what was in sprint-artifacts to _bmad-output/implementation-artifacts,
|
||||
and if you had brainstorming content, a PRD, UX or Architecture, you can move the content to _bmad-output/planning-artifacts.
|
||||
|
||||
Read the latest updates before continuing:
|
||||
https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
|
||||
@@ -35,8 +37,11 @@ endMessage: |
|
||||
|
||||
✨ BMAD IS READY TO USE!
|
||||
|
||||
ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of being migrated to the improved workflow progressive disclosure system.
|
||||
Along with this, the full conversion to the new path locations for content being searched may possibly be incomplete. If you run a workflow that relies on finding input documents automatically, and you notice they are not being found / looking in the wrong location, either:
|
||||
ONE FINAL NOTE WITH VERSION Alpha.20: Phase 4 (Implementation) is still in the process of
|
||||
being migrated to the improved workflow progressive disclosure system.
|
||||
Along with this, the full conversion to the new path locations for content being searched
|
||||
may possibly be incomplete. If you run a workflow that relies on finding input documents
|
||||
automatically, and you notice they are not being found / looking in the wrong location, either:
|
||||
1. Manually specify the correct input location when prompted
|
||||
2. Open an issue on GitHub so we can address the problem quickly if you think its a bug.
|
||||
3. Ensure your content is in the new locations for best results:
|
||||
@@ -47,6 +52,7 @@ endMessage: |
|
||||
Thank you for helping test the early release version of the new BMad Core and BMad Method!
|
||||
Stable Beta coming soon - please read the full README.md and linked documentation to get started.
|
||||
|
||||
And again, here is the Change Log with all the details of recent updates: https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
|
||||
And again, here is the Change Log with all the details of recent updates:
|
||||
https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md
|
||||
|
||||
════════════════════════════════════════════════════════════════════════════════
|
||||
|
||||
@@ -210,26 +210,6 @@ class Detector {
|
||||
* @returns {{ hasLegacyV4: boolean, offenders: string[] }}
|
||||
*/
|
||||
async detectLegacyV4(projectDir) {
|
||||
// Helper: check existence of a nested path with case-sensitive segment matching
|
||||
const existsCaseSensitive = async (baseDir, segments) => {
|
||||
let dir = baseDir;
|
||||
for (let i = 0; i < segments.length; i++) {
|
||||
const seg = segments[i];
|
||||
let entries;
|
||||
try {
|
||||
entries = await fs.readdir(dir, { withFileTypes: true });
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
const hit = entries.find((e) => e.name === seg);
|
||||
if (!hit) return false;
|
||||
// Parents must be directories; the last segment may be a file or directory
|
||||
if (i < segments.length - 1 && !hit.isDirectory()) return false;
|
||||
dir = path.join(dir, hit.name);
|
||||
}
|
||||
return true;
|
||||
};
|
||||
|
||||
// Helper: check if a directory is a V6+ installation
|
||||
const isV6Installation = async (dirPath) => {
|
||||
const manifestPath = path.join(dirPath, '_config', 'manifest.yaml');
|
||||
|
||||
@@ -11,25 +11,7 @@ const sidebars = {
|
||||
type: 'category',
|
||||
label: 'IDE Guides',
|
||||
collapsed: true,
|
||||
items: [
|
||||
'ide-info/index',
|
||||
'ide-info/claude-code',
|
||||
'ide-info/cursor',
|
||||
'ide-info/windsurf',
|
||||
'ide-info/cline',
|
||||
'ide-info/github-copilot',
|
||||
'ide-info/auggie',
|
||||
'ide-info/codex',
|
||||
'ide-info/crush',
|
||||
'ide-info/gemini',
|
||||
'ide-info/iflow',
|
||||
'ide-info/kilo',
|
||||
'ide-info/opencode',
|
||||
'ide-info/qwen',
|
||||
'ide-info/roo',
|
||||
'ide-info/rovo-dev',
|
||||
'ide-info/trae',
|
||||
],
|
||||
items: [],
|
||||
},
|
||||
'v4-to-v6-upgrade',
|
||||
],
|
||||
|
||||
@@ -33,15 +33,6 @@ docs = requests.get("https://bmad-code-org.github.io/BMAD-METHOD/llms-full.txt")
|
||||
# Include in your system prompt or context
|
||||
```
|
||||
|
||||
## Source Bundles
|
||||
|
||||
Download the complete source code for offline development or contribution.
|
||||
|
||||
| Bundle | Contents |
|
||||
| --------------------------------------------------- | ------------------------------------------- |
|
||||
| **[bmad-sources.zip](/downloads/bmad-sources.zip)** | Complete `/src/` directory with all modules |
|
||||
| **[bmad-prompts.zip](/downloads/bmad-prompts.zip)** | Agent prompts and workflows from `/_bmad/` |
|
||||
|
||||
## Installation Options
|
||||
|
||||
### NPM (Recommended)
|
||||
@@ -50,12 +41,6 @@ Download the complete source code for offline development or contribution.
|
||||
npx bmad-method@alpha install
|
||||
```
|
||||
|
||||
### Manual Installation
|
||||
|
||||
1. Download `bmad-prompts.zip`
|
||||
2. Extract to your project root
|
||||
3. Configure your IDE per the [IDE Guides](/docs/ide-info/)
|
||||
|
||||
## Version Information
|
||||
|
||||
- **Current Version:** See [CHANGELOG](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CHANGELOG.md)
|
||||
|
||||
Reference in New Issue
Block a user