bmad-method 6.0.0-alpha.3 → 6.0.0-alpha.4

package/src/modules/bmb/workflows/create-workflow/workflow-creation-guide.md

@@ -1020,6 +1020,164 @@ _Generated on {{date}}_
 - **Unclosed check tags** - Always close `<check if="">...</check>` blocks
 - **Wrong conditional pattern** - Use `<action if="">` for single items, `<check if="">` for blocks
 
+## Document Sharding Support
+
+If your workflow loads large planning documents (PRDs, epics, architecture, etc.), implement sharding support for efficiency.
+
+### What is Document Sharding?
+
+Document sharding splits large markdown files into smaller section-based files:
+
+- `PRD.md` (50k tokens) → `prd/epic-1.md`, `prd/epic-2.md`, etc.
+- Enables selective loading (90%+ token savings)
+- All BMM workflows support both whole and sharded documents
+
+### When to Add Sharding Support
+
+**Add sharding support if your workflow:**
+
+- Loads planning documents (PRD, epics, architecture, UX specs)
+- May be used in large multi-epic projects
+- Processes documents that could exceed 20k tokens
+- Would benefit from selective section loading
+
+**Skip sharding support if your workflow:**
+
+- Only generates small documents
+- Doesn't load external documents
+- Works with code files (not planning docs)
+
+### Implementation Pattern
+
+#### 1. Add input_file_patterns to workflow.yaml
+
+```yaml
+# Smart input file references - handles both whole docs and sharded docs
+# Priority: Whole document first, then sharded version
+input_file_patterns:
+  prd:
+    whole: '{output_folder}/*prd*.md'
+    sharded: '{output_folder}/*prd*/index.md'
+
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_index: '{output_folder}/*epic*/index.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md' # For selective load
+
+  architecture:
+    whole: '{output_folder}/*architecture*.md'
+    sharded: '{output_folder}/*architecture*/index.md'
+
+  document_project:
+    sharded: '{output_folder}/docs/index.md' # Brownfield always uses index
+```
+
+#### 2. Add Discovery Instructions to instructions.md
+
+Place early in instructions (after critical declarations, before workflow steps):
+
+```markdown
+## 📚 Document Discovery
+
+This workflow requires: [list required documents]
+
+**Discovery Process** (execute for each document):
+
+1. **Search for whole document first** - Use fuzzy file matching
+2. **Check for sharded version** - If whole document not found, look for `{doc-name}/index.md`
+3. **If sharded version found**:
+   - Read `index.md` to understand the document structure
+   - Read ALL section files listed in the index (or specific sections for selective load)
+   - Treat the combined content as if it were a single document
+4. **Brownfield projects**: The `document-project` workflow creates `{output_folder}/docs/index.md`
+
+**Priority**: If both whole and sharded versions exist, use the whole document.
+
+**Fuzzy matching**: Be flexible with document names - users may use variations.
+```
+
+#### 3. Choose Loading Strategy
+
+**Full Load Strategy** (most workflows):
+
+```xml
+<action>Search for document using fuzzy pattern: {output_folder}/*prd*.md</action>
+<action>If not found, check for sharded version: {output_folder}/*prd*/index.md</action>
+<action if="sharded found">Read index.md to understand structure</action>
+<action if="sharded found">Read ALL section files listed in index</action>
+<action if="sharded found">Combine content as single document</action>
+```
+
+**Selective Load Strategy** (advanced - for phase 4 type workflows):
+
+```xml
+<action>Determine section needed (e.g., epic_num from story key)</action>
+<action>Check for sharded version: {output_folder}/*epics*/index.md</action>
+<action if="sharded found">Read ONLY the specific section file: epics/epic-{{epic_num}}.md</action>
+<action if="sharded found">Skip all other section files (efficiency optimization)</action>
+<action if="whole document found">Load complete document and extract relevant section</action>
+```
+
+### Pattern Examples
+
+**Example 1: Simple Full Load**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  requirements:
+    whole: '{output_folder}/*requirements*.md'
+    sharded: '{output_folder}/*requirements*/index.md'
+```
+
+```markdown
+<!-- instructions.md -->
+
+## Document Discovery
+
+Load requirements document (whole or sharded).
+
+1. Try whole: _requirements_.md
+2. If not found, try sharded: _requirements_/index.md
+3. If sharded: Read index + ALL section files
+```
+
+**Example 2: Selective Load with Epic Number**
+
+```yaml
+# workflow.yaml
+input_file_patterns:
+  epics:
+    whole: '{output_folder}/*epic*.md'
+    sharded_single: '{output_folder}/*epic*/epic-{{epic_num}}.md'
+```
+
+```xml
+<!-- instructions.md step -->
+<step n="2" goal="Load Epic Content">
+  <action>Extract epic number from story key (e.g., "3-2-feature" → epic_num = 3)</action>
+  <action>Check for sharded epics: {output_folder}/*epic*/index.md</action>
+  <action if="sharded found">Load ONLY epics/epic-{{epic_num}}.md (selective optimization)</action>
+  <action if="whole document found">Load full epics.md and extract Epic {{epic_num}}</action>
+</step>
+```
+
+### Testing Your Sharding Support
+
+1. **Test with whole document**: Verify workflow works with single `document.md`
+2. **Test with sharded document**: Create sharded version and verify discovery
+3. **Test with both present**: Ensure whole document takes priority
+4. **Test selective loading**: Verify only needed sections are loaded (if applicable)
+
+### Complete Reference
+
+**[→ Document Sharding Guide](../../../../docs/document-sharding-guide.md)** - Comprehensive guide with examples
+
+**BMM Examples**:
+
+- Full Load: `src/modules/bmm/workflows/2-plan-workflows/prd/`
+- Selective Load: `src/modules/bmm/workflows/4-implementation/epic-tech-context/`
+
 ## Web Bundles
 
 Web bundles allow workflows to be deployed as self-contained packages for web environments.

package/src/modules/bmm/README.md

@@ -2,143 +2,127 @@
 
 Core orchestration system for AI-driven agile development, providing comprehensive lifecycle management through specialized agents and workflows.
 
-## Table of Contents
-
-- [Essential Reading](#essential-reading)
-- [Module Structure](#module-structure)
-- [Quick Start](#quick-start)
-- [Key Concepts](#key-concepts)
-- [Scale Levels](#scale-levels)
-- [Story Lifecycle](#story-lifecycle)
-- [Best Practices](#best-practices)
-
-## Essential Reading
-
-**[📖 BMM v6 Workflows Guide](./workflows/README.md)** - Required reading before using BMM. Explains the revolutionary workflow system and component integration.
+---
 
-## Module Structure
+## 📚 Complete Documentation
 
-### 🤖 Agents
+👉 **[BMM Documentation Hub](./docs/README.md)** - Start here for complete guides, tutorials, and references
 
-**Core Development Roles:**
+**Quick Links:**
 
-- **PM** - Product Manager for planning and requirements
-- **Analyst** - Business analysis and research
-- **Architect** - Technical architecture and design
-- **SM** - Scrum Master for sprint and story management
-- **DEV** - Developer for implementation
-- **TEA** - Test Architect for quality assurance
-- **UX** - User experience design
+- **[Quick Start Guide](./docs/quick-start.md)** - New to BMM? Start here (15 min)
+- **[Agents Guide](./docs/agents-guide.md)** - Meet your 12 specialized AI agents (45 min)
+- **[Scale Adaptive System](./docs/scale-adaptive-system.md)** - How BMM adapts to project size (42 min)
+- **[FAQ](./docs/faq.md)** - Quick answers to common questions
+- **[Glossary](./docs/glossary.md)** - Key terminology reference
 
-**Game Development** (Optional):
+---
 
-- **Game Designer** - Creative vision and GDD creation
-- **Game Developer** - Game-specific implementation
-- **Game Architect** - Game systems and infrastructure
+## 🏗️ Module Structure
 
-### 📋 Workflows
+This module contains:
 
-Four-phase methodology adapting to project complexity:
+```
+bmm/
+├── agents/          # 12 specialized AI agents (PM, Architect, SM, DEV, TEA, etc.)
+├── workflows/       # 34 workflows across 4 phases + testing
+├── teams/           # Pre-configured agent groups
+├── tasks/           # Atomic work units
+├── testarch/        # Comprehensive testing infrastructure
+└── docs/            # Complete user documentation
+```
 
-**1. Analysis** (Optional)
+### Agent Roster
 
-- `brainstorm-project` - Project ideation
-- `research` - Market/technical research
-- `product-brief` - Product strategy
+**Core Development:** PM, Analyst, Architect, SM, DEV, TEA, UX Designer, Paige
+**Game Development:** Game Designer, Game Developer, Game Architect
+**Orchestration:** BMad Master (from Core)
 
-**2. Planning** (Required)
+👉 **[Full Agents Guide](./docs/agents-guide.md)** - Roles, workflows, and when to use each agent
 
-- `prd` - Scale-adaptive planning
-- Routes to appropriate documentation level
+### Workflow Phases
 
-**3. Solutioning** (Level 3-4)
+**Phase 0:** Documentation (brownfield only)
+**Phase 1:** Analysis (optional) - 5 workflows
+**Phase 2:** Planning (required) - 6 workflows
+**Phase 3:** Solutioning (Level 3-4) - 2 workflows
+**Phase 4:** Implementation (iterative) - 10 workflows
+**Testing:** Quality assurance (parallel) - 9 workflows
 
-- `architecture` - System design
-- `tech-spec` - Epic technical specifications
+👉 **[Workflow Guides](./docs/README.md#-workflow-guides)** - Detailed documentation for each phase
 
-**4. Implementation** (Iterative)
+---
 
-- `create-story` - Draft stories
-- `story-context` - Inject expertise
-- `dev-story` - Implement
-- `code-review` - Validate quality
+## 🚀 Getting Started
 
-### 👥 Teams
+**New Project:**
 
-Pre-configured agent groups for coordinated complex tasks.
+```bash
+# Install BMM
+npx bmad-method@alpha install
 
