docs: massive documentation overhaul + introduce Paige (Documentation Guide agent)

## 📚 Complete Documentation Restructure

**BMM Documentation Hub Created:**
- New centralized documentation system at `src/modules/bmm/docs/`
- 18 comprehensive guides organized by topic (7000+ lines total)
- Clear learning paths for greenfield, brownfield, and quick spec flows
- Professional technical writing standards throughout

**New Documentation:**
- `README.md` - Complete documentation hub with navigation
- `quick-start.md` - 15-minute getting started guide
- `agents-guide.md` - Comprehensive 12-agent reference (45 min read)
- `party-mode.md` - Multi-agent collaboration guide (20 min read)
- `scale-adaptive-system.md` - Deep dive on Levels 0-4 (42 min read)
- `brownfield-guide.md` - Existing codebase development (53 min read)
- `quick-spec-flow.md` - Rapid Level 0-1 development (26 min read)
- `workflows-analysis.md` - Phase 1 workflows (12 min read)
- `workflows-planning.md` - Phase 2 workflows (19 min read)
- `workflows-solutioning.md` - Phase 3 workflows (13 min read)
- `workflows-implementation.md` - Phase 4 workflows (33 min read)
- `workflows-testing.md` - Testing & QA workflows (29 min read)
- `workflow-architecture-reference.md` - Architecture workflow deep-dive
- `workflow-document-project-reference.md` - Document-project workflow reference
- `enterprise-agentic-development.md` - Team collaboration patterns
- `faq.md` - Comprehensive Q&A covering all topics
- `glossary.md` - Complete terminology reference
- `troubleshooting.md` - Common issues and solutions

**Documentation Improvements:**
- Removed all version/date footers (git handles versioning)
- Agent customization docs now include full rebuild process
- Cross-referenced links between all guides
- Reading time estimates for all major docs
- Consistent professional formatting and structure

**Consolidated & Streamlined:**
- Module README (`src/modules/bmm/README.md`) streamlined to lean signpost
- Root README polished with better hierarchy and clear CTAs
- Moved docs from root `docs/` to module-specific locations
- Better separation of user docs vs. developer reference

## 🤖 New Agent: Paige (Documentation Guide)

**Role:** Technical documentation specialist and information architect

**Expertise:**
- Professional technical writing standards
- Documentation structure and organization
- Information architecture and navigation
- User-focused content design
- Style guide enforcement

**Status:** Work in progress - Paige will evolve as documentation needs grow

**Integration:**
- Listed in agents-guide.md, glossary.md, FAQ
- Available for all phases (documentation is continuous)
- Can be customized like all BMM agents

## 🔧 Additional Changes

- Updated agent manifest with Paige
- Updated workflow manifest with new documentation workflows
- Fixed workflow-to-agent mappings across all guides
- Improved root README with clearer Quick Start section
- Better module structure explanations
- Enhanced community links with Discord channel names

**Total Impact:**
- 18 new/restructured documentation files
- 7000+ lines of professional technical documentation
- Complete navigation system with cross-references
- Clear learning paths for all user types
- Foundation for knowledge base (coming in beta)

Co-Authored-By: Claude <noreply@anthropic.com>

bmad/bmm/workflows/workflow-status/paths/brownfield-level-0.yaml

@@ -0,0 +1,54 @@
+# Brownfield Level 0 - Single Atomic Change in Existing Codebase
+# One change to existing system
+
+project_type: "software"
+level: 0
+field_type: "brownfield"
+description: "Single atomic change to existing codebase"
+
+phases:
+  - prerequisite: true
+    name: "Documentation"
+    conditional: "if_undocumented"
+    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
+    workflows:
+      - id: "document-project"
+        required: true
+        agent: "analyst"
+        command: "document-project"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "tech-spec"
+        required: true
+        agent: "architect"
+        command: "tech-spec"
+        output: "Creates single story file"
+        note: "Must understand existing patterns"
+
+  - phase: 3
+    name: "Solutioning"
+    skip: true
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/brownfield-level-1.yaml

