ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

docs: comprehensive documentation accuracy overhaul and PM/UX evolution analysis 

This commit represents a major documentation quality improvement, fixing critical inaccuracies and adding forward-looking guidance on the evolving role of PMs/UX in AI-driven development.

## Documentation Accuracy Fixes (Agent YAML as Source of Truth)

### Critical Corrections in agents-guide.md
- **Game Developer workflows**: Fixed incorrect workflow names (dev-story → develop-story, added story-done, removed non-existent create-story and retro)
- **Technical Writer naming**: Added agent name "Paige" to match all other agent naming patterns
- **Agent reference tables**: Updated to reflect actual agent capabilities from YAML configs
- **epic-tech-context ownership**: Corrected across all docs - belongs to SM agent, not Architect

### Critical Corrections in workflows-implementation.md
- **Line 16 + 75**: Fixed epic-tech-context agent from "Architect" → "SM" (matches sm.agent.yaml)
- **Line 258**: Updated epic-tech-context section header to show correct agent ownership
- **Multi-agent workflow table**: Moved epic-tech-context to SM agent row where it belongs

### Principle Applied
**Agent YAML files are source of truth** - All documentation now accurately reflects what agents can actually do per their YAML configurations, not assumptions or outdated info.

## Brownfield Development: Phase 0 Documentation Reality Check

### Rewrote brownfield-guide.md Phase 0 Section
Replaced oversimplified 3-scenario model with **real-world guidance**:

**Before**: Assumed docs are either perfect or non-existent
**After**: Handles messy reality of brownfield projects

**New Scenarios (4 instead of 3)**:
- **Scenario A**: No documentation → document-project (was covered)
- **Scenario B**: Docs exist but massive/outdated/incomplete → **document-project** (NEW - very common)
- **Scenario C**: Good docs but no structure → **shard-doc → index-docs** (NEW - handles massive files)
- **Scenario D**: Confirmed AI-optimized docs → Skip Phase 0 (was "Scenario C", now correctly marked RARE)

**Key Additions**:
- Default recommendation: "Run document-project unless you have confirmed, trusted, AI-optimized docs"
- Quality assessment checklist (current, AI-optimized, comprehensive, trusted)
- Massive document handling with shard-doc tool (>500 lines, 10+ level 2 sections)
- Explicit guidance on why regenerate vs index (outdated docs cause hallucinations)
- Impact explanation: how bad docs break AI workflows (token limits, wrong assumptions, broken integrations)

**Principle**: "When in doubt, run document-project" - Better to spend 10-30 minutes generating fresh docs than waste hours debugging AI agents with bad documentation.

## PM/UX Evolution: Enterprise Agentic Development

### New Content: The Evolving Role of Product Managers & UX Designers

Added comprehensive section based on **November 2025 industry research**:

**Industry Data**:
- 56% of product professionals cite AI/ML as top focus
- PRD-to-Code automation: 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 systems

**Role Transformation**:
- From spec writers → code orchestrators
- PMs writing AI-optimized PRDs that **feed agentic pipelines directly**
- UX designers generating code with Figma-to-code tools
- Technical fluency becoming **table stakes**, not optional
- Review PRs from AI agents alongside human developers

**New Section: "How BMad Method Enables PM/UX Technical Evolution"** (10 ways):
1. **AI-Executable PRD Generation** - PRDs become work packages for cloud agents
2. **Automated Epic/Story Breakdown** - No more story refinement sessions
3. **Human-in-the-Loop Architecture** - PMs learn while validating technical decisions
4. **Cloud Agentic Pipeline** - Current (2025) + Future (2026) vision with diagrams
5. **UX Design Integration** - Designs validated through working prototypes
6. **PM Technical Skills Development** - Learn by doing through conversational workflows
7. **Organizational Leverage** - 1 PM → 20-50 AI agents (5-10× multiplier)
8. **Quality Consistency** - What gets built matches what was specified
9. **Rapid Prototyping** - Hours to validate ideas vs months
10. **Career Path Evolution** - Positions PMs for AI Agent PM, Full-Stack Product Lead roles