-### 📝 Tasks
+# Load Analyst agent in your IDE, then:
+*workflow-init
+```
 
-Atomic work units composing into larger workflows.
+**Existing Project (Brownfield):**
 
-### 🏗️ Test Architecture
+```bash
+# Document your codebase first
+*document-project
 
-**[TEA Guide](./testarch/README.md)** - Comprehensive testing strategy across 9 specialized workflows.
+# Then initialize
+*workflow-init
+```
 
-## Quick Start
+👉 **[Quick Start Guide](./docs/quick-start.md)** - Complete setup and first project walkthrough
 
-1. **Load PM agent** in your IDE
-2. **Wait for menu** to appear
-3. **Run workflow:**
-   ```
-   *prd
-   ```
+---
 
-**IDE Instructions:**
+## 🎯 Key Concepts
 
-- [Claude Code](../../docs/ide-info/claude-code.md)
-- [Cursor](../../docs/ide-info/cursor.md)
-- [VS Code](../../docs/ide-info/windsurf.md)
-- [Others](../../docs/ide-info/)
+### Scale-Adaptive Design
 
-## Key Concepts
+BMM automatically adjusts to project complexity (Levels 0-4):
 
-### Scale Levels
+- **Level 0-1:** Quick Spec Flow for bug fixes and small features
+- **Level 2:** PRD with optional architecture
+- **Level 3-4:** Full PRD + comprehensive architecture
 
-BMM automatically adapts complexity:
+👉 **[Scale Adaptive System](./docs/scale-adaptive-system.md)** - Complete level breakdown
 
-| Level | Stories       | Documentation     |
-| ----- | ------------- | ----------------- |
-| 0     | Single change | Minimal           |
-| 1     | 1-10          | Light PRD         |
-| 2     | 5-15          | Focused PRD       |
-| 3     | 12-40         | Full architecture |
-| 4     | 40+           | Enterprise scale  |
+### Story-Centric Implementation
 
-### Story Lifecycle
+Stories move through a defined lifecycle: `backlog → drafted → ready → in-progress → review → done`
 
-Four-state machine tracked in status file:
+Just-in-time epic context and story context provide exact expertise when needed.
 
-```
-BACKLOG → TODO → IN PROGRESS → DONE
-```
+👉 **[Implementation Workflows](./docs/workflows-implementation.md)** - Complete story lifecycle guide
 
-- **BACKLOG** - Ordered stories to draft
-- **TODO** - Ready for SM drafting
-- **IN PROGRESS** - Approved for DEV
-- **DONE** - Completed with metrics
+### Multi-Agent Collaboration
 
-### Just-In-Time Design
+Use party mode to engage all 19+ agents (from BMM, CIS, BMB, custom modules) in group discussions for strategic decisions, creative brainstorming, and complex problem-solving.
 
-Technical specifications created per epic during implementation, enabling learning and adaptation.
+👉 **[Party Mode Guide](./docs/party-mode.md)** - How to orchestrate multi-agent collaboration
 
-### Context Injection
+---
 
-Dynamic technical guidance generated for each story, providing exact expertise when needed.
+## 📖 Additional Resources
 
-## Best Practices
+- **[Brownfield Guide](./docs/brownfield-guide.md)** - Working with existing codebases
+- **[Quick Spec Flow](./docs/quick-spec-flow.md)** - Fast-track for Level 0-1 projects
+- **[Enterprise Agentic Development](./docs/enterprise-agentic-development.md)** - Team collaboration patterns
+- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
+- **[IDE Setup Guides](../../../docs/ide-info/)** - Configure Claude Code, Cursor, Windsurf, etc.
 
-1. **Start with workflows** - Let process guide you
-2. **Respect scale** - Don't over-document small projects
-3. **Trust the process** - Methodology carefully designed
-4. **Use status file** - Single source of truth for stories
+---
 
-## Related Documentation
+## 🤝 Community
 
-- **[Workflows Guide](./workflows/README.md)** - Complete workflow reference
-- **[Test Architect Guide](./testarch/README.md)** - Testing strategy
-- **[IDE Setup](../../docs/ide-info/)** - Environment configuration
+- **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share feedback (#general-dev, #bugs-issues)
+- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
+- **[YouTube](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs
 
 ---
 
-For complete BMad Method workflow system details, see the [BMM Workflows README](./workflows/README.md).
+**Ready to build?** → [Start with the Quick Start Guide](./docs/quick-start.md)

package/src/modules/bmm/agents/game-designer.agent.yaml

@@ -30,11 +30,11 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml"
       description: Guide me through Game Brainstorming
 
-    - trigger: game-brief
+    - trigger: create-game-brief
       workflow: "{project-root}/bmad/bmm/workflows/1-analysis/game-brief/workflow.yaml"
       description: Create Game Brief
 
-    - trigger: gdd
+    - trigger: create-gdd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/gdd/workflow.yaml"
       description: Create Game Design Document (GDD)
 

package/src/modules/bmm/agents/paige.agent.yaml

@@ -0,0 +1,69 @@
+# Paige - Documentation Guide Agent Definition
+
+agent:
+  metadata:
+    id: bmad/bmm/agents/paige.md
+    name: Paige
+    title: Documentation Guide
+    icon: 📚
+    module: bmm
+
+  persona:
+    role: Technical Documentation Specialist + Knowledge Curator
+    identity: Experienced technical writer with deep expertise in documentation standards (CommonMark, DITA, OpenAPI), API documentation, and developer experience. Master of clarity - transforms complex technical concepts into accessible, well-structured documentation. Proficient in multiple style guides (Google Developer Docs, Microsoft Manual of Style) and modern documentation practices including docs-as-code, structured authoring, and task-oriented writing. Specializes in creating comprehensive technical documentation across the full spectrum - API references, architecture decision records, user guides, developer onboarding, and living knowledge bases.
+    communication_style: Patient and supportive teacher who makes documentation feel approachable rather than daunting. Uses clear examples and analogies to explain complex topics. Balances precision with accessibility - knows when to be technically detailed and when to simplify. Encourages good documentation habits while being pragmatic about real-world constraints. Celebrates well-written docs and helps improve unclear ones without judgment.
+    principles:
+      - I believe documentation is teaching - every doc should help someone accomplish a specific task, not just describe features.
+      - My philosophy embraces clarity above all - I use plain language, structured content, and visual aids (Mermaid diagrams) to make complex topics accessible.
+      - I treat documentation as living artifacts that evolve with the codebase, advocating for docs-as-code practices and continuous maintenance rather than one-time creation.
+      - I operate with a standards-first mindset (CommonMark, OpenAPI, style guides) while remaining flexible to project needs, always prioritizing the reader's experience over rigid adherence to rules.
+
+  critical_actions:
+    - "CRITICAL: Load COMPLETE file {project-root}/src/modules/bmm/workflows/techdoc/documentation-standards.md into permanent memory and follow ALL rules within"
+    - "Load into memory {project-root}/bmad/bmm/config.yaml and set variables"
+    - "Remember the user's name is {user_name}"
+    - "ALWAYS communicate in {communication_language}"
+    - "ALWAYS write documentation in {document_output_language}"
+    - "CRITICAL: All documentation MUST follow CommonMark specification strictly - zero tolerance for violations"
+    - "CRITICAL: All Mermaid diagrams MUST use valid syntax - mentally validate before outputting"
+
+  menu:
+    - trigger: document-project
+      workflow: "{project-root}/bmad/bmm/workflows/document-project/workflow.yaml"
+      description: Comprehensive project documentation (brownfield analysis, architecture scanning)
+
+    - trigger: create-api-docs
+      workflow: "todo"
+      description: Create API documentation with OpenAPI/Swagger standards
+
+    - trigger: create-architecture-docs
+      workflow: "todo"
+      description: Create architecture documentation with diagrams and ADRs
+
+    - trigger: create-user-guide
+      workflow: "todo"
+      description: Create user-facing guides and tutorials
+
+    - trigger: audit-docs
+      workflow: "todo"
+      description: Review documentation quality and suggest improvements
+
+    - trigger: generate-diagram
+      action: "Create a Mermaid diagram based on user description. Ask for diagram type (flowchart, sequence, class, ER, state, git) and content, then generate properly formatted Mermaid syntax following CommonMark fenced code block standards."
+      description: Generate Mermaid diagrams (architecture, sequence, flow, ER, class, state)
+
+    - trigger: validate-doc
+      action: "Review the specified document against CommonMark standards, technical writing best practices, and style guide compliance. Provide specific, actionable improvement suggestions organized by priority."
+      description: Validate documentation against standards and best practices
+
+    - trigger: improve-readme
+      action: "Analyze the current README file and suggest improvements for clarity, completeness, and structure. Follow task-oriented writing principles and ensure all essential sections are present (Overview, Getting Started, Usage, Contributing, License)."
+      description: Review and improve README files
+
+    - trigger: explain-concept
+      action: "Create a clear technical explanation with examples and diagrams for a complex concept. Break it down into digestible sections using task-oriented approach. Include code examples and Mermaid diagrams where helpful."
+      description: Create clear technical explanations with examples
+
+    - trigger: standards-guide
+      action: "Display the complete documentation standards from {project-root}/src/modules/bmm/workflows/techdoc/documentation-standards.md in a clear, formatted way for the user."
+      description: Show BMAD documentation standards reference (CommonMark, Mermaid, OpenAPI)

package/src/modules/bmm/agents/pm.agent.yaml

@@ -31,10 +31,20 @@ agent:
       workflow: "{project-root}/bmad/bmm/workflows/workflow-status/workflow.yaml"
       description: Check workflow status and get recommendations (START HERE!)
 
-    - trigger: prd
+    - trigger: create-prd
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
       description: Create Product Requirements Document (PRD) for Level 2-4 projects
 
+    - trigger: create-epics-and-stories
+      workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/create-epics-and-stories/workflow.yaml"
+      description: Break PRD requirements into implementable epics and stories
+
+    - trigger: validate-prd
+      validate-workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/workflow.yaml"
+      checklist: "{project-root}/bmad/bmm/workflows/2-plan-workflows/prd/checklist.md"
+      document: "{output_folder}/PRD.md"
+      description: Validate PRD + Epics + Stories completeness and quality
+
     - trigger: tech-spec
       workflow: "{project-root}/bmad/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml"
       description: Create Tech Spec for Level 0-1 (sometimes Level 2) projects