bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.11

package/README.md

@@ -1,261 +1,212 @@
-# BMad CORE v6 Beta
+# BMad Method & BMad Core
 
-[![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
+[![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)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![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)
 
-**The Universal Human-AI Collaboration Platform**
+## AI-Driven Agile Development That Scales From Bug Fixes to Enterprise
 
-BMad-CORE (**C**ollaboration **O**ptimized **R**eflection **E**ngine) is a revolutionary framework that amplifies human potential through specialized AI agents. Unlike traditional AI tools that replace human thinking, BMad-CORE guides you through reflective workflows that bring out your best ideas and the AI's full capabilities.
+**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.
 
-**🎯 Human Amplification, Not Replacement** • **🎨 Works in Any Domain** • **⚡ Powered by Specialized Agents**
+> **🚀 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)
 
----
-
-## 🔄 Upgrading from v4?
+> **📌 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).
 
-**[→ v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Complete migration instructions for existing v4 users
+## 🎯 Why BMad Method?
 
----
+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.
 
-## What is BMad-CORE?
+**✨ Key Benefits:**
 
-BMad-CORE is the **universal foundation** that powers all BMad modules. It provides:
+- **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
 
-- **Agent orchestration framework** for specialized AI personas
-- **Workflow execution engine** for guided processes
-- **Modular architecture** allowing domain-specific extensions
-- **IDE integrations** across multiple development environments
-- **Update-safe customization system** for all agents and workflows
+## 🏗️ The Power of BMad Core
 
-### Core v6 Framework Enhancements
+**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:
 
-**All modules benefit from these new core capabilities:**
+- **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
 
-- **🎨 Full Agent Customization** - Modify any agent's name, role, personality, and behavior via `bmad/_cfg/agents/` customize files that survive all updates
-- **🌐 Multi-Language Support** - Choose your language for both agent communication and documentation output independently
-- **👤 User Personalization** - Agents address you by name and adapt to your technical level and preferences
-- **🔄 Update-Safe Configuration** - Your customizations persist through framework and module updates
-- **⚙️ Flexible Settings** - Configure communication style, technical depth, output formats, and more per module or globally
+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!
 
-### The C.O.R.E. Philosophy
+## 📊 See It In Action
 
-- **C**ollaboration: Human-AI partnership where both contribute unique strengths
-- **O**ptimized: Refined processes for maximum effectiveness
-- **R**eflection: Guided thinking that unlocks better solutions
-- **E**ngine: Powerful framework orchestrating specialized agents and workflows
+<p align="center">
+  <img src="./src/modules/bmm/docs/images/workflow-method-greenfield.svg" alt="BMad Method Workflow" width="100%">
+</p>
 
-Instead of giving you answers, BMad-CORE helps you **discover better solutions** through strategic questioning, expert guidance, and structured thinking.
+<p align="center">
+  <em>Complete BMad Method workflow showing all phases, agents, and decision points</em>
+</p>
 
----
+## 🚀 Get Started in 3 Steps
 
-## The BMad Method - Agile AI-Driven Development
+### 1. Install BMad Method
 
-**The flagship module for software and game development excellence.**
+```bash
+# Install v6 Alpha (recommended)
+npx bmad-method@alpha install
 
-The BMad Method (BMM) is a complete AI-driven agile development framework that revolutionizes how you build software and games. Whether you're fixing a bug, building a feature, or architecting an enterprise system, BMM adapts to your needs.
+# Or stable v4 for production
+npx bmad-method install
+```
 
-### What's New in v6?
+### 2. Initialize Your Project
 
-**🎯 Revolutionary Scale-Adaptive Workflows**
+Load any agent in your IDE and run:
 
-- **Levels 0-4**: Automatically adjusts from quick fixes to enterprise-scale projects
-- **Greenfield & Brownfield**: Full support for new projects and existing codebases
-- **Smart Context Engine**: New optimized brownfield documentation engine that understands your existing code
+```
+*workflow-init
+```
 
-**🏗️ Project-Adaptive Architecture**
+This analyzes your project and recommends the right workflow track.
 
-- Architecture documents that adapt to YOUR project type (web, mobile, embedded, game, etc.)
-- No more "one-size-fits-all" templates
-- Specialized sections based on what you're actually building
-- Game development fully integrated with engine-specific guidance (Unity, Phaser, Godot, Unreal, and more)
+### 3. Choose Your Track
 
-**⚡ From Simple to Complex - All in One System**
+BMad Method adapts to your needs with three intelligent tracks:
 
-- **Level 0-1**: Quick fixes and small features with minimal overhead
-- **Level 2**: Feature development with lightweight planning
-- **Level 3-4**: Full enterprise workflows with comprehensive documentation
-- Seamless workflow progression as complexity grows
+| 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  |
 
-**💬 Highly Interactive & Guided**
+> **Not sure?** Run `*workflow-init` and let BMad analyze your project goal.
 
-- Interactive workflows that ask the right questions
-- Agents guide you through discovery rather than giving generic answers
-- Context-aware recommendations based on your project state
-- Real-time validation and course correction
+## 🔄 How It Works: 4-Phase Methodology
 
-**📋 Four-Phase Methodology**
+BMad Method guides you through a proven development lifecycle:
 
-1. **Analysis** (Optional) - Brainstorming, research, product briefs
-2. **Planning** (Required) - Scale-adaptive PRD/GDD generation
-3. **Solutioning** (Level 3-4) - Adaptive architecture and tech specs
-4. **Implementation** (Iterative) - Story creation, context gathering, development, review
+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
 
-### Specialized Agents
+Each phase has specialized workflows and agents working together to deliver exceptional results.
 
-- **PM** - Product planning and requirements
-- **Analyst** - Research and business analysis
-- **Architect** - Technical architecture and design
-- **Scrum Master** - Sprint planning and story management
-- **Developer** - Implementation with senior dev review
-- **Game Development** (Optional) - Game Designer, Game Developer, Game Architect
-- **And more** - UX, Test Architect, and other specialized roles
+## 🤖 Meet Your Team
 
-### Documentation
+**12 Specialized Agents** working in concert:
 
-- **[📚 Complete BMM Documentation](./src/modules/bmm/README.md)** - Full module reference
-- **[📖 BMM Workflows Guide](./src/modules/bmm/workflows/README.md)** - Essential reading for using BMM
+| Development | Architecture   | Product       | Leadership     |
+| ----------- | -------------- | ------------- | -------------- |
+| Developer   | Architect      | PM            | Scrum Master   |
+| UX Designer | Test Architect | Analyst       | BMad Master    |
+| Tech Writer | Game Architect | Game Designer | Game Developer |
 
----
+Each agent brings deep expertise and can be customized to match your team's style.
 
-## Additional Beta Modules
+## 📦 What's Included
 
-### **[BMad Builder (BMB)](./src/modules/bmb/README.md)** - Create Custom Solutions
+### Core Modules
 
-Build your own agents, workflows, and modules using the BMad-CORE framework.
+- **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)
 
-- **Agent Creation**: Design specialized agents with custom roles and behaviors
-- **Workflow Design**: Build structured multi-step processes
-- **Module Development**: Package complete solutions for any domain
-- **Three Agent Types**: Full module, hybrid, and standalone agents
+- **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)
 