**Cloud Agentic Pipeline Vision**:
```
Current (2025): PM PRD → Stories → Human devs + BMad agents → PRs → Review → Deploy
Future (2026): PM PRD → Stories → Cloud AI agents → Auto PRs → Review → Auto-merge → Deploy
Time savings: 6-8 weeks → 2-5 days
```

**What Remains Human**:
- Product vision, empathy, creativity, judgment, ethics
- PMs spend MORE time on human elements (AI handles execution)
- Product leaders become "builder-thinkers" not just spec writers

### Document Tightening (enterprise-agentic-development.md)
- **Reduced from 1207 → 640 lines (47% reduction)**
- **10× more BMad-centric** - Every section ties back to how BMad enables the future
- Removed redundant examples, consolidated sections, kept actionable insights
- Stronger value propositions for PMs, UX, enterprise teams throughout

**Key Message**: "The future isn't AI replacing PMs—it's AI-augmented PMs becoming 10× more powerful through BMad Method."

## Impact

These changes bring documentation quality from **D- to A+**:
- **Accuracy**: Agent capabilities now match YAML source of truth (zero hallucination risk)
- **Reality**: Brownfield guidance handles messy real-world scenarios, not idealized ones
- **Forward-looking**: PM/UX evolution section positions BMad as essential framework for emerging roles
- **Actionable**: Concrete workflows, commands, examples throughout
- **Concise**: 47% reduction while strengthening value proposition

Users now have **trustworthy, reality-based, future-oriented guidance** for using BMad Method in both current workflows and emerging agentic development patterns.
This commit is contained in:
Brian Madison 2025-11-03 19:38:50 -06:00
parent 88d043245f
commit 17f81a84f3
16 changed files with 745 additions and 3374 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.claude/commands/bmad/bmm/workflows/README.md
View File