@@ -0,0 +1,58 @@
+# Brownfield Level 1 - Small Feature in Existing Codebase
+# 1-10 stories adding to existing system
+
+project_type: "software"
+level: 1
+field_type: "brownfield"
+description: "Small feature addition to existing codebase"
+
+phases:
+  - prerequisite: true
+    name: "Documentation"
+    conditional: "if_undocumented"
+    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
+    workflows:
+      - id: "document-project"
+        required: true
+        agent: "analyst"
+        command: "document-project"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "tech-spec"
+        required: true
+        agent: "pm"
+        command: "tech-spec"
+        output: "Creates story files for feature"
+        note: "Must integrate with existing architecture"
+
+  - phase: 3
+    name: "Solutioning"
+    skip: true
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/brownfield-level-2.yaml

@@ -0,0 +1,76 @@
+# Brownfield Level 2 - Medium Project in Existing Codebase
+# 5-15 stories, multiple features added to existing system
+
+project_type: "software"
+level: 2
+field_type: "brownfield"
+description: "Medium project adding multiple features to existing codebase"
+
+phases:
+  - prerequisite: true
+    name: "Documentation"
+    conditional: "if_undocumented"
+    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
+    workflows:
+      - id: "document-project"
+        required: true
+        agent: "analyst"
+        command: "document-project"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+      - id: "product-brief"
+        optional: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        recommended: true
+        agent: "pm"
+        command: "prd"
+        output: "Focused PRD for new features"
+        note: "Must consider existing system constraints"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "tech-spec"
+        required: true
+        agent: "pm"
+        command: "tech-spec"
+        output: "Creates spec with multiple story files"
+        note: "Integrate with existing patterns"
+      - id: "create-design"
+        conditional: "if_has_ui"
+        agent: "ux-designer"
+        command: "create-design"
+
+  - phase: 3
+    name: "Solutioning"
+    skip: true
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/brownfield-level-3.yaml

@@ -0,0 +1,95 @@
+# Brownfield Level 3 - Complex Integration with Existing System
+# Major feature addition requiring architectural integration
+
+project_type: "software"
+level: 3
+field_type: "brownfield"
+description: "Complex integration with existing system architecture"
+
+phases:
+  - prerequisite: true
+    name: "Documentation"
+    conditional: "if_undocumented"
+    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup"
+    workflows:
+      - id: "document-project"
+        required: true
+        agent: "analyst"
+        command: "document-project"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+
+  - phase: 1
+    name: "Analysis"
+    recommended: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        recommended: true
+        agent: "analyst"
+        command: "research"
+        note: "Research existing architecture patterns"
+      - id: "product-brief"
+        recommended: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        required: true
+        agent: "pm"
+        command: "prd"
+        output: "Requirements with integration points"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "create-design"
+        conditional: "if_has_ui"
+        agent: "ux-designer"
+        command: "create-design"
+        note: "Must align with existing UI patterns"
+
+  - phase: 3
+    name: "Solutioning"
+    required: true
+    workflows:
+      - id: "architecture-review"
+        required: true
+        agent: "architect"
+        command: "architecture-review"
+        note: "Review existing architecture first"
+      - id: "integration-planning"
+        required: true
+        agent: "architect"
+        command: "integration-planning"
+        output: "Integration strategy document"
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        note: "Extension of existing architecture"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        required: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/brownfield-level-4.yaml

