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

package/CHANGELOG.md

@@ -2,6 +2,245 @@
 
 ## [Unreleased]
 
+## [6.0.0-alpha.4]
+
+**Release: November 2, 2025**
+
+This alpha release represents a major leap forward in documentation, workflow intelligence, and usability. The BMM module now features professional documentation, context-aware planning workflows, and universal document management capabilities.
+
+### 📚 Complete Documentation Overhaul
+
+**New Documentation Hub** (`src/modules/bmm/docs/`)
+
+- Created centralized documentation system with 18 comprehensive guides (7000+ lines)
+- Clear learning paths for greenfield, brownfield, and quick spec flows
+- Professional technical writing standards throughout all documentation
+- Reading time estimates and cross-referenced navigation
+
+**New Documentation Files:**
+
+- `README.md` - Complete documentation hub with topic 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 deep-dive (12 min read)
+- `workflows-planning.md` - Phase 2 workflows deep-dive (19 min read)
+- `workflows-solutioning.md` - Phase 3 workflows deep-dive (13 min read)
+- `workflows-implementation.md` - Phase 4 workflows deep-dive (33 min read)
+- `workflows-testing.md` - Testing & QA workflows (29 min read)
+- `workflow-architecture-reference.md` - Architecture workflow technical reference
+- `workflow-document-project-reference.md` - Document-project workflow technical reference
+- `enterprise-agentic-development.md` - Team collaboration patterns
+- `faq.md` - Comprehensive Q&A covering all common questions
+- `glossary.md` - Complete BMM terminology reference
+- `troubleshooting.md` - Common issues and solutions guide
+
+**Documentation Improvements:**
+
+- Removed version/date footers (git handles versioning automatically)
+- Agent customization docs now include full rebuild process
+- Consistent professional formatting and structure across all docs
+- Better separation of user documentation vs developer reference
+
+### 🤖 New Agent: Paige (Documentation Guide)
+
+Introduced Paige, a specialized technical documentation agent:
+
+- **Expertise:** Professional technical writing, information architecture, documentation structure
+- **Integration:** Available across all BMM phases for continuous documentation support
+- **Customizable:** Like all BMM agents, can be customized via sidecar files
+- **Status:** Work in progress - will evolve as documentation needs grow
+
+### 🚀 Quick Spec Flow - Intelligent Level 0-1 Planning
+
+**Major Tech-Spec Workflow Transformation:**
+
+- Transformed from template-filling into context-aware intelligent planning system
+- Ideal for bug fixes, single endpoint additions, and small isolated changes
+- Auto-detects project stack (package.json, requirements.txt, etc.)
+- Analyzes brownfield codebases for conventions and patterns
+- Integrates WebSearch for current framework versions and best practices
+
+**Context-Aware Intelligence:**
+
+- Interactive level detection (Level 0 vs Level 1)
+- Brownfield convention detection with user confirmation
+- Comprehensive context discovery (stack, patterns, dependencies, test frameworks)
+- Auto-validation with quality scoring (no manual checklist needed)
+- UX/UI considerations capture for user-facing changes
+
+**Enhanced Tech-Spec Template:**
+
+- Expanded from 8 to 23 sections for complete planning context
+- New sections: Development Context, UX/UI Considerations, Integration Points
+- Developer Resources section with file paths and testing guidance
+- All sections populated via template-output tags during workflow
+
+**Story Generation Improvements:**
+
+- Level 0: Extract single story from comprehensive tech-spec
+- Level 1: Story sequence validation with acceptance criteria quality checks
+- User Story Template includes Dev Agent Record sections for implementation tracking
+- Complete epic template rewrite with proper variable structure
+
+**Phase 4 Integration:**
+
+- Story Context and Create Story workflows now recognize tech-spec as authoritative source
+- Seamless integration between Quick Spec Flow and traditional BMM workflows
+- Tech-spec provides brownfield analysis, framework details, and existing patterns
+
+### 📦 Universal Document Sharding
+
+**New Capability: Shard-Doc Workflow**
+
+- Split large markdown documents into organized, smaller files based on sections
+- Dual-strategy loading: include individual shards OR single large document
+- Configurable section level (default: level 2 headings)
+- Automatic index.md generation with navigation links
+- Ideal for large guides, API documentation, and knowledge bases
+
+**Use Cases:**
+
+- Breaking down massive planning documents for better context management
+- Creating navigable documentation hierarchies
+- Managing agent knowledge bases efficiently
+- Optimizing context window usage during development
+
+**Integration:**
+
+- Available as BMad Core workflow: `/bmad:core:tools:shard-doc`
+- Works with any markdown document in your project
+- Preserves original file with automatic backups
+- Generated shards maintain formatting and structure
+
+### 🔧 Planning Workflow Enhancements
+
+**Intent-Driven Discovery (Product Brief & PRD):**
+
+- Transformed from rigid template-filling to natural conversational discovery
+- Adaptive questioning based on project context (hobby/startup/enterprise)
+- Real-time document building instead of end-of-session generation
+- Skill-level aware facilitation (expert/intermediate/beginner)
+- Context detection from user responses to guide exploration depth
+
+**Product Brief Workflow (96% BMAD v6 compliance):**
+
+- Intent-driven facilitation with context-appropriate probing
+- Living document approach with continuous template updates
+- Enhanced discovery areas: problem exploration, solution vision, user understanding
+- Ruthless MVP scope management with feature prioritization
+- Template improvements with context-aware conditional sections
+
+**PRD Workflow (improved from 65% to 85%+ compliance):**
+
+- Fixed critical config issues (missing date variable, status file extension mismatch)
+- Scale-adaptive intelligence with project type detection (API/Web App/Mobile/SaaS)
+- Domain complexity mapping (14 domain types with specialized considerations)
+- Enhanced requirements coverage: project-type specific sections, domain considerations
+- Separated epic planning into dedicated create-epics-and-stories child workflow
+
+**Architecture Workflow:**
+
+- Better integration with PRD outputs
+- Domain complexity context support
+- Enhanced technical decision capture framework
+
+### 🛠️ Research Workflow Improvements
+
+**Enhanced Research Capabilities:**
+
+- Updated to use web search more frequently for current information
+- Better understanding of current date context for finding latest documentation
+- Improved deep research prompt generation options
+- More accurate and up-to-date research results
+
+### 🎨 User Experience Improvements
+
+**Installer Updates:**
+
+- Improved installation notes and guidance
+- Better command examples (shard-doc uses npx command pattern)
+
+**Workflow Cleanup:**
+
+- Removed unused voice hooks functionality
+- Cleaned up backup and temporary files
+- Better workflow naming consistency
+
+### 📋 Infrastructure & Quality
+
+**Agent & Workflow Manifests:**
+
+- Added Paige to agent manifest
+- Updated workflow manifest with new and restructured workflows
+- Better workflow-to-agent mappings across all documentation
+- Updated files manifest with all new documentation
+
+**Module Organization:**
+
+- Streamlined BMM README to lean signpost format
+- Polished root README with better hierarchy and clear CTAs
+- Moved documentation from root `docs/` to module-specific locations
+- Better separation of user docs vs developer reference
+
+**Data Infrastructure:**
+
+- New CSV data files for project types and domain complexity
+- Enhanced workflow configuration with runtime variables
+- Better template variable mapping and tracking
+
+### 🔄 Breaking Changes
+
+**File Removals:**
+
+- Removed `src/modules/bmm/workflows/2-plan-workflows/prd/epics-template.md` (replaced by create-epics-and-stories child workflow)
+
+**Workflow Trigger Changes:**
+
+- PM agent: `prd` → `create-prd`
+- New workflow triggers: `create-epics-and-stories`, `validate-prd`
+- Game Designer agent triggers renamed for consistency
+
+### 📖 What's Next (Beta Roadmap)
+
+- Knowledge base integration for enhanced context management
+- Web bundle functionality completion
+- Additional specialized agents based on community feedback
+- Enhanced multi-agent collaboration patterns
+- Performance optimizations for large projects
+
+---
+
+### Installation
+
+```bash
+npx bmad-method@6.0.0-alpha.4 install
+```
+
+For upgrading from alpha.3:
+
+```bash
+# Backup your customizations first
+npx bmad-method@6.0.0-alpha.4 install
+```
+
+### Migration Notes
+
+If upgrading from v6.0.0-alpha.3:
+
+1. New documentation is available in `bmad/bmm/docs/` - review the README.md for navigation
+2. Tech-spec workflow now has enhanced capabilities - review `docs/quick-spec-flow.md`
+3. Product Brief and PRD workflows have new conversational approaches
+4. Paige agent is now available for documentation tasks
+5. No breaking changes to existing project structures
+
+---
+
+## [6.0.0-alpha.3]
+
 ### Codex Installer
 
 - Codex installer uses custom prompts in `.codex/prompts/`, instead of `AGENTS.md`