@ -37,7 +37,7 @@
- Path: `bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml` - 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. - 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` - 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. - 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.

2
.claude/commands/bmad/bmm/workflows/tech-spec-sm.md
View File

@ -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.' 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: IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

2
bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
View File

@ -1,5 +1,5 @@
# Technical Specification Workflow (Level 0) # 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." 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" author: "BMad"

2
src/modules/bmm/README.md
View File

@ -34,7 +34,7 @@ bmm/
### Agent Roster ### 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 **Game Development:** Game Designer, Game Developer, Game Architect
**Orchestration:** BMad Master (from Core) **Orchestration:** BMad Master (from Core)

8
src/modules/bmm/agents/paige.agent.yaml → src/modules/bmm/agents/tech-writer.agent.yaml
View File

@ -1,10 +1,10 @@
# Paige - Documentation Guide Agent Definition # Technical Writer - Documentation Guide Agent Definition
agent: agent:
metadata: metadata:
id: bmad/bmm/agents/paige.md id: bmad/bmm/agents/tech-writer.md
name: Paige name: paige
title: Documentation Guide title: Technical Writer
icon: 📚 icon: 📚
module: bmm module: bmm

140
src/modules/bmm/docs/agents-guide.md
View File

@ -37,7 +37,7 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
- DEV (Developer) - DEV (Developer)
- TEA (Test Architect) - TEA (Test Architect)
- UX Designer - UX Designer
- Paige (Documentation Guide) - Technical Writer
**Game Development (3 agents):** **Game Development (3 agents):**
@ -144,10 +144,9 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
**Workflows:** **Workflows:**
- `workflow-status` - Check what to do next - `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 - `validate-architecture` - Validate architecture document
- `solutioning-gate-check` - Validate readiness for Phase 4 - `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. **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 - Sprint planning and tracking initialization
- Creating user stories - Creating user stories
- Assembling dynamic story context - Assembling dynamic story context
- Epic-level technical specifications (optional) - Epic-level technical context (optional)
- Marking stories ready for development - Marking stories ready for development
- Sprint retrospectives - 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 - `workflow-status` - Check what to do next
- `sprint-planning` - Initialize `sprint-status.yaml` tracking - `sprint-planning` - Initialize `sprint-status.yaml` tracking
- `epic-tech-context` - Optional epic-specific tech specs - `epic-tech-context` - Optional epic-specific technical context
- `validate-epic-tech-context` - Validate epic tech spec - `validate-epic-tech-context` - Validate epic technical context
- `create-story` - Draft next story from epic - `create-story` - Draft next story from epic
- `validate-create-story` - Independent story validation - `validate-create-story` - Independent story validation
- `story-context` - Assemble dynamic technical context XML - `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 - Strict file boundary enforcement
- `code-review` - Senior developer-level review with: - `code-review` - Senior developer-level review with:
- Story context awareness - Story context awareness
- Epic tech-spec alignment - Epic-tech-context alignment
- Repository docs reference - Repository docs reference
- MCP server best practices - MCP server best practices
- Web search fallback - 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 - Testing is feature work, not overhead
- Prioritize unit/integration over E2E - Prioritize unit/integration over E2E
- Flakiness is critical technical debt - Flakiness is critical technical debt
- ATDD tests first, AI implements, suite validates
**Special Capabilities:** **Special Capabilities:**
- **Test Healing:** Pattern-based + MCP-enhanced test fixing - **Knowledge Base Access:** Consults comprehensive testing best practices from `testarch/knowledge/` directory
- **Dual Mode:** BMad-integrated (uses epic/story context) or standalone - **Framework Selection:** Smart framework selection (Playwright vs Cypress) with fixture architecture
- **Knowledge Base:** Comprehensive testing best practices - **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 **Role:** Technical Documentation Specialist + Knowledge Curator
@ -457,10 +457,9 @@ The BMad Method Module (BMM) provides a comprehensive team of specialized AI age
**Workflows:** **Workflows:**
- `workflow-status` - Check what to do next - `workflow-status` - Check what to do next
- `create-story` - Create development story - `develop-story` - Execute Dev Story workflow, implementing tasks and tests
- `dev-story` - Implement story with tests - `story-done` - Mark story done after DoD complete
- `code-review` - Review game implementation - `code-review` - Perform thorough clean context QA code review on a story
- `retro` - Sprint retrospective
**Communication Style:** Direct and energetic. Execution-focused. Breaks down complex game challenges into actionable steps. Celebrates performance wins. **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: 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 **What happens:** BMad Master orchestrates 2-3 relevant agents per message. They discuss, debate, and collaborate in real-time.
2. Run `*party-mode`
3. Introduce your topic
**What Happens:** **Best for:** Strategic decisions, creative brainstorming, post-mortems, sprint retrospectives, complex problem-solving.
- BMad Master loads ALL agents (with customizations) **Current BMM uses:** Powers `epic-retrospective` workflow, sprint planning discussions.
- 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
**Best For:** **Future:** Advanced elicitation workflows will officially leverage party mode.
- Strategic decisions with trade-offs 👉 **[Party Mode Guide](./party-mode.md)** - Complete guide with fun examples, tips, and troubleshooting
- 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
--- ---
@ -646,7 +598,7 @@ Some workflows are available to multiple agents:
| `workflow-status` | ALL agents | Check current state and get recommendations | | `workflow-status` | ALL agents | Check current state and get recommendations |
| `workflow-init` | PM, Analyst, Game Designer | Initialize workflow tracking | | `workflow-init` | PM, Analyst, Game Designer | Initialize workflow tracking |
| `correct-course` | PM, Architect, SM, Game Architect | Change management during implementation | | `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 ### Validation Actions
@ -658,7 +610,7 @@ Many workflows have optional validation workflows that perform independent revie
| `validate-tech-spec` | PM | Technical specification quality | | `validate-tech-spec` | PM | Technical specification quality |
| `validate-architecture` | Architect | Architecture document | | `validate-architecture` | Architect | Architecture document |
| `validate-design` | UX Designer | UX specification and artifacts | | `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-create-story` | SM | Story draft |
| `validate-story-context` | SM | Story context XML | | `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 3 (Solutioning):** Architect, Game Architect
- **Phase 4 (Implementation):** SM, DEV, Game Developer - **Phase 4 (Implementation):** SM, DEV, Game Developer
- **Testing:** TEA (all phases) - **Testing:** TEA (all phases)
- **Documentation:** Paige (all phases) - **Documentation:** Technical Writer (all phases)
**3. Use specialists** **3. Use specialists**
- **Testing:** TEA for comprehensive quality strategy - **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 - **Games:** Game Designer/Developer/Architect for game-specific needs
- **UX:** UX Designer for user-centered design - **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):** **Starting with Existing Code (Brownfield):**
``` ```
1. Analyst or Paige: *document-project 1. Analyst or Technical Writer: *document-project
2. PM or Analyst: *workflow-init 2. PM or Analyst: *workflow-init
3. PM: *create-prd or *tech-spec 3. PM: *create-prd or *tech-spec
4. Architect: *create-architecture (if needed) 4. Architect: *create-architecture (if needed)
@ -986,20 +938,20 @@ TEA can be invoked at any phase:
Quick reference for agent selection: Quick reference for agent selection:
| Agent | Icon | Primary Phase | Key Workflows | Best For | | Agent | Icon | Primary Phase | Key Workflows | Best For |
| ------------------ | ---- | ------------------ | --------------------------------------------- | ------------------------------------- | | ----------------------- | ---- | ------------------ | --------------------------------------------- | ------------------------------------- |
| **Analyst** | 📊 | 1 (Analysis) | brainstorm, brief, research, document-project | Discovery, requirements, brownfield | | **Analyst** | 📊 | 1 (Analysis) | brainstorm, brief, research, document-project | Discovery, requirements, brownfield |
| **PM** | 📋 | 2 (Planning) | prd, tech-spec, epics-stories | Planning, requirements docs | | **PM** | 📋 | 2 (Planning) | prd, tech-spec, epics-stories | Planning, requirements docs |
| **UX Designer** | 🎨 | 2 (Planning) | create-design, validate-design | UX-heavy projects, design | | **UX Designer** | 🎨 | 2 (Planning) | create-design, validate-design | UX-heavy projects, design |
| **Architect** | 🏗️ | 3 (Solutioning) | architecture, gate-check | Technical design, architecture | | **Architect** | 🏗️ | 3 (Solutioning) | architecture, gate-check | Technical design, architecture |
| **SM** | 🏃 | 4 (Implementation) | sprint-planning, create-story, story-context | Story management, sprint coordination | | **SM** | 🏃 | 4 (Implementation) | sprint-planning, create-story, story-context | Story management, sprint coordination |
| **DEV** | 💻 | 4 (Implementation) | develop-story, code-review, story-done | Implementation, coding | | **DEV** | 💻 | 4 (Implementation) | develop-story, code-review, story-done | Implementation, coding |
| **TEA** | 🧪 | All Phases | framework, atdd, automate, trace, ci | Testing, quality assurance | | **TEA** | 🧪 | All Phases | framework, atdd, automate, trace, ci | Testing, quality assurance |
| **Paige** | 📚 | All Phases | document-project, diagrams, validation | Documentation, diagrams | | **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 Designer** | 🎲 | 1-2 (Games) | brainstorm-game, gdd, narrative | Game design, creative vision |
| **Game Developer** | 🕹️ | 4 (Games) | dev-story, code-review | Game implementation | | **Game Developer** | 🕹️ | 4 (Games) | develop-story, story-done, code-review | Game implementation |
| **Game Architect** | 🏛️ | 3 (Games) | architecture, gate-check | Game systems architecture | | **Game Architect** | 🏛️ | 3 (Games) | architecture, gate-check | Game systems architecture |
| **BMad Master** | 🧙 | Meta | party-mode, list tasks/workflows | Orchestration, multi-agent | | **BMad Master** | 🧙 | Meta | party-mode, list tasks/workflows | Orchestration, multi-agent |
### Agent Capabilities Summary ### Agent Capabilities Summary
@ -1028,7 +980,7 @@ Quick reference for agent selection:
**Support Agents (2):** **Support Agents (2):**
- Analyst: Research and discovery - Analyst: Research and discovery
- Paige: Documentation and diagrams - Technical Writer: Documentation and diagrams
**Meta Agent (1):** **Meta Agent (1):**
@ -1079,7 +1031,7 @@ Quick reference for agent selection:
**Starting a Project:** **Starting a Project:**
- [ ] Determine project type (greenfield vs brownfield) - [ ] 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` - [ ] Load PM or Analyst → `*workflow-init`
- [ ] Follow phase-appropriate workflows - [ ] Follow phase-appropriate workflows
- [ ] Try `*party-mode` for strategic decisions - [ ] Try `*party-mode` for strategic decisions

168
src/modules/bmm/docs/brownfield-guide.md
View File

@ -92,22 +92,82 @@ You: "Yes"
## Phase 0: Documentation (Critical First Step) ## 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 | **Best practice:** Run `document-project` workflow unless you have **confirmed, trusted, AI-optimized documentation**.
| -------- | --------------------------- | -------------------- | -------- | ------ |
| **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 |
### 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 **Common Problems:**
2. Run "document-project"
- **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: 3. Choose scan level:
- **Quick** (2-5min): Pattern analysis, no source reading - **Quick** (2-5min): Pattern analysis, no source reading
- **Deep** (10-30min): Reads critical paths - **Recommended** - **Deep** (10-30min): Reads critical paths - **Recommended**
@ -119,31 +179,87 @@ You: "Yes"
- `docs/project-overview.md` - Executive summary - `docs/project-overview.md` - Executive summary
- `docs/architecture.md` - Architecture analysis - `docs/architecture.md` - Architecture analysis
- `docs/source-tree-analysis.md` - Directory structure - `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) Even if `docs/` folder exists, if you're unsure about quality → **regenerate**.
2. Load task: `bmad/core/tasks/index-docs.xml`
3. Specify docs directory (e.g., `./docs`)
4. Task generates `index.md` from existing docs
**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 ### 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 - **tech-spec** (Quick Flow) can't auto-detect stack/patterns → Makes wrong assumptions
- **PRD** (BMad Method/Enterprise) can't reference existing code - **PRD** (BMad Method) can't reference existing code → Designs incompatible features
- **architecture** (BMad Method/Enterprise) can't build on existing structure - **architecture** can't build on existing structure → Suggests conflicting patterns
- **story-context** can't inject pattern-specific guidance - **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.
--- ---