@@ -0,0 +1,88 @@
+# Brownfield Level 4 - Enterprise Scale Changes to Existing System
+# 40+ stories, major expansion of existing enterprise system
+
+project_type: "software"
+level: 4
+field_type: "brownfield"
+description: "Enterprise scale expansion of existing system"
+
+phases:
+  - prerequisite: true
+    name: "Documentation"
+    conditional: "if_undocumented"
+    note: "NOT a phase - prerequisite for brownfield without docs OR post-completion cleanup. Critical for enterprise-scale changes"
+    workflows:
+      - id: "document-project"
+        required: true
+        agent: "analyst"
+        command: "document-project"
+        output: "Comprehensive project documentation"
+        purpose: "Understand existing codebase before planning OR create superior final docs after Phase 4"
+
+  - phase: 1
+    name: "Analysis"
+    required: true
+    workflows:
+      - id: "brainstorm-project"
+        recommended: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        required: true
+        agent: "analyst"
+        command: "research"
+        note: "Research existing system architecture deeply"
+      - id: "product-brief"
+        required: true
+        agent: "analyst"
+        command: "product-brief"
+        note: "Strategic brief for major expansion"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        required: true
+        agent: "pm"
+        command: "prd"
+        output: "Comprehensive PRD considering existing system"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "create-design"
+        required: true
+        agent: "ux-designer"
+        command: "create-design"
+        note: "Multiple UI/UX specifications"
+
+  - phase: 3
+    name: "Solutioning"
+    required: true
+    workflows:
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        output: "Architecture for system expansion"
+        note: "Must maintain backward compatibility"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        required: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+        note: "Critical validation before major changes"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/game-design.yaml

@@ -0,0 +1,75 @@
+# Game Design - All Levels
+# Game development follows a different path than software
+
+project_type: "game"
+level: "all"
+field_type: "any"
+description: "Game development workflow - applies to all complexity levels"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-game"
+        optional: true
+        agent: "game-designer"
+        command: "brainstorm-game"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+        note: "Market research, competitive analysis"
+      - id: "game-brief"
+        recommended: true
+        agent: "game-designer"
+        command: "game-brief"
+        output: "Game concept and vision document"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "gdd"
+        required: true
+        agent: "pm"
+        command: "gdd"
+        output: "Game Design Document with features and mechanics"
+      - id: "tech-spec"
+        conditional: "if_level_0_1"
+        agent: "architect"
+        command: "tech-spec"
+        note: "For simpler games, jump to implementation"
+
+  - phase: 3
+    name: "Solutioning"
+    conditional: "if_level_3_4"
+    workflows:
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        note: "Engine architecture, networking, systems"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        required: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"
+
+special_considerations:
+  - "Iterative playtesting throughout development"
+  - "Art and audio pipelines run parallel to code"
+  - "Balance and tuning as ongoing process"

bmad/bmm/workflows/workflow-status/paths/greenfield-level-0.yaml

@@ -0,0 +1,45 @@
+# Greenfield Level 0 - Single Atomic Change
+# The simplest possible workflow - one change, one story
+
+project_type: "software"
+level: 0
+field_type: "greenfield"
+description: "Single atomic change - bug fix, tiny feature, one story"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "product-brief"
+        optional: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "tech-spec"
+        required: true
+        agent: "pm"
+        command: "tech-spec"
+        output: "Creates Technical Specification with single story file"
+
+  - phase: 3
+    name: "Solutioning"
+    skip: true
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/greenfield-level-1.yaml

@@ -0,0 +1,49 @@
+# Greenfield Level 1 - Small Feature
+# Coherent feature with 2-3 stories in a single epic
+
+project_type: "software"
+level: 1
+field_type: "greenfield"
+description: "Small coherent feature - 2-3 stories, single epic"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+      - id: "product-brief"
+        optional: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "tech-spec"
+        required: true
+        agent: "pm"
+        command: "tech-spec"
+        output: "Creates Technical Specification with an epic and 2-3 story files"
+
+  - phase: 3
+    name: "Solutioning"
+    skip: true
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/greenfield-level-2.yaml

