bmad-method 6.0.0-alpha.10 → 6.0.0-alpha.12

package/README.md

@@ -1,4 +1,4 @@
-# BMad CORE + BMad Method
+# BMad Method & BMad Core
 
 [![Stable Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=stable)](https://www.npmjs.com/package/bmad-method)
 [![Alpha Version](https://img.shields.io/npm/v/bmad-method/alpha?color=orange&label=alpha)](https://www.npmjs.com/package/bmad-method)
@@ -6,437 +6,207 @@
 [![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 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! (There is no v5).
->
-> **Getting Started:**
->
-> - **Install v6 Alpha:** `npx bmad-method install`
-> - **Install stable v4:** `npx bmad-method@latest install`
-> - **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.
-
-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
-
-- [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) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development)
-      - [v6 Highlights](#v6-highlights)
-  - [🚀 Quick Start](#-quick-start)
-    - [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)
-  - [🎯 Working with Agents \& Commands](#-working-with-agents--commands)
-    - [Method 1: Agent Menu (Recommended for Beginners)](#method-1-agent-menu-recommended-for-beginners)
-    - [Method 2: Direct Slash Commands](#method-2-direct-slash-commands)
-    - [Method 3: Party Mode Execution](#method-3-party-mode-execution)
-  - [Key Features](#key-features)
-    - [🎨 Update-Safe Customization](#-update-safe-customization)
-    - [🚀 Intelligent Installation](#-intelligent-installation)
-    - [📁 Clean Architecture](#-clean-architecture)
-    - [📄 Document Sharding (Advanced)](#-document-sharding-advanced)
-  - [Documentation](#documentation)
-  - [Community \& Support](#community--support)
-  - [Development \& Quality Checks](#development--quality-checks)
-    - [Testing \& Validation](#testing--validation)
-    - [Code Quality](#code-quality)
-    - [Build \& Development](#build--development)
-  - [Contributing](#contributing)
-  - [License](#license)
+## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
 
----
-
-## What is BMad-CORE?
-
-Foundation framework powering all BMad modules:
-
-- **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_folder}/_cfg/agents/` **[→ Customization Guide](./docs/agent-customization-guide.md)**
-- **🌐 Multi-Language** - Independent language settings for communication and output
-- **👤 Personalization** - Agents adapt to your name, skill level, and preferences
-- **🔄 Persistent Config** - Customizations survive module updates
-- **⚙️ Flexible Settings** - Configure per-module or globally
-- **📦 Web Bundles** - Share agents in Gemini Gems and Custom GPTs **[→ Web Bundles Guide](./docs/web-bundles-gemini-gpt-guide.md)**
-
-### C.O.R.E. Philosophy
-
-- **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 doesn't give you answers—it helps you **discover better solutions** through guided reflection.
-
-## Modules
+**Build More, Architect Dreams** (BMAD) with **19 specialized AI agents** and **50+ guided workflows** that adapt to your project's complexity—from quick bug fixes to enterprise platforms.
 
-### BMad Method (BMM) - AI-Driven Agile Development
+> **🚀 v6 is a MASSIVE upgrade from v4!** Complete architectural overhaul, scale-adaptive intelligence, visual workflows, and the powerful BMad Core framework. v4 users: this changes everything. [See what's new →](#whats-new-in-v6)
 
-Revolutionary AI-driven agile framework for software and game development. Automatically adapts from single bug fixes to enterprise-scale systems.
+> **📌 v6 Alpha Status:** Near-beta quality with vastly improved stability. Documentation is being finalized. New videos coming soon to [BMadCode YouTube](https://www.youtube.com/@BMadCode).
 
-#### v6 Highlights
+## 🎯 Why BMad Method?
 
-**🎯 Scale-Adaptive Intelligence (3 Planning Tracks)**
+Unlike generic AI coding assistants, BMad Method provides **structured, battle-tested workflows** powered by specialized agents who understand agile development. Each agent has deep domain expertise—from product management to architecture to testing—working together seamlessly.
 
-Automatically adjusts planning depth and documentation based on project needs:
+**✨ Key Benefits:**
 
-- **Quick Flow Track:** Fast implementation (tech-spec only) - bug fixes, small features, clear scope
-- **BMad Method Track:** Full planning (PRD + Architecture + UX) - products, platforms, complex features
-- **Enterprise Method Track:** Extended planning (BMad Method + Security/DevOps/Test) - enterprise requirements, compliance
+- **Scale-Adaptive Intelligence** - Automatically adjusts planning depth from bug fixes to enterprise systems
+- **Complete Development Lifecycle** - Analysis → Planning → Architecture → Implementation
+- **Specialized Expertise** - 19 agents with specific roles (PM, Architect, Developer, UX Designer, etc.)
+- **Proven Methodologies** - Built on agile best practices with AI amplification
+- **IDE Integration** - Works with Claude Code, Cursor, Windsurf, VS Code
 
-**🏗️ Four-Phase Methodology**
+## 🏗️ The Power of BMad Core
 
-1. **Phase 1: Analysis** (Optional) - Brainstorming, research, product briefs
-2. **Phase 2: Planning** (Required) - Scale-adaptive PRD/tech-spec/GDD
-3. **Phase 3: Solutioning** (Track-dependent) - Architecture, (Coming soon: security, DevOps, test strategy)
-4. **Phase 4: Implementation** (Iterative) - Story-centric development with just-in-time context
+**BMad Method** is actually a sophisticated module built on top of **BMad Core** (**C**ollaboration **O**ptimized **R**eflection **E**ngine). This revolutionary architecture means:
 
-**🤖 12 Specialized Agents**
+- **BMad Core** provides the universal framework for human-AI collaboration
+- **BMad Method** leverages Core to deliver agile development workflows
+- **BMad Builder** lets YOU create custom modules as powerful as BMad Method itself
 
-PM • Analyst • Architect • Scrum Master • Developer • Test Architect (TEA) • UX Designer • Technical Writer • Game Designer • Game Developer • Game Architect • BMad Master (Orchestrator)
+With **BMad Builder**, you can architect both simple agents and vastly complex domain-specific modules (legal, medical, finance, education, creative) that will soon be sharable in an **official community marketplace**. Imagine building and sharing your own specialized AI team!
 
-**📚 Documentation**
+## 📊 See It In Action
 
-- **[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
+<p align="center">
+  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
+</p>
 
----
-
-## 🚀 Quick Start
-
-**After installation** (see [Installation](#installation) below), choose your path:
-
-**Three Planning Tracks:**
-
-1. **⚡ Quick Flow Track** - Bug fixes and small features
-   - 🐛 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. **📋 BMad Method Track** - Products and platforms
-   - 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 Flow or BMad Method
-   - **[→ 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 track.
-
-**[📚 Learn More: Scale Adaptive System](./src/modules/bmm/docs/scale-adaptive-system.md)** - How BMM adapts across three planning tracks
-
----
+<p align="center">
+  <em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
+</p>
 
-### BMad Builder (BMB) - Create Custom Solutions
+## 🚀 Get Started in 3 Steps
 
-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
-
-**Perfect For:** Creating domain-specific solutions (legal, medical, finance, education, creative, etc.) or extending BMM with custom development workflows.
-
-**Documentation:**
-
-- **[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 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
-
-**Shared Resource:** CIS workflows are used by other modules (BMM's `brainstorm-project` uses CIS brainstorming)
-
-**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))
+### 1. Install BMad Method
 
 ```bash
-# v6 Alpha (recommended for new projects)
+# Install v6 Alpha (recommended)
 npx bmad-method@alpha install
 
-# Stable v4 (production)
+# Or stable v4 for production
 npx bmad-method install
 ```
 
-The installer provides:
-
-1. **Module Selection** - Choose BMM, BMB, CIS (or all)
-2. **Configuration** - Your name, language preferences, game dev options
-3. **IDE Integration** - Automatic setup for your IDE
+### 2. Initialize Your Project
 
-**Installation creates:**
+Load any agent in your IDE and run:
 
 ```
-your-project/
-└── {bmad_folder}/
-    ├── 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
+*workflow-init
 ```
 
-**Next Steps:**
+This analyzes your project and recommends the right workflow track.
 
-1. Load any agent in your IDE
-2. Run `*workflow-init` to set up your project workflow path
-3. Follow the [Quick Start](#-quick-start) guide above to choose your planning track
+### 3. Choose Your Track
 
-**Alternative:** [**Web Bundles**](https://bmad-code-org.github.io/bmad-bundles/) - Download pre-built agent bundles for use in Claude Projects, ChatGPT, or Gemini without installation (automatically updated on every commit to main)
+BMad Method adapts to your needs with three intelligent tracks:
 
----
+| Track              | Use For                   | Planning                | Time to Start |
+| ------------------ | ------------------------- | ----------------------- | ------------- |
+| **⚡ Quick Flow**  | Bug fixes, small features | Tech spec only          | < 5 minutes   |
+| **📋 BMad Method** | Products, platforms       | PRD + Architecture + UX | < 15 minutes  |
+| **🏢 Enterprise**  | Compliance, scale         | Full governance suite   | < 30 minutes  |
 
-## 🎯 Working with Agents & Commands
+> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
 
-**Multiple Ways to Execute Workflows:**
+## 🔄 How It Works: 4-Phase Methodology
 
-BMad is flexible - you can execute workflows in several ways depending on your preference and IDE:
+BMad Method guides you through a proven development lifecycle:
 
-### Method 1: Agent Menu (Recommended for Beginners)
+1. **📊 Analysis** (Optional) - Brainstorm, research, and explore solutions
+2. **📝 Planning** - Create PRDs, tech specs, or game design documents
+3. **🏗️ Solutioning** - Design architecture, UX, and technical approach
+4. **⚡ Implementation** - Story-driven development with continuous validation
 
-1. **Load an agent** in your IDE (see [IDE-specific instructions](./docs/ide-info/))
-2. **Wait for the menu** to appear showing available workflows
-3. **Tell the agent** what to run using natural language or shortcuts:
-   - Natural: "Run workflow-init"
-   - Shortcut: `*workflow-init`
-   - Menu number: "Run option 2"
+Each phase has specialized workflows and agents working together to deliver exceptional results.
 
-### Method 2: Direct Slash Commands
+## 🤖 Meet Your Team
 
-**Execute workflows directly** using slash commands:
+**12 Specialized Agents** working in concert:
 
-```
-/bmad:bmm:workflows:workflow-init
-/bmad:bmm:workflows:prd
-/bmad:bmm:workflows:dev-story
-```
+| Development | Architecture   | Product       | Leadership     |
+| ----------- | -------------- | ------------- | -------------- |
+| Developer   | Architect      | PM            | Scrum Master   |
+| UX Designer | Test Architect | Analyst       | BMad Master    |
+| Tech Writer | Game Architect | Game Designer | Game Developer |
 
-**Tip:** While you can run these without loading an agent first, **loading an agent is still recommended** - it can make a difference with certain workflows.
+Each agent brings deep expertise and can be customized to match your team's style.
 
-**Benefits:**
+## 📦 What's Included
 
-- ✅ Mix and match any agent with any workflow
-- ✅ Run workflows not in the loaded agent's menu
-- ✅ Faster access for experienced users who know the command names
+### Core Modules
 
-### Method 3: Party Mode Execution
+- **BMad Method (BMM)** - Complete agile development framework
+  - 12 specialized agents
+  - 34 workflows across 4 phases
+  - Scale-adaptive planning
+  - [→ Documentation Hub](./src/modules/bmm/docs/README.md)
 
-**Run workflows with multi-agent collaboration:**
+- **BMad Builder (BMB)** - Create custom agents and workflows
+  - Build anything from simple agents to complex modules
+  - Create domain-specific solutions (legal, medical, finance, education)
+  - Share your creations in the upcoming community marketplace
+  - [→ Builder Guide](./src/modules/bmb/README.md)
 
-1. Start party mode: `/bmad:core:workflows:party-mode`
-2. Execute any workflow - **the entire team collaborates on it**
-3. Get diverse perspectives from multiple specialized agents
+- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
+  - Brainstorming, design thinking, storytelling
+  - 5 creative facilitation workflows
+  - [→ Creative Workflows](./src/modules/cis/README.md)
 
-**Perfect for:** Strategic decisions, complex workflows, cross-functional tasks
+### Key Features
 
----
-
-> **📌 IDE-Specific Note:**
->
-> Slash command format varies by IDE:
->
-> - **Claude Code:** `/bmad:bmm:workflows:prd`
-> - **Cursor/Windsurf:** May use different syntax - check your IDE's [documentation](./docs/ide-info/)
-> - **VS Code with Copilot Chat:** Syntax may differ
->
-> See **[IDE Integration Guides](./docs/ide-info/)** for your specific IDE's command format.
-
----
-
-## Key Features
-
-### 🎨 Update-Safe Customization
-
-Modify agents without touching core files:
-
-- Override agent names, personalities, expertise via `{bmad_folder}/_cfg/agents/`
-- Customizations persist through all updates
-- Multi-language support (communication + output)
-- Module-level or global configuration
-
-### 🚀 Intelligent Installation
-
-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}/` folder (no scattered files, default folder name is .bmad)
-- Modules live side-by-side (core, bmm, bmb, cis)
-- Your configs in `_cfg/` (survives updates)
-- Easy to version control or exclude
-
-### 📄 Document Sharding (Advanced)
-
-Optional optimization for large projects (BMad Method and Enterprise tracks):
-
-- **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
+- **🎨 Customizable Agents** - Modify personalities, expertise, and communication styles
+- **🌐 Multi-Language Support** - Separate settings for communication and code output
+- **📄 Document Sharding** - 90% token savings for large projects
+- **🔄 Update-Safe** - Your customizations persist through updates
+- **🚀 Web Bundles** - Use in ChatGPT, Claude Projects, or Gemini Gems
 
-**Module Documentation:**
+## 📚 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
+### Quick Links
 
-**Customization & Sharing:**
+- **[Quick Start Guide](./src/modules/bmm/docs/quick-start.md)** - 15-minute introduction
+- **[Complete BMM Documentation](./src/modules/bmm/docs/README.md)** - All guides and references
+- **[Agent Customization](./docs/agent-customization-guide.md)** - Personalize your agents
+- **[All Documentation](./docs/index.md)** - Complete documentation index
 
-- **[Agent Customization Guide](./docs/agent-customization-guide.md)** - Customize agent names, personas, and behaviors
-- **[Web Bundles for Gemini & GPT](./docs/web-bundles-gemini-gpt-guide.md)** - Use BMad agents in Gemini Gems and Custom GPTs
+### For v4 Users
 
-**Additional Resources:**
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
 
-- **[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 and build tool reference
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute
+## 💬 Community & Support
 
----
-
-## Community & Support
-
-- 💬 **[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
-
----
-
-## Development & Quality Checks
+- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Get help, share projects
+- **[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 demos
+- **[Web Bundles](https://bmad-code-org.github.io/bmad-bundles/)** - Pre-built agent bundles
 
-**For contributors working on the BMAD codebase:**
+## 🛠️ Development
 
-**Requirements:** Node.js 22+ (see `.nvmrc`). Run `nvm use` to switch to the correct version.
-
-### Testing & Validation
+For contributors working on the BMad codebase:
 
 ```bash
-# Run all quality checks (comprehensive - use before pushing)
+# Run all quality checks
 npm test
 
-# Individual test suites
-npm run test:schemas     # Agent schema validation (fixture-based)
-npm run test:install     # Installation component tests (compilation)
-npm run validate:schemas # YAML schema validation
-npm run validate:bundles # Web bundle integrity
+# Development commands
+npm run lint          # Check code style
+npm run format:fix    # Auto-format code
+npm run bundle        # Build web bundles
 ```
 
-### Code Quality
-
-```bash
-# Lint check
-npm run lint
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
 
-# Auto-fix linting issues
-npm run lint:fix
+## What's New in v6
 
-# Format check
-npm run format:check
-
-# Auto-format all files
-npm run format:fix
-```
+**v6 represents a complete architectural revolution from v4:**
 
-### Build & Development
+### 🚀 Major Upgrades
 
-```bash
-# Bundle for web deployment
-npm run bundle
-
-# Test local installation
-npm run install:bmad
-```
-
-**Pre-commit Hook:** Auto-fixes changed files (lint-staged) + validates everything (npm test)
-**CI:** GitHub Actions runs all quality checks in parallel on every PR
-
----
-
-## Contributing
-
-We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
+- **BMad Core Framework** - Modular architecture enabling custom domain solutions
+- **Scale-Adaptive Intelligence** - Automatic adjustment from bug fixes to enterprise
+- **Visual Workflows** - Beautiful SVG diagrams showing complete methodology
+- **BMad Builder Module** - Create and share your own AI agent teams
+- **50+ Workflows** - Up from 20 in v4, covering every development scenario
+- **19 Specialized Agents** - Enhanced with customizable personalities and expertise
+- **Update-Safe Customization** - Your configs persist through all updates
+- **Web Bundles** - Use agents in ChatGPT, Claude, and Gemini
+- **Multi-Language Support** - Separate settings for communication and code
+- **Document Sharding** - 90% token savings for large projects
 
-- Code contribution guidelines
-- Documentation improvements
-- Module development
-- Issue reporting
+### 🔄 For v4 Users
 
----
+- **[Comprehensive Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Step-by-step migration
+- **[v4 Documentation Archive](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)** - Legacy reference
+- Backwards compatibility where possible
+- Smooth migration path with installer detection
 
-## License
+## 📄 License
 
-**MIT License** - See [LICENSE](LICENSE) for details
+MIT License - See [LICENSE](LICENSE) for details.
 
 **Trademarks:** BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC.
 
 ---
 
-[![Contributors](https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD)](https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors)
+<p align="center">
+  <a href="https://github.com/bmad-code-org/BMAD-METHOD/graphs/contributors">
+    <img src="https://contrib.rocks/image?repo=bmad-code-org/BMAD-METHOD" alt="Contributors">
+  </a>
+</p>
 
-<sub>Built with ❤️ for the human-AI collaboration community</sub>
+<p align="center">
+  <sub>Built with ❤️ for the human-AI collaboration community</sub>
+</p>