package/README.md

@@ -5,204 +5,320 @@
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
-> **🚨 ALPHA VERSION DOCUMENTATION**
+> **🚨 Alpha Version Notice**
+>
+> v6-alpha is near-beta quality—stable and vastly improved over v4, but documentation is still being refined. New videos coming soon to the [BMadCode YouTube channel](https://www.youtube.com/@BMadCode)—subscribe for updates!
+>
+> **Getting Started:**
 >
 > - **Install v6 Alpha:** `npx bmad-method@alpha install`
 > - **Install stable v4:** `npx bmad-method install`
-> - **[View v4 documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+> - **Not sure what to do?** Load any agent and run `*workflow-init` for guided setup
+> - **v4 Users:** [View v4 documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4) or [upgrade guide](./docs/v4-to-v6-upgrade.md)
 
 ## Universal Human-AI Collaboration Platform
 
-BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.
+**BMad-CORE** (**C**ollaboration **O**ptimized **R**eflection **E**ngine) amplifies human potential through specialized AI agents. Unlike tools that replace thinking, BMad-CORE guides reflective workflows that bring out your best ideas and AI's full capabilities.
+
+The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but you can also use **BMad Builder** to create custom agents, workflows, and modules for any domain—software development, business strategy, creativity, learning, and more.
 
 **🎯 Human Amplification** • **🎨 Domain Agnostic** • **⚡ Agent-Powered**
 
 ## Table of Contents
 
-- [Quick Start](#quick-start)
-- [What is BMad-CORE?](#what-is-bmad-core)
-- [Modules](#modules)
-  - [BMad Method (BMM)](#bmad-method-bmm---agile-ai-development)
-  - [BMad Builder (BMB)](#bmad-builder-bmb---create-custom-solutions)
-  - [Creative Intelligence Suite (CIS)](#creative-intelligence-suite-cis---innovation--creativity)
-- [Installation](#installation)
-- [Key Features](#key-features)
-- [Documentation](#documentation)
-- [Community & Support](#community--support)
-
-## Quick Start
+- [BMad CORE + BMad Method](#bmad-core--bmad-method)
+  - [Universal Human-AI Collaboration Platform](#universal-human-ai-collaboration-platform)
+  - [Table of Contents](#table-of-contents)
+  - [What is BMad-CORE?](#what-is-bmad-core)
+    - [v6 Core Enhancements](#v6-core-enhancements)
+    - [C.O.R.E. Philosophy](#core-philosophy)
+  - [Modules](#modules)
+    - [BMad Method (BMM) - Agile AI Development](#bmad-method-bmm---agile-ai-development)
+      - [v6 Highlights](#v6-highlights)
+    - [Quick Start](#quick-start)
+      - [⚡ NEW: Quick Spec Flow for Rapid Development](#-new-quick-spec-flow-for-rapid-development)
+    - [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions)
+    - [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
+  - [Installation](#installation)
+    - [Project Structure](#project-structure)
+    - [Getting Started](#getting-started)
+  - [Key Features](#key-features)
+    - [🎨 Update-Safe Customization](#-update-safe-customization)
+    - [🚀 Intelligent Installation](#-intelligent-installation)
+    - [📁 Unified Architecture](#-unified-architecture)
+    - [📄 Document Sharding](#-document-sharding)
+  - [Documentation](#documentation)
+  - [Community \& Support](#community--support)
+  - [Contributing](#contributing)
+  - [License](#license)
 
-- **New to v6?** [→ BMad Method V6 Quick Start Guide](./docs/BMad-Method-V6-Quick-Start.md)
-- **Upgrading?** [→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)
+---
 
 ## What is BMad-CORE?
 
 Foundation framework powering all BMad modules:
 
-- **Agent Orchestration** - Specialized AI personas with unique capabilities
-- **Workflow Engine** - Guided multi-step processes
-- **Modular Architecture** - Domain-specific extensions
-- **IDE Integration** - Works across development environments
-- **Update-Safe Customization** - Persistent configuration through updates
+- **Agent Orchestration** - Specialized AI personas with domain expertise
+- **Workflow Engine** - Guided multi-step processes with built-in best practices
+- **Modular Architecture** - Extend with domain-specific modules (BMM, BMB, CIS, custom)
+- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code, and more
+- **Update-Safe Customization** - Your configs persist through all updates
 
 ### v6 Core Enhancements
 
 - **🎨 Agent Customization** - Modify names, roles, personalities via `bmad/_cfg/agents/`
 - **🌐 Multi-Language** - Independent language settings for communication and output
-- **👤 Personalization** - Agents adapt to your name, technical level, preferences
-- **🔄 Persistent Config** - Customizations survive all updates
-- **⚙️ Flexible Settings** - Module or global configuration options
+- **👤 Personalization** - Agents adapt to your name, skill level, and preferences
+- **🔄 Persistent Config** - Customizations survive module updates
+- **⚙️ Flexible Settings** - Configure per-module or globally
 
 ### C.O.R.E. Philosophy
 
-- **C**ollaboration: Human-AI partnership leveraging unique strengths
-- **O**ptimized: Refined processes for maximum effectiveness
-- **R**eflection: Guided thinking unlocking better solutions
-- **E**ngine: Framework orchestrating specialized agents and workflows
+- **C**ollaboration: Human-AI partnership leveraging complementary strengths
+- **O**ptimized: Battle-tested processes for maximum effectiveness
+- **R**eflection: Strategic questioning that unlocks breakthrough solutions
+- **E**ngine: Framework orchestrating 19+ specialized agents and 50+ workflows
 
-BMad-CORE helps you **discover better solutions** through strategic questioning and structured thinking.
+BMad-CORE doesn't give you answers—it helps you **discover better solutions** through guided reflection.
 
 ## Modules
 
-### BMad Method (BMM) - Agile AI Development
+### BMad Method (BMM) - AI-Driven Agile Development
 
-AI-driven agile framework revolutionizing software and game development. Adapts from bug fixes to enterprise systems.
+Revolutionary AI-driven agile framework for software and game development. Automatically adapts from single bug fixes to enterprise-scale systems.
 
 #### v6 Highlights
 
-**🎯 Scale-Adaptive Workflows (Levels 0-4)**
+**🎯 Scale-Adaptive Intelligence (Levels 0-4)**
+
+Automatically adjusts planning depth and documentation based on project complexity:
+
+- **Level 0:** Bug fixes (hours)
+- **Level 1:** Small features (1-10 stories)
+- **Level 2:** Medium projects (5-15 stories)
+- **Level 3:** Complex integration (12-40 stories)
+- **Level 4:** Enterprise scale (40+ stories)
 
-- Automatically adjusts complexity from quick fixes to enterprise projects
-- Greenfield & brownfield support with smart context engine
+**🏗️ Four-Phase Methodology**
 
-**🏗️ Project-Adaptive Architecture**
+1. **Phase 1: Analysis** (Optional) - Brainstorming, research, product briefs
+2. **Phase 2: Planning** (Required) - Scale-adaptive PRD/tech-spec/GDD
+3. **Phase 3: Solutioning** (Level 3-4) - Architecture and design decisions
+4. **Phase 4: Implementation** (Iterative) - Story-centric development with just-in-time context
 
-- Documents adapt to project type (web, mobile, embedded, game)
-- Engine-specific game development (Unity, Phaser, Godot, Unreal)
+**🤖 12 Specialized Agents**
 
-**📋 Four-Phase Methodology**
+PM • Analyst • Architect • Scrum Master • Developer • Test Architect (TEA) • UX Designer • Paige (Documentation) • Game Designer • Game Developer • Game Architect • BMad Master (Orchestrator)
 
-1. **Analysis** - Brainstorming, research, briefs
-2. **Planning** - Scale-adaptive PRD/GDD
-3. **Solutioning** - Architecture and tech specs
-4. **Implementation** - Stories, development, review
+**📚 Documentation**
 
-**Specialized Agents**: PM, Analyst, Architect, Scrum Master, Developer, Game Designer/Developer/Architect, UX, Test Architect
+- **[Complete Documentation Hub](./src/modules/bmm/docs/README.md)** - Start here for all BMM guides
+- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - Get building in 15 minutes
+- **[Agents Guide](./src/modules/bmm/docs/agents-guide.md)** - Meet all 12 agents (45 min read)
+- **[34 Workflow Guides](./src/modules/bmm/docs/README.md#-workflow-guides)** - Complete phase-by-phase reference
+- **[BMM Module Overview](./src/modules/bmm/README.md)** - Module structure and quick links
 
-**Documentation**: [📚 BMM Module](./src/modules/bmm/README.md) | [📖 Workflows Guide](./src/modules/bmm/workflows/README.md)
+---
+
+## 🚀 Quick Start
+
+**First Time?**
+
+```bash
+npx bmad-method@alpha install
+# Load Analyst agent → *workflow-init
+```
+
+**Three Paths to Choose From:**
+
+1. **⚡ Quick Spec Flow** - Bug fixes and small features (Level 0-1)
+   - 🐛 Bug fixes in minutes
+   - ✨ Small features (2-3 related changes)
+   - 🚀 Rapid prototyping
+   - **[→ Quick Spec Flow Guide](./src/modules/bmm/docs/quick-spec-flow.md)**
+
+2. **📋 Full BMM Flow** - Medium to enterprise projects (Level 2-4)
+   - Complete planning (PRD/GDD)
+   - Architecture decisions
+   - Story-centric implementation
+   - **[→ Complete Quick Start Guide](./src/modules/bmm/docs/quick-start.md)**
+
+3. **🏢 Brownfield Projects** - Add to existing codebases
+   - Document existing code first
+   - Then choose Quick Spec or Full BMM
+   - **[→ Brownfield Guide](./src/modules/bmm/docs/brownfield-guide.md)**
+
+**Not sure which path?** Run `*workflow-init` and let BMM analyze your project goal and recommend the right approach.
+
+**[📚 Learn More: Scale Adaptive System](./src/modules/bmm/docs/scale-adaptive-system.md)** - How BMM adapts from Level 0 to Level 4
+
+---
 
 ### BMad Builder (BMB) - Create Custom Solutions
 
-Build custom agents, workflows, and modules using BMad-CORE framework.
+Build your own agents, workflows, and modules using the BMad-CORE framework.
+
+**What You Can Build:**
+
+- **Custom Agents** - Domain experts with specialized knowledge
+- **Guided Workflows** - Multi-step processes for any task
+- **Complete Modules** - Full solutions for specific domains
+- **Three Agent Types** - Full module, hybrid, or standalone
 
-- **Agent Creation** - Custom roles and behaviors
-- **Workflow Design** - Structured multi-step processes
-- **Module Development** - Complete domain solutions
-- **Three Agent Types** - Full module, hybrid, standalone
+**Perfect For:** Creating domain-specific solutions (legal, medical, finance, education, creative, etc.) or extending BMM with custom development workflows.
 
-**Documentation**:
+**Documentation:**
 
-- [📚 BMB Module](./src/modules/bmb/README.md) - Complete module reference
-- [🎯 Create Agent](./src/modules/bmb/workflows/create-agent/README.md) - Agent builder workflow
-- [📋 Create Workflow](./src/modules/bmb/workflows/create-workflow/README.md) - Workflow designer
-- [📦 Create Module](./src/modules/bmb/workflows/create-module/README.md) - Module scaffolding
+- **[BMB Module Overview](./src/modules/bmb/README.md)** - Complete reference
+- **[Create Agent Workflow](./src/modules/bmb/workflows/create-agent/README.md)** - Build custom agents
+- **[Create Workflow](./src/modules/bmb/workflows/create-workflow/README.md)** - Design guided processes
+- **[Create Module](./src/modules/bmb/workflows/create-module/README.md)** - Package complete solutions
 
 ### Creative Intelligence Suite (CIS) - Innovation & Creativity
 
-AI-powered creative facilitation across five domains.
+AI-powered creative facilitation using proven methodologies and techniques.
+
+**5 Interactive Workflows:**
+
+- **Brainstorming** - Generate and refine ideas with 30+ techniques
+- **Design Thinking** - Human-centered problem solving
+- **Problem Solving** - Systematic breakthrough techniques
+- **Innovation Strategy** - Disruptive business model thinking
+- **Storytelling** - Compelling narrative frameworks
+
+**5 Specialized Agents:** Each with unique facilitation styles and domain expertise
 
-- **5 Interactive Workflows** - Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
-- **150+ Creative Techniques** - Proven frameworks and methodologies
-- **5 Specialized Agents** - Unique personas and facilitation styles
-- **Shared Resource** - Powers creative workflows in other modules
+**Shared Resource:** CIS workflows are used by other modules (BMM's `brainstorm-project` uses CIS brainstorming)
 
-**Documentation**: [📚 CIS Module](./src/modules/cis/README.md) | [📖 CIS Workflows](./src/modules/cis/workflows/README.md)
+**Documentation:**
+
+- **[CIS Module Overview](./src/modules/cis/README.md)** - Complete reference
+- **[CIS Workflows Guide](./src/modules/cis/workflows/README.md)** - All 5 creative workflows
+
+---
 
 ## Installation
 
-**Prerequisites**: Node.js v20+ ([Download](https://nodejs.org))
+**Prerequisites:** Node.js v20+ ([Download](https://nodejs.org))
 
 ```bash
-# Install v6 Alpha
+# v6 Alpha (recommended for new projects)
 npx bmad-method@alpha install
 
-# Install stable v4
+# Stable v4 (production)
 npx bmad-method install
 ```
 
-Interactive installer guides you through:
+**Interactive Setup:** The installer walks you through:
 
-1. **Project location** - Installation directory
-2. **Module selection** - BMM, BMB, CIS
-3. **Configuration** - Name, language, game dev options
-4. **IDE integration** - Environment setup
+1. **Project Location** - Where to install (defaults to current directory)
+2. **Module Selection** - Choose BMM, BMB, CIS (or all)
+3. **Configuration** - Your name, language, game dev options
+4. **IDE Integration** - Automatic environment setup
 
-### Project Structure
+**Result:** Clean, unified `bmad/` folder structure:
 
 ```
 your-project/
 └── bmad/
-    ├── core/         # Core framework
-    ├── bmm/          # BMad Method
-    ├── bmb/          # BMad Builder
-    ├── cis/          # Creative Intelligence
-    └── _cfg/         # Your customizations
-        └── agents/   # Agent configs
+    ├── core/         # Core framework + BMad Master agent
+    ├── bmm/          # BMad Method (12 agents, 34 workflows)
+    ├── bmb/          # BMad Builder (1 agent, 7 workflows)
+    ├── cis/          # Creative Intelligence (5 agents, 5 workflows)
+    └── _cfg/         # Your customizations (survives updates)
+        └── agents/   # Agent customization files
 ```
 
-### Getting Started
+**First Steps After Install:**
 
-After installation, activate Analyst agent and run:
+Load any agent in your IDE and run `*workflow-init` to set up your project workflow path.
 
-```
-/workflow-init
-```
-
-This initializes the workflow system and helps choose your starting point.
+---
 
 ## Key Features
 
 ### 🎨 Update-Safe Customization
 
-- Agent modification via `bmad/_cfg/agents/`
-- Persistent settings through updates
-- Multi-language support
-- Flexible configuration
+Modify agents without touching core files:
+
+- Override agent names, personalities, expertise via `bmad/_cfg/agents/`
+- Customizations persist through all updates
+- Multi-language support (communication + output)
+- Module-level or global configuration
 
 ### 🚀 Intelligent Installation
 
-- Auto-detects v4 installations
-- Configures IDE integrations
-- Resolves dependencies
-- Creates unified manifests
+Smart setup that adapts to your environment:
+
+- Auto-detects v4 installations for smooth upgrades
+- Configures IDE integrations (Claude Code, Cursor, Windsurf, VS Code)
+- Resolves cross-module dependencies
+- Generates unified agent/workflow manifests
+
+### 📁 Clean Architecture
+
+Everything in one place:
+
+- Single `bmad/` folder (no scattered files)
+- Modules live side-by-side (core, bmm, bmb, cis)
+- Your configs in `_cfg/` (survives updates)
+- Easy to version control or exclude
+
+### 📄 Document Sharding (Advanced)
 
-### 📁 Unified Architecture
+Optional optimization for large projects (Level 3-4):
 
-Single `bmad/` folder - clean, organized, maintainable.
+- **Massive Token Savings** - Phase 4 workflows load only needed sections (90%+ reduction)
+- **Automatic Support** - All workflows handle whole or sharded documents seamlessly
+- **Easy Setup** - Built-in tool splits documents by headings
+- **Smart Discovery** - Workflows auto-detect format
+
+**[→ Document Sharding Guide](./docs/document-sharding-guide.md)**
+
+---
 
 ## Documentation
 
-- **[📚 Documentation Index](./docs/index.md)** - Complete documentation map
+**Module Documentation:**
+
+- **[BMM Complete Documentation Hub](./src/modules/bmm/docs/README.md)** - All BMM guides, FAQs, troubleshooting
+- **[BMB Module Reference](./src/modules/bmb/README.md)** - Build custom agents and workflows
+- **[CIS Workflows Guide](./src/modules/cis/workflows/README.md)** - Creative facilitation workflows
+
+**Additional Resources:**
+
+- **[Documentation Index](./docs/index.md)** - All project documentation
 - **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions
-- **[CLI Tool Guide](./tools/cli/README.md)** - Installer reference
-- **[Contributing Guide](./CONTRIBUTING.md)** - Contribution guidelines
+- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and build tool reference
+- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
+
+---
 
 ## Community & Support
 
-- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Community help
-- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Bug reports
-- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials
-- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Updates
+- 💬 **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects (#general-dev, #bugs-issues)
+- 🐛 **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs, request features
+- 🎥 **[YouTube Channel](https://www.youtube.com/@BMadCode)** - Video tutorials and walkthroughs
+- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Stay updated on releases
+
+---
 
 ## Contributing
 
-See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
+We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
+
+- Code contribution guidelines
+- Documentation improvements
+- Module development
+- Issue reporting
+
+---
 
 ## License
 
-MIT License - See [LICENSE](LICENSE)
+**MIT License** - See [LICENSE](LICENSE) for details
 
-**Trademark**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
+**Trademarks:** BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
 
 ---