@@ -0,0 +1,78 @@
+# Greenfield Level 2 - Medium Project
+# Multiple epics with 10+ stories total
+
+project_type: "software"
+level: 2
+field_type: "greenfield"
+description: "Medium project - multiple epics, 10+ stories"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+        note: "Can have multiple research docs"
+      - id: "product-brief"
+        recommended: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        required: true
+        agent: "pm"
+        command: "prd"
+        output: "Creates PRD with epics.md and story list"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "create-design"
+        conditional: "if_has_ui"
+        agent: "ux-designer"
+        command: "create-design"
+      - id: "tech-spec"
+        optional: true
+        agent: "pm"
+        command: "tech-spec"
+        note: "Lightweight Technical Specification planning"
+
+  - phase: 3
+    name: "Solutioning"
+    required: true
+    workflows:
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        output: "System-wide architecture document"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        required: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+        note: "Validate PRD + UX + architecture cohesion before implementation"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/greenfield-level-3.yaml

@@ -0,0 +1,73 @@
+# Greenfield Level 3 - Complex System
+# Subsystems, integrations, architectural decisions required
+
+project_type: "software"
+level: 3
+field_type: "greenfield"
+description: "Complex system - subsystems, integrations, architectural decisions"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    optional: true
+    workflows:
+      - id: "brainstorm-project"
+        optional: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        optional: true
+        agent: "analyst"
+        command: "research"
+        note: "Multiple research areas likely"
+      - id: "product-brief"
+        recommended: true
+        agent: "analyst"
+        command: "product-brief"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        required: true
+        agent: "pm"
+        command: "prd"
+        output: "High-level requirements and epic definitions"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "create-design"
+        conditional: "if_has_ui"
+        agent: "ux-designer"
+        command: "create-design"
+
+  - phase: 3
+    name: "Solutioning"
+    required: true
+    workflows:
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        output: "System-wide architecture document"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        recommended: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+        note: "Validate PRD + UX + architecture cohesion before implementation"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"

bmad/bmm/workflows/workflow-status/paths/greenfield-level-4.yaml

@@ -0,0 +1,75 @@
+# Greenfield Level 4 - Enterprise Scale
+# Multiple products, enterprise architecture, 40+ stories
+
+project_type: "software"
+level: 4
+field_type: "greenfield"
+description: "Enterprise scale - multiple products, enterprise architecture"
+
+phases:
+  - phase: 1
+    name: "Analysis"
+    required: true
+    workflows:
+      - id: "brainstorm-project"
+        recommended: true
+        agent: "analyst"
+        command: "brainstorm-project"
+      - id: "research"
+        required: false
+        agent: "analyst"
+        command: "research"
+        note: "Extensive research across multiple domains"
+      - id: "product-brief"
+        required: true
+        agent: "analyst"
+        command: "product-brief"
+        note: "Strategic brief for enterprise scope"
+
+  - phase: 2
+    name: "Planning"
+    required: true
+    workflows:
+      - id: "prd"
+        required: true
+        agent: "pm"
+        command: "prd"
+        output: "Comprehensive product requirements document"
+      - id: "validate-prd"
+        optional: true
+        agent: "pm"
+        command: "validate-prd"
+      - id: "create-design"
+        required: true
+        agent: "ux-designer"
+        command: "create-design"
+        note: "Multiple UI/UX specifications needed"
+
+  - phase: 3
+    name: "Solutioning"
+    required: true
+    workflows:
+      - id: "create-architecture"
+        required: true
+        agent: "architect"
+        command: "create-architecture"
+        output: "Enterprise architecture documentation"
+      - id: "validate-architecture"
+        optional: true
+        agent: "architect"
+        command: "validate-architecture"
+      - id: "solutioning-gate-check"
+        required: true
+        agent: "architect"
+        command: "solutioning-gate-check"
+        note: "Validate PRD + UX + architecture cohesion before implementation"
+
+  - phase: 4
+    name: "Implementation"
+    required: true
+    workflows:
+      - id: "sprint-planning"
+        required: true
+        agent: "sm"
+        command: "sprint-planning"
+        note: "Creates sprint plan with all stories - subsequent work tracked in sprint plan output, not workflow-status"