1324
src/modules/bmm/docs/brownfield-guide.md.backup
View File

File diff suppressed because it is too large Load Diff

1160
src/modules/bmm/docs/enterprise-agentic-development.md
View File

File diff suppressed because it is too large Load Diff

20
src/modules/bmm/docs/faq.md
View File

@ -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? ### 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? ### 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 ## 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:** **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 - **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+? ### 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) - PRD (product vision, requirements, epics)
- Architecture (system design) - 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? ### 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 went well
- What could improve - What could improve
- Technical insights - 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. 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:** **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 2. Introduce your topic
3. BMad Master selects 2-3 most relevant agents per message 3. BMad Master selects 2-3 most relevant agents per message
4. Agents cross-talk, debate, and build on each other's ideas 4. Agents cross-talk, debate, and build on each other's ideas

10
src/modules/bmm/docs/glossary.md
View File

@ -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. **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. **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) ### 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 ### 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 ### 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. 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 ### UX Designer

1234
src/modules/bmm/docs/party-mode.md
View File

File diff suppressed because it is too large Load Diff

41
src/modules/bmm/docs/workflows-implementation.md
View File

@ -10,18 +10,18 @@ Phase 4 (Implementation) workflows manage the iterative sprint-based development
## Quick Reference ## Quick Reference
| Workflow | Agent | Duration | Purpose | | Workflow | Agent | Duration | Purpose |
| --------------------- | --------- | -------------- | ------------------------------------ | | --------------------- | ------- | -------------- | ------------------------------------ |
| **sprint-planning** | SM | 30-60 min | Initialize sprint tracking file | | **sprint-planning** | SM | 30-60 min | Initialize sprint tracking file |
| **epic-tech-context** | Architect | 15-30 min/epic | Epic-specific technical guidance | | **epic-tech-context** | SM | 15-30 min/epic | Epic-specific technical guidance |
| **create-story** | SM | 10-20 min | Create next story from epics | | **create-story** | SM | 10-20 min | Create next story from epics |
| **story-context** | PM | 10-15 min | Assemble dynamic story context | | **story-context** | PM | 10-15 min | Assemble dynamic story context |
| **dev-story** | DEV | 2-8 hours | Implement story with tests | | **dev-story** | DEV | 2-8 hours | Implement story with tests |
| **code-review** | DEV | 30-60 min | Senior dev review of completed story | | **code-review** | DEV | 30-60 min | Senior dev review of completed story |
| **correct-course** | SM | 30-90 min | Handle mid-sprint changes | | **correct-course** | SM | 30-90 min | Handle mid-sprint changes |
| **retrospective** | SM | 60-90 min | Post-epic review and lessons | | **retrospective** | SM | 60-90 min | Post-epic review and lessons |
| **workflow-status** | All | 2-5 min | Check "what should I do now?" | | **workflow-status** | All | 2-5 min | Check "what should I do now?" |
| **document-project** | Analyst | 1-3 hours | Document brownfield projects | | **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: Phase 4 involves coordination between agents:
| Agent | Primary Workflows | Role | | Agent | Primary Workflows | Role |
| ------------- | ------------------------------------------------------------ | --------------------------- | | ----------- | ------------------------------------------------------------------------------- | -------------------------- |
| **SM** | sprint-planning, create-story, correct-course, retrospective | Orchestration, tracking | | **SM** | sprint-planning, epic-tech-context, create-story, correct-course, retrospective | Orchestration, tracking |
| **Architect** | epic-tech-context | Technical guidance per epic | | **PM** | story-context | Context assembly |
| **PM** | story-context | Context assembly | | **DEV** | dev-story, code-review | Implementation, quality |
| **DEV** | dev-story, code-review | Implementation, quality | | **Analyst** | document-project | Documentation (brownfield) |
| **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. 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) **Phase:** 4 (Implementation)
**Required:** Optional (recommended for Level 3-4) **Required:** Optional (recommended for Level 3-4)
**Typical Duration:** 15-30 minutes per epic **Typical Duration:** 15-30 minutes per epic
@ -974,7 +973,7 @@ Tests Added:
### Purpose ### 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) **Agent:** DEV (Senior Developer persona)
**Phase:** 4 (Implementation) **Phase:** 4 (Implementation)

