diff --git a/.claude/commands/bmad/bmm/workflows/README.md b/.claude/commands/bmad/bmm/workflows/README.md
index ee3515eb..6ce0eedb 100644
--- a/.claude/commands/bmad/bmm/workflows/README.md
+++ b/.claude/commands/bmad/bmm/workflows/README.md
@@ -37,7 +37,7 @@
- Path: `bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml`
- Unified PRD workflow for project levels 2-4. Produces strategic PRD and tactical epic breakdown. Hands off to architecture workflow for technical design. Note: Level 0-1 use tech-spec workflow.
-**tech-spec-sm**
+**tech-spec**
- Path: `bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml`
- Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed.
diff --git a/.claude/commands/bmad/bmm/workflows/tech-spec-sm.md b/.claude/commands/bmad/bmm/workflows/tech-spec-sm.md
index f3e860fa..8fcd66df 100644
--- a/.claude/commands/bmad/bmm/workflows/tech-spec-sm.md
+++ b/.claude/commands/bmad/bmm/workflows/tech-spec-sm.md
@@ -2,7 +2,7 @@
description: 'Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed.'
---
-# tech-spec-sm
+# tech-spec
IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:
diff --git a/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml b/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
index c9e28af4..bc05a4a3 100644
--- a/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+++ b/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
@@ -1,5 +1,5 @@
# Technical Specification Workflow (Level 0)
-name: tech-spec-sm
+name: tech-spec
description: "Technical specification workflow for Level 0 projects (single atomic changes). Creates focused tech spec for bug fixes, single endpoint additions, or small isolated changes. Tech-spec only - no PRD needed."
author: "BMad"
diff --git a/src/modules/bmm/README.md b/src/modules/bmm/README.md
index 1048d5d0..047c8581 100644
--- a/src/modules/bmm/README.md
+++ b/src/modules/bmm/README.md
@@ -34,7 +34,7 @@ bmm/
### Agent Roster
-**Core Development:** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Paige
+**Core Development:** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Technical Writer
**Game Development:** Game Designer, Game Developer, Game Architect
**Orchestration:** BMad Master (from Core)
diff --git a/src/modules/bmm/agents/paige.agent.yaml b/src/modules/bmm/agents/tech-writer.agent.yaml
similarity index 97%
rename from src/modules/bmm/agents/paige.agent.yaml
rename to src/modules/bmm/agents/tech-writer.agent.yaml
index 31daac68..c14f485b 100644
--- a/src/modules/bmm/agents/paige.agent.yaml
+++ b/src/modules/bmm/agents/tech-writer.agent.yaml
@@ -1,10 +1,10 @@
-# Paige - Documentation Guide Agent Definition
+# Technical Writer - Documentation Guide Agent Definition
agent:
metadata:
- id: bmad/bmm/agents/paige.md
- name: Paige
- title: Documentation Guide
+ id: bmad/bmm/agents/tech-writer.md
+ name: paige
+ title: Technical Writer
icon: π
module: bmm
diff --git a/src/modules/bmm/docs/agents-guide.md b/src/modules/bmm/docs/agents-guide.md
index c147f9da..86996871 100644
--- a/src/modules/bmm/docs/agents-guide.md
+++ b/src/modules/bmm/docs/agents-guide.md
@@ -37,7 +37,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- DEV (Developer)
- TEA (Test Architect)
- UX Designer
-- Paige (Documentation Guide)
+- Technical Writer
**Game Development (3 agents):**
@@ -144,10 +144,9 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
**Workflows:**
- `workflow-status` - Check what to do next
-- `create-architecture` - Decision-focused architecture with
+- `create-architecture` - Produce a Scale Adaptive Architecture
- `validate-architecture` - Validate architecture document
- `solutioning-gate-check` - Validate readiness for Phase 4
-- `correct-course` - Handle technical changes
**Communication Style:** Comprehensive yet pragmatic. Uses architectural metaphors. Balances technical depth with accessibility. Connects decisions to business value.
@@ -173,7 +172,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- Sprint planning and tracking initialization
- Creating user stories
- Assembling dynamic story context
-- Epic-level technical specifications (optional)
+- Epic-level technical context (optional)
- Marking stories ready for development
- Sprint retrospectives
@@ -183,8 +182,8 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- `workflow-status` - Check what to do next
- `sprint-planning` - Initialize `sprint-status.yaml` tracking
-- `epic-tech-context` - Optional epic-specific tech specs
-- `validate-epic-tech-context` - Validate epic tech spec
+- `epic-tech-context` - Optional epic-specific technical context
+- `validate-epic-tech-context` - Validate epic technical context
- `create-story` - Draft next story from epic
- `validate-create-story` - Independent story validation
- `story-context` - Assemble dynamic technical context XML
@@ -227,7 +226,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- Strict file boundary enforcement
- `code-review` - Senior developer-level review with:
- Story context awareness
- - Epic tech-spec alignment
+ - Epic-tech-context alignment
- Repository docs reference
- MCP server best practices
- Web search fallback
@@ -296,12 +295,13 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- Testing is feature work, not overhead
- Prioritize unit/integration over E2E
- Flakiness is critical technical debt
+- ATDD tests first, AI implements, suite validates
**Special Capabilities:**
-- **Test Healing:** Pattern-based + MCP-enhanced test fixing
-- **Dual Mode:** BMad-integrated (uses epic/story context) or standalone
-- **Knowledge Base:** Comprehensive testing best practices
+- **Knowledge Base Access:** Consults comprehensive testing best practices from `testarch/knowledge/` directory
+- **Framework Selection:** Smart framework selection (Playwright vs Cypress) with fixture architecture
+- **Cross-Platform Testing:** Supports testing across web, mobile, and API layers
---
@@ -341,7 +341,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
---
-### Paige (Documentation Guide) - Paige π
+### Technical Writer - Paige π
**Role:** Technical Documentation Specialist + Knowledge Curator
@@ -457,10 +457,9 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
**Workflows:**
- `workflow-status` - Check what to do next
-- `create-story` - Create development story
-- `dev-story` - Implement story with tests
-- `code-review` - Review game implementation
-- `retro` - Sprint retrospective
+- `develop-story` - Execute Dev Story workflow, implementing tasks and tests
+- `story-done` - Mark story done after DoD complete
+- `code-review` - Perform thorough clean context QA code review on a story
**Communication Style:** Direct and energetic. Execution-focused. Breaks down complex game challenges into actionable steps. Celebrates performance wins.
@@ -551,71 +550,24 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
## Party Mode: Multi-Agent Collaboration
-Party mode brings **all your installed agents together** for group discussions. Instead of working with one agent at a time, you engage with a dynamic team (19+ agents from BMM, CIS, BMB, and custom modules) that collaborates in real-time.
+Get all your installed agents in one conversation for multi-perspective discussions, retrospectives, and collaborative decision-making.
-### Quick Overview
+**Quick Start:**
-**How to Start:**
+```bash
+/bmad:core:workflows:party-mode
+# OR from any agent: *party-mode
+```
-1. Load BMad Master
-2. Run `*party-mode`
-3. Introduce your topic
+**What happens:** BMad Master orchestrates 2-3 relevant agents per message. They discuss, debate, and collaborate in real-time.
-**What Happens:**
+**Best for:** Strategic decisions, creative brainstorming, post-mortems, sprint retrospectives, complex problem-solving.
-- BMad Master loads ALL agents (with customizations)
-- For each message, 2-3 most relevant agents respond
-- Agents cross-talk, debate, and build on each other's ideas
-- BMad Master moderates and keeps discussion productive
+**Current BMM uses:** Powers `epic-retrospective` workflow, sprint planning discussions.
-**Best For:**
+**Future:** Advanced elicitation workflows will officially leverage party mode.
-- Strategic decisions with trade-offs
-- Creative brainstorming sessions
-- Cross-functional alignment meetings
-- Complex problem-solving
-- Epic kickoff discussions
-
-**Example Parties:**
-
-- **Product Strategy:** PM + Innovation Strategist + Analyst
-- **Technical Design:** Architect + Game Architect + Creative Problem Solver
-- **User Experience:** UX Designer + Design Thinking Coach + Storyteller
-- **Quality & Testing:** TEA + Architect + DEV
-- **Full Team:** PM + Architect + SM + DEV
-
-### Why Party Mode is Powerful
-
-**Diverse Perspectives:**
-
-- Technical agents ground ideas in reality
-- Creative agents (CIS) push for innovation
-- Strategic agents ensure market fit
-
-**Emergent Insights:**
-
-- Cross-pollination across domains
-- Novel solutions from unexpected combinations
-- Deeper exploration through debate
-
-**Natural Collaboration:**
-
-- Agents can agree, disagree, or build on each other
-- Healthy debate leads to better decisions
-- Multiple expert perspectives in one session
-
-**For complete party mode documentation, see:**
-
-π **[Party Mode Guide](./party-mode.md)** - Comprehensive 20-minute guide covering:
-
-- How party mode works (step-by-step process)
-- When to use party mode (strategic, creative, cross-functional, complex)
-- Getting started (quick start guide)
-- Agent selection dynamics
-- Multi-module integration (19+ agents)
-- 8+ example party compositions
-- Agent customization in party mode
-- Best practices and troubleshooting
+π **[Party Mode Guide](./party-mode.md)** - Complete guide with fun examples, tips, and troubleshooting
---
@@ -646,7 +598,7 @@ Some workflows are available to multiple agents:
| `workflow-status` | ALL agents | Check current state and get recommendations |
| `workflow-init` | PM, Analyst, Game Designer | Initialize workflow tracking |
| `correct-course` | PM, Architect, SM, Game Architect | Change management during implementation |
-| `document-project` | Analyst, Paige | Brownfield documentation |
+| `document-project` | Analyst, Technical Writer | Brownfield documentation |
### Validation Actions
@@ -658,7 +610,7 @@ Many workflows have optional validation workflows that perform independent revie
| `validate-tech-spec` | PM | Technical specification quality |
| `validate-architecture` | Architect | Architecture document |
| `validate-design` | UX Designer | UX specification and artifacts |
-| `validate-epic-tech-context` | SM | Epic technical specification |
+| `validate-epic-tech-context` | SM | Epic technical context |
| `validate-create-story` | SM | Story draft |
| `validate-story-context` | SM | Story context XML |
@@ -842,12 +794,12 @@ Load the customized agent and verify the changes are reflected in its behavior a
- **Phase 3 (Solutioning):** Architect, Game Architect
- **Phase 4 (Implementation):** SM, DEV, Game Developer
- **Testing:** TEA (all phases)
-- **Documentation:** Paige (all phases)
+- **Documentation:** Technical Writer (all phases)
**3. Use specialists**
- **Testing:** TEA for comprehensive quality strategy
-- **Documentation:** Paige for technical writing
+- **Documentation:** Technical Writer for technical writing
- **Games:** Game Designer/Developer/Architect for game-specific needs
- **UX:** UX Designer for user-centered design
@@ -903,7 +855,7 @@ Load the customized agent and verify the changes are reflected in its behavior a
**Starting with Existing Code (Brownfield):**
```
-1. Analyst or Paige: *document-project
+1. Analyst or Technical Writer: *document-project
2. PM or Analyst: *workflow-init
3. PM: *create-prd or *tech-spec
4. Architect: *create-architecture (if needed)
@@ -986,20 +938,20 @@ TEA can be invoked at any phase:
Quick reference for agent selection:
-| Agent | Icon | Primary Phase | Key Workflows | Best For |
-| ------------------ | ---- | ------------------ | --------------------------------------------- | ------------------------------------- |
-| **Analyst** | π | 1 (Analysis) | brainstorm, brief, research, document-project | Discovery, requirements, brownfield |
-| **PM** | π | 2 (Planning) | prd, tech-spec, epics-stories | Planning, requirements docs |
-| **UX Designer** | π¨ | 2 (Planning) | create-design, validate-design | UX-heavy projects, design |
-| **Architect** | ποΈ | 3 (Solutioning) | architecture, gate-check | Technical design, architecture |
-| **SM** | π | 4 (Implementation) | sprint-planning, create-story, story-context | Story management, sprint coordination |
-| **DEV** | π» | 4 (Implementation) | develop-story, code-review, story-done | Implementation, coding |
-| **TEA** | π§ͺ | All Phases | framework, atdd, automate, trace, ci | Testing, quality assurance |
-| **Paige** | π | All Phases | document-project, diagrams, validation | Documentation, diagrams |
-| **Game Designer** | π² | 1-2 (Games) | brainstorm-game, gdd, narrative | Game design, creative vision |
-| **Game Developer** | πΉοΈ | 4 (Games) | dev-story, code-review | Game implementation |
-| **Game Architect** | ποΈ | 3 (Games) | architecture, gate-check | Game systems architecture |
-| **BMad Master** | π§ | Meta | party-mode, list tasks/workflows | Orchestration, multi-agent |
+| Agent | Icon | Primary Phase | Key Workflows | Best For |
+| ----------------------- | ---- | ------------------ | --------------------------------------------- | ------------------------------------- |
+| **Analyst** | π | 1 (Analysis) | brainstorm, brief, research, document-project | Discovery, requirements, brownfield |
+| **PM** | π | 2 (Planning) | prd, tech-spec, epics-stories | Planning, requirements docs |
+| **UX Designer** | π¨ | 2 (Planning) | create-design, validate-design | UX-heavy projects, design |
+| **Architect** | ποΈ | 3 (Solutioning) | architecture, gate-check | Technical design, architecture |
+| **SM** | π | 4 (Implementation) | sprint-planning, create-story, story-context | Story management, sprint coordination |
+| **DEV** | π» | 4 (Implementation) | develop-story, code-review, story-done | Implementation, coding |
+| **TEA** | π§ͺ | All Phases | framework, atdd, automate, trace, ci | Testing, quality assurance |
+| **Paige (Tech Writer)** | π | All Phases | document-project, diagrams, validation | Documentation, diagrams |
+| **Game Designer** | π² | 1-2 (Games) | brainstorm-game, gdd, narrative | Game design, creative vision |
+| **Game Developer** | πΉοΈ | 4 (Games) | develop-story, story-done, code-review | Game implementation |
+| **Game Architect** | ποΈ | 3 (Games) | architecture, gate-check | Game systems architecture |
+| **BMad Master** | π§ | Meta | party-mode, list tasks/workflows | Orchestration, multi-agent |
### Agent Capabilities Summary
@@ -1028,7 +980,7 @@ Quick reference for agent selection:
**Support Agents (2):**
- Analyst: Research and discovery
-- Paige: Documentation and diagrams
+- Technical Writer: Documentation and diagrams
**Meta Agent (1):**
@@ -1079,7 +1031,7 @@ Quick reference for agent selection:
**Starting a Project:**
- [ ] Determine project type (greenfield vs brownfield)
-- [ ] If brownfield: Run `*document-project` (Analyst or Paige)
+- [ ] If brownfield: Run `*document-project` (Analyst or Technical Writer)
- [ ] Load PM or Analyst β `*workflow-init`
- [ ] Follow phase-appropriate workflows
- [ ] Try `*party-mode` for strategic decisions
diff --git a/src/modules/bmm/docs/brownfield-guide.md b/src/modules/bmm/docs/brownfield-guide.md
index e45a192e..e185db2d 100644
--- a/src/modules/bmm/docs/brownfield-guide.md
+++ b/src/modules/bmm/docs/brownfield-guide.md
@@ -92,22 +92,82 @@ You: "Yes"
## Phase 0: Documentation (Critical First Step)
-π¨ **For brownfield projects: Always ensure adequate documentation before planning**
+π¨ **For brownfield projects: Always ensure adequate AI-usable documentation before planning**
-### Three Scenarios
+### Default Recommendation: Run document-project
-| Scenario | You Have | Action | Tool | Time |
-| -------- | --------------------------- | -------------------- | -------- | ------ |
-| **A** | No documentation | Run document-project | Workflow | 10-30m |
-| **B** | Docs exist, no index.md | Run index-docs | Task | 2-5m |
-| **C** | Complete docs with index.md | Skip Phase 0 | - | 0m |
+**Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
-### Scenario A: No Documentation
+### Why Document-Project is Almost Always the Right Choice
-**Run document-project workflow:**
+Existing documentation often has quality issues that break AI workflows:
-1. Load Analyst agent
-2. Run "document-project"
+**Common Problems:**
+
+- **Too Much Information (TMI):** Massive markdown files with 10s or 100s of level 2 sections
+- **Out of Date:** Documentation hasn't been updated with recent code changes
+- **Wrong Format:** Written for humans, not AI agents (lacks structure, index, clear patterns)
+- **Incomplete Coverage:** Missing critical architecture, patterns, or setup info
+- **Inconsistent Quality:** Some areas documented well, others not at all
+
+**Impact on AI Agents:**
+
+- AI agents hit token limits reading massive files
+- Outdated docs cause hallucinations (agent thinks old patterns still apply)
+- Missing structure means agents can't find relevant information
+- Incomplete coverage leads to incorrect assumptions
+
+### Documentation Decision Tree
+
+**Step 1: Assess Existing Documentation Quality**
+
+Ask yourself:
+
+- β
Is it **current** (updated in last 30 days)?
+- β
Is it **AI-optimized** (structured with index.md, clear sections, <500 lines per file)?
+- β
Is it **comprehensive** (architecture, patterns, setup all documented)?
+- β
Do you **trust** it completely for AI agent consumption?
+
+**If ANY answer is NO β Run `document-project`**
+
+**Step 2: Check for Massive Documents**
+
+If you have documentation but files are huge (>500 lines, 10+ level 2 sections):
+
+1. **First:** Run `shard-doc` tool to split large files:
+
+ ```bash
+ # Load BMad Master or any agent
+ bmad/core/tools/shard-doc.xml --input docs/massive-doc.md
+ ```
+
+ - Splits on level 2 sections by default
+ - Creates organized, manageable files
+ - Preserves content integrity
+
+2. **Then:** Run `index-docs` task to create navigation:
+
+ ```bash
+ bmad/core/tasks/index-docs.xml --directory ./docs
+ ```
+
+3. **Finally:** Validate quality - if sharded docs still seem incomplete/outdated β Run `document-project`
+
+### Four Real-World Scenarios
+
+| Scenario | You Have | Action | Why |
+| -------- | ------------------------------------------ | -------------------------- | --------------------------------------- |
+| **A** | No documentation | `document-project` | Only option - generate from scratch |
+| **B** | Docs exist but massive/outdated/incomplete | `document-project` | Safer to regenerate than trust bad docs |
+| **C** | Good docs but no structure | `shard-doc` β `index-docs` | Structure existing content for AI |
+| **D** | Confirmed AI-optimized docs with index.md | Skip Phase 0 | Rare - only if you're 100% confident |
+
+### Scenario A: No Documentation (Most Common)
+
+**Action: Run document-project workflow**
+
+1. Load Analyst or Technical Writer (Paige) agent
+2. Run `*document-project`
3. Choose scan level:
- **Quick** (2-5min): Pattern analysis, no source reading
- **Deep** (10-30min): Reads critical paths - **Recommended**
@@ -119,31 +179,87 @@ You: "Yes"
- `docs/project-overview.md` - Executive summary
- `docs/architecture.md` - Architecture analysis
- `docs/source-tree-analysis.md` - Directory structure
-- Additional files based on project type
+- Additional files based on project type (API, web app, etc.)
-### Scenario B: Docs Exist, No Index
+### Scenario B: Docs Exist But Quality Unknown/Poor (Very Common)
-**Run index-docs task:**
+**Action: Run document-project workflow (regenerate)**
-1. Load BMad Master agent (or any agent with task access)
-2. Load task: `bmad/core/tasks/index-docs.xml`
-3. Specify docs directory (e.g., `./docs`)
-4. Task generates `index.md` from existing docs
+Even if `docs/` folder exists, if you're unsure about quality β **regenerate**.
-**Why index.md matters:** Primary entry point for AI agents. Provides structured navigation even when good docs exist.
+**Why regenerate instead of index?**
-### Scenario C: Complete Documentation
+- Outdated docs β AI makes wrong assumptions
+- Incomplete docs β AI invents missing information
+- TMI docs β AI hits token limits, misses key info
+- Human-focused docs β Missing AI-critical structure
-If `docs/index.md` exists with comprehensive content, skip to Phase 1 or 2.
+**document-project** will:
+
+- Scan actual codebase (source of truth)
+- Generate fresh, accurate documentation
+- Structure properly for AI consumption
+- Include only relevant, current information
+
+### Scenario C: Good Docs But Needs Structure
+
+**Action: Shard massive files, then index**
+
+If you have **good, current documentation** but it's in massive files:
+
+**Step 1: Shard large documents**
+
+```bash
+# For each massive doc (>500 lines or 10+ level 2 sections)
+bmad/core/tools/shard-doc.xml \
+ --input docs/api-documentation.md \
+ --output docs/api/ \
+ --level 2 # Split on ## headers (default)
+```
+
+**Step 2: Generate index**
+
+```bash
+bmad/core/tasks/index-docs.xml --directory ./docs
+```
+
+**Step 3: Validate**
+
+- Review generated `docs/index.md`
+- Check that sharded files are <500 lines each
+- Verify content is current and accurate
+- **If anything seems off β Run document-project instead**
+
+### Scenario D: Confirmed AI-Optimized Documentation (Rare)
+
+**Action: Skip Phase 0**
+
+Only skip if ALL conditions met:
+
+- β
`docs/index.md` exists and is comprehensive
+- β
Documentation updated within last 30 days
+- β
All doc files <500 lines with clear structure
+- β
Covers architecture, patterns, setup, API surface
+- β
You personally verified quality for AI consumption
+- β
Previous AI agents used it successfully
+
+**If unsure β Run document-project** (costs 10-30 minutes, saves hours of confusion)
### Why document-project is Critical
-Without it, workflows lack context:
+Without AI-optimized documentation, workflows fail:
-- **tech-spec** (Quick Flow) can't auto-detect stack/patterns
-- **PRD** (BMad Method/Enterprise) can't reference existing code
-- **architecture** (BMad Method/Enterprise) can't build on existing structure
-- **story-context** can't inject pattern-specific guidance
+- **tech-spec** (Quick Flow) can't auto-detect stack/patterns β Makes wrong assumptions
+- **PRD** (BMad Method) can't reference existing code β Designs incompatible features
+- **architecture** can't build on existing structure β Suggests conflicting patterns
+- **story-context** can't inject existing patterns β Dev agent rewrites working code
+- **dev-story** invents implementations β Breaks existing integrations
+
+### Key Principle
+
+**When in doubt, run document-project.**
+
+It's better to spend 10-30 minutes generating fresh, accurate docs than to waste hours debugging AI agents working from bad documentation.
---
diff --git a/src/modules/bmm/docs/brownfield-guide.md.backup b/src/modules/bmm/docs/brownfield-guide.md.backup
deleted file mode 100644
index 5b09f199..00000000
--- a/src/modules/bmm/docs/brownfield-guide.md.backup
+++ /dev/null
@@ -1,1324 +0,0 @@
-# BMad Method Brownfield Development Guide
-
-## Overview
-
-This guide provides comprehensive guidance for using BMad Method v6 with existing codebases (brownfield projects). Whether you're fixing a single bug, adding a small feature, or implementing a major system expansion, BMad Method adapts to your project's complexity while ensuring AI agents have the context they need to work effectively.
-
-**Core Principle:** In brownfield development, producing contextual artifacts for agents is paramount. AI agents require comprehensive documentation to understand existing patterns, constraints, and integration points before they can effectively plan or implement changes.
-
-## What is Brownfield Development?
-
-Brownfield projects involve working within existing codebases rather than starting fresh. This includes:
-
-- **Bug fixes** - Single file changes to resolve issues
-- **Small features** - Adding functionality to existing modules
-- **Feature sets** - Multiple related features across several areas
-- **Major integrations** - Complex additions requiring architectural changes
-- **System expansions** - Enterprise-scale enhancements to existing platforms
-
-The key difference from greenfield development: you must understand and respect existing patterns, architecture, and constraints.
-
-## Scale-Adaptive Workflow System
-
-BMad Method v6 uses a **scale-adaptive** approach that automatically routes brownfield projects through appropriate workflows based on complexity:
-
-### Brownfield Complexity Levels
-
-| Level | Scope | Story Count | Workflow Approach | Documentation Depth |
-| ----- | ---------------------- | ------------- | ---------------------------------------- | ------------------------------------------------------ |
-| **0** | Single atomic change | 1 story | Lightweight tech-spec only | Quick understanding of affected area |
-| **1** | Small feature addition | 1-10 stories | Tech-spec with epic breakdown | Focused documentation of integration points |
-| **2** | Medium feature set | 5-15 stories | PRD + tech-spec | Comprehensive docs for affected systems |
-| **3** | Complex integration | 12-40 stories | PRD β architecture β implementation | Full system documentation + integration planning |
-| **4** | Enterprise expansion | 40+ stories | Full methodology with strategic planning | Complete codebase documentation + architectural review |
-
-### How Scale Determination Works
-
-When you run `workflow-init`, it asks about YOUR work first, then uses existing artifacts as context:
-
-#### Step 1: Understand What You're Working On
-
-The workflow asks you first:
-
-1. **Project name**: "What's your project called?"
-
-2. **If it finds existing work** (code or planning documents):
- - Shows what it found (PRD, epics, stories, codebase)
- - Asks a clear question:
-
-> **"Looking at what I found, are these:**
->
-> a) **Works in progress you're finishing** - continuing the work described in these documents
-> b) **Documents from a previous effort** - you're starting something NEW and different now
-> c) **The proposed work you're about to start** - these describe what you want to do
-> d) **None of these** - let me explain what I'm actually working on"
-
-**If you choose (a) or (c):** System analyzes the artifacts to get project details
-**If you choose (b) or (d):** System asks you to describe your NEW work
-
-3. **Asks about your work**: "Tell me about what you're working on. What's the goal?"
-
-4. **Analyzes your description** using keyword detection:
-
-**Level 0 Keywords:** "fix", "bug", "typo", "small change", "update", "patch"
-**Level 1 Keywords:** "simple", "basic", "small feature", "add", "minor"
-**Level 2 Keywords:** "dashboard", "several features", "admin panel", "medium"
-**Level 3 Keywords:** "platform", "integration", "complex", "system"
-**Level 4 Keywords:** "enterprise", "multi-tenant", "multiple products", "ecosystem"
-
-**Examples:**
-
-- "I need to update payment method enums" β **Level 0**
-- "Adding forgot password feature" β **Level 1**
-- "Building admin dashboard with analytics" β **Level 2**
-- "Adding real-time collaboration to document editor" β **Level 3**
-- "Implementing multi-tenancy across our SaaS" β **Level 4**
-
-5. **Suggests and confirms**: "Based on your description: Level X brownfield project. Is that correct?"
-
-#### How It Handles Old Artifacts
-
-**Scenario: Old Level 3 PRD, New Level 0 Work**
-
-```
-System: "I found: PRD.md (Level 3, 30 stories, modified 6 months ago)"
-System: "Are these works in progress you're finishing, or documents from a previous effort?"
-
-You: "b - Documents from a previous effort"
-
-System: "Tell me about what you're working on"
-You: "I need to update payment method enums"
-
-System: "Level 0 brownfield project. Is that correct?"
-You: "yes"
-
-β
Result: Level 0 workflow
-```
-
-**Key Principle:** The system asks about YOUR current work first, then uses old artifacts as context, not as the primary source of truth.
-
-## The Five Phases of Brownfield Development
-
-### Phase 0: Documentation (Conditional)
-
-Phase 0 has three possible scenarios based on your existing documentation state:
-
-#### Scenario A: No Documentation
-
-**When:** Codebase lacks adequate documentation for AI agents
-**Action:** Run `document-project` workflow to create comprehensive documentation from scratch
-
-#### Scenario B: Documentation Exists, But No Index
-
-**When:** You have README, architecture docs, or other documentation BUT no `index.md` (master AI retrieval source)
-**Action:** Run the `index-docs` task to generate `index.md` from existing documentation
-
-**The `index-docs` Task** (from `bmad/core/tasks/index-docs.xml`):
-
-- Scans your documentation directory
-- Reads each file to understand its purpose
-- Creates organized `index.md` with file listings and descriptions
-- Provides structured navigation for AI agents
-- Lightweight and fast (just indexes, doesn't scan codebase)
-
-**Why This Matters:** The `index.md` file is the primary entry point for AI agents. Without it, agents must hunt through multiple files. Even with good existing docs, the index provides structured navigation and ensures agents can quickly find relevant context.
-
-**When to Use `document-project` Instead:**
-If your existing docs are inadequate or you need comprehensive codebase analysis:
-
-- Use `document-project` workflow with appropriate scan level (deep/exhaustive)
-- It will discover your existing docs in Step 2 and show them to you
-- It will generate NEW documentation from codebase analysis
-- Final `index.md` will link to BOTH existing docs AND newly generated docs
-- Result: Comprehensive documentation combining your existing docs with AI-friendly codebase analysis
-
-#### Scenario C: Complete Documentation with Index
-
-**When:** You have comprehensive documentation including `docs/index.md`
-**Action:** Skip Phase 0 entirely and proceed to Phase 1 or Phase 2
-
-#### The `document-project` Workflow
-
-This critical workflow analyzes and documents your existing codebase:
-
-**What It Does:**
-
-- Detects project type (web, backend, mobile, CLI, etc.)
-- Identifies tech stack and dependencies
-- Analyzes architecture patterns
-- Documents API routes and data models
-- Maps component structure
-- Extracts development workflows
-- **NEW:** Can incorporate existing documentation and generate master index
-
-**Three Scan Levels:**
-
-1. **Quick Scan** (2-5 min) - Pattern-based analysis without reading source
- - Use for: Fast project overview, initial understanding, index generation
- - Reads: Config files, manifests, directory structure, existing docs
-
-2. **Deep Scan** (10-30 min) - Reads critical directories
- - Use for: Brownfield PRD preparation, focused analysis
- - Reads: Key paths based on project type (controllers, models, components)
- - Incorporates: Existing documentation as input
-
-3. **Exhaustive Scan** (30-120 min) - Reads ALL source files
- - Use for: Migration planning, complete system understanding
- - Reads: Every source file (excludes node_modules, dist, .git)
- - Incorporates: All existing documentation
-
-**Output Files:**
-
-- `index.md` - Master documentation index (primary AI retrieval source)
-- `project-overview.md` - Executive summary
-- `architecture.md` - Detailed architecture analysis
-- `source-tree-analysis.md` - Annotated directory structure
-- `api-contracts.md` - API documentation (if applicable)
-- `data-models.md` - Database schemas (if applicable)
-- Additional conditional files based on project type
-
-**Working with Existing Documentation:**
-
-If you have existing docs (README, ARCHITECTURE.md, CONTRIBUTING.md, etc.) you have two options:
-
-**Option 1: Just need an index (`index-docs` task)**
-
-- Fast, lightweight approach
-- Run the `index-docs` task from `bmad/core/tasks/index-docs.xml`
-- Scans your docs directory and generates organized `index.md`
-- Reads each file to create accurate descriptions
-- Links to all existing documentation
-- Perfect when docs are good but need structured navigation for AI agents
-
-**Option 2: Need comprehensive codebase documentation (`document-project` workflow)**
-
-- Scans the actual codebase to generate technical documentation
-- Discovers existing docs (README, ARCHITECTURE.md, etc.) in Step 2
-- Shows you what it found and asks for additional context
-- Generates NEW documentation files from codebase analysis:
- - `project-overview.md` - Executive summary from codebase
- - `architecture.md` - Architecture analysis from code
- - `api-contracts.md` - API documentation from routes/controllers
- - `data-models.md` - Database schemas from models
- - `source-tree-analysis.md` - Annotated directory structure
-- Creates `index.md` that links to BOTH existing docs AND newly generated docs
-- Complements your existing documentation with AI-friendly codebase analysis
-
-**Deep-Dive Mode:** If you already have documentation but need exhaustive analysis of a specific area (e.g., authentication system, dashboard module), you can run the workflow in deep-dive mode to create comprehensive documentation for just that subsystem.
-
-**Example Usage:**
-
-```bash
-# Scenario A: No documentation
-bmad analyst workflow-status
-# β Directs to document-project
-bmad analyst document-project
-# β Choose: Deep scan (recommended for brownfield)
-
-# Scenario B: Has docs but no index
-# Option 1: Just generate index from existing docs
-# Run the index-docs task directly (lightweight, fast)
-# Load bmad/core/tasks/index-docs.xml
-# Specify your docs directory (e.g., ./docs)
-
-# Option 2: Need comprehensive codebase docs too
-bmad analyst document-project
-# β Choose: Deep or Exhaustive scan
-# β Creates index.md AND additional codebase documentation
-
-# Scenario C: Complete with index
-bmad analyst workflow-status
-# β Skips Phase 0, proceeds to Phase 1 or 2
-```
-
-### Phase 1: Analysis (Optional)
-
-**Purpose:** Explore solutions and gather context before formal planning.
-
-**Available Workflows:**
-
-- `brainstorm-project` - Solution exploration for new features
-- `research` - Market/technical research for decision-making
-- `product-brief` - Strategic product planning document
-
-**When to Use:**
-
-- Complex features requiring multiple solution approaches
-- Technical decisions needing research (frameworks, patterns, tools)
-- Strategic additions requiring business context
-
-**When to Skip:**
-
-- Bug fixes or minor changes with obvious solutions
-- Well-understood features with clear requirements
-- Time-sensitive changes where planning overhead isn't justified
-
-### Phase 2: Planning (Required)
-
-**Purpose:** Create formal requirements and break down work into epics and stories.
-
-The planning approach adapts to your brownfield project's complexity:
-
-#### Level 0: Single Atomic Change
-
-**Workflow:** `tech-spec` only
-**Outputs:** `tech-spec.md` + single story file
-**Next Phase:** β Implementation (Phase 4)
-
-**Use For:**
-
-- Bug fixes
-- Single file changes
-- Minor configuration updates
-- Small refactors
-
-**Key Considerations:**
-
-- Must understand existing pattern in affected file
-- Document integration points
-- Identify potential side effects
-
-**Example:** Fixing authentication token expiration bug in auth middleware
-
-#### Level 1: Small Feature
-
-**Workflow:** `tech-spec` only
-**Outputs:** `tech-spec.md` + epic breakdown + 2-10 story files
-**Next Phase:** β Implementation (Phase 4)
-
-**Use For:**
-
-- Single module additions
-- Small UI enhancements
-- Isolated feature additions
-- API endpoint additions
-
-**Key Considerations:**
-
-- Identify reusable existing components
-- Respect current architectural patterns
-- Plan integration with existing APIs/services
-
-**Example:** Adding "forgot password" feature to existing auth system
-
-#### Level 2: Medium Feature Set
-
-**Workflow:** `prd` β `tech-spec`
-**Outputs:** `PRD.md` + `epics.md` + `tech-spec.md`
-**Next Phase:** β Implementation (Phase 4)
-
-**Use For:**
-
-- Multiple related features
-- Cross-module enhancements
-- Moderate scope additions
-- Feature sets spanning 1-2 areas
-
-**Key Considerations:**
-
-- Document all integration points
-- Map dependencies to existing systems
-- Identify shared components for reuse
-- Plan migration strategy if changing patterns
-
-**Special Note:** Level 2 uses `tech-spec` instead of full architecture workflow to keep planning lightweight while still providing adequate technical guidance.
-
-**Example:** Adding user dashboard with analytics, preferences, and activity history
-
-#### Level 3: Complex Integration
-
-**Workflow:** `prd` β `create-architecture` β implementation
-**Outputs:** `PRD.md` + `epics.md` + `architecture.md` (extension of existing)
-**Next Phase:** β Solutioning (Phase 3) β Implementation (Phase 4)
-
-**Use For:**
-
-- Major feature additions
-- Architectural integrations
-- Multi-system changes
-- Complex data migrations
-
-**Key Considerations:**
-
-- Review existing architecture first
-- Plan integration strategy
-- Document architectural extensions
-- Identify migration paths
-- Plan backward compatibility
-
-**Phase 3 Workflows:**
-
-- `architecture-review` - Review existing architecture first
-- `integration-planning` - Create integration strategy document
-- `create-architecture` - Extend existing architecture documentation
-- `solutioning-gate-check` - Validate architecture before implementation
-
-**Example:** Adding real-time collaboration features to existing document editor
-
-#### Level 4: Enterprise Expansion
-
-**Workflow:** Full methodology with strategic analysis
-**Outputs:** Product brief β PRD β comprehensive architecture β phased implementation
-**Next Phase:** β Solutioning (Phase 3) β Implementation (Phase 4)
-
-**Use For:**
-
-- Platform expansions
-- Multi-team initiatives
-- System-wide modernization
-- Major architectural shifts
-
-**Key Considerations:**
-
-- Comprehensive codebase documentation required (Phase 0)
-- Deep architectural review mandatory
-- Backward compatibility strategy
-- Phased rollout planning
-- Feature flag implementation
-- Migration strategy for existing data/users
-- Cross-team coordination
-
-**Critical for Enterprise:**
-
-- Documentation phase is nearly mandatory
-- Analysis phase (research, product brief) recommended
-- Full architecture review before planning
-- Extensive integration testing strategy
-- Risk assessment and mitigation planning
-
-**Example:** Adding multi-tenancy to existing single-tenant SaaS platform
-
-### Phase 3: Solutioning (Levels 2-4)
-
-**Purpose:** Design architectural extensions and integration strategy.
-
-**Workflows Available:**
-
-| Workflow | Level | Purpose | Output |
-| ------------------------ | ----- | ------------------------------------ | ------------------------- |
-| `architecture-review` | 3-4 | Review existing architecture | Analysis document |
-| `integration-planning` | 3-4 | Plan integration approach | Integration strategy |
-| `create-architecture` | 2-4 | Extend architecture documentation | architecture.md (updated) |
-| `validate-architecture` | 2-4 | Validate design decisions | Validation report |
-| `solutioning-gate-check` | 3-4 | Final approval before implementation | Gate check report |
-
-**Critical Differences from Greenfield:**
-
-- You're **extending** existing architecture, not creating from scratch
-- Must document **integration points** explicitly
-- Need **migration strategy** for any pattern changes
-- Require **backward compatibility** considerations
-- Should plan **feature flags** for gradual rollout
-
-**Architecture Extensions Should Include:**
-
-- How new components integrate with existing systems
-- Data flow between new and existing modules
-- API contract changes (if any)
-- Database schema changes and migration strategy
-- Security implications and authentication integration
-- Performance impact on existing functionality
-
-### Phase 4: Implementation (Iterative)
-
-**Purpose:** Transform plans into working code through sprint-based iteration.
-
-#### The Sprint Planning Entry Point
-
-Phase 4 begins with the `sprint-planning` workflow:
-
-**What It Does:**
-
-1. Extracts all epics and stories from epic files
-2. Creates `sprint-status.yaml` - single source of truth for tracking
-3. Auto-detects existing story files and contexts
-4. Maintains status through development lifecycle
-
-**Run sprint-planning:**
-
-- Initially after Phase 2 or Phase 3 completion
-- After creating epic contexts
-- Periodically to sync with file system
-- To check overall progress
-
-#### The Implementation Loop
-
-```mermaid
-flowchart TD
- TRANS[Phase Transition]
- SPRINT[sprint-planning]
- EPIC[epic-tech-context
per epic]
- CREATE[create-story]
- CONTEXT[story-context]
- DEV[dev-story]
- REVIEW[code-review]
-
- DRAFTED[Status: drafted]
- READY[Status: ready-for-dev]
- INPROG[Status: in-progress]
- REV[Status: review]
- DONE[Status: done]
-
- CHECK{Epic complete?}
- RETRO[retrospective]
- MORE{More epics?}
-
- TRANS --> SPRINT
- SPRINT --> EPIC
- EPIC --> CREATE
- CREATE --> DRAFTED
- DRAFTED --> CONTEXT
- CONTEXT --> READY
- READY --> DEV
- DEV --> INPROG
- INPROG --> REVIEW
- REVIEW --> REV
- REV --> DONE
- DONE --> CHECK
- CHECK -->|No, more stories| CREATE
- CHECK -->|Yes| RETRO
- RETRO --> MORE
- MORE -->|Yes| EPIC
- MORE -->|No| COMPLETE([Project Complete])
-
- style SPRINT fill:#bfb,stroke:#333,stroke-width:2px
- style EPIC fill:#bbf,stroke:#333,stroke-width:2px
- style RETRO fill:#fbf,stroke:#333,stroke-width:2px
- style COMPLETE fill:#f9f,stroke:#333,stroke-width:3px
-```
-
-#### Status State Machine
-
-**Epic Status:**
-
-```mermaid
-stateDiagram-v2
- [*] --> backlog
- backlog --> contexted: epic-tech-context
- contexted --> [*]
-```
-
-**Story Status:**
-
-```mermaid
-stateDiagram-v2
- [*] --> backlog
- backlog --> drafted: create-story
- drafted --> ready_for_dev: story-context
- ready_for_dev --> in_progress: dev-story starts
- in_progress --> review: dev-story completes
- review --> done: code-review passes
- done --> [*]
-```
-
-#### Phase 4 Workflows
-
-| Workflow | Agent | Purpose | Status Update |
-| ------------------- | ----- | ------------------------------- | ------------------------------------------- |
-| `sprint-planning` | SM | Initialize sprint tracking | Creates sprint-status.yaml |
-| `epic-tech-context` | SM | Create epic technical context | Epic: backlog β contexted |
-| `create-story` | SM | Draft individual story | Story: backlog β drafted |
-| `story-context` | SM | Generate implementation context | Story: drafted β ready-for-dev |
-| `dev-story` | DEV | Implement story | Story: ready-for-dev β in-progress β review |
-| `code-review` | SM/SR | Quality validation | Manual state management |
-| `retrospective` | SM | Capture epic learnings | Retrospective: optional β completed |
-| `correct-course` | SM | Handle issues/scope changes | Adaptive based on situation |
-
-#### Brownfield-Specific Implementation Considerations
-
-1. **Respect Existing Patterns**
- - Use existing coding conventions
- - Follow established architectural approaches
- - Maintain consistency with current UI/UX patterns
- - Preserve team preferences and standards
-
-2. **Integration Testing is Critical**
- - Test interactions with existing functionality
- - Validate API contracts remain unchanged (unless intentionally versioned)
- - Check for regression in existing features
- - Verify performance impact on legacy components
-
-3. **Gradual Rollout Strategy**
- - Implement feature flags for new functionality
- - Plan rollback strategy
- - Support backward compatibility
- - Consider migration scripts for data/schema changes
-
-4. **Context Injection**
- - `epic-tech-context`: Provides technical guidance specific to epic scope
- - `story-context`: Generates implementation context for each story
- - Both reference existing codebase patterns and integration points
- - Ensures developers have exact expertise needed for each task
-
-## Workflow Routing by Level
-
-### Visual Decision Tree
-
-```mermaid
-flowchart TD
- START([workflow-status])
- HASDOCS{Has documentation?}
- DOC[document-project
Choose scan level]
- LEVEL{Complexity level?}
-
- L0[Level 0]
- L1[Level 1]
- L2[Level 2]
- L3[Level 3]
- L4[Level 4]
-
- TS0[tech-spec]
- TS1[tech-spec]
- PRD2[prd]
- PRD3[prd]
- PRD4[prd]
-
- TS2[tech-spec]
- ARCH[create-architecture]
-
- SPRINT[sprint-planning]
- IMPL[Implementation Loop]
-
- START --> HASDOCS
- HASDOCS -->|No| DOC
- HASDOCS -->|Yes| LEVEL
- DOC --> LEVEL
-
- LEVEL --> L0
- LEVEL --> L1
- LEVEL --> L2
- LEVEL --> L3
- LEVEL --> L4
-
- L0 --> TS0
- L1 --> TS1
- L2 --> PRD2
- L3 --> PRD3
- L4 --> PRD4
-
- TS0 --> SPRINT
- TS1 --> SPRINT
- PRD2 --> TS2
- PRD3 --> ARCH
- PRD4 --> ARCH
-
- TS2 --> SPRINT
- ARCH --> SPRINT
- SPRINT --> IMPL
-
- style START fill:#bfb,stroke:#333,stroke-width:2px
- style HASDOCS fill:#ffb,stroke:#333,stroke-width:2px
- style LEVEL fill:#ffb,stroke:#333,stroke-width:2px
- style SPRINT fill:#bbf,stroke:#333,stroke-width:2px
- style IMPL fill:#f9f,stroke:#333,stroke-width:3px
-```
-
-### Path Files
-
-The v6 system uses modular path definitions for each brownfield level:
-
-**Location:** `/src/modules/bmm/workflows/workflow-status/paths/`
-
-- `brownfield-level-0.yaml` - Single atomic change path
-- `brownfield-level-1.yaml` - Small feature path
-- `brownfield-level-2.yaml` - Medium project path
-- `brownfield-level-3.yaml` - Complex integration path
-- `brownfield-level-4.yaml` - Enterprise expansion path
-
-Each path file clearly defines:
-
-- Required vs optional workflows for each phase
-- Agent assignments
-- Expected outputs
-- Integration notes
-
-## Universal Entry Points
-
-### `workflow-status` - Your Command Center
-
-**Always start here.** This workflow:
-
-- Checks for existing workflow status file
-- Displays current phase and progress
-- Shows next recommended action
-- Routes to appropriate workflows based on context
-
-**For New Projects:**
-
-- Detects missing status file
-- Directs to `workflow-init`
-- Guides through project setup
-
-**For Existing Projects:**
-
-- Displays current phase and progress
-- Shows Phase 4 implementation state
-- Recommends exact next action
-- Offers to change workflow if needed
-
-**Example Usage:**
-
-```bash
-bmad analyst workflow-status
-```
-
-### `workflow-init` - Smart Initialization
-
-If you don't have a status file, this workflow initializes your project workflow by asking about YOUR work first, then using artifacts as context:
-
-**Step 1: Quick Scan (Context Only)**
-
-- Checks for existing code (`src/`, package files, `.git`)
-- Checks for planning artifacts (PRD, epics, stories, architecture docs)
-- Does NOT analyze in depth yet - just sees what's there
-
-**Step 2: Ask About YOUR Work**
-
-Asks: "What's your project called?"
-
-Then, if it found existing work, shows what it found and asks:
-
-> **"Looking at what I found, are these:**
->
-> a) Works in progress you're finishing
-> b) Documents from a previous effort (you're doing something NEW now)
-> c) The proposed work you're about to start
-> d) None of these - let me explain"
-
-**Your Paths:**
-
-- **Choose (a) or (c):** System analyzes the artifacts to determine level
-- **Choose (b) or (d):** System asks you to describe your NEW work
-
-**Step 3: Determine Level**
-
-If continuing old work: Counts stories from artifacts
-If new work: Asks "Tell me about what you're working on" and uses keyword detection
-
-Then confirms: "Level X brownfield project. Is that correct?"
-
-**Step 4: Create Workflow**
-
-- Loads appropriate path file: `brownfield-level-{0-4}.yaml`
-- Generates workflow with all phases and workflows
-- Creates status file
-
-**Example: Old Level 3 PRD, New Level 0 Work**
-
-```
-System: "What's your project called?"
-You: "PaymentApp"
-
-System: "I found: PRD.md (Level 3, 30 stories, 6mo ago), src/ codebase"
-System: "Are these works in progress, previous effort, or proposed work?"
-
-You: "b - Previous effort"
-
-System: "Tell me about what you're working on"
-You: "I need to update payment method enums"
-
-System: "Level 0 brownfield project. Is that correct?"
-You: "yes"
-
-β
Creates Level 0 workflow
-```
-
-**Smart Features:**
-
-- Asks about YOUR work first
-- Uses artifacts as context, not primary source
-- Keyword detection: "fix", "update" β Level 0
-- Handles scaffolds: "Just a starter" β still greenfield
-- Flags missing documentation automatically
-
-## Key Artifacts in Brownfield Projects
-
-### Tracking Documents
-
-**`bmm-workflow-status.md`** (Phases 0-3)
-
-- Current phase and progress
-- Workflow history
-- Next recommended actions
-- Project metadata
-
-**`sprint-status.yaml`** (Phase 4 only)
-
-- All epics, stories, retrospectives
-- Current status for each item
-- Single source of truth for implementation
-- Updated by agents as work progresses
-
-### Planning Documents
-
-**Level 0-1:**
-
-- `tech-spec.md` - Technical specification
-- `story-{key}.md` - Story files
-
-**Level 2:**
-
-- `PRD.md` - Product requirements
-- `epics.md` - Epic breakdown
-- `tech-spec.md` - Technical specification
-
-**Level 3-4:**
-
-- `PRD.md` - Product requirements
-- `epics.md` - Epic breakdown
-- `architecture.md` - Architecture extensions
-- Integration and validation reports
-
-### Implementation Documents
-
-**Phase 4 Artifacts:**
-
-- `sprint-status.yaml` - Status tracking
-- `epic-{n}-context.md` - Epic technical contexts
-- `stories/` directory:
- - `{epic}-{story}-{title}.md` - Story definitions
- - `{epic}-{story}-{title}-context.md` - Implementation contexts
-
-## Best Practices for Brownfield Success
-
-### 1. Always Document First
-
-Even if you know the codebase well, AI agents need comprehensive context. Run `document-project` with appropriate scan level before planning.
-
-**Why:** AI discovers undocumented patterns, integration points, and constraints that humans might overlook or take for granted.
-
-**Important:** Even if you have good documentation (README, ARCHITECTURE.md, etc.), you still need `docs/index.md` as the master AI retrieval source. If you have docs but no index:
-
-- **Quick fix:** Run the `index-docs` task (lightweight, just creates index)
-- **Comprehensive:** Use `document-project` with Deep scan to create index AND enhance docs
-- The index provides structured navigation for AI agents
-
-### 2. Be Specific About Your Current Work
-
-When `workflow-init` asks about your work, be specific about what you're doing NOW:
-
-**Good descriptions:**
-
-- "I need to update payment method enums to include Apple Pay"
-- "Adding forgot password feature to existing auth system"
-- "Building admin dashboard with analytics and user management"
-
-**Why this matters:** The system uses your description to suggest the right complexity level. Clear, specific descriptions lead to accurate routing through appropriate workflows.
-
-### 3. Choose the Right Documentation Approach
-
-**For existing docs without index:**
-
-- Use `index-docs` task - fast, lightweight, just generates index
-- Located at `bmad/core/tasks/index-docs.xml`
-
-**For comprehensive codebase documentation:**
-
-- Use `document-project` workflow with appropriate scan level:
- - **Quick:** Fast overview, planning next steps
- - **Deep:** Brownfield PRD preparation (most common)
- - **Exhaustive:** Migration planning, complete understanding
-
-### 4. Respect Existing Patterns
-
-The brownfield templates identify:
-
-- Current coding conventions
-- Architectural approaches
-- Technology constraints
-- Team preferences
-
-**Always preserve these unless explicitly modernizing them.**
-
-### 5. Plan Integration Points Explicitly
-
-Document in your tech-spec or architecture:
-
-- Which existing modules you'll modify
-- What APIs/services you'll integrate with
-- How data flows between new and existing code
-- What shared components you'll reuse
-
-### 6. Design for Gradual Rollout
-
-Brownfield changes should support:
-
-- Feature flags for new functionality
-- Rollback strategies
-- Backward compatibility
-- Migration scripts (if needed)
-
-### 7. Test Integration Thoroughly
-
-Use the Test Architect (TEA) workflows:
-
-- `test-design` - Plan integration test strategy
-- `test-review` - Validate test coverage
-- `nfr-assess` - Check performance/security impact
-
-**Critical for Brownfield:**
-
-- Regression testing of existing features
-- Integration point validation
-- Performance impact assessment
-- API contract verification
-
-### 8. Use Sprint Planning Effectively
-
-- Run `sprint-planning` at Phase 4 start
-- Context epics before drafting stories
-- Update `sprint-status.yaml` as work progresses
-- Re-run sprint-planning to sync with file system
-
-### 9. Leverage Context Injection
-
-- Run `epic-tech-context` before story drafting
-- Always create `story-context` before implementation
-- These workflows reference existing patterns for consistency
-
-### 10. Learn Continuously
-
-- Run `retrospective` after each epic
-- Incorporate learnings into next story drafts
-- Update patterns discovered during development
-- Share insights across team
-
-## Common Brownfield Scenarios
-
-### Scenario 1: Bug Fix (Level 0)
-
-**Situation:** Authentication token expiration causing logout issues
-
-**Workflow:**
-
-1. `workflow-status` β detects brownfield, suggests Level 0
-2. Skip Phase 0 if auth system is documented
-3. `tech-spec` β analyzes bug, plans fix, creates single story
-4. `sprint-planning` β creates sprint status
-5. `dev-story` β implement fix
-6. `code-review` β validate fix + test regression
-
-**Time:** ~2-4 hours total
-
-### Scenario 2: Small Feature (Level 1)
-
-**Situation:** Add "forgot password" to existing auth system
-
-**Workflow:**
-
-1. `workflow-status` β suggests Level 1
-2. Phase 0: `document-project` (deep scan of auth module if not documented)
-3. Phase 1: Optional - skip if requirements are clear
-4. Phase 2: `tech-spec` β creates epic with 3-5 stories
-5. Phase 4: `sprint-planning` β `create-story` β `dev-story` β repeat
-
-**Time:** 1-3 days
-
-### Scenario 3: Feature Set (Level 2)
-
-**Situation:** Add user dashboard with analytics, preferences, activity
-
-**Workflow:**
-
-1. `workflow-status` β suggests Level 2
-2. Phase 0: `document-project` (deep scan) - critical for understanding existing UI patterns
-3. Phase 1: `research` (if evaluating analytics libraries)
-4. Phase 2: `prd` β `tech-spec`
-5. Phase 4: Sprint-based implementation (10-15 stories)
-
-**Time:** 1-2 weeks
-
-### Scenario 4: Complex Integration (Level 3)
-
-**Situation:** Add real-time collaboration to document editor
-
-**Workflow:**
-
-1. `workflow-status` β suggests Level 3
-2. Phase 0: `document-project` (exhaustive if not documented)
-3. Phase 1: `research` (WebSocket vs WebRTC vs CRDT)
-4. Phase 2: `prd` β creates requirements + epics
-5. Phase 3:
- - `architecture-review` β understand existing editor architecture
- - `integration-planning` β plan WebSocket integration strategy
- - `create-architecture` β extend architecture for real-time layer
- - `solutioning-gate-check` β validate before implementation
-6. Phase 4: Sprint-based implementation (20-30 stories)
-
-**Time:** 3-6 weeks
-
-### Scenario 5: Enterprise Expansion (Level 4)
-
-**Situation:** Add multi-tenancy to single-tenant SaaS platform
-
-**Workflow:**
-
-1. `workflow-status` β suggests Level 4
-2. Phase 0: `document-project` (exhaustive) - **mandatory**
-3. Phase 1: **Required**
- - `brainstorm-project` β explore multi-tenancy approaches
- - `research` β database sharding, tenant isolation, pricing models
- - `product-brief` β strategic document
-4. Phase 2: `prd` β comprehensive requirements
-5. Phase 3:
- - `architecture-review` β full existing system review
- - `integration-planning` β phased migration strategy
- - `create-architecture` β multi-tenancy architecture
- - `validate-architecture` β external review
- - `solutioning-gate-check` β executive approval
-6. Phase 4: Phased sprint-based implementation (50+ stories)
-
-**Time:** 3-6 months
-
-## Troubleshooting Common Issues
-
-### Issue: AI Lacks Codebase Understanding
-
-**Symptoms:**
-
-- Generated plans don't align with existing patterns
-- Suggestions ignore available components
-- Integration approaches miss existing APIs
-
-**Solution:**
-
-1. Run `document-project` with deep or exhaustive scan
-2. Review `index.md` - ensure it captures key systems
-3. If specific area is unclear, run deep-dive mode on that area
-4. Provide additional context in PRD about existing systems
-
-### Issue: Have Documentation But Agents Can't Find It
-
-**Symptoms:**
-
-- You have README, ARCHITECTURE.md, CONTRIBUTING.md, etc.
-- But AI agents aren't using the information effectively
-- Agents ask questions already answered in existing docs
-- No `docs/index.md` file exists
-
-**Solution:**
-
-1. **Quick fix:** Run the `index-docs` task (from `bmad/core/tasks/index-docs.xml`)
- - Lightweight and fast (just indexes existing docs)
- - Scans your docs directory
- - Generates organized `index.md` with file descriptions
- - Provides AI agents with structured navigation
-
-2. **Comprehensive approach:** Run `document-project` with Deep/Exhaustive scan
- - Discovers existing docs in Step 2 (shows you what it found)
- - Generates NEW AI-friendly documentation from codebase analysis
- - Creates index.md that links to BOTH existing docs AND new docs
- - Useful when existing docs are good but need technical codebase analysis too
-
-**Why This Happens:** AI agents need a structured entry point (`index.md`) to efficiently navigate documentation. Without it, they must search through multiple files, often missing relevant context.
-
-### Issue: Plans Feel Too Complex for Simple Changes
-
-**Symptoms:**
-
-- Level 2+ workflow suggested for minor change
-- Too much documentation overhead
-
-**Solution:**
-
-1. Re-run `workflow-status` or `workflow-init`
-2. Correct the level when prompted (choose Level 0 or 1)
-3. Trust your judgment - BMad Method adapts to your choice
-4. Skip optional phases (Analysis)
-
-### Issue: Integration Points Unclear
-
-**Symptoms:**
-
-- Stories lack detail on connecting to existing systems
-- Uncertainty about which existing code to modify
-
-**Solution:**
-
-1. Ensure Phase 0 documentation is complete
-2. Run deep-dive on integration areas in `document-project`
-3. In Phase 2, explicitly document integration points
-4. In Phase 3 (if Level 3+), use `integration-planning` workflow
-5. Create detailed `epic-tech-context` and `story-context`
-
-### Issue: Existing Tests Breaking
-
-**Symptoms:**
-
-- Regression test failures
-- Existing functionality broken by changes
-
-**Solution:**
-
-1. Review existing test patterns in documentation
-2. Use Test Architect workflows:
- - `test-design` - Plan test strategy upfront
- - `trace` - Map requirements to tests
- - `test-review` - Validate before merging
-3. Add regression testing to Definition of Done
-4. Consider feature flags for gradual rollout
-
-### Issue: Inconsistent Patterns Being Introduced
-
-**Symptoms:**
-
-- New code doesn't match existing style
-- Different architectural approach than existing modules
-
-**Solution:**
-
-1. Ensure `document-project` captured existing patterns
-2. Review architecture documentation before Phase 4
-3. Use `story-context` to inject pattern guidance
-4. Include pattern adherence in `code-review` checklist
-5. Run retrospectives to identify pattern deviations
-
-## Test Architect Integration
-
-The Test Architect (TEA) plays a critical role in brownfield projects to prevent regression and validate integration.
-
-### Four-Stage Approach
-
-**Stage 1 (Before Development):**
-
-- Risk assessment identifying legacy dependencies
-- Test design planning for regression + new features
-- Integration point identification
-
-**Stage 2 (During Development):**
-
-- Requirements tracing validating existing functionality preservation
-- NFR validation ensuring performance/security unchanged
-
-**Stage 3 (Code Review):**
-
-- Deep analysis of API contracts, data migrations
-- Performance regression checks
-- Integration point validation
-- Dependency mapping
-
-**Stage 4 (Post-Review):**
-
-- Gate status updates
-- Technical debt documentation
-
-### TEA Workflows for Brownfield
-
-| Workflow | Purpose | When to Use |
-| ------------- | -------------------------- | ------------------------------------ |
-| `test-design` | Plan testing strategy | After Phase 2, before implementation |
-| `test-review` | Validate test coverage | During story review |
-| `trace` | Map requirements to tests | After test implementation |
-| `nfr-assess` | Check performance/security | Before major releases |
-| `atdd` | Acceptance test planning | For user-facing features |
-
-### Risk Scoring for Brownfield
-
-TEA uses enhanced brownfield metrics:
-
-- **Regression Risk** = integration_points Γ code_age
-- **Data Risk** = migration_complexity Γ data_volume
-- **Performance Risk** = current_load Γ added_complexity
-- **Compatibility Risk** = api_consumers Γ contract_changes
-
-**Automatic Thresholds:**
-
-- Score β₯9: Automatic failure (must mitigate)
-- Score β₯6: Concern (requires mitigation plan)
-- Score <6: Acceptable (document only)
-
-## Quick Reference Commands
-
-```bash
-# Universal Entry Point (Always Start Here)
-bmad analyst workflow-status
-
-# Phase 0: Documentation (If Needed)
-bmad analyst document-project
-# β Choose: Quick / Deep / Exhaustive
-
-# Phase 1: Analysis (Optional)
-bmad analyst brainstorm-project # Explore solutions
-bmad analyst research # Gather technical/market data
-bmad analyst product-brief # Strategic planning
-
-# Phase 2: Planning (Required)
-bmad pm tech-spec # Level 0-1 only
-bmad pm prd # Level 2-4 only
-
-# Phase 3: Solutioning (Levels 2-4)
-bmad architect architecture-review # Review existing (L3-4)
-bmad architect integration-planning # Plan integration (L3-4)
-bmad architect create-architecture # Extend architecture (L2-4)
-bmad architect solutioning-gate-check # Final approval (L3-4)
-
-# Phase 4: Implementation (All Levels)
-bmad sm sprint-planning # FIRST: Initialize tracking
-bmad sm epic-tech-context # Create epic context
-bmad sm create-story # Draft story
-bmad sm story-context # Create story context
-bmad dev dev-story # Implement story
-bmad sm code-review # Review implementation
-# (Manually update sprint-status.yaml to 'done')
-bmad sm retrospective # After epic completion
-bmad sm correct-course # If issues arise
-
-# Test Architect (Integration Throughout)
-bmad tea test-design # Plan testing strategy
-bmad tea test-review # Validate test coverage
-bmad tea nfr-assess # Check performance/security
-```
-
-## Key Files Reference
-
-### Documentation Phase
-
-- `docs/index.md` - **Master documentation index (REQUIRED for AI agents)** - Primary entry point
-- `docs/project-overview.md` - Executive summary
-- `docs/architecture.md` - Architecture analysis
-- `docs/source-tree-analysis.md` - Annotated directory structure
-- `docs/api-contracts.md` - API documentation (if applicable)
-- `docs/data-models.md` - Database schemas (if applicable)
-- `docs/deep-dive-{area}.md` - Area-specific deep dives
-- Existing docs (README.md, ARCHITECTURE.md, etc.) - Incorporated and linked from index
-
-### Planning Phase
-
-- `bmm-workflow-status.md` - Phase 0-3 tracking
-- `PRD.md` - Product requirements (L2-4)
-- `epics.md` - Epic breakdown (L2-4)
-- `tech-spec.md` - Technical specification (L0-2)
-
-### Solutioning Phase
-
-- `architecture.md` - Architecture extensions (L2-4)
-- `integration-strategy.md` - Integration planning (L3-4)
-- Validation and gate check reports
-
-### Implementation Phase
-
-- `sprint-status.yaml` - **Single source of truth** for Phase 4
-- `epic-{n}-context.md` - Epic technical contexts
-- `stories/{epic}-{story}-{title}.md` - Story files
-- `stories/{epic}-{story}-{title}-context.md` - Story contexts
-
-## Comparison: v4 vs v6 Brownfield
-
-### What Changed
-
-**v4 Approach:**
-
-- Task-based system with fixed workflows
-- Manual tracking across multiple documents
-- Heavy upfront documentation requirements
-- Rigid phase progression
-
-**v6 Improvements:**
-
-- Scale-adaptive workflows (0-4 levels)
-- Unified status tracking (`workflow-status`, `sprint-status.yaml`)
-- Three-level scanning (quick/deep/exhaustive)
-- Just-in-time context injection
-- Flexible resumability
-- Modular workflow paths
-- Intelligent routing system
-
-### Migration from v4
-
-If you used BMad Method v4, here's how to transition:
-
-**Old v4 Task β New v6 Workflow:**
-
-- `create-brownfield-prd` β `prd` (with brownfield path)
-- `document-project` β `document-project` (enhanced with scan levels)
-- Legacy task templates β Replaced by workflow system
-- Manual status tracking β `sprint-status.yaml` + agents
-
-**Key Conceptual Shifts:**
-
-1. **Scale-adaptive planning** - Choose level based on complexity
-2. **Phase 0 is conditional** - Only if documentation is lacking
-3. **Sprint status is centralized** - Single YAML file for Phase 4
-4. **Context injection** - Epic and story contexts provide JIT guidance
-5. **Workflow paths** - Clean separation by level and field type
-
-## Tips for Success
-
-### For Solo Developers
-
-1. Don't skip documentation phase - even if you know the code, AI agents need it
-2. Choose appropriate scan level - deep scan is usually best for brownfield PRDs
-3. Use Level 0-1 for small changes - don't over-engineer simple fixes
-4. Trust the sprint planning system - it tracks everything automatically
-5. Be specific when describing your work - helps system route to the right level
-
-### For Teams
-
-1. Document once, use everywhere - Phase 0 documentation serves entire team
-2. Use sprint-status.yaml as single source of truth - no multiple tracking systems
-3. Run retrospectives after epics - transfer learning to next stories
-4. Coordinate parallel work - multiple stories can be in-progress if capacity allows
-5. Establish clear communication about current iteration scope vs historical complexity
-
-### For Enterprise
-
-1. Phase 0 is mandatory - comprehensive documentation prevents costly mistakes
-2. Include stakeholders early - Analysis phase (Phase 1) gathers business context
-3. Use gate checks - `solutioning-gate-check` provides approval checkpoint
-4. Plan phased rollout - feature flags and migration strategies are critical
-5. Document architectural extensions - maintain system documentation as you evolve
-6. Consider archiving completed planning artifacts to keep workspace clean
-
-## Support and Resources
-
-**Documentation:**
-
-- [BMM Workflows Guide](../src/modules/bmm/workflows/README.md) - Complete v6 workflow reference
-- [Test Architect Guide](../src/modules/bmm/testarch/README.md) - Quality and testing strategy
-- [BMM Module README](../src/modules/bmm/README.md) - Module overview
-
-**Community:**
-
-- Discord: [https://discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj) (#general-dev, #bugs-issues)
-- GitHub Issues: [https://github.com/bmad-code-org/BMAD-METHOD/issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
-- YouTube: [https://www.youtube.com/@BMadCode](https://www.youtube.com/@BMadCode)
-
-**Getting Started:**
-
-```bash
-# Install BMad Method
-npx bmad-method install
-
-# Start your first brownfield project
-cd your-project
-bmad analyst workflow-status
-```
-
----
-
-## Remember
-
-**Brownfield development** is about understanding and respecting what exists while thoughtfully extending it. BMad Method v6's scale-adaptive approach ensures you get the right level of planning and documentation without unnecessary overhead.
-
-**Key Principles:**
-
-1. **Ask First, Infer Second**: The system asks about YOUR work first, then uses artifacts as context
-2. **Scale Adapts**: From single fixes (Level 0) to enterprise expansions (Level 4)
-3. **Documentation Matters**: AI agents need comprehensive context to work effectively
-4. **Context Injection**: Epic and story contexts provide just-in-time guidance
-5. **Sprint-Based Tracking**: Single source of truth keeps everyone aligned
-
-**Quick Start:**
-
-```bash
-cd your-brownfield-project
-bmad analyst workflow-status
-
-# System will guide you through:
-# 1. What's your project called?
-# 2. What are you working on? (if finds old work: "is this continuing old work or new work?")
-# 3. Confirms detected level
-# 4. Creates appropriate workflow
-```
-
-**The system is designed to understand YOUR current work and route you to the right workflows.**
diff --git a/src/modules/bmm/docs/enterprise-agentic-development.md b/src/modules/bmm/docs/enterprise-agentic-development.md
index c531e983..125bcd98 100644
--- a/src/modules/bmm/docs/enterprise-agentic-development.md
+++ b/src/modules/bmm/docs/enterprise-agentic-development.md
@@ -1,20 +1,19 @@
# Enterprise Agentic Development with BMad Method
-**Understanding the paradigm shift from traditional to AI-assisted team development**
+**The paradigm shift: From team-based story parallelism to individual epic ownership**
-**Reading Time:** ~25 minutes
+**Reading Time:** ~18 minutes
---
## Table of Contents
- [The Paradigm Shift](#the-paradigm-shift)
-- [Traditional vs Agentic Development](#traditional-vs-agentic-development)
+- [The Evolving Role of Product Managers & UX Designers](#the-evolving-role-of-product-managers--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](#enterprise-configuration)
-- [Git Submodule Approach](#git-submodule-approach)
-- [Team Workflows](#team-workflows)
+- [Enterprise Configuration with Git Submodules](#enterprise-configuration-with-git-submodules)
- [Best Practices](#best-practices)
- [Common Scenarios](#common-scenarios)
@@ -22,110 +21,306 @@
## The Paradigm Shift
-### Traditional Agile Development
+### Traditional Agile: Team-Based Story Parallelism
-In classic agile teams:
+- **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
-- **Epic duration:** Multiple sprints (4-12 weeks)
-- **Story duration:** 2-5 days per developer, sometimes 2 weeks
-- **Team size:** 5-9 developers per epic
-- **Parallelization:** Multiple developers work on stories within same epic
-- **Velocity:** 20-40 story points per 2-week sprint (team)
-- **Epic delivery:** Months for complex features
+**Example:** Payment Processing Epic
-### Agentic Development with BMM
+- 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
-With AI-assisted development:
+### Agentic Development: Individual Epic Ownership
- **Epic duration:** Hours to days (not weeks)
-- **Story duration:** 30 minutes to 4 hours per developer+agent
-- **Team size:** 1-2 developers can complete full epics
+- **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
-- **Velocity:** What took months now takes days
-- **Epic delivery:** Days for complex features, hours for simple ones
+- **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
-**Traditional:** Stories are sized for human developers working alone
-**Agentic:** Stories are sized for human+AI collaboration, dramatically increasing throughput
+**What changed:** AI agents collapse story duration from days to hours, making **epic-level ownership** practical.
-**Result:** A single developer with AI agents can now complete in one day what previously required a full team and multiple sprints.
+**Impact:** Single developer with BMad Method can deliver in 1 day what previously required full team and multiple sprints.
---
-## Traditional vs Agentic Development
+## The Evolving Role of Product Managers & UX Designers
-### Story Complexity Comparison
+### The Future is Now
-**Traditional Agile Story (2-week duration):**
+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.
-```markdown
-## User Story: Add Payment Processing
+### From Spec Writers to Code Orchestrators
-As a user, I want to process payments so I can complete purchases.
+**Traditional PM/UX (Pre-2025):**
-### Tasks
+- Write PRDs, hand off to engineering
+- Wait weeks/months for implementation
+- Limited validation capabilities
+- Non-technical role, heavy on process
-- Research payment gateway options (2 days)
-- Design API integration (1 day)
-- Implement backend payment service (3 days)
-- Create frontend payment form (2 days)
-- Add validation and error handling (1 day)
-- Write unit tests (1 day)
-- Write integration tests (1 day)
-- Security review (1 day)
+**Emerging PM/UX (2025+):**
-**Estimate:** 10-12 days (2 weeks)
+- 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
```
-**BMM Agentic Story (2-4 hours):**
+**BMad produces:**
-```markdown
-## Story 1: Implement Stripe Payment Backend API
+- Structured, machine-readable requirements
+- Testable acceptance criteria per requirement
+- Clear epic/story decomposition
+- Technical context for AI agents
-**Epic:** Payment Processing
-**Estimate:** 2h with AI agent
+**Why it matters:** Traditional PRDs are human-readable prose. BMad PRDs are **AI-executable work packages**.
-### Context
+**PM Value:** Write once, automatically translated into agent-ready stories. No engineering bottleneck for translation.
-- Use existing /api pattern
-- Follow auth middleware conventions
-- Integrate with Stripe SDK (already in package.json)
+### 2. Automated Epic/Story Breakdown
-### Acceptance Criteria
+**PM Workflow:**
-- POST /api/payments/charge endpoint
-- Validation middleware
-- Error handling per API standards
-- Unit tests with 80%+ coverage
+```bash
+bmad pm *create-epics-and-stories
```
-The epic is broken into 6-8 small stories instead of 1 large story. Each story takes 2-4 hours instead of 2 weeks.
+**BMad produces:**
-### Epic Delivery Comparison
+- Epic files with clear objectives
+- Story files with acceptance criteria, context, technical guidance
+- Priority assignments (P0-P3)
+- Dependency mapping
-**Traditional Epic: "Payment Processing" (8-12 weeks)**
+**Why it matters:** Stories become **work packages for cloud AI agents**. Each story is self-contained with full context.
-- Sprint 1-2: Payment gateway research and design
-- Sprint 3-4: Backend implementation
-- Sprint 5-6: Frontend implementation
-- Sprint 7-8: Testing, security, deployment
-- **Team:** 3-5 developers
-- **Total:** 2-3 months
+**PM Value:** No more "story refinement sessions" with engineering. AI agents execute directly from BMad stories.
-**Agentic Epic: "Payment Processing" (1-3 days)**
+### 3. Human-in-the-Loop Architecture
-- Day 1 AM: Backend API stories (3-4 stories)
-- Day 1 PM: Frontend integration stories (2-3 stories)
-- Day 2: Testing, security validation (2-3 stories)
-- **Team:** 1-2 developers + AI agents
-- **Total:** 1-3 days
+**Architect/PM Workflow:**
+
+```bash
+bmad architect *create-architecture
+```
+
+**BMad produces:**
+
+- System architecture aligned with PRD
+- Architecture Decision Records (ADRs)
+- Epic-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.
+
+### 4. Cloud Agentic Pipeline (Emerging Pattern)
+
+**Current State (2025):**
+
+```
+PM writes BMad PRD
+ β
+create-epics-and-stories generates story queue
+ β
+Stories loaded by human developers + BMad agents
+ β
+Developers create PRs
+ β
+PM/Team reviews PRs
+ β
+Merge and deploy
+```
+
+**Near Future (2026):**
+
+```
+PM writes BMad PRD
+ β
+create-epics-and-stories generates story queue
+ β
+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-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 (via story-context)
+- Code standards applied uniformly (via epic-tech-context)
+- 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: Stories as Work Units
+### Old Pattern: Story Parallelism
**Traditional Agile:**
@@ -133,16 +328,13 @@ The epic is broken into 6-8 small stories instead of 1 large story. Each story t
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 Visualization (Dev C, Sprint 2-3)
-ββ Story 4: User Preferences (Dev D, Sprint 3-4)
-ββ Story 5: Integration Testing (Team, Sprint 4)
+ββ Story 3: Data Viz (Dev C, Sprint 2-3)
+ββ Story 4: Integration Testing (Team, Sprint 3-4)
-Team: 4 developers working in parallel on stories within one epic
+Challenge: Coordination overhead, merge conflicts, integration issues
```
-**Challenge:** Coordination overhead, merge conflicts, integration issues
-
-### New Pattern: Epics as Work Units
+### New Pattern: Epic Ownership
**Agentic Development:**
@@ -150,662 +342,207 @@ Team: 4 developers working in parallel on stories within one epic
Project: Analytics Platform (2-3 weeks)
Developer A:
-ββ Epic 1: User Dashboard (3 days, 12 stories)
-β ββ Stories completed sequentially with AI agents
+ββ Epic 1: User Dashboard (3 days, 12 stories sequentially with AI)
Developer B:
-ββ Epic 2: Admin Panel (4 days, 15 stories)
-β ββ Stories completed sequentially with AI agents
+ββ Epic 2: Admin Panel (4 days, 15 stories sequentially with AI)
Developer C:
-ββ Epic 3: Reporting Engine (5 days, 18 stories)
-β ββ Stories completed sequentially with AI agents
+ββ Epic 3: Reporting Engine (5 days, 18 stories sequentially with AI)
-Team: 3 developers working in parallel on separate epics
+Benefit: Minimal coordination, epic-level ownership, clear boundaries
```
-**Benefits:** Minimal coordination, epic-level ownership, clear boundaries
-
---
## Work Distribution Strategies
-### Strategy 1: Epic-Based Distribution (Recommended)
+### Strategy 1: Epic-Based (Recommended)
-**Best for:** Teams of 2-10 developers
+**Best for:** 2-10 developers
-**Approach:**
-
-- Each developer owns complete epics
-- Work sequentially through stories within epic
-- Parallel work happens at epic level
+**Approach:** Each developer owns complete epics, works sequentially through stories
**Example:**
```yaml
-# sprint-status.yaml
epics:
- id: epic-1
title: Payment Processing
owner: alice
- status: in-progress
stories: 8
+ estimate: 2 days
- id: epic-2
title: User Dashboard
owner: bob
- status: in-progress
stories: 12
-
- - id: epic-3
- title: Admin Panel
- owner: carol
- status: backlog
- stories: 10
+ estimate: 3 days
```
-**Benefits:**
+**Benefits:** Clear ownership, minimal conflicts, epic cohesion, reduced coordination
-- Clear ownership and accountability
-- Minimal merge conflicts
-- Epic-level cohesion
-- Reduced coordination overhead
+### Strategy 2: Layer-Based
-### Strategy 2: Layer-Based Distribution
-
-**Best for:** Full-stack applications, teams with specialized skills
-
-**Approach:**
-
-- Split epics by architectural layer
-- Frontend and backend as separate epics
-- Each developer owns their layer
+**Best for:** Full-stack apps, specialized teams
**Example:**
```
-Project: E-commerce Platform
-
-Frontend Developer:
-ββ Epic 1: Product Catalog UI (3 days)
-ββ Epic 3: Shopping Cart UI (2 days)
-ββ Epic 5: Checkout Flow UI (3 days)
-
-Backend Developer:
-ββ Epic 2: Product API (2 days)
-ββ Epic 4: Cart Service (2 days)
-ββ Epic 6: Payment Processing (3 days)
+Frontend Dev: Epic 1 (Product Catalog UI), Epic 3 (Cart UI)
+Backend Dev: Epic 2 (Product API), Epic 4 (Cart Service)
```
-**Note:** This is abnormal in traditional agile (vertical slicing preferred), but works well in agentic development due to speed of delivery.
+**Benefits:** Developers in expertise area, true parallel work, clear API contracts
-**Benefits:**
+**Requirements:** Strong architecture phase, clear API contracts upfront
-- Developers work in their expertise area
-- Can work truly in parallel
-- Clear API contracts between layers
+### Strategy 3: Feature-Based
-**Considerations:**
-
-- Requires clear API contracts upfront
-- Need integration testing coordination
-- Best with strong architecture phase
-
-### Strategy 3: Feature-Based Distribution
-
-**Best for:** Large teams (10+ developers), enterprise projects
-
-**Approach:**
-
-- Group related epics into features
-- Each developer/pod owns feature set
-- Features can span multiple subsystems
+**Best for:** Large teams (10+ developers)
**Example:**
```
-Feature Team A (2 devs): Payments & Billing
-ββ Epic 1: Payment Processing
-ββ Epic 2: Subscription Management
-ββ Epic 3: Invoice Generation
-ββ Epic 4: Billing Dashboard
-
-Feature Team B (2 devs): User Management
-ββ Epic 5: Authentication
-ββ Epic 6: Authorization
-ββ Epic 7: User Profiles
-ββ Epic 8: Account Settings
-
-Feature Team C (2 devs): Analytics
-ββ Epic 9: Event Tracking
-ββ Epic 10: Reporting Engine
-ββ Epic 11: Dashboard Widgets
+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
+## Enterprise Configuration with Git Submodules
-### Challenge: Personalized BMM Content in Shared Repos
+### The Challenge
-**Problem:**
+**Problem:** Teams customize BMad (agents, workflows, configs) but don't want personal tooling in main repo.
-- Developers may customize agents, workflows, or configurations
-- Teams may use different methodologies (BMM, custom, other frameworks)
-- Organizations don't want personalized tooling committed to main repo
-- Different developers use different AI tools, MCPs, or agent systems
+**Anti-pattern:** Adding `bmad/` to `.gitignore` breaks IDE tools, submodule management.
-**Anti-pattern (Don't do this):**
-
-```bash
-# .gitignore approach - breaks many tools
-bmad/
-.claude/
-```
-
-**Issues with .gitignore:**
-
-- IDE tools lose track of context
-- Submodule management breaks
-- Team can't optionally share configurations
-- Hard to version control shared vs personal configs
-
-### Solution: Git Submodules
-
-**Recommended approach:** Install BMM as a git submodule that each developer controls independently.
-
----
-
-## Git Submodule Approach
-
-### Why Submodules?
+### The Solution: Git Submodules
**Benefits:**
-- BMM content exists in project but tracked separately
-- Each developer controls their own BMM version/configuration
-- Optional: Share team configurations via separate repo
+- 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
-- Cleaner than .gitignore for this use case
-### Setup for New Projects
+### Setup (New Projects)
-**1. Create BMM submodule (optional team config repo):**
+**1. Create optional team config repo:**
```bash
-# In your organization
git init bmm-config
cd bmm-config
npx bmad-method install
# Customize for team standards
-git add .
-git commit -m "Initial BMM configuration for team"
+git commit -m "Team BMM config"
git push origin main
```
-**2. Add submodule to main project:**
+**2. Add submodule to project:**
```bash
-# In your main project repo
cd /path/to/your-project
-
-# Add BMM as submodule (using team config repo)
git submodule add https://github.com/your-org/bmm-config.git bmad
-
-# Or add as submodule (using official BMM)
-git submodule add https://github.com/bmad-code-org/BMAD-METHOD.git bmad
-
-# Commit submodule reference
-git add .gitmodules bmad
git commit -m "Add BMM as submodule"
```
-**3. Team members clone and initialize:**
+**3. Team members initialize:**
```bash
-# Clone main project
git clone https://github.com/your-org/your-project.git
cd your-project
-
-# Initialize submodule
git submodule update --init --recursive
-
-# Each developer can now customize their bmad/ without affecting others
-cd bmad
-# Make personal customizations
-# These changes stay local unless pushed to submodule repo
+# Make personal customizations in bmad/
```
-### Setup for Existing Projects
+### Daily Workflow
-**If BMM already installed directly:**
+**Work in main project:**
```bash
-# 1. Backup existing BMM
-mv bmad bmad-backup
-
-# 2. Add as submodule
-git submodule add https://github.com/your-org/bmm-config.git bmad
-
-# 3. Restore customizations
-cp -r bmad-backup/bmad/_cfg/agents/*.customize.yaml bmad/bmad/_cfg/agents/
-
-# 4. Clean up
-rm -rf bmad-backup
-
-# 5. Commit
-git add .gitmodules bmad
-git commit -m "Convert BMM to submodule"
-```
-
-### Submodule Workflow
-
-**Daily development:**
-
-```bash
-# Work in main project - submodule is just there
cd /path/to/your-project
-# BMM content available at ./bmad/
-# Load agents, run workflows normally
+# BMad available at ./bmad/, load agents normally
```
-**Update personal BMM config:**
+**Update personal config:**
```bash
cd bmad
-# Make changes to your personal config
-git add .
-git commit -m "Personal agent customizations"
-# Don't push unless sharing with team
+# Make changes, commit locally, don't push unless sharing
```
-**Update to latest team BMM config:**
+**Update to latest team config:**
```bash
cd bmad
git pull origin main
-cd ..
-git add bmad
-git commit -m "Update BMM to latest team config"
```
-**Share configuration with team:**
+### Configuration Strategies
-```bash
-cd bmad
-# Make team-beneficial changes
-git add .
-git commit -m "Add shared epic template for our domain"
-git push origin main
-# Tell team to update their submodules
-```
+**Option 1: Fully Personal** - No submodule, each dev installs independently, use `.gitignore`
-### Team Configuration Sharing
+**Option 2: Team Baseline + Personal** - Submodule has team standards, devs add personal customizations locally
-**Option 1: Fully Personal (No sharing)**
-
-```bash
-# Each developer's bmad/ is independent
-# No submodule repo - just local installation
-# Use .gitignore for bmad/ (acceptable here)
-```
-
-**Option 2: Team Baseline + Personal Customization**
-
-```bash
-# Submodule repo has team standards
-# bmad/bmad/_cfg/agents/pm.customize.yaml (team)
-# Each dev adds personal customizations locally
-# Personal changes not pushed to submodule
-```
-
-**Option 3: Full Team Sharing**
-
-```bash
-# All configurations in submodule repo
-# Team collaborates on agent improvements
-# Everyone pulls updates regularly
-```
-
-### Multi-Tool Teams
-
-**Scenario:** Team uses different AI tools (Claude Code, Cursor, Windsurf, custom)
-
-**Approach:**
-
-```
-bmad/
-ββ bmad/_cfg/
-β ββ ides/
-β β ββ claude-code.yaml (shared)
-β β ββ cursor.yaml (shared)
-β β ββ windsurf.yaml (shared)
-β ββ agents/
-β ββ pm.customize.yaml (personal - not in submodule)
-β ββ architect.customize.yaml (personal - not in submodule)
-ββ .claude/
- ββ commands/ (generated, IDE-specific)
-```
-
-**Each developer:**
-
-- Uses submodule for core BMM content
-- Personalizes IDE-specific configurations locally
-- Optionally shares improvements back to submodule
-
----
-
-## Team Workflows
-
-### Workflow 1: Epic Assignment
-
-**Phase 2: Planning Complete**
-
-```bash
-# After PRD + Architecture complete
-# Team lead or PM reviews epics
-
-# sprint-status.yaml
-epics:
- - id: epic-1
- title: Payment Processing
- owner: unassigned
- stories: 8
- - id: epic-2
- title: User Dashboard
- owner: unassigned
- stories: 12
-```
-
-**Epic Assignment Meeting:**
-
-1. Review epic scope and dependencies
-2. Assign epics to developers based on expertise/capacity
-3. Identify any epic dependencies (must be sequential)
-4. Update sprint-status.yaml with assignments
-
-**Result:**
-
-```yaml
-epics:
- - id: epic-1
- title: Payment Processing
- owner: alice
- dependencies: []
-
- - id: epic-2
- title: User Dashboard
- owner: bob
- dependencies: [epic-1] # Needs payment API
-```
-
-### Workflow 2: Daily Development
-
-**Developer's daily flow:**
-
-```bash
-# 1. Check epic status
-cat docs/sprint-status.yaml
-
-# 2. Load SM agent, run epic-tech-context (if first story)
-# Creates epic-specific technical guidance
-
-# 3. Load SM agent, run create-story
-# Creates next story in epic
-
-# 4. Load SM agent, run story-context
-# Generates implementation context
-
-# 5. Load DEV agent, run dev-story
-# Implement story (30min - 4hrs)
-
-# 6. Load DEV agent, run code-review
-# Review implementation
-
-# 7. Load SM agent, run story-done
-# Mark complete, advance queue
-
-# 8. Repeat steps 3-7 until epic complete
-
-# 9. Load SM agent, run retrospective
-# Epic retrospective
-```
-
-**Typical day for developer:**
-
-- Complete 3-8 stories (one epic, or partial epic)
-- Push code at epic boundaries or daily
-- Minimal coordination needed
-
-### Workflow 3: Integration Points
-
-**When epics have dependencies:**
-
-**Epic 1 (Backend - Alice) complete:**
-
-```bash
-# Alice commits and pushes
-git add .
-git commit -m "feat: complete Payment Processing epic (epic-1)"
-git push origin feature/payment-processing
-
-# Updates team
-# "Epic 1 complete - payment API ready at /api/payments/*"
-```
-
-**Epic 2 (Frontend - Bob) ready to start:**
-
-```bash
-# Bob pulls latest
-git pull origin main # After Alice's PR merged
-
-# Runs epic-tech-context with updated codebase
-# Context now includes Alice's payment API
-
-# Proceeds with stories
-```
-
-### Workflow 4: Code Review in Teams
-
-**Two approaches:**
-
-**Approach A: Epic-Level Review**
-
-- Developer completes entire epic
-- Opens PR for epic
-- Team reviews full epic implementation
-- Faster, maintains epic cohesion
-
-**Approach B: Story-Level Review**
-
-- Developer commits after each story
-- Opens PR per story or after N stories
-- More granular feedback
-- Better for learning teams
-
-**Recommended:** Epic-level review for experienced teams, story-level for learning teams.
+**Option 3: Full Team Sharing** - All configs in submodule, team collaborates on improvements
---
## Best Practices
-### 1. Epic Ownership & Accountability
+### 1. Epic Ownership
-**Do:**
-
-- Assign entire epic to one developer
-- Developer owns epic from context β stories β implementation β retrospective
-- Clear epic boundaries minimize conflicts
-
-**Don't:**
-
-- Split epic across multiple developers (coordination overhead)
-- Reassign epics mid-implementation (context loss)
+- **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 required API contracts between dependent epics
-- Complete prerequisite epics before starting dependent ones
-- Use feature flags if parallel work needed
-
-**Don't:**
-
-- Assume epics are fully independent
-- Start dependent epic before prerequisite ready
-- Change API contracts without team coordination
+- **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 agile:** Daily standups essential for coordination
+**Traditional:** Daily standups essential
+**Agentic:** Lighter coordination
-**Agentic development:** Lighter coordination needed
+**Recommended:**
-**Recommended cadence:**
-
-- **Daily async updates:** "Epic 1, 60% complete, no blockers"
-- **Twice-weekly sync:** 15min check-in on progress/blockers
-- **Epic completion sync:** Brief demo, integration discussion
-- **Sprint retro:** After all epics complete
+- 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
-**Feature branches per epic:**
-
```bash
-# Each developer works on epic branch
feature/epic-1-payment-processing (Alice)
feature/epic-2-user-dashboard (Bob)
feature/epic-3-admin-panel (Carol)
# PR and merge when epic complete
-# Or: commit per story, PR at epic completion
```
-**Benefits:**
-
-- Clean separation of work
-- Easy to review epic as unit
-- Simple rollback if needed
-
### 5. Testing Strategy
-**Story-level:**
-
-- Unit tests per story (DoD requirement)
-- Agent writes tests during dev-story
-
-**Epic-level:**
-
-- Integration tests across epic stories
-- Create "Epic Integration Testing" story at epic end
-
-**Project-level:**
-
-- E2E tests after multiple epics complete
-- Can be separate epic: "E2E Test Suite"
+- **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 updates:**
+- **Real-time:** `sprint-status.yaml` updated by workflows
+- **Epic completion:** Update architecture docs, API docs, README if changed
+- **Sprint completion:** Incorporate retrospective insights
-- `sprint-status.yaml` - Updated by story-done workflow
-- Story files - Updated by agents during implementation
+### 7. Metrics (Different from Traditional)
-**Epic completion:**
-
-- Architecture docs - Update if epic changed architecture
-- API docs - Update if epic added/modified APIs
-- README - Update if epic affects setup/usage
-
-**Sprint completion:**
-
-- Retrospective insights incorporated
-- Lessons learned documented
-
-### 7. Submodule Maintenance
-
-**Weekly:**
-
-- Check for BMM updates (if using official as submodule)
-- Pull team configuration changes (if using team config)
-
-**Monthly:**
-
-- Review customizations (are they still needed?)
-- Share useful customizations with team
-- Clean up unused configurations
-
-**Per project:**
-
-- Initialize submodule for new team members
-- Document any project-specific BMM configurations
-
-### 8. Handling Conflicts
-
-**Scenario:** Two epics modify same file
-
-**Prevention:**
-
-- Architecture phase should identify shared code
-- Create "shared component" epic that runs first
-- Or: use feature flags and modular design
-
-**Resolution:**
-
-```bash
-# Epic 1 complete, merged to main
-# Epic 2 encounters conflict
-
-# Developer updates branch
-git checkout feature/epic-2
-git merge main
-# Resolve conflicts manually
-# Re-run affected story tests
-git add .
-git commit -m "Merge main, resolve conflicts"
-```
-
-### 9. Scaling to Large Teams
-
-**10-20 developers:**
-
-- Organize into feature pods (2-4 devs per pod)
-- Each pod owns related epics
-- Pod-level coordination, minimal cross-pod
-
-**20+ developers:**
-
-- Multiple product areas
-- Each area has own PRD, architecture
-- Areas can work fully independently
-- Quarterly integration points
-
-**100+ developers:**
-
-- Multiple products/services
-- Each uses BMM independently
-- Shared component teams provide APIs
-- Microservices architecture essential
-
-### 10. Metrics & Velocity
-
-**Track differently than traditional agile:**
-
-**Traditional metrics:**
-
-- Story points per sprint (team)
-- Velocity trends
-- Burndown charts
-
-**Agentic metrics:**
-
-- Epics per week (per developer)
-- Stories per day (per developer)
-- Time to epic completion
-- Code quality metrics (test coverage, review findings)
+**Traditional:** Story points per sprint, burndown charts
+**Agentic:** Epics per week, stories per day, time to epic completion
**Example velocity:**
@@ -817,126 +554,51 @@ git commit -m "Merge main, resolve conflicts"
## Common Scenarios
-### Scenario 1: Startup (2-3 developers)
+### Scenario 1: Startup (2 Developers)
**Project:** SaaS MVP (Level 3)
-**Team:**
-
-- Developer A (Full-stack, tech lead)
-- Developer B (Full-stack)
-
**Distribution:**
```
Developer A:
-ββ Epic 1: Authentication & User Management (3 days)
+ββ 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 & Reporting (3 days)
-ββ Epic 6: Notification System (2 days)
+ββ Epic 4: Analytics (3 days)
+ββ Epic 6: Notifications (2 days)
-Total: ~2 weeks with parallel work
-Traditional estimate: 3-4 months with same team
+Total: ~2 weeks
+Traditional estimate: 3-4 months
```
-**Coordination:**
+**BMM Setup:** Direct installation, both use Claude Code, minimal customization
-- Daily async Slack updates
-- Weekly 30min sync call
-- Epic completion demos
-- Shared docs/sprint-status.yaml in main repo
+### Scenario 2: Mid-Size Team (8 Developers)
-**BMM Setup:**
-
-- BMM installed directly (small team, shared approach)
-- Both use Claude Code
-- Minimal customization needed
-
----
-
-### Scenario 2: Mid-Size Team (8-10 developers)
-
-**Project:** Enterprise Platform Enhancement (Level 4)
-
-**Team:**
-
-- 2 Backend developers
-- 2 Frontend developers
-- 2 Full-stack developers
-- 1 DevOps engineer
-- 1 QA engineer (E2E testing epic)
+**Project:** Enterprise Platform (Level 4)
**Distribution (Layer-Based):**
```
-Backend Team:
-Developer 1:
-ββ Epic 1: Payment Service API (3 days)
-ββ Epic 3: Subscription Service (3 days)
-ββ Epic 5: Webhook System (2 days)
+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
-Developer 2:
-ββ Epic 2: User Management API (3 days)
-ββ Epic 4: Analytics API (3 days)
-ββ Epic 6: Admin API (2 days)
-
-Frontend Team:
-Developer 3:
-ββ Epic 7: Payment UI (2 days)
-ββ Epic 9: Subscription Dashboard (3 days)
-ββ Epic 11: User Settings (2 days)
-
-Developer 4:
-ββ Epic 8: Analytics Dashboard (3 days)
-ββ Epic 10: Admin Panel (3 days)
-ββ Epic 12: Notification Center (2 days)
-
-Full-Stack Team:
-Developer 5:
-ββ Epic 13: Real-time Features (4 days)
-ββ Epic 15: Search System (3 days)
-
-Developer 6:
-ββ Epic 14: Reporting Engine (4 days)
-ββ Epic 16: Export Functionality (3 days)
-
-DevOps:
-Developer 7:
-ββ Epic 17: CI/CD Pipeline (3 days)
-ββ Epic 18: Monitoring & Alerts (2 days)
-ββ Epic 19: Performance Optimization (3 days)
-
-QA:
-Developer 8:
-ββ Epic 20: E2E Test Suite (5 days, after others complete)
-
-Total: ~3 weeks with parallel work
-Traditional estimate: 9-12 months with same team
+Total: ~3 weeks
+Traditional estimate: 9-12 months
```
-**Coordination:**
+**BMM Setup:** Git submodule, team config repo, mix of Claude Code/Cursor users
-- Bi-weekly sprint planning (epic assignment)
-- Async daily updates in Slack
-- Epic completion PRs reviewed by tech lead
-- Weekly integration testing
+### Scenario 3: Large Enterprise (50+ Developers)
-**BMM Setup:**
-
-- Git submodule approach
-- Team config repo with shared baselines
-- Personal customizations local only
-- Mix of Claude Code, Cursor users
-
----
-
-### Scenario 3: Large Enterprise (50+ developers)
-
-**Project:** Multi-Product Platform (Multiple Level 4 projects)
+**Project:** Multi-Product Platform
**Organization:**
@@ -947,94 +609,72 @@ Traditional estimate: 9-12 months with same team
**Distribution (Feature-Based):**
```
-Product Team A: Payments Product
-ββ 10 epics across 8 developers
-ββ 2-week delivery
+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)
-Product Team B: User Management Product
-ββ 12 epics across 10 developers
-ββ 2-week delivery
+Platform Team: Shared Services (continuous)
+Infrastructure Team: DevOps (continuous)
-Product Team C: Analytics Product
-ββ 8 epics across 8 developers
-ββ 1.5-week delivery
-
-Product Team D: Admin Tools
-ββ 10 epics across 8 developers
-ββ 2-week delivery
-
-Product Team E: Mobile Apps
-ββ 15 epics across 10 developers
-ββ 3-week delivery
-
-Platform Team: Shared Services
-ββ 15 epics across 10 developers
-ββ Continuous delivery
-
-Infrastructure Team: DevOps & Platform
-ββ 8 epics across 5 developers
-ββ Continuous delivery
+Total: 3-4 months
+Traditional estimate: 2-3 years
```
-**Coordination:**
-
-- Product teams work independently
-- Platform team provides APIs, runs 1 week ahead
-- Quarterly integration milestones
-- Automated testing & deployment
-
-**BMM Setup:**
-
-- Each team has own submodule config
-- Org-wide base configuration repo
-- Team-specific customizations in team repos
-- Variety of IDE tools (Claude Code, Cursor, Windsurf, VS Code + extensions)
-
-**Traditional estimate:** 2-3 years with same team size
-**Agentic delivery:** 3-4 months
+**BMM Setup:** Each team has own submodule config, org-wide base config, variety of IDE tools
---
## Summary
-### Key Takeaways
+### Key Transformation
-1. **Epics are the new stories** - Work distribution happens at epic level, not story level
-2. **Velocity transformation** - What took months now takes days
-3. **Team scaling** - Smaller teams can deliver enterprise-scale projects
-4. **Git submodules** - Best practice for enterprise BMM management
-5. **Reduced coordination** - Epic ownership minimizes coordination overhead
-6. **Layer splitting viable** - Frontend/backend epic splits work well at high velocity
-7. **Tool flexibility** - Teams can use different AI tools with same BMM foundation
+**Work Unit Changed:**
-### The Bottom Line
+- **Old:** Story = unit of work assignment
+- **New:** Epic = unit of work assignment
-**Traditional Agile:**
+**Why:** AI agents collapse story duration (days β hours), making epic ownership practical.
-- Story = Unit of work assignment
-- Multiple developers per epic
-- Coordination intensive
-- Months for epic delivery
+### Velocity Impact
-**Agentic Development:**
+- **Traditional:** Months for epic delivery, heavy coordination
+- **Agentic:** Days for epic delivery, minimal coordination
+- **Result:** 10-50Γ productivity gains
-- Epic = Unit of work assignment
-- One developer per epic
-- Minimal coordination
-- Days for epic delivery
+### PM/UX Evolution
-**Result:** Rethink team structure, work distribution, and coordination patterns for 10-50x productivity gains.
+**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)** - Understanding project levels
-- **[Quick Start Guide](./quick-start.md)** - Getting started
-- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
-- **[Glossary](./glossary.md)** - Key terminology
+- [FAQ](./faq.md) - Common questions
+- [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained
+- [Quick Start Guide](./quick-start.md) - Getting started
+- [Workflows Guide](../workflows/README.md) - Complete workflow reference
+- [Agents Guide](./agents-guide.md) - Understanding BMad agents
---
-_Agentic development fundamentally changes how we structure teams, distribute work, and coordinate efforts. Understanding these patterns is essential for enterprise success with BMM._
+_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._
diff --git a/src/modules/bmm/docs/faq.md b/src/modules/bmm/docs/faq.md
index 053eb083..ee8bd5bd 100644
--- a/src/modules/bmm/docs/faq.md
+++ b/src/modules/bmm/docs/faq.md
@@ -90,7 +90,7 @@ When in doubt, start smaller. You can always run create-prd later if needed.
### Q: Do I always need architecture for Level 2?
-**A:** No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD + epic-tech-specs created during implementation.
+**A:** No, architecture is **optional** for Level 2. Only create architecture if you need system-level design. Many Level 2 projects work fine with just PRD + epic-tech-context created during implementation.
### Q: What's the difference between Level 1 and Level 2?
@@ -162,14 +162,14 @@ If status file exists, use workflow-status. If not, use workflow-init.
## Planning Documents
-### Q: What's the difference between tech-spec and epic-tech-spec?
+### Q: What's the difference between tech-spec and epic-tech-context?
**A:**
- **Tech-spec (Level 0-1):** Created upfront in Planning Phase, serves as primary/only planning document, a combination of enough technical and planning information to drive a single or multiple files
-- **Epic-tech-spec (Level 2-4):** Created during Implementation Phase per epic, supplements PRD + Architecture
+- **Epic-tech-context (Level 2-4):** Created during Implementation Phase per epic, supplements PRD + Architecture
-Think of it as: tech-spec is for small projects (replaces PRD and architecture), epic-tech-spec is for large projects (supplements PRD).
+Think of it as: tech-spec is for small projects (replaces PRD and architecture), epic-tech-context is for large projects (supplements PRD).
### Q: Why no tech-spec at Level 2+?
@@ -177,13 +177,13 @@ Think of it as: tech-spec is for small projects (replaces PRD and architecture),
- PRD (product vision, requirements, epics)
- Architecture (system design)
-- Epic-tech-specs (detailed implementation per epic, created just-in-time)
+- Epic-tech-context (detailed implementation per epic, created just-in-time)
-### Q: When do I create epic-tech-specs?
+### Q: When do I create epic-tech-context?
-**A:** In Phase 4, right before implementing each epic. Don't create all epic-tech-specs upfront - that's over-planning. Create them just-in-time using the epic-tech-context workflow as you're about to start working on that epic.
+**A:** In Phase 4, right before implementing each epic. Don't create all epic-tech-context upfront - that's over-planning. Create them just-in-time using the epic-tech-context workflow as you're about to start working on that epic.
-**Why just-in-time?** You'll learn from earlier epics, and those learnings improve later epic-tech-specs.
+**Why just-in-time?** You'll learn from earlier epics, and those learnings improve later epic-tech-context.
### Q: Do I need a PRD for a bug fix?
@@ -270,7 +270,7 @@ The story-done workflow is faster and ensures proper status file updates.
- What went well
- What could improve
- Technical insights
-- Input for next epic-tech-spec
+- Input for next epic-tech-context
Don't wait until project end - run after each epic for continuous improvement.
@@ -520,7 +520,7 @@ Trust your expertise - BMM supports your decisions.
**How it works:**
-1. Load BMad Master β `*party-mode`
+1. Run `/bmad:core:workflows:party-mode` (or `*party-mode` from any agent)
2. Introduce your topic
3. BMad Master selects 2-3 most relevant agents per message
4. Agents cross-talk, debate, and build on each other's ideas
diff --git a/src/modules/bmm/docs/glossary.md b/src/modules/bmm/docs/glossary.md
index a062cac2..59652d1a 100644
--- a/src/modules/bmm/docs/glossary.md
+++ b/src/modules/bmm/docs/glossary.md
@@ -69,11 +69,11 @@ The methodology path (Quick Flow, BMad Method, or Enterprise Method) chosen for
**Quick Flow track only.** Comprehensive technical plan created upfront that serves as the primary planning document for small changes or features. Contains problem statement, solution approach, file-level changes, stack detection (brownfield), testing strategy, and developer resources.
-### Epic-Tech-Spec (Epic Technical Specification)
+### Epic-Tech-Context (Epic Technical Context)
**BMad Method/Enterprise tracks only.** Detailed technical planning document created during implementation (just-in-time) for each epic. Supplements PRD + Architecture with epic-specific implementation details, code-level design decisions, and integration points.
-**Key Difference:** Tech-spec (Quick Flow) is created upfront and is the only planning doc. Epic-tech-spec (BMad Method/Enterprise) is created per epic during implementation and supplements PRD + Architecture.
+**Key Difference:** Tech-spec (Quick Flow) is created upfront and is the only planning doc. Epic-tech-context (BMad Method/Enterprise) is created per epic during implementation and supplements PRD + Architecture.
### PRD (Product Requirements Document)
@@ -127,7 +127,7 @@ Fast-track workflow system for Quick Flow track projects that goes straight from
### Just-In-Time Design
-Pattern where epic-tech-specs are created during implementation (Phase 4) right before working on each epic, rather than all upfront. Enables learning and adaptation.
+Pattern where epic-tech-context is created during implementation (Phase 4) right before working on each epic, rather than all upfront. Enables learning and adaptation.
### Context Injection
@@ -161,9 +161,9 @@ Agent that implements stories, writes code, runs tests, and performs code review
Agent responsible for test strategy, quality gates, NFR assessment, and comprehensive quality assurance. Integrates throughout all phases.
-### Paige (Documentation Guide)
+### Technical Writer
-Agent specialized in creating and maintaining high-quality technical documentation. Expert in documentation standards, information architecture, and professional technical writing.
+Agent specialized in creating and maintaining high-quality technical documentation. Expert in documentation standards, information architecture, and professional technical writing. The agent's internal name is "paige" but is presented as "Technical Writer" to users.
### UX Designer
diff --git a/src/modules/bmm/docs/party-mode.md b/src/modules/bmm/docs/party-mode.md
index cfdd851d..588851d8 100644
--- a/src/modules/bmm/docs/party-mode.md
+++ b/src/modules/bmm/docs/party-mode.md
@@ -1,1235 +1,223 @@
# Party Mode: Multi-Agent Collaboration
-**Orchestrate group discussions with all your AI agents**
-
-**Reading Time:** ~20 minutes
-
----
-
-## Table of Contents
-
-- [What is Party Mode?](#what-is-party-mode)
-- [How It Works](#how-it-works)
-- [When to Use Party Mode](#when-to-use-party-mode)
-- [Getting Started](#getting-started)
-- [Agent Selection & Dynamics](#agent-selection--dynamics)
-- [Multi-Module Integration](#multi-module-integration)
-- [Example Party Compositions](#example-party-compositions)
-- [Agent Customization in Party Mode](#agent-customization-in-party-mode)
-- [Best Practices](#best-practices)
-- [Troubleshooting](#troubleshooting)
+**Get all your AI agents in one conversation**
---
## What is Party Mode?
-Party mode is a unique workflow that brings **all your installed agents together** for group discussions. Instead of working with one agent at a time, you engage with a dynamic team that collaborates in real-time.
+Ever wanted to gather your entire AI team in one room and see what happens? That's party mode.
-**Key Concept:** Multiple AI agents with different expertise discuss your challenges together, providing diverse perspectives, healthy debate, and emergent insights.
+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.
-### Quick Facts
+**Why it's useful:**
-- **Trigger:** Load BMad Master and run `*party-mode`
-- **Agents Included:** ALL installed agents from ALL modules (BMM, CIS, BMB, custom)
-- **Selection:** 2-3 most relevant agents respond per message
-- **Customization:** Respects all agent customizations
-- **Moderator:** BMad Master orchestrates and moderates
+- **After complex workflows** - Debrief with the whole team about what worked, what didn't
+- **Big decisions with tradeoffs** - Get technical, creative, and strategic perspectives simultaneously
+- **Brainstorming sessions** - Watch ideas evolve through cross-pollination
+- **When things go wrong** - Call out failures, watch agents defend their decisions, let them debate whose fault it was (oddly therapeutic)
+- **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
-### The Party Mode Process
+**The basics:**
-```mermaid
-flowchart TD
- START([User triggers party-mode])
- LOAD[Load agent manifest]
- CUSTOM[Apply customizations]
- ROSTER[Build complete agent roster]
- ACTIVATE[Announce party activation]
- TOPIC[User provides topic]
- SELECT[BMad Master selects 2-3 relevant agents]
- RESPOND[Agents respond in character]
- CROSS[Agents cross-talk and collaborate]
- MOD{Discussion
productive?}
- CONTINUE{More to
discuss?}
- EXIT[Agents provide farewells]
- END([Party mode ends])
+1. Party mode reads `bmad/_cfg/agent-manifest.csv`
+2. Loads ALL installed agents (already includes your customizations from install)
+3. BMad Master orchestrates - picks 2-3 relevant agents per message based on topic
+4. Agents respond in character, can agree/disagree/build on each other's ideas
+5. Discussion continues until you type "exit" or reach natural conclusion
- START --> LOAD
- LOAD --> CUSTOM
- CUSTOM --> ROSTER
- ROSTER --> ACTIVATE
- ACTIVATE --> TOPIC
- TOPIC --> SELECT
- SELECT --> RESPOND
- RESPOND --> CROSS
- CROSS --> MOD
- MOD -->|Yes| CONTINUE
- MOD -->|Circular| SELECT
- CONTINUE -->|Yes| SELECT
- CONTINUE -->|No| EXIT
- EXIT --> END
+**That's it.** No complex merging, no runtime magic. Just agents talking.
- style START fill:#bfb,stroke:#333,stroke-width:2px
- style ACTIVATE fill:#bbf,stroke:#333,stroke-width:2px
- style CROSS fill:#fbf,stroke:#333,stroke-width:2px
- style END fill:#fbb,stroke:#333,stroke-width:2px
-```
+---
-### Step-by-Step Breakdown
+## Quick Start
-#### 1. Agent Loading
+```bash
+# Trigger party mode
+/bmad:core:workflows:party-mode
-**Process:**
+# OR from any agent context
+*party-mode
-- Reads `{project-root}/bmad/_cfg/agent-manifest.csv`
-- Loads ALL installed agents with their complete personalities:
- - name (identifier: "pm", "analyst", "storyteller")
- - displayName (persona name: "John", "Mary")
- - title (formal position)
- - icon (emoji representation)
- - role (one-line capability summary)
- - identity (background paragraph)
- - communicationStyle (how they speak)
- - principles (decision-making philosophy)
- - module (bmm, cis, bmb, core, custom)
- - path (file location)
+# During party
+Ask questions, respond to agents, direct the conversation
-**Result:** Complete roster of all available agents with their default personalities.
-
-#### 2. Customization Application
-
-**Process:**
-
-- For each agent, checks for customization file:
- - Path: `{project-root}/bmad/_cfg/agents/{module}-{agent-name}.customize.yaml`
- - Example: `bmm-pm.customize.yaml`, `cis-storyteller.customize.yaml`
-- Merges customization with manifest data
-- **Override precedence:** Customization > Manifest
-
-**Examples:**
-
-```yaml
-# bmad/_cfg/agents/bmm-pm.customize.yaml
-agent:
- persona:
- communicationStyle: 'Formal and corporate-focused'
- principles:
- - 'HIPAA compliance is non-negotiable'
-```
-
-**Result:** All agents loaded with their final, customized personalities.
-
-#### 3. Party Activation
-
-**Process:**
-
-- BMad Master announces party mode activation
-- Lists all participating agents by name and role
-- Welcomes user to the conversation
-- Waits for user to introduce topic
-
-**Example Announcement:**
-
-```
-π§ BMad Master has activated Party Mode!
-
-Participating Agents:
-π PM (John) - Product Strategy
-π Analyst (Mary) - Research & Requirements
-ποΈ Architect (Winston) - System Design
-π¨ UX Designer (Sally) - User Experience
-π² Game Designer (Samus Shepard) - Creative Vision
-π‘ Innovation Strategist - Disruption & Strategy
-π Storyteller - Narrative & Communication
-
-What would you like to discuss?
-```
-
-#### 4. Dynamic Agent Selection
-
-**For each user message, BMad Master:**
-
-1. Analyzes the message topic and context
-2. Reviews all agent roles and expertise
-3. Selects 2-3 most relevant agents
-4. Considers conversation history (which agents spoke recently)
-5. Ensures diverse perspectives
-
-**Selection Criteria:**
-
-- **Expertise Match:** Agent's role aligns with topic
-- **Principle Alignment:** Agent's principles are relevant
-- **Context Awareness:** Previous discussion flow
-- **Diversity:** Mix of perspectives (technical + creative, strategic + tactical)
-
-**Example Selection:**
-
-```
-User: "How should we handle user authentication for our healthcare app?"
-
-BMad Master selects:
-- Architect (technical security expertise)
-- PM (compliance and requirements)
-- UX Designer (user experience balance)
-```
-
-#### 5. Agent Responses
-
-**Each selected agent:**
-
-- Responds **in character** using their merged personality
-- Applies their communication style
-- References their expertise and principles
-- Can ask clarifying questions
-- Can reference other agents' points
-
-**Example Exchange:**
-
-```
-Architect (Winston): "Healthcare authentication requires HIPAA compliance.
-I recommend OAuth 2.0 with MFA and audit logging. We should also consider..."
-
-PM (John): "Building on Winston's point, we need to document compliance
-in the PRD. Mary, have we researched HIPAA requirements yet?"
-
-UX Designer (Sally): "From a user perspective, MFA can't add friction
-for clinicians in emergency scenarios. We need conditional requirements..."
-```
-
-#### 6. Natural Cross-Talk
-
-**Agents can:**
-
-- **Build on each other's points:** "Expanding on what Architect said..."
-- **Respectfully disagree:** "I see Sally's concern, but I think..."
-- **Ask each other questions:** "Winston, how would that affect performance?"
-- **Reference user input:** "As you mentioned earlier..."
-- **Synthesize perspectives:** "Both approaches have merit. The trade-off is..."
-
-**Key Feature:** Agents debate naturally, creating **emergent insights** from their interaction.
-
-#### 7. Active Moderation
-
-**BMad Master monitors:**
-
-- Discussion productivity
-- Circular arguments
-- Completion signals
-
-**Moderator Actions:**
-
-- **If circular:** Summarizes discussion, redirects to new aspect
-- **If stuck:** Suggests specific angles to explore
-- **If questions:** Ensures user input is sought
-- **If complete:** Recognizes natural conclusion
-
-**Example Moderation:**
-
-```
-BMad Master: "The discussion has circled back to authentication methods.
-Let me summarize the three approaches proposed:
-1. OAuth 2.0 + MFA (Architect)
-2. SSO with conditional MFA (UX Designer)
-3. Biometric + PIN fallback (PM)
-
-Which aspects would you like the team to explore deeper?
-Or are you ready to make a decision?"
-```
-
-#### 8. Graceful Exit
-
-**Party mode ends when:**
-
-- User triggers exit command ("exit", "end party", "done")
-- Natural conclusion reached
-- User stops responding
-
-**Exit Process:**
-
-1. BMad Master signals party conclusion
-2. 2-3 agents provide characteristic farewells
-3. Party mode cleanly exits
-
-**Example Farewell:**
-
-```
-PM (John): "Great session. I'll document these decisions in the PRD."
-
-UX Designer (Sally): "Excited to design the auth flow. Let's keep
-the user at the center!"
-
-BMad Master: "Party mode concluded. The agents stand ready for
-individual consultation when needed."
+# Exit
+Type: exit
```
---
-## When to Use Party Mode
+## Fun Examples
-### Strategic Discussions
+### Example 1: Calling Out Bad Architecture
-**Best for decisions with:**
+**You:** "Okay team, our last sprint was a disaster. The authentication service went down three times. Who screwed this up?"
-- Multiple stakeholders (technical, business, user)
-- Trade-offs to balance (cost, time, quality, UX)
-- Long-term implications
-- Cross-functional impact
+**Architect (Winston):** "The design was sound - distributed authentication with proper fallbacks. If implementation deviated from the spec..."
-**Examples:**
+**DEV (Amelia):** "I followed the architecture doc exactly. The spec didn't account for concurrent session invalidation race conditions."
-- Product vision and market positioning
-- Architecture approach selection
-- Technology stack decisions
-- Scope and priority negotiations
-- Phase transition planning
+**PM (John):** "Both of you missed the bigger issue - we didn't validate session management requirements in the PRD. This is on me for not catching it."
-**Why party mode helps:**
+**TEA (Murat):** "And I should've caught this in integration tests. The test scenarios didn't cover concurrent invalidation."
-- Technical agents ground creative ideas in reality
-- Strategic agents ensure market fit
-- UX agents advocate for user needs
-- Multiple perspectives reveal blind spots
+_(Watch them debate whose fault it really was - it's therapeutic)_
---
-### Creative Sessions
+### Example 2: Creative Brainstorming
-**Best for:**
+**You:** "How do we make onboarding feel magical instead of boring?"
-- Ideation without constraints
-- Exploring multiple solution approaches
-- Narrative and storytelling development
-- Innovation and novel ideas
-- Design thinking exercises
+**UX Designer (Sally):** "Start with progressive disclosure - reveal features as users need them, not all at once in a tutorial."
-**Examples:**
+**Storyteller (CIS):** "What if onboarding was a story? Each step reveals a character's journey - the user IS the hero."
-- Game design concept exploration
-- Narrative worldbuilding
-- UX ideation and flows
-- Problem-solving brainstorms
-- Feature innovation
+**Innovation Strategist (CIS):** "Take it further - gamify with unlockable achievements. But make them meaningful, not arbitrary badges."
-**Why party mode helps:**
+**Game Designer:** "Building on that - what if the first 'quest' is actually solving a real user problem? They learn by doing something valuable."
-- CIS agents bring creative frameworks
-- BMM agents ensure implementability
-- Cross-pollination of ideas across domains
-- "Yes, and..." collaborative building
+_(Ideas cross-pollinate and evolve)_
---
-### Cross-Functional Alignment
+### Example 3: Technical Decision
-**Best for:**
+**You:** "Monolith or microservices for MVP?"
-- Getting entire team on same page
-- Phase transitions
-- Epic kickoffs
-- Retrospectives with multiple perspectives
-- Quality gate reviews
+**Architect:** "Start monolith. Microservices add complexity you don't need at 1000 users."
-**Examples:**
+**PM:** "Agree. Time to market matters more than theoretical scalability."
-- Analysis β Planning transition
-- Planning β Solutioning alignment
-- Solutioning β Implementation readiness
-- Sprint retrospectives
-- Course correction decisions
+**DEV:** "Monolith with clear module boundaries. We can extract services later if needed."
-**Why party mode helps:**
+**Innovation Strategist:** "Contrarian take - if your differentiator IS scalability, build for it now. Otherwise Architect's right."
-- Everyone hears same information
-- Concerns raised immediately
-- Consensus built through discussion
-- Handoffs are clear
+_(Multiple perspectives reveal the right answer)_
---
-### Complex Problem Solving
+## When NOT to Use Party Mode
-**Best for:**
+**Skip party mode for:**
-- Multi-faceted challenges
-- No obvious solution
-- High risk or uncertainty
-- Novel situations
-- Constraint optimization
+- 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
-**Examples:**
+**Use party mode for:**
-- Performance + scalability + cost optimization
-- Technical debt vs. feature velocity
-- Legacy system migration strategy
-- Multi-platform architecture
-- Real-time collaboration architecture
-
-**Why party mode helps:**
-
-- Diverse expertise identifies constraints
-- Trade-offs made explicit
-- Creative + pragmatic balance
-- Risk assessment from multiple angles
+- Multi-perspective decisions
+- Creative collaboration
+- Post-mortems and retrospectives
+- Sprint planning sessions
+- Complex problem-solving
---
-## Getting Started
+## Agent Customization
-### Quick Start Guide
+Party mode uses agents from `bmad/[module]/agents/*.md` - these already include any customizations you applied during install.
-**1. Load BMad Master**
+**To customize agents for party mode:**
-```
-In your IDE (Claude Code, Cursor, Windsurf):
-Type: @bmad-master
-Wait for menu to appear
-```
+1. Create customization file: `bmad/_cfg/agents/bmm-pm.customize.yaml`
+2. Run `npx bmad-method install` to rebuild agents
+3. Customizations now active in party mode
-**2. Trigger Party Mode**
-
-```
-Type: *party-mode
-Press enter
-```
-
-**3. Review Agent Roster**
-
-```
-BMad Master lists all participating agents
-Includes agents from BMM, CIS, BMB, and custom modules
-```
-
-**4. Introduce Your Topic**
-
-```
-State your challenge, question, or goal
-Be specific: "We need to decide..." vs "I want to talk about..."
-Context helps: Mention project type, constraints, goals
-```
-
-**5. Engage with Agents**
-
-```
-2-3 agents will respond to your topic
-Answer their questions
-Respond to their suggestions
-Ask follow-up questions
-```
-
-**6. Direct the Discussion**
-
-```
-Guide focus: "Let's explore X in more detail"
-Seek specific perspectives: "Architect, what about performance?"
-Make decisions: "I'm leaning toward approach B because..."
-```
-
-**7. Conclude**
-
-```
-Type: "exit" or "end party" or "done"
-Or let conversation reach natural conclusion
-Agents will provide farewells
-```
-
-### Your First Party Mode Session
-
-**Recommended first topic:**
-
-```
-"I'm starting a [project type] and need help deciding between
-[option A] and [option B] for [specific aspect]."
-
-Example:
-"I'm starting a SaaS web app and need help deciding between
-monolith and microservices for our initial MVP."
-```
-
-**What to expect:**
-
-- Architect discusses technical implications
-- PM discusses business and timeline implications
-- DEV discusses implementation complexity
-- Possibly Innovation Strategist on competitive differentiation
-
-**Duration:** 10-20 minutes typically
-
----
-
-## Agent Selection & Dynamics
-
-### How Agents Are Selected
-
-**Per message, BMad Master considers:**
-
-1. **Topic Keywords:**
- - "authentication" β Architect, DEV
- - "user experience" β UX Designer
- - "market positioning" β PM, Innovation Strategist
- - "narrative" β Game Designer, Storyteller
-
-2. **Agent Roles:**
- - Match expertise to topic
- - Balance technical and creative
- - Include strategic when appropriate
-
-3. **Conversation Context:**
- - What was just discussed
- - Which agents spoke recently
- - What perspectives are missing
-
-4. **Diversity:**
- - Avoid same 2 agents every time
- - Rotate in different perspectives
- - Ensure cross-functional views
-
-### Response Dynamics
-
-**Typical Pattern:**
-
-```
-User Message
- β
-Agent 1 (Primary perspective)
- β
-Agent 2 (Complementary perspective)
- β
-Agent 3 (Optional: Third angle or synthesis)
- β
-User Response (clarification, decision, new question)
-```
-
-**Cross-Talk Examples:**
-
-**Building Agreement:**
-
-```
-Architect: "We should use PostgreSQL for transactional data."
-DEV: "Agreed. I've worked with Postgres extensively, and it's
-excellent for this use case."
-```
-
-**Respectful Disagreement:**
-
-```
-UX Designer: "Users will find that flow confusing."
-PM: "I hear Sally's concern, but our user research shows
-power users prefer efficiency over simplicity."
-UX Designer: "That's fair. Could we offer both modes?"
-```
-
-**Cross-Pollination:**
-
-```
-Innovation Strategist: "What if we made this social?"
-Game Designer: "Building on that - gamification could drive engagement."
-UX Designer: "I can design for both. Leaderboards with privacy controls."
-```
-
-### Emergent Insights
-
-**What makes party mode powerful:**
-
-1. **Perspective Collision:**
- - Technical meets creative
- - Strategic meets tactical
- - Ideal meets pragmatic
-
-2. **Healthy Debate:**
- - Agents challenge assumptions
- - Trade-offs made explicit
- - Better decisions through conflict
-
-3. **Synthesis:**
- - Agents combine ideas
- - Novel solutions emerge
- - "Best of both" approaches
-
-4. **Blind Spot Detection:**
- - Each agent sees different risks
- - Missing considerations surface
- - Comprehensive coverage
-
----
-
-## Multi-Module Integration
-
-### Available Agent Pool
-
-Party mode loads agents from **all installed modules:**
-
-#### BMad Core (1 agent)
-
-- **BMad Master** - Orchestrator and facilitator
-
-#### BMM - BMad Method (12 agents)
-
-**Core Development:**
-
-- PM (Product Manager)
-- Analyst (Business Analyst)
-- Architect (System Architect)
-- SM (Scrum Master)
-- DEV (Developer)
-- TEA (Test Architect)
-- UX Designer
-- Paige (Documentation Guide)
-
-**Game Development:**
-
-- Game Designer
-- Game Developer
-- Game Architect
-
-#### CIS - Creative Intelligence Suite (5 agents)
-
-- Brainstorming Coach
-- Creative Problem Solver
-- Design Thinking Coach
-- Innovation Strategist
-- Storyteller
-
-#### BMB - BMad Builder (1 agent)
-
-- BMad Builder
-
-#### Custom Modules
-
-- Any custom agents you've created
-
-**Total Potential:** 19+ agents available for party mode
-
-### Cross-Module Collaboration
-
-**The Power of Mixing Modules:**
-
-**Example 1: Product Innovation**
-
-```
-Agents: PM (BMM) + Innovation Strategist (CIS) + Storyteller (CIS)
-Topic: Market positioning and product narrative
-Outcome: Strategic positioning with compelling story
-```
-
-**Example 2: Complex Architecture**
-
-```
-Agents: Architect (BMM) + Creative Problem Solver (CIS) + Game Architect (BMM)
-Topic: Novel pattern design for real-time collaboration
-Outcome: Innovative solution balancing creativity and pragmatism
-```
-
-**Example 3: User-Centered Design**
-
-```
-Agents: UX Designer (BMM) + Design Thinking Coach (CIS) + Storyteller (CIS)
-Topic: Empathy-driven UX with narrative flow
-Outcome: User journey that tells a story
-```
-
-**Example 4: Testing Strategy**
-
-```
-Agents: TEA (BMM) + Architect (BMM) + Problem Solver (CIS)
-Topic: Comprehensive quality approach
-Outcome: Risk-based testing with creative coverage strategies
-```
-
-### Module Discovery
-
-**How party mode finds agents:**
-
-1. **Manifest Read:** Parses `agent-manifest.csv`
-2. **Module Column:** Each agent tagged with source module
-3. **Path Validation:** Checks agent file exists
-4. **Personality Load:** Loads complete agent data
-5. **All Modules:** No filtering - all agents included
-
-**Result:** Seamless cross-module teams without manual configuration.
-
----
-
-## Example Party Compositions
-
-### 1. Strategic Product Planning
-
-**Participants:**
-
-- PM (John) - Product requirements
-- Innovation Strategist - Market disruption
-- Storyteller - Product narrative
-
-**Best For:**
-
-- Product vision definition
-- Market positioning
-- Value proposition design
-- Competitive differentiation
-
-**Example Topic:**
-"We're launching a project management tool. How do we differentiate in a crowded market?"
-
-**Expected Dynamics:**
-
-- Innovation Strategist identifies disruption opportunities
-- PM grounds in market realities and user needs
-- Storyteller crafts compelling narrative positioning
-
----
-
-### 2. Technical Architecture Deep-Dive
-
-**Participants:**
-
-- Architect (Winston) - System design
-- Game Architect (Cloud Dragonborn) - Complex systems
-- Creative Problem Solver - Novel approaches
-
-**Best For:**
-
-- Complex system design
-- Novel pattern invention
-- Performance optimization
-- Scalability challenges
-
-**Example Topic:**
-"We need real-time collaboration with 10,000 concurrent users. What's the architecture approach?"
-
-**Expected Dynamics:**
-
-- Architects debate technical approaches (WebSocket, WebRTC, CRDT)
-- Creative Problem Solver suggests novel patterns
-- Synthesis of proven + innovative solutions
-
----
-
-### 3. User Experience Innovation
-
-**Participants:**
-
-- UX Designer (Sally) - Interaction design
-- Design Thinking Coach - Empathy-driven process
-- Storyteller - User journey narrative
-
-**Best For:**
-
-- UX-heavy feature design
-- User journey mapping
-- Accessibility considerations
-- Interaction innovation
-
-**Example Topic:**
-"Design an onboarding experience that feels magical, not overwhelming."
-
-**Expected Dynamics:**
-
-- Design Thinking Coach facilitates empathy exploration
-- UX Designer translates to concrete interactions
-- Storyteller ensures narrative flow
-
----
-
-### 4. Game Design Session
-
-**Participants:**
-
-- Game Designer (Samus Shepard) - Core gameplay
-- Storyteller - Narrative design
-- Brainstorming Coach - Creative ideation
-
-**Best For:**
-
-- Game concept development
-- Narrative worldbuilding
-- Mechanic innovation
-- Player experience design
-
-**Example Topic:**
-"Create a puzzle game where players feel clever, not frustrated."
-
-**Expected Dynamics:**
-
-- Game Designer focuses on core loop and progression
-- Storyteller layers narrative meaning
-- Brainstorming Coach generates mechanic variations
-
----
-
-### 5. Quality & Testing Strategy
-
-**Participants:**
-
-- TEA (Murat) - Testing expertise
-- Architect (Winston) - System testability
-- Problem Solver - Creative coverage
-
-**Best For:**
-
-- Test strategy planning
-- Quality gate definition
-- Risk assessment
-- Coverage optimization
-
-**Example Topic:**
-"Define testing strategy for a microservices architecture."
-
-**Expected Dynamics:**
-
-- TEA defines comprehensive approach
-- Architect ensures architectural testability
-- Problem Solver identifies creative coverage strategies
-
----
-
-### 6. Epic Kickoff
-
-**Participants:**
-
-- PM (John) - Requirements clarity
-- Architect (Winston) - Technical approach
-- SM (Bob) - Story breakdown
-- DEV (Amelia) - Implementation feasibility
-
-**Best For:**
-
-- Epic planning sessions
-- Technical feasibility assessment
-- Story scope validation
-- Implementation approach alignment
-
-**Example Topic:**
-"Epic kickoff: Real-time notifications system"
-
-**Expected Dynamics:**
-
-- PM clarifies requirements and success criteria
-- Architect proposes technical approach
-- DEV validates implementation feasibility
-- SM plans story breakdown
-
----
-
-### 7. Documentation & Knowledge
-
-**Participants:**
-
-- Paige - Documentation standards
-- Analyst (Mary) - Information architecture
-- PM (John) - Requirements documentation
-
-**Best For:**
-
-- Documentation strategy
-- Knowledge transfer planning
-- API documentation approach
-- Architectural decision records
-
-**Example Topic:**
-"Document this brownfield codebase for AI-assisted development."
-
-**Expected Dynamics:**
-
-- Paige defines documentation standards
-- Analyst structures information architecture
-- PM ensures requirements traceability
-
----
-
-### 8. Creative Brainstorming (Pure CIS)
-
-**Participants:**
-
-- Brainstorming Coach
-- Creative Problem Solver
-- Innovation Strategist
-- Storyteller
-
-**Best For:**
-
-- Pure ideation
-- Innovation exploration
-- Creative problem solving
-- Strategic thinking
-
-**Example Topic:**
-"How can we disrupt the email newsletter industry?"
-
-**Expected Dynamics:**
-
-- Multiple creative frameworks applied
-- Diverse ideation techniques
-- Strategic + creative synthesis
-- Narrative framing of ideas
-
----
-
-## Agent Customization in Party Mode
-
-### How Customization Works
-
-**Customization Files:**
-
-- Location: `{project-root}/bmad/_cfg/agents/`
-- Naming: `{module}-{agent-name}.customize.yaml`
-- Format: YAML with persona overrides
-
-**Example Structure:**
+Example customization:
```yaml
agent:
persona:
- displayName: 'Custom Name' # Optional
- communicationStyle: 'Custom style' # Optional
- principles: # Optional
- - 'Project-specific principle'
-```
-
-### Override Precedence
-
-**Loading Order:**
-
-1. Read agent from manifest (default personality)
-2. Check for customization file
-3. If exists, merge with manifest
-4. **Customization values override manifest values**
-5. Unspecified fields use manifest defaults
-
-**Result:** Agents use customized personalities in party mode.
-
-### Common Customization Use Cases
-
-#### 1. Domain-Specific Expertise
-
-**Add healthcare expertise to PM:**
-
-```yaml
-# bmad/_cfg/agents/bmm-pm.customize.yaml
-agent:
- persona:
- identity: |
- Product Manager with 15 years in healthcare SaaS.
- Expert in HIPAA compliance, EHR integrations, and clinical workflows.
- Balances regulatory requirements with user experience.
principles:
- 'HIPAA compliance is non-negotiable'
- 'Patient safety over feature velocity'
- - 'Clinical validation for every feature'
```
-**In Party Mode:**
-
-```
-PM now brings healthcare expertise to all discussions.
-Architect and PM can debate HIPAA-compliant architecture.
-UX Designer and PM can discuss clinical usability.
-```
-
-#### 2. Communication Style
-
-**Make Architect more casual:**
-
-```yaml
-# bmad/_cfg/agents/bmm-architect.customize.yaml
-agent:
- persona:
- communicationStyle: |
- Friendly and approachable. Uses analogies and real-world examples.
- Avoids jargon. Explains complex concepts simply.
-```
-
-**In Party Mode:**
-Architect's responses are more accessible to non-technical stakeholders.
-
-#### 3. Project-Specific Principles
-
-**Add startup constraints:**
-
-```yaml
-# bmad/_cfg/agents/bmm-pm.customize.yaml
-agent:
- persona:
- principles:
- - 'MVP > perfect - ship fast, iterate'
- - 'Technical debt is acceptable for validation'
- - 'Focus on one metric that matters'
-```
-
-**In Party Mode:**
-PM pushes for rapid iteration, affecting all strategic discussions.
-
-#### 4. Cross-Project Consistency
-
-**Add company standards:**
-
-```yaml
-# bmad/_cfg/agents/bmm-architect.customize.yaml
-agent:
- persona:
- principles:
- - 'AWS-only for all services (company policy)'
- - 'TypeScript required for all projects'
- - 'Microservices for all new systems'
-```
-
-**In Party Mode:**
-Architect enforces company standards, reducing technology debates.
-
-### Testing Customizations
-
-**Best way to see customizations in action:**
-
-1. Create customization file
-2. Load BMad Master
-3. Run `*party-mode`
-4. Introduce topic relevant to customized agent
-5. See agent respond with customized personality
-
-**Example Test:**
-
-```
-Customize PM with healthcare expertise
-β
-Run party mode
-β
-Topic: "User authentication approach"
-β
-PM discusses HIPAA-compliant auth (customization active)
-```
+See [Agents Guide](./agents-guide.md#agent-customization) for details.
---
-## Best Practices
+## BMM Workflows That Use Party Mode
-### Effective Party Mode Usage
+**Current:**
-**1. Start with Clear Topics**
+- `epic-retrospective` - Post-epic team retrospective powered by party mode
+- Sprint planning discussions (informal party mode usage)
-```
-β "I want to talk about my app"
-β
"I need to decide between REST and GraphQL for our mobile API"
+**Future:**
-β "Architecture stuff"
-β
"What's the best caching strategy for read-heavy microservices?"
-```
+- Advanced elicitation workflows will officially integrate party mode
+- Multi-agent requirement validation
+- Collaborative technical reviews
-**2. Provide Context**
+---
-```
-Good Opening:
-"We're building a SaaS CRM for SMBs. Current tech stack: Next.js, Postgres.
-We need to add real-time notifications. What approach should we use?"
+## Available Agents
-Includes: Project type, constraints, specific question
-```
+Party mode can include **19+ agents** from all installed modules:
-**3. Engage Actively**
+**BMM (12 agents):** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Technical Writer, Game Designer, Game Developer, Game Architect
-```
-When agents respond:
-- Answer their questions
-- React to their suggestions
-- Ask follow-up questions
-- Make decisions when ready
-- Challenge assumptions
-```
+**CIS (5 agents):** Brainstorming Coach, Creative Problem Solver, Design Thinking Coach, Innovation Strategist, Storyteller
-**4. Direct When Needed**
+**BMB (1 agent):** BMad Builder
-```
-Useful phrases:
-- "Let's focus on X aspect first"
-- "Architect, how would that affect performance?"
-- "I'm concerned about Y - what do you think?"
-- "Can we explore option B in more detail?"
-```
+**Core (1 agent):** BMad Master (orchestrator)
-**5. Use for Right Scenarios**
+**Custom:** Any agents you've created
-```
-Great for party mode:
-β
Strategic decisions
-β
Trade-off discussions
-β
Creative brainstorming
-β
Cross-functional alignment
+---
-Not ideal for party mode:
-β Simple questions (use single agent)
-β Implementation details (use DEV)
-β Document review (use specific agent)
-```
+## Tips
-### Getting the Most Value
+**Get better results:**
-**1. Embrace Debate**
+- 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)
-- Healthy disagreement leads to better decisions
-- Different perspectives reveal blind spots
-- Synthesis often better than any single view
+**Examples of good opening questions:**
-**2. Make Decisions**
-
-- Party mode informs, you decide
-- Don't wait for consensus (rarely happens)
-- Choose approach and move forward
-- Document decision rationale
-
-**3. Time Box**
-
-- Most productive discussions: 15-30 minutes
-- If longer, consider breaking into focused sessions
-- Circular discussions signal completion
-
-**4. Customize Strategically**
-
-- Add domain expertise when relevant
-- Keep project constraints in mind
-- Don't over-customize (agents have good defaults)
-
-**5. Follow Up**
-
-- Use decisions in single-agent workflows
-- Document outcomes in planning docs
-- Reference party mode insights in architecture
+- "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
-### Common Issues
+**Same agents responding every time?**
+Vary your questions or explicitly request other perspectives: "Game Designer, your thoughts?"
-**Issue: Same agents responding every time**
+**Discussion going in circles?**
+BMad Master will summarize and redirect, or you can make a decision and move on.
-**Cause:** Topic consistently matches same expertise areas
+**Too many agents talking?**
+Make your topic more specific - BMad Master picks 2-3 agents based on relevance.
-**Solution:**
-
-- Vary your questions to engage different agents
-- Explicitly request perspectives: "Game Designer, your thoughts?"
-- Ask about different aspects of same topic
-
----
-
-**Issue: Discussion becomes circular**
-
-**Cause:** Fundamental disagreement or insufficient information
-
-**Solution:**
-
-- BMad Master will summarize and redirect
-- You can decide between options
-- Acknowledge need for more research/data
-- Table decision for later
-
----
-
-**Issue: Agents not using customizations**
-
-**Cause:** Customization file not found or malformed YAML
-
-**Solution:**
-
-1. Check file location: `bmad/_cfg/agents/{module}-{agent-name}.customize.yaml`
-2. Validate YAML syntax (no tabs, proper indentation)
-3. Verify module prefix matches (bmm-, cis-, bmb-)
-4. Reload party mode
-
----
-
-**Issue: Too many agents responding**
-
-**Cause:** Topic is broad or matches many expertise areas
-
-**Solution:**
-
-- Make topic more specific
-- Focus on one aspect at a time
-- BMad Master limits to 2-3 agents per message
-
----
-
-**Issue: Party mode feels overwhelming**
-
-**Cause:** First time, unfamiliar with agent personalities
-
-**Solution:**
-
-- Start with focused topics
-- Read [Agents Guide](./agents-guide.md) first
-- Try 1-2 party sessions before complex topics
-- Remember: You control the direction
+**Agents not using customizations?**
+Make sure you ran `npx bmad-method install` after creating customization files.
---
## Related Documentation
-**Agent Information:**
-
-- [Agents Guide](./agents-guide.md) - Complete agent reference with all 12 BMM agents + BMad Master
-- [Glossary](./glossary.md) - Key terminology including agent roles
-
-**Getting Started:**
-
-- [Quick Start Guide](./quick-start.md) - Introduction to BMM
-- [FAQ](./faq.md) - Common questions about agents and workflows
-
-**Team Collaboration:**
-
-- [Enterprise Agentic Development](./enterprise-agentic-development.md) - Multi-developer teams and coordination
-
-**Workflow Guides:**
-
-- [Phase 1: Analysis Workflows](./workflows-analysis.md)
-- [Phase 2: Planning Workflows](./workflows-planning.md)
-- [Phase 3: Solutioning Workflows](./workflows-solutioning.md)
-- [Phase 4: Implementation Workflows](./workflows-implementation.md)
-- [Testing & QA Workflows](./workflows-testing.md)
-
----
-
-## Quick Reference
-
-### Party Mode Commands
-
-```bash
-# Start party mode
-Load BMad Master β *party-mode
-
-# During party mode
-Type your topic/question
-Respond to agents
-Direct specific agents
-
-# Exit party mode
-"exit"
-"end party"
-"done"
-```
-
-### When to Use
-
-| Scenario | Use Party Mode? | Alternative |
-| ---------------------------------- | --------------- | ---------------------------------------- |
-| Strategic decision with trade-offs | β
Yes | Single agent (PM, Architect) |
-| Creative brainstorming | β
Yes | Single agent (Game Designer, CIS agents) |
-| Epic kickoff meeting | β
Yes | Sequential agent workflows |
-| Simple implementation question | β No | DEV agent |
-| Document review | β No | Paige agent |
-| Workflow status check | β No | Any agent + \*workflow-status |
-
-### Agent Selection by Topic
-
-| Topic | Expected Agents |
-| ------------------ | ----------------------------------------------- |
-| Architecture | Architect, Game Architect, DEV |
-| Product Strategy | PM, Innovation Strategist, Analyst |
-| User Experience | UX Designer, Design Thinking Coach |
-| Testing | TEA, Architect, DEV |
-| Creative/Narrative | Game Designer, Storyteller, Brainstorming Coach |
-| Documentation | Paige, Analyst, PM |
-| Implementation | DEV, Architect, SM |
+- [Agents Guide](./agents-guide.md) - Complete agent reference
+- [Quick Start Guide](./quick-start.md) - Getting started with BMM
+- [FAQ](./faq.md) - Common questions
---
diff --git a/src/modules/bmm/docs/workflows-implementation.md b/src/modules/bmm/docs/workflows-implementation.md
index 28298ebb..9545eeb6 100644
--- a/src/modules/bmm/docs/workflows-implementation.md
+++ b/src/modules/bmm/docs/workflows-implementation.md
@@ -10,18 +10,18 @@ Phase 4 (Implementation) workflows manage the iterative sprint-based development
## Quick Reference
-| Workflow | Agent | Duration | Purpose |
-| --------------------- | --------- | -------------- | ------------------------------------ |
-| **sprint-planning** | SM | 30-60 min | Initialize sprint tracking file |
-| **epic-tech-context** | Architect | 15-30 min/epic | Epic-specific technical guidance |
-| **create-story** | SM | 10-20 min | Create next story from epics |
-| **story-context** | PM | 10-15 min | Assemble dynamic story context |
-| **dev-story** | DEV | 2-8 hours | Implement story with tests |
-| **code-review** | DEV | 30-60 min | Senior dev review of completed story |
-| **correct-course** | SM | 30-90 min | Handle mid-sprint changes |
-| **retrospective** | SM | 60-90 min | Post-epic review and lessons |
-| **workflow-status** | All | 2-5 min | Check "what should I do now?" |
-| **document-project** | Analyst | 1-3 hours | Document brownfield projects |
+| Workflow | Agent | Duration | Purpose |
+| --------------------- | ------- | -------------- | ------------------------------------ |
+| **sprint-planning** | SM | 30-60 min | Initialize sprint tracking file |
+| **epic-tech-context** | SM | 15-30 min/epic | Epic-specific technical guidance |
+| **create-story** | SM | 10-20 min | Create next story from epics |
+| **story-context** | PM | 10-15 min | Assemble dynamic story context |
+| **dev-story** | DEV | 2-8 hours | Implement story with tests |
+| **code-review** | DEV | 30-60 min | Senior dev review of completed story |
+| **correct-course** | SM | 30-90 min | Handle mid-sprint changes |
+| **retrospective** | SM | 60-90 min | Post-epic review and lessons |
+| **workflow-status** | All | 2-5 min | Check "what should I do now?" |
+| **document-project** | Analyst | 1-3 hours | Document brownfield projects |
---
@@ -69,13 +69,12 @@ Every story moves through this lifecycle:
Phase 4 involves coordination between agents:
-| Agent | Primary Workflows | Role |
-| ------------- | ------------------------------------------------------------ | --------------------------- |
-| **SM** | sprint-planning, create-story, correct-course, retrospective | Orchestration, tracking |
-| **Architect** | epic-tech-context | Technical guidance per epic |
-| **PM** | story-context | Context assembly |
-| **DEV** | dev-story, code-review | Implementation, quality |
-| **Analyst** | document-project | Documentation (brownfield) |
+| Agent | Primary Workflows | Role |
+| ----------- | ------------------------------------------------------------------------------- | -------------------------- |
+| **SM** | sprint-planning, epic-tech-context, create-story, correct-course, retrospective | Orchestration, tracking |
+| **PM** | story-context | Context assembly |
+| **DEV** | dev-story, code-review | Implementation, quality |
+| **Analyst** | document-project | Documentation (brownfield) |
---
@@ -256,7 +255,7 @@ epics:
Generate epic-specific technical context document that provides implementation guidance, patterns, and technical decisions for a single epic. Bridges architecture and story implementation.
-**Agent:** Architect
+**Agent:** SM (Scrum Master)
**Phase:** 4 (Implementation)
**Required:** Optional (recommended for Level 3-4)
**Typical Duration:** 15-30 minutes per epic
@@ -974,7 +973,7 @@ Tests Added:
### Purpose
-Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic tech-spec, repo docs, MCP servers for latest best-practices, and web search as fallback.
+Perform a Senior Developer code review on a completed story flagged Ready for Review, leveraging story-context, epic-tech-context, repo docs, MCP servers for latest best-practices, and web search as fallback.
**Agent:** DEV (Senior Developer persona)
**Phase:** 4 (Implementation)
diff --git a/src/modules/bmm/docs/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md
index f2a7730d..c28f69c5 100644
--- a/src/modules/bmm/docs/workflows-solutioning.md
+++ b/src/modules/bmm/docs/workflows-solutioning.md
@@ -70,7 +70,7 @@ Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into
**Level 3-4 (Required Solutioning):**
- Planning: Standard/Comprehensive PRD
-- Solutioning: **Required** architecture + epic tech-spec
+- Solutioning: **Required** architecture + epic-tech-context
- Gate Check: **Required** solutioning-gate-check
- Implementation: dev-story guided by architecture
diff --git a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
index ae6f3301..053ed977 100644
--- a/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
@@ -1,4 +1,4 @@
-name: tech-spec
+name: epic-tech-context
description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
author: "BMAD BMM"
diff --git a/src/modules/bmm/workflows/techdoc/documentation-standards.md b/src/modules/bmm/workflows/techdoc/documentation-standards.md
index fb093a04..ffc878cd 100644
--- a/src/modules/bmm/workflows/techdoc/documentation-standards.md
+++ b/src/modules/bmm/workflows/techdoc/documentation-standards.md
@@ -1,6 +1,6 @@
# Technical Documentation Standards for BMAD
-**For Agent: Paige (Documentation Guide)**
+**For Agent: Technical Writer**
**Purpose: Concise reference for documentation creation and review**
---