mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
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
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user