2
src/modules/bmm/docs/workflows-solutioning.md
View File

@ -70,7 +70,7 @@ Phase 3 (Solutioning) workflows translate **what** to build (from Planning) into
**Level 3-4 (Required Solutioning):** **Level 3-4 (Required Solutioning):**
- Planning: Standard/Comprehensive PRD - Planning: Standard/Comprehensive PRD
- Solutioning: **Required** architecture + epic tech-spec - Solutioning: **Required** architecture + epic-tech-context
- Gate Check: **Required** solutioning-gate-check - Gate Check: **Required** solutioning-gate-check
- Implementation: dev-story guided by architecture - Implementation: dev-story guided by architecture

2
src/modules/bmm/workflows/4-implementation/epic-tech-context/workflow.yaml
View File

@ -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" description: "Generate a comprehensive Technical Specification from PRD and Architecture with acceptance criteria and traceability mapping"
author: "BMAD BMM" author: "BMAD BMM"

2
src/modules/bmm/workflows/techdoc/documentation-standards.md
View File

@ -1,6 +1,6 @@
# Technical Documentation Standards for BMAD # Technical Documentation Standards for BMAD
**For Agent: Paige (Documentation Guide)** **For Agent: Technical Writer**
**Purpose: Concise reference for documentation creation and review** **Purpose: Concise reference for documentation creation and review**
--- ---