bmad-method 4.27.5 → 5.0.0

package/CONTRIBUTING.md

@@ -2,17 +2,8 @@
 
 Thank you for considering contributing to this project! This document outlines the process for contributing and some guidelines to follow.
 
-🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
-
-📋 **Before contributing**, please read our [Guiding Principles](docs/GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
-
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
-💬 **Discord Community**: Join our [Discord server](https://discord.gg/g6ypHytrCB) for real-time discussions:
-
-- **#general-dev** - Technical discussions, feature ideas, and development questions
-- **#bugs-issues** - Bug reports and issue discussions
-
 ## Code of Conduct
 
 By participating in this project, you agree to abide by our Code of Conduct. Please read it before participating.
@@ -21,96 +12,18 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
 
 ### Reporting Bugs
 
-1. **Check existing issues** first to avoid duplicates
-2. **Use the bug report template** when creating a new issue - it will guide you through providing:
-   - Clear bug description
-   - Steps to reproduce
-   - Expected vs actual behavior
-   - Model/IDE/BMad version details
-   - Screenshots or links if applicable
-3. **Consider discussing in Discord** (#bugs-issues channel) for quick help
-4. **Indicate if you're working on a fix** to avoid duplicate efforts
+- Check if the bug has already been reported in the Issues section
+- Include detailed steps to reproduce the bug
+- Include any relevant logs or screenshots
 
 ### Suggesting Features
 
-1. **Discuss first in Discord** (#general-dev channel) - the feature request template asks if you've done this
-2. **Check existing issues and discussions** to avoid duplicates
-3. **Use the feature request template** when creating an issue - it will guide you through:
-   - Confirming Discord discussion
-   - Describing the problem it solves
-   - Explaining your solution
-   - Listing alternatives considered
-4. **Be specific** about why this feature would benefit the BMad community
+- Check if the feature has already been suggested in the Issues section, and consider using the discussions tab in GitHub also. Explain the feature in detail and why it would be valuable.
 
 ### Pull Request Process
 
-⚠️ **Before starting work:**
-
-1. **For bugs**: Check if an issue exists (create one using the bug template if not)
-2. **For features**: Ensure you've discussed in Discord (#general-dev) AND created a feature request issue
-3. **For large changes**: Always open an issue first to discuss alignment
-
 Please only propose small granular commits! If its large or significant, please discuss in the discussions tab and open up an issue first. I do not want you to waste your time on a potentially very large PR to have it rejected because it is not aligned or deviates from other planned changes. Communicate and lets work together to build and improve this great community project!
 
-**Important**: All contributions must align with our [Guiding Principles](docs/GUIDING-PRINCIPLES.md). Key points:
-
-- Keep dev agents lean - they need context for coding, not documentation
-- Web/planning agents can be larger with more complex tasks
-- Everything is natural language (markdown) - no code in core framework
-- Use expansion packs for domain-specific features
-
-#### Which Branch for Your PR?
-
-**Submit to `next` branch** (most contributions):
-
-- ✨ New features or agents
-- 🎨 Enhancements to existing features
-- 📚 Documentation updates
-- ♻️ Code refactoring
-- ⚡ Performance improvements
-- 🧪 New tests
-- 🎁 New expansion packs
-
-**Submit to `main` branch** (critical only):
-
-- 🚨 Critical bug fixes that break basic functionality
-- 🔒 Security patches
-- 📚 Fixing dangerously incorrect documentation
-- 🐛 Bugs preventing installation or basic usage
-
-**When in doubt, submit to `next`**. We'd rather test changes thoroughly before they hit stable.
-
-#### PR Size Guidelines
-
-- **Ideal PR size**: 200-400 lines of code changes
-- **Maximum PR size**: 800 lines (excluding generated files)
-- **One feature/fix per PR**: Each PR should address a single issue or add one feature
-- **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
-- **Related changes**: Even related changes should be separate PRs if they deliver independent value
-
-#### Breaking Down Large PRs
-
-If your change exceeds 800 lines, use this checklist to split it:
-
-- [ ] Can I separate the refactoring from the feature implementation?
-- [ ] Can I introduce the new API/interface in one PR and implementation in another?
-- [ ] Can I split by file or module?
-- [ ] Can I create a base PR with shared utilities first?
-- [ ] Can I separate test additions from implementation?
-- [ ] Even if changes are related, can they deliver value independently?
-- [ ] Can these changes be merged in any order without breaking things?
-
-Example breakdown:
-
-1. PR #1: Add utility functions and types (100 lines)
-2. PR #2: Refactor existing code to use utilities (200 lines)
-3. PR #3: Implement new feature using refactored code (300 lines)
-4. PR #4: Add comprehensive tests (200 lines)
-
-**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value and don't depend on each other's merge order.
-
-#### Pull Request Steps
-
 1. Fork the repository
 2. Create a new branch (`git checkout -b feature/your-feature-name`)
 3. Make your changes
@@ -119,85 +32,9 @@ Example breakdown:
 6. Push to your branch (`git push origin feature/your-feature-name`)
 7. Open a Pull Request against the main branch
 
-## Issue Templates
-
-We use GitHub issue templates to ensure all necessary information is provided:
-
-- **Bug Reports**: Automatically guides you through providing reproduction steps, environment details, and expected behavior
-- **Feature Requests**: Requires Discord discussion confirmation and asks for problem/solution descriptions
-
-Using these templates helps maintainers understand and address your contribution faster.
-
-## Pull Request Description Guidelines
-
-Keep PR descriptions short and to the point following this template:
-
-### PR Description Template
-
-Keep your PR description concise and focused. Use this template:
-
-```markdown
-## What
-
-[1-2 sentences describing WHAT changed]
-
-## Why
-
-[1-2 sentences explaining WHY this change is needed]
-Fixes #[issue number] (if applicable)
-
-## How
-
-[2-3 bullets listing HOW you implemented it]
-
--
--
--
-
-## Testing
-
-[1-2 sentences on how you tested this]
-```
-
-**Maximum PR description length: 200 words** (excluding code examples if needed)
-
-### Good vs Bad PR Descriptions
-
-❌ **Bad Example:**
-
-> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics and deliver unprecedented value to stakeholders through innovative approaches...
-
-✅ **Good Example:**
-
-> **What:** Added validation for agent dependency resolution
-> **Why:** Build was failing silently when agents had circular dependencies
-> **How:**
->
-> - Added cycle detection in dependency-resolver.js
-> - Throws clear error with dependency chain
->   **Testing:** Tested with circular deps between 3 agents
-
 ## Commit Message Convention
 
-Use conventional commits format:
-
-- `feat:` New feature
-- `fix:` Bug fix
-- `docs:` Documentation only
-- `refactor:` Code change that neither fixes a bug nor adds a feature
-- `test:` Adding missing tests
-- `chore:` Changes to build process or auxiliary tools
-
-Keep commit messages under 72 characters.
-
-### Atomic Commits
-
-Each commit should represent one logical change:
-
-- **Do:** One bug fix per commit
-- **Do:** One feature addition per commit
-- **Don't:** Mix refactoring with bug fixes
-- **Don't:** Combine unrelated changes
+PRs with a wall of AI Generated marketing hype that is unclear in what is being proposed will be closed and rejected. Your best change to contribute is with a small clear PR description explaining, what is the issue being solved or gap in the system being filled. Also explain how it leads to the core guiding principles of the project.
 
 ## Code Style
 

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Brian AKA BMad AKA BMad Code
+Copyright (c) 2025 Brian AKA BMad AKA Bmad Code
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,139 +1,292 @@
-# BMad-Method: Universal AI Agent Framework
+# BMAD-METHOD
 
 [![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](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)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)](https://nodejs.org)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/g6ypHytrCB)
 
-Foundations in Agentic Agile Driven Development, known as the Breakthrough Method of Agile AI-Driven Development, but it is so much more. Transform any domain with specialized AI expertise: software development, entertainment, creative writing, business strategy to personal wellness just to name a few.
+**AI-Powered Agile Development Framework** - Transform your software development with specialized AI agents that work as your complete Agile team.
 
-**[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)**
+📺 **[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)** - V4 walkthrough and comprehensive guide coming soon!
 
-**[Join our Discord Community](https://discord.gg/gk8jAdXWmj)** - A growing community for AI enthusiasts! Get help, share ideas, explore AI agents & frameworks, collaborate on tech projects, enjoy hobbies, and help each other succeed. Whether you're stuck on BMad, building your own agents, or just want to chat about the latest in AI - we're here for you!
+⭐ **If you find this project helpful or useful, please give it a star!** It helps others discover BMAD-METHOD and you will be notified of updates!
 
-⭐ **If you find this project helpful or useful, please give it a star in the upper right hand corner!** It helps others discover BMad-Method and you will be notified of updates!
+## 🚀 Quick Start
 
-## Overview
+### Fastest Start: Web UI (2 minutes) 🏃‍♂️
+
+1. Copy `.bmad-core/web-bundles/teams/team-fullstack.txt`
+2. Create a new Gemini Gem or CustomGPT
+3. Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
+4. Start chatting! Type `/help` to see available commands
+
+### IDE Quick Start (5 minutes) 💻
+
+**Prerequisites**: Install [Node.js](https://nodejs.org) (v14 or higher)
 
-**BMad Method's Two Key Innovations:**
+````bash
+npx bmad-method install
+# The installer will automatically detect your project state and guide you through:
+# - Fresh installation or upgrade from v3
+# - Full installation or single agent
+# - Destination folder and IDE configuration
+```text
+
+This installs all agents and configures them for your IDE. If you have an existing v3 installation, it will offer to upgrade it automatically.
 
-**1. Agentic Planning:** Dedicated agents (Analyst, PM, Architect) collaborate with you to create detailed, consistent PRDs and Architecture documents. Through advanced prompt engineering and human-in-the-loop refinement, these planning agents produce comprehensive specifications that go far beyond generic AI task generation.
+## 📋 Table of Contents
 
-**2. Context-Engineered Development:** The Scrum Master agent then transforms these detailed plans into hyper-detailed development stories that contain everything the Dev agent needs - full context, implementation details, and architectural guidance embedded directly in story files.
+- [Overview](#overview)
+- [Installation](#installation)
+- [Available Agents](#available-agents)
+- [Usage](#usage)
+- [Project Structure](#project-structure)
+- [Contributing](#contributing)
 
-This two-phase approach eliminates both **planning inconsistency** and **context loss** - the biggest problems in AI-assisted development. Your Dev agent opens a story file with complete understanding of what to build, how to build it, and why.
+## Overview
 
-**📖 [See the complete workflow in the User Guide](docs/user-guide.md)** - Planning phase, development cycle, and all agent roles
+BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) revolutionizes software development by providing specialized AI agents for every role in an Agile team. Each agent has deep expertise in their domain and can collaborate to deliver complete software projects.
 
-## Quick Navigation
+### Why BMAD?
 
-### Understanding the BMad Workflow
+- **🎯 Specialized Expertise**: Each agent is an expert in their specific role
+- **🔄 True Agile Workflow**: Follows real Agile methodologies and best practices
+- **📦 Modular Design**: Use one agent or an entire team
+- **🛠️ IDE Integration**: Works seamlessly with Cursor, Claude Code, and Windsurf
+- **🌐 Platform Agnostic**: Use with ChatGPT, Claude, Gemini, or any AI platform
 
-**Before diving in, review these critical workflow diagrams that explain how BMad works:**
+## Installation
 
-1. **[Planning Workflow (Web UI)](docs/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
-2. **[Core Development Cycle (IDE)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
+### Method 1: Pre-Built Web Bundles (Fastest) 📦
 
-> ⚠️ **These diagrams explain 90% of BMad Method Agentic Agile flow confusion** - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner!
+For ChatGPT, Claude, or Gemini web interfaces:
 
-### What would you like to do?
+1. Choose a bundle:
+   - **Recommended**: `.bmad-core/web-bundles/teams/team-fullstack.txt` (complete development team)
+   - Or pick from individual agents in `.bmad-core/web-bundles/agents/`
+2. Upload to your AI platform (Gemini Gem, CustomGPT, or directly in chat)
+3. Set instructions: "Your critical operating instructions are attached, do not break character as directed"
+4. Type `/help` to see available commands
 
-- **[Install and Build software with Full Stack Agile AI Team](#quick-start)** → Quick Start Instruction
-- **[Learn how to use BMad](docs/user-guide.md)** → Complete user guide and walkthrough
-- **[See available AI agents](#available-agents)** → Specialized roles for your team
-- **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education
-- **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain
-- **[Browse ready-made expansion packs](expansion-packs/)** → Game dev, DevOps, infrastructure and get inspired with ideas and examples
-- **[Understand the architecture](docs/core-architecture.md)** → Technical deep dive
-- **[Join the community](https://discord.gg/g6ypHytrCB)** → Get help and share ideas
+### Method 2: CLI Installer (For IDEs) 🎯
 
-## Important: Keep Your BMad Installation Updated
+**Prerequisites**: Install [Node.js](https://nodejs.org) v14+ first
 
-**Stay up-to-date effortlessly!** If you already have BMad-Method installed in your project, simply run:
+Install directly into your project:
 
 ```bash
+# Interactive installation (recommended)
 npx bmad-method install
-# OR
-git pull
-npm run install:bmad
-```
+# The installer automatically detects your project state and guides you through:
+# - Fresh installation or upgrade from v3
+# - Installation type (full/single agent)
+# - Destination directory
+# - IDE configuration
+
+# Or use command line options for fresh installations
+npx bmad-method install --full --directory ./my-project --ide cursor
+npx bmad-method install --agent pm --directory ./my-project --ide claude-code
+````
+
+**Supported IDEs:**
+
+The BMad Method works with any IDE, but has built-in integration for:
+
+- `cursor` - Cursor IDE with @agent commands
+- `claude-code` - Claude Code with /agent commands
+- `windsurf` - Windsurf with @agent commands
+- `roo` - Roo Code with custom modes (see `.roomodes`)
+- More coming soon - BUT ITS easy to use with ANY IDE!
+
+## Available Agents
+
+### Core Development Team
+
+| Agent       | Role               | Specialty                                     |
+| ----------- | ------------------ | --------------------------------------------- |
+| `analyst`   | Business Analyst   | market analysis, brainstorming, project brief |
+| `pm`        | Product Manager    | Product strategy, roadmaps, PRDs              |
+| `architect` | Solution Architect | System design, technical architecture         |
+| `dev`       | Developer          | Code implementation across all technologies   |
+| `qa`        | QA Specialist      | Testing strategies, quality assurance         |
+| `ux-expert` | UX Designer        | User experience, UI design, prototypes        |
+| `po`        | Product Owner      | Backlog management, story validation          |
+| `sm`        | Scrum Master       | Sprint planning, story creation               |
 
-This will:
+### Meta Agents
 
-- ✅ Automatically detect your existing v4 installation
-- ✅ Update only the files that have changed and add new files
-- ✅ Create `.bak` backup files for any custom modifications you've made
-- ✅ Preserve your project-specific configurations
+| Agent               | Role             | Specialty                                                           |
+| ------------------- | ---------------- | ------------------------------------------------------------------- |
+| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching, is part of every team bundle |
+| `bmad-master`       | Universal Expert | All capabilities without switching                                  |
 
-This makes it easy to benefit from the latest improvements, bug fixes, and new agents without losing your customizations!
+## Usage
 
-## Quick Start
+### With IDE Integration
 
-### One Command for Everything (IDE Installation)
+After installation with `--ide` flag:
 
-**Just run one of these commands:**
+````bash
+# In Cursor
+@pm Create a PRD for a task management app
+
+# In Claude Code
+/architect Design a microservices architecture
+
+# In Windsurf
+@dev Implement story 1.3
+```text
+
+### With Web UI (ChatGPT/Claude/Gemini)
+
+After uploading a bundle you can ask /help of the agent to learn what it can do
+
+### CLI Commands
 
 ```bash
+# List all available agents
+npx bmad-method list
+
+# Install or update (automatically detects existing installations)
 npx bmad-method install
-# OR if you already have BMad installed:
-git pull
-npm run install:bmad
-```
 
-This single command handles:
+# Check installation status
+npx bmad-method status
+````
+
+### Upgrading from V3 to V4
+
+If you have an existing BMAD-METHOD V3 project, simply run the installer in your project directory:
+
+````bash
+npx bmad-method install
+# The installer will automatically detect your V3 installation and offer to upgrade
+```text
+
+The upgrade process will:
+
+1. Create a backup of your V3 files in `.bmad-v3-backup/`
+2. Install the new V4 `.bmad-core/` structure
+3. Migrate your documents (PRD, Architecture, Stories, Epics)
+4. Set up IDE integration for all V4 agents
+5. Create an install manifest for future updates
+
+After upgrading:
 
-- **New installations** - Sets up BMad in your project
-- **Upgrades** - Updates existing installations automatically
-- **Expansion packs** - Installs any expansion packs you've added to package.json
+1. Review your documents in the `docs/` folder
+2. Use `@bmad-master` agent to run the `doc-migration-task` to align your documents with V4 templates
+3. If you have separate front-end and backend architecture docs, the migration task will help merge them into a unified `full-stack-architecture.md`
 
-> **That's it!** Whether you're installing for the first time, upgrading, or adding expansion packs - these commands do everything.
+**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/`.
 
-**Prerequisites**: [Node.js](https://nodejs.org) v20+ required
+## Teams & Workflows
 
-### Fastest Start: Web UI Full Stack Team at your disposal (2 minutes)
+### Pre-Configured Teams
 
-1. **Get the bundle**: Save or clone the [full stack team file](dist/teams/team-fullstack.txt) or choose another team
-2. **Create AI agent**: Create a new Gemini Gem or CustomGPT
-3. **Upload & configure**: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
-4. **Start Ideating and Planning**: Start chatting! Type `*help` to see available commands or pick an agent like `*analyst` to start right in on creating a brief.
-5. **CRITICAL**: Talk to BMad Orchestrator in the web at ANY TIME (#bmad-orchestrator command) and ask it questions about how this all works!
-6. **When to moved to the IDE**: Once you have your PRD, Architecture, optional UX and Briefs - its time to switch over to the IDE to shard your docs, and start implementing the actual code! See the [User guide](docs/user-guide.md) for more details
+Save context by using specialized teams:
 
-### Alternative: Clone and Build
+- **Team All**: Complete Agile team with all 10 agents
+- **Team Fullstack**: Frontend + Backend development focus
+- **Team No-UI**: Backend/API development without UX
+
+### Workflows
+
+Structured approaches for different scenarios:
+
+- **Greenfield**: Starting new projects (fullstack/service/UI)
+- **Brownfield**: Enhancing existing projects
+- **Simple**: Quick prototypes and MVPs
+- **Complex**: Enterprise and large-scale projects
+
+## Project Structure
+
+```plaintext
+.bmad-core/
+├── agents/          # Individual agent definitions
+├── agent-teams/     # Team configurations
+├── workflows/       # Development workflows
+├── templates/       # Document templates (PRD, Architecture, etc.)
+├── tasks/           # Reusable task definitions
+├── checklists/      # Quality checklists
+├── data/            # Knowledge base
+└── web-bundles/     # Pre-built bundles
+
+tools/
+├── cli.js           # Build tool
+├── installer/       # NPX installer
+└── lib/             # Build utilities
+
+expansion-packs/     # Optional add-ons (DevOps, Mobile, etc.)
+````
+
+## Advanced Features
+
+### Dynamic Dependencies
+
+Each agent only loads the resources it needs, keeping context windows lean.
+
+### Template System
+
+Rich templates for all document types:
+
+- Product Requirements (PRD)
+- Architecture Documents
+- User Stories
+- Test Plans
+- And more...
+
+### Slash Star Commands
+
+Ask the agent you are using for help with /help (in the web) or \*help in the ide to see what commands are available!
+
+## Contributing
+
+We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+
+### Development Setup
 
 ```bash
 git clone https://github.com/bmadcode/bmad-method.git
-npm run install:bmad # build and install all to a destination folder
+cd bmad-method
+npm install
 ```
 
-## 🌟 Beyond Software Development - Expansion Packs
+## Documentation & Guides
 
-BMad's natural language framework works in ANY domain. Expansion packs provide specialized AI agents for creative writing, business strategy, health & wellness, education, and more. Also expansion packs can expand the core BMad-Method with specific functionality that is not generic for all cases. [See the Expansion Packs Guide](docs/expansion-packs.md) and learn to create your own!
+### Workflow Guides
 
-## Documentation & Resources
-
-### Essential Guides
-
-- 📖 **[User Guide](docs/user-guide.md)** - Complete walkthrough from project inception to completion
-- 🏗️ **[Core Architecture](docs/core-architecture.md)** - Technical deep dive and system design
-- 🚀 **[Expansion Packs Guide](docs/expansion-packs.md)** - Extend BMad to any domain beyond software development
-- [IDE Specific Guides available in this folder](docs/agentic-tools/)
+- 📚 [Universal BMAD Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs
+- 🎯 [Cursor Guide](docs/cursor-guide.md) - Complete workflow for Cursor users
+- 🤖 [Claude Code Guide](docs/claude-code-guide.md) - Complete workflow for Claude Code users
+- 🌊 [Windsurf Guide](docs/windsurf-guide.md) - Complete workflow for Windsurf users
+- 🦘 [Roo Code Guide](docs/roo-code-guide.md) - Complete workflow for Roo Code users
 
 ## Support
 
 - 💬 [Discord Community](https://discord.gg/g6ypHytrCB)
+- 📖 [Documentation](docs/)
 - 🐛 [Issue Tracker](https://github.com/bmadcode/bmad-method/issues)
 - 💬 [Discussions](https://github.com/bmadcode/bmad-method/discussions)
 
-## Contributing
+## License
 
-**We're excited about contributions and welcome your ideas, improvements, and expansion packs!** 🎉
+MIT License - see [LICENSE](LICENSE) for details.
 
-📋 **[Read CONTRIBUTING.md](CONTRIBUTING.md)** - Complete guide to contributing, including guidelines, process, and requirements
+## Version History
 
-## License
+- **Current**: [v4.0.0](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs
+- **Previous Versions**:
+  - [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3) - Introduced the unified BMAD Agent and Gemini optimization
+  - [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2) - Added web agents and template separation
+  - [Version 1](https://github.com/bmadcode/BMAD-METHOD/tree/V1) - Original 7-file proof of concept
 
-MIT License - see [LICENSE](LICENSE) for details.
+See [versions.md](docs/versions.md) for detailed version history and migration guides.
+
+## Author
+
+Created by Brian (BMad) Madison
+
+---
 
 [![Contributors](https://contrib.rocks/image?repo=bmadcode/bmad-method)](https://github.com/bmadcode/bmad-method/graphs/contributors)