17f81a84f3
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. |
||
|---|---|---|
| .. | ||
| create-ux-design | ||
| narrative | ||
| prd | ||
| tech-spec | ||
| README.md | ||
README.md
| last-redoc-date |
|---|
| 2025-10-01 |
Project Planning Workflow (Phase 2)
The Phase 2 Planning workflow is scale-adaptive, meaning it automatically determines the right level of planning documentation based on project complexity (Levels 0-4). This ensures planning overhead matches project value—from minimal tech specs for bug fixes to comprehensive PRDs for enterprise platforms.
Scale-Adaptive Flow (Levels 0-4)
The workflow routes to different planning approaches based on project level:
Level 0 - Single File Change / Bug Fix
Planning: Tech-spec only (lightweight implementation plan)
Output: tech-spec.md with single story
Next Phase: Direct to implementation (Phase 4)
Level 1 - Small Feature (1-3 files, 2-5 stories)
Planning: Tech-spec only (implementation-focused)
Output: tech-spec.md with epic breakdown and stories
Next Phase: Direct to implementation (Phase 4)
Level 2 - Feature Set / Small Project (5-15 stories, 1-2 epics)
Planning: PRD (product-focused) + Tech-spec (technical planning)
Output: PRD.md, epics.md, tech-spec.md
Next Phase: Tech-spec workflow (lightweight solutioning), then implementation (Phase 4)
Note: Level 2 uses tech-spec instead of full architecture to keep planning lightweight
Level 3 - Medium Project (15-40 stories, 2-5 epics)
Planning: PRD (strategic product document)
Output: PRD.md, epics.md
Next Phase: create-architecture workflow (Phase 3), then implementation (Phase 4)
Level 4 - Large/Enterprise Project (40-100+ stories, 5-10 epics)
Planning: PRD (comprehensive product specification)
Output: PRD.md, epics.md
Next Phase: create-architecture workflow (Phase 3), then implementation (Phase 4)
Critical Distinction:
- Levels 0-1: No PRD, tech-spec only
- Level 2: PRD + tech-spec (skips full architecture)
- Levels 3-4: PRD → full create-architecture workflow
Critical to v6's flow improvement is this workflow's integration with the bmm-workflow-status.md tracking document, which maintains project state across sessions, tracks which agents participate in each phase, and provides continuity for multi-session planning efforts. The workflow can resume from any point, intelligently detecting existing artifacts and determining next steps without redundant work. For UX-heavy projects, it can generate standalone UX specifications or AI frontend prompts from existing specs.
Key Features
- Scale-adaptive planning - Automatically determines output based on project complexity
- Intelligent routing - Uses router system to load appropriate instruction sets
- Continuation support - Can resume from previous sessions and handle incremental work
- Multi-level outputs - Supports 5 project levels (0-4) with appropriate artifacts
- Input integration - Leverages product briefs and market research when available
- Template-driven - Uses validated templates for consistent output structure
Configuration
The workflow adapts automatically based on project assessment, but key configuration options include:
- scale_parameters: Defines story/epic counts for each project level
- output_folder: Where all generated documents are stored
- project_name: Used in document names and templates
Workflow Structure
Files Included
2-plan-workflows/
├── README.md # Overview and usage details
├── checklist.md # Shared validation criteria
├── prd/
│ ├── epics-template.md # Epic breakdown template
│ ├── instructions.md # Level 2-4 PRD instructions
│ ├── prd-template.md # Product Requirements Document template
│ └── workflow.yaml
├── tech-spec/
│ ├── epics-template.md # Epic-to-story handoff template
│ ├── instructions-level0-story.md
│ ├── instructions-level1-stories.md
│ ├── instructions.md # Level 0-1 tech-spec instructions
│ ├── tech-spec-template.md # Technical Specification template
│ ├── user-story-template.md # Story template for Level 0/1
│ └── workflow.yaml
├── gdd/
│ ├── instructions-gdd.md # Game Design Document instructions
│ ├── gdd-template.md # GDD template
│ ├── game-types.csv # Genre catalog
│ ├── game-types/ # Genre-specific templates
│ └── workflow.yaml
├── narrative/
│ ├── instructions-narrative.md # Narrative design instructions
│ ├── narrative-template.md # Narrative planning template
│ └── workflow.yaml
└── create-ux-design/
├── instructions.md # UX design instructions
├── ux-design-template.md # UX design template
├── checklist.md # UX design validation checklist
└── workflow.yaml
Workflow Process
Phase 1: Assessment and Routing (Steps 1-5)
- Project Analysis: Determines project type (greenfield/brownfield/legacy)
- Scope Assessment: Classifies into 5 levels based on complexity
- Document Discovery: Identifies existing inputs and documentation
- Workflow Routing: Loads appropriate instruction set based on level
- Continuation Handling: Resumes from previous work when applicable
Phase 2: Level-Specific Planning (Steps vary by level)
Level 0 (Single File Change / Bug Fix):
- Tech-spec only workflow
- Single story implementation plan
- Direct to Phase 4 (implementation)
Level 1 (Small Feature):
- Tech-spec only workflow
- Epic breakdown with 2-5 stories
- Direct to Phase 4 (implementation)
Level 2 (Feature Set / Small Project):
- PRD workflow (strategic product document)
- Generates
PRD.mdandepics.md - Then runs tech-spec workflow (lightweight solutioning)
- Then to Phase 4 (implementation)
Level 3-4 (Medium to Enterprise Projects):
- PRD workflow (comprehensive product specification)
- Generates
PRD.mdandepics.md - Hands off to Phase 3 (create-architecture workflow)
- Full architecture design before implementation
Phase 3: Validation and Handoff (Final steps)
- Document Review: Validates outputs against checklists
- Architect Preparation: For Level 3-4, prepares handoff materials
- Next Steps: Provides guidance for development phase
Output
Generated Files
- Primary output: PRD.md (except Level 0), tech-spec.md, bmm-workflow-status.md
- Supporting files: epics.md (Level 2-4), PRD-validation-report.md (if validation run)
Output Structure by Level
Level 0 - Tech Spec Only:
tech-spec.md- Single story implementation plan- Direct to implementation
Level 1 - Tech Spec with Epic Breakdown:
tech-spec.md- Epic breakdown with 2-5 stories- Direct to implementation
Level 2 - PRD + Tech Spec:
PRD.md- Strategic product document (goals, requirements, user journeys, UX principles, UI goals, epic list, scope)epics.md- Tactical implementation roadmap (detailed story breakdown)tech-spec.md- Lightweight technical planning (generated after PRD)- Then to implementation
Level 3-4 - PRD + Full Architecture:
PRD.md- Comprehensive product specificationepics.md- Complete epic/story breakdown- Hands off to create-architecture workflow (Phase 3)
architecture.md- Generated by architect workflow- Then to implementation
Requirements
- Input Documents: Product brief and/or market research (recommended but not required)
- Project Configuration: Valid config.yaml with project_name and output_folder
- Assessment Readiness: Clear understanding of project scope and objectives
Best Practices
Before Starting
- Gather Context: Collect any existing product briefs, market research, or requirements
- Define Scope: Have a clear sense of project boundaries and complexity
- Prepare Stakeholders: Ensure key stakeholders are available for input if needed
During Execution
- Be Honest About Scope: Accurate assessment ensures appropriate planning depth
- Leverage Existing Work: Reference previous documents and avoid duplication
- Think Incrementally: Remember that planning can evolve - start with what you know
After Completion
- Validate Against Checklist: Use included validation criteria to ensure completeness
- Share with Stakeholders: Distribute appropriate documents to relevant team members
- Prepare for Architecture: For Level 3-4 projects, ensure architect has complete context
Troubleshooting
Common Issues
Issue: Workflow creates wrong level of documentation
- Solution: Review project assessment and restart with correct scope classification
- Check: Verify the bmm-workflow-status.md reflects actual project complexity
Issue: Missing input documents cause incomplete planning
- Solution: Gather recommended inputs or proceed with manual context gathering
- Check: Ensure critical business context is captured even without formal documents
Issue: Continuation from previous session fails
- Solution: Check for existing bmm-workflow-status.md and ensure output folder is correct
- Check: Verify previous session completed at a valid checkpoint
Customization
To customize this workflow:
- Modify Assessment Logic: Update instructions-router.md to adjust level classification
- Adjust Templates: Customize PRD, tech-spec, or epic templates for organizational needs
- Add Validation: Extend checklist.md with organization-specific quality criteria
- Configure Outputs: Modify workflow.yaml to change file naming or structure
Version History
- v6.0.0 - Scale-adaptive architecture with intelligent routing
- Multi-level project support (0-4)
- Continuation and resumption capabilities
- Template-driven output generation
- Input document integration
Support
For issues or questions:
- Review the workflow creation guide at
/bmad/bmb/workflows/create-workflow/workflow-creation-guide.md - Validate output using
checklist.md - Consult project assessment in
bmm-workflow-status.md - Check continuation status in existing output documents
Part of the BMad Method v6 - BMM (Method) Module