-**[📚 Complete BMB Documentation](./src/modules/bmb/README.md)** | **[🎯 Agent Creation Guide](./src/modules/bmb/workflows/create-agent/README.md)**
+- **Creative Intelligence Suite (CIS)** - Innovation & problem-solving
+  - Brainstorming, design thinking, storytelling
+  - 5 creative facilitation workflows
+  - [→ Creative Workflows](./src/modules/cis/README.md)
 
----
+### Key Features
 
-### **[Creative Intelligence Suite (CIS)](./src/modules/cis/readme.md)** - Innovation & Creativity
+- **🎨 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
 
-Transform creative and strategic thinking through AI-powered facilitation across five specialized domains.
+## 📚 Documentation
 
-- **5 Interactive Workflows**: Brainstorming, Design Thinking, Problem Solving, Innovation Strategy, Storytelling
-- **150+ Creative Techniques**: Proven frameworks and methodologies
-- **5 Specialized Agents**: Each with unique personas and facilitation styles
-- **Shared Resource**: Powers creative workflows in other modules (e.g., BMM brainstorming)
+### Quick Links
 
-**[📚 Complete CIS Documentation](./src/modules/cis/readme.md)** | **[📖 CIS Workflows](./src/modules/cis/workflows/README.md)**
+- **[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
 
----
+### For v4 Users
 
-## Quick Start
+- **[v4 Documentation](https://github.com/bmad-code-org/BMAD-METHOD/tree/V4)**
+- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)**
 
-### Prerequisites
+## 💬 Community & Support
 
-- **Node.js v20+** ([Download](https://nodejs.org))
+- **[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
 
-### Installation
+## 🛠️ Development
 
-Install BMad to your project using npx:
+For contributors working on the BMad codebase:
 
 ```bash
-npx bmad-method install
-```
-
-> **Version Selection:** When running `npx bmad-method install`, you'll be prompted to choose:
->
-> - **Stable (v4.x)** - Production-ready version
-> - **Beta (v6.0.0-beta)** - Latest features with early access
->
-> To install a specific version directly (skip prompt):
->
-> ```bash
-> npx bmad-method@4 install              # Stable v4.x
-> npx bmad-method@6.0.0-beta.0 install   # Beta v6
-> ```
-
-The interactive installer will guide you through:
-
-1. **Project location** - Where to install BMad
-2. **Module selection** - Choose which modules you need (BMM, BMB, CIS)
-3. **Configuration** - Set your name, language preferences, and module options
-   - **Game Development (Optional)**: When installing BMM, you can optionally include game development agents and workflow!
-4. **IDE integration** - Configure your development environment
-
-### What Gets Installed
-
-All modules install to a single `bmad/` folder in your project:
-
-```
-your-project/
-└── bmad/
-    ├── core/         # Core framework (always installed)
-    ├── bmm/          # BMad Method (if selected)
-    ├── bmb/          # BMad Builder (if selected)
-    ├── cis/          # Creative Intelligence Suite (shared resources)
-    └── _cfg/         # Your customizations
-        └── agents/   # Agent customization files
-```
+# Run all quality checks
+npm test
 
-### Getting Started with BMM
-
-After installation, activate the Analyst agent in your IDE and run:
-
-```bash
-/workflow-init
+# Development commands
+npm run lint          # Check code style
+npm run format:fix    # Auto-format code
+npm run bundle        # Build web bundles
 ```
 
-Or run it directly as a command (command syntax varies by IDE - use slash commands in Claude Code, OpenCode, etc.).
-
-This sets up the guided workflow system and helps you choose the right starting point for your project based on its complexity.
-
----
-
-## Key Features
-
-### 🎨 Update-Safe Customization
-
-- **Agent Customization**: Modify agents via `bmad/_cfg/agents/` customize files
-- **Persistent Settings**: Your customizations survive updates
-- **Multi-Language Support**: Agents communicate in your preferred language
-- **Flexible Configuration**: Adjust agent names, roles, communication styles, and more
-
-### 🚀 Intelligent Installation
-
-The installer automatically:
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines.
 
-- Detects and migrates v4 installations
-- Configures IDE integrations
-- Resolves module dependencies
-- Sets up agent customization templates
-- Creates unified agent manifests
+## What's New in v6
 
-### 📁 Unified Architecture
+**v6 represents a complete architectural revolution from v4:**
 
-Everything in one place - no more scattered configuration folders. Clean, organized, maintainable.
+### 🚀 Major Upgrades
 
----
-
-## Additional Documentation
-
-- **[v4 to v6 Upgrade Guide](./docs/v4-to-v6-upgrade.md)** - Migration instructions for v4 users
-- **[CLI Tool Guide](./tools/cli/README.md)** - Installer and bundler reference
-- **[Contributing Guide](./CONTRIBUTING.md)** - How to contribute to BMad
-
----
-
-## Community & Support
+- **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
 
-- 💬 **[Discord](https://discord.gg/gk8jAdXWmj)** - Get help, share ideas, and collaborate
-- 🐛 **[Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs and request features
-- 🎥 **[YouTube](https://www.youtube.com/@BMadCode)** - Tutorials and updates
-- ⭐ **[Star this repo](https://github.com/bmad-code-org/BMAD-METHOD)** - Get notified of updates
+### 🔄 For v4 Users
 
----
-
-## Contributing
-
-We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for guidelines.
-
----
+- **[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.
 
-**Trademark Notice**: BMAD™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. All rights reserved.
+**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>

package/docs/BUNDLE_DISTRIBUTION_SETUP.md

@@ -0,0 +1,95 @@
+# Bundle Distribution Setup (For Maintainers)
+
+**Audience:** BMAD maintainers setting up bundle auto-publishing
+
+---
+
+## One-Time Setup
+
+Run these commands once to enable auto-publishing:
+
+```bash
+# 1. Create bmad-bundles repo
+gh repo create bmad-code-org/bmad-bundles --public --description "BMAD Web Bundles"
+
+# 2. Ensure `main` exists (GitHub Pages API requires a source branch)
+git clone git@github.com:bmad-code-org/bmad-bundles.git
+cd bmad-bundles
+printf '# bmad-bundles\n\nStatic bundles published from BMAD-METHOD.\n' > README.md
+git add README.md
+git commit -m "Initial commit"
+git push origin main
+cd -
+
+# 3. Enable GitHub Pages (API replacement for removed --enable-pages flag)
+gh api repos/bmad-code-org/bmad-bundles/pages --method POST -f source[branch]=main -f source[path]=/
+# (Optional) confirm status
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source}'
+
+# 4. Create GitHub PAT and add as secret
+# Go to: https://github.com/settings/tokens/new
+# Scopes: repo (full control)
+# Name: bmad-bundles-ci
+# Then add as secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+# (paste PAT when prompted)
+```
+
+If the Pages POST returns `409`, the site already exists. If it returns `422` about `main` missing, redo step 2 to push the initial commit.
+
+**Done.** Bundles auto-publish on every main merge.
+
+---
+
+## How It Works
+
+**On main merge:**
+
+- `.github/workflows/bundle-latest.yaml` runs
+- Publishes to: `https://bmad-code-org.github.io/bmad-bundles/`
+
+**On release:**
+
+- `npm run release:patch` runs `.github/workflows/manual-release.yaml`
+- Attaches bundles to: `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+
+---
+
+## Testing
+
+```bash
+# Test latest channel
+git push origin main
+# Wait 2 min, then: curl https://bmad-code-org.github.io/bmad-bundles/
+
+# Test stable channel
+npm run release:patch
+# Check: gh release view
+```
+
+---
+
+## Troubleshooting
+
+**"Permission denied" or auth errors**
+
+```bash
+# Verify PAT secret exists
+gh secret list --repo bmad-code-org/BMAD-METHOD | grep BUNDLES_PAT
+
+# If missing, recreate PAT and add secret:
+gh secret set BUNDLES_PAT --repo bmad-code-org/BMAD-METHOD
+```
+
+**GitHub Pages not updating / need to re-check config**
+
+```bash
+gh api repos/bmad-code-org/bmad-bundles/pages --jq '{status,source,html_url}'
+```
+
+---
+
+## Distribution URLs
+
+**Stable:** `https://github.com/bmad-code-org/BMAD-METHOD/releases/latest`
+**Latest:** `https://bmad-code-org.github.io/bmad-bundles/`