bmad-method 4.37.0-beta.2 → 4.37.0-beta.3

package/docs/how-to-contribute-with-pull-requests.md

@@ -1,158 +0,0 @@
-# How to Contribute with Pull Requests
-
-**New to GitHub and pull requests?** This guide will walk you through the basics step by step.
-
-## What is a Pull Request?
-
-A pull request (PR) is how you propose changes to a project on GitHub. Think of it as saying "Here are some changes I'd like to make - please review and consider adding them to the main project."
-
-## Before You Start
-
-⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change.
-
-**Required before submitting PRs:**
-
-- **For bug fixes**: Create an issue using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
-- **For new features**:
-  1. Discuss in Discord [#general-dev channel](https://discord.gg/gk8jAdXWmj)
-  2. Create an issue using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
-- **For large changes**: Always open an issue first to discuss alignment
-
-## Step-by-Step Guide
-
-### 1. Fork the Repository
-
-1. Go to the [BMad-Method repository](https://github.com/bmadcode/bmad-method)
-2. Click the "Fork" button in the top-right corner
-3. This creates your own copy of the project
-
-### 2. Clone Your Fork
-
-```bash
-# Replace YOUR-USERNAME with your actual GitHub username
-git clone https://github.com/YOUR-USERNAME/bmad-method.git
-cd bmad-method
-```
-
-### 3. Create a New Branch
-
-**Never work directly on the `main` branch!** Always create a new branch for your changes:
-
-```bash
-# Create and switch to a new branch
-git checkout -b fix/typo-in-readme
-# or
-git checkout -b feature/add-new-agent
-```
-
-**Branch naming tips:**
-
-- `fix/description` - for bug fixes
-- `feature/description` - for new features
-- `docs/description` - for documentation changes
-
-### 4. Make Your Changes
-
-- Edit the files you want to change
-- Keep changes small and focused on one thing
-- Test your changes if possible
-
-### 5. Commit Your Changes
-
-```bash
-# Add your changes
-git add .
-
-# Commit with a clear message
-git commit -m "Fix typo in README.md"
-```
-
-**Good commit messages:**
-
-- "Fix typo in installation instructions"
-- "Add example for new agent usage"
-- "Update broken link in docs"
-
-**Bad commit messages:**
-
-- "stuff"
-- "changes"
-- "update"
-
-### 6. Push to Your Fork
-
-```bash
-# Push your branch to your fork
-git push origin fix/typo-in-readme
-```
-
-### 7. Create the Pull Request
-
-1. Go to your fork on GitHub
-2. You'll see a green "Compare & pull request" button - click it
-3. Select the correct target branch:
-   - **`next` branch** for most contributions (features, docs, enhancements)
-   - **`main` branch** only for critical fixes
-4. Fill out the PR description using the template in CONTRIBUTING.md:
-   - **What**: 1-2 sentences describing what changed
-   - **Why**: 1-2 sentences explaining why
-   - **How**: 2-3 bullets on implementation
-   - **Testing**: How you tested
-5. Reference the related issue number (e.g., "Fixes #123")
-
-### 8. Wait for Review
-
-- A maintainer will review your PR
-- They might ask for changes
-- Be patient and responsive to feedback
-
-## What Makes a Good Pull Request?
-
-✅ **Good PRs:**
-
-- Change one thing at a time
-- Have clear, descriptive titles
-- Explain what and why in the description
-- Include only the files that need to change
-
-❌ **Avoid:**
-
-- Changing formatting of entire files
-- Multiple unrelated changes in one PR
-- Copying your entire project/repo into the PR
-- Changes without explanation
-
-## Common Mistakes to Avoid
-
-1. **Don't reformat entire files** - only change what's necessary
-2. **Don't include unrelated changes** - stick to one fix/feature per PR
-3. **Don't paste code in issues** - create a proper PR instead
-4. **Don't submit your whole project** - contribute specific improvements
-
-## Need Help?
-
-- 💬 Join our [Discord Community](https://discord.gg/gk8jAdXWmj) for real-time help:
-  - **#general-dev** - Technical questions and feature discussions
-  - **#bugs-issues** - Get help with bugs before filing issues
-- 💬 Ask questions in [GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions)
-- 🐛 Report bugs using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
-- 💡 Suggest features using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
-- 📖 Read the full [Contributing Guidelines](../CONTRIBUTING.md)
-
-## Example: Good vs Bad PRs
-
-### 😀 Good PR Example
-
-**Title**: "Fix broken link to installation guide"
-**Changes**: One file, one line changed
-**Description**: "The link in README.md was pointing to the wrong file. Updated to point to correct installation guide."
-
-### 😞 Bad PR Example
-
-**Title**: "Updates"
-**Changes**: 50 files, entire codebase reformatted
-**Description**: "Made some improvements"
-
----
-
-**Remember**: We're here to help! Don't be afraid to ask questions. Every expert was once a beginner.

package/docs/user-guide.md

@@ -1,251 +0,0 @@
-# BMad-Method BMAd Code User Guide
-
-This guide will help you understand and effectively use the BMad Method for agile AI driven planning and development.
-
-## The BMad Plan and Execute Workflow
-
-First, here is the full standard Greenfield Planning + Execution Workflow. Brownfield is very similar, but it's suggested to understand this greenfield first, even if on a simple project before tackling a brownfield project. The BMad Method needs to be installed to the root of your new project folder. For the planning phase, you can optionally perform it with powerful web agents, potentially resulting in higher quality results at a fraction of the cost it would take to complete if providing your own API key or credits in some Agentic tools. For planning, powerful thinking models and larger context - along with working as a partner with the agents will net the best results.
-
-If you are going to use the BMad Method with a Brownfield project (an existing project), review **[Working in the Brownfield](./working-in-the-brownfield.md)**.
-
-If you do not see the diagrams that following rendering, you can install Markdown All in One along with the Markdown Preview Mermaid Support plugins to VSCode (or one of the forked clones). With these plugin's, if you right click on the tab when open, there should be a Open Preview option, or check the IDE documentation.
-
-### The Planning Workflow (Web UI or Powerful IDE Agents)
-
-Before development begins, BMad follows a structured planning workflow that's ideally done in web UI for cost efficiency:
-
-```mermaid
-graph TD
-    A["Start: Project Idea"] --> B{"Optional: Analyst Research"}
-    B -->|Yes| C["Analyst: Brainstorming (Optional)"]
-    B -->|No| G{"Project Brief Available?"}
-    C --> C2["Analyst: Market Research (Optional)"]
-    C2 --> C3["Analyst: Competitor Analysis (Optional)"]
-    C3 --> D["Analyst: Create Project Brief"]
-    D --> G
-    G -->|Yes| E["PM: Create PRD from Brief (Fast Track)"]
-    G -->|No| E2["PM: Interactive PRD Creation (More Questions)"]
-    E --> F["PRD Created with FRs, NFRs, Epics & Stories"]
-    E2 --> F
-    F --> F2{"UX Required?"}
-    F2 -->|Yes| F3["UX Expert: Create Front End Spec"]
-    F2 -->|No| H["Architect: Create Architecture from PRD"]
-    F3 --> F4["UX Expert: Generate UI Prompt for Lovable/V0 (Optional)"]
-    F4 --> H2["Architect: Create Architecture from PRD + UX Spec"]
-    H --> I["PO: Run Master Checklist"]
-    H2 --> I
-    I --> J{"Documents Aligned?"}
-    J -->|Yes| K["Planning Complete"]
-    J -->|No| L["PO: Update Epics & Stories"]
-    L --> M["Update PRD/Architecture as needed"]
-    M --> I
-    K --> N["📁 Switch to IDE (If in a Web Agent Platform)"]
-    N --> O["PO: Shard Documents"]
-    O --> P["Ready for SM/Dev Cycle"]
-
-    style A fill:#f5f5f5,color:#000
-    style B fill:#e3f2fd,color:#000
-    style C fill:#e8f5e9,color:#000
-    style C2 fill:#e8f5e9,color:#000
-    style C3 fill:#e8f5e9,color:#000
-    style D fill:#e8f5e9,color:#000
-    style E fill:#fff3e0,color:#000
-    style E2 fill:#fff3e0,color:#000
-    style F fill:#fff3e0,color:#000
-    style F2 fill:#e3f2fd,color:#000
-    style F3 fill:#e1f5fe,color:#000
-    style F4 fill:#e1f5fe,color:#000
-    style G fill:#e3f2fd,color:#000
-    style H fill:#f3e5f5,color:#000
-    style H2 fill:#f3e5f5,color:#000
-    style I fill:#f9ab00,color:#fff
-    style J fill:#e3f2fd,color:#000
-    style K fill:#34a853,color:#fff
-    style L fill:#f9ab00,color:#fff
-    style M fill:#fff3e0,color:#000
-    style N fill:#1a73e8,color:#fff
-    style O fill:#f9ab00,color:#fff
-    style P fill:#34a853,color:#fff
-```
-
-#### Web UI to IDE Transition
-
-**Critical Transition Point**: Once the PO confirms document alignment, you must switch from web UI to IDE to begin the development workflow:
-
-1. **Copy Documents to Project**: Ensure `docs/prd.md` and `docs/architecture.md` are in your project's docs folder (or a custom location you can specify during installation)
-2. **Switch to IDE**: Open your project in your preferred Agentic IDE
-3. **Document Sharding**: Use the PO agent to shard the PRD and then the Architecture
-4. **Begin Development**: Start the Core Development Cycle that follows
-
-### The Core Development Cycle (IDE)
-
-Once planning is complete and documents are sharded, BMad follows a structured development workflow:
-
-```mermaid
-graph TD
-    A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
-    B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
-    B2 --> B3{"PO: Validate Story Draft (Optional)"}
-    B3 -->|Validation Requested| B4["PO: Validate Story Against Artifacts"]
-    B3 -->|Skip Validation| C{"User Approval"}
-    B4 --> C
-    C -->|Approved| D["Dev: Sequential Task Execution"]
-    C -->|Needs Changes| B2
-    D --> E["Dev: Implement Tasks + Tests"]
-    E --> F["Dev: Run All Validations"]
-    F --> G["Dev: Mark Ready for Review + Add Notes"]
-    G --> H{"User Verification"}
-    H -->|Request QA Review| I["QA: Senior Dev Review + Active Refactoring"]
-    H -->|Approve Without QA| M["IMPORTANT: Verify All Regression Tests and Linting are Passing"]
-    I --> J["QA: Review, Refactor Code, Add Tests, Document Notes"]
-    J --> L{"QA Decision"}
-    L -->|Needs Dev Work| D
-    L -->|Approved| M
-    H -->|Needs Fixes| D
-    M --> N["IMPORTANT: COMMIT YOUR CHANGES BEFORE PROCEEDING!"]
-    N --> K["Mark Story as Done"]
-    K --> B
-
-    style A fill:#f5f5f5,color:#000
-    style B fill:#e8f5e9,color:#000
-    style B2 fill:#e8f5e9,color:#000
-    style B3 fill:#e3f2fd,color:#000
-    style B4 fill:#fce4ec,color:#000
-    style C fill:#e3f2fd,color:#000
-    style D fill:#e3f2fd,color:#000
-    style E fill:#e3f2fd,color:#000
-    style F fill:#e3f2fd,color:#000
-    style G fill:#e3f2fd,color:#000
-    style H fill:#e3f2fd,color:#000
-    style I fill:#f9ab00,color:#fff
-    style J fill:#ffd54f,color:#000
-    style K fill:#34a853,color:#fff
-    style L fill:#e3f2fd,color:#000
-    style M fill:#ff5722,color:#fff
-    style N fill:#d32f2f,color:#fff
-```
-
-## Installation
-
-### Optional
-
-If you want to do the planning in the Web with Claude (Sonnet 4 or Opus), Gemini Gem (2.5 Pro), or Custom GPT's:
-
-1. Navigate to `dist/teams/`
-2. Copy `team-fullstack.txt`
-3. Create new Gemini Gem or CustomGPT
-4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
-5. Type `/help` to see available commands
-
-### IDE Project Setup
-
-```bash
-# Interactive installation (recommended)
-npx bmad-method install
-```
-
-## Special Agents
-
-There are two bmad agents - in the future they will be consolidated into the single bmad-master.
-
-### BMad-Master
-
-This agent can do any task or command that all other agents can do, aside from actual story implementation. Additionally, this agent can help explain the BMad Method when in the web by accessing the knowledge base and explaining anything to you about the process.
-
-If you don't want to bother switching between different agents aside from the dev, this is the agent for you. Just remember that as the context grows, the performance of the agent degrades, therefore it is important to instruct the agent to compact the conversation and start a new conversation with the compacted conversation as the initial message. Do this often, preferably after each story is implemented.
-
-### BMad-Orchestrator
-
-This agent should NOT be used within the IDE, it is a heavy weight special purpose agent that utilizes a lot of context and can morph into any other agent. This exists solely to facilitate the team's within the web bundles. If you use a web bundle you will be greeted by the BMad Orchestrator.
-
-### How Agents Work
-
-#### Dependencies System
-
-Each agent has a YAML section that defines its dependencies:
-
-```yaml
-dependencies:
-  templates:
-    - prd-template.md
-    - user-story-template.md
-  tasks:
-    - create-doc.md
-    - shard-doc.md
-  data:
-    - bmad-kb.md
-```
-
-**Key Points:**
-
-- Agents only load resources they need (lean context)
-- Dependencies are automatically resolved during bundling
-- Resources are shared across agents to maintain consistency
-
-#### Agent Interaction
-
-**In IDE:**
-
-```bash
-# Some Ide's, like Cursor or Windsurf for example, utilize manual rules so interaction is done with the '@' symbol
-@pm Create a PRD for a task management app
-@architect Design the system architecture
-@dev Implement the user authentication
-
-# Some, like Claude Code use slash commands instead
-/pm Create user stories
-/dev Fix the login bug
-```
-
-#### Interactive Modes
-
-- **Incremental Mode**: Step-by-step with user input
-- **YOLO Mode**: Rapid generation with minimal interaction
-
-## IDE Integration
-
-### IDE Best Practices
-
-- **Context Management**: Keep relevant files only in context, keep files as lean and focused as necessary
-- **Agent Selection**: Use appropriate agent for task
-- **Iterative Development**: Work in small, focused tasks
-- **File Organization**: Maintain clean project structure
-- **Commit Regularly**: Save your work frequently
-
-## Technical Preferences System
-
-BMad includes a personalization system through the `technical-preferences.md` file located in `.bmad-core/data/` - this can help bias the PM and Architect to recommend your preferences for design patterns, technology selection, or anything else you would like to put in here.
-
-### Using with Web Bundles
-
-When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
-
-## Core Configuration
-
-The `bmad-core/core-config.yaml` file is a critical config that enables BMad to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml.
-
-### Developer Context Files
-
-Define which files the dev agent should always load:
-
-```yaml
-devLoadAlwaysFiles:
-  - docs/architecture/coding-standards.md
-  - docs/architecture/tech-stack.md
-  - docs/architecture/project-structure.md
-```
-
-You will want to verify from sharding your architecture that these documents exist, that they are as lean as possible, and contain exactly the information you want your dev agent to ALWAYS load into it's context. These are the rules the agent will follow.
-
-As your project grows and the code starts to build consistent patterns, coding standards should be reduced to include only the standards that the agent still makes with. The agent will look at surrounding code in files to infer the coding standards that are relevant to the current task.
-
-## Getting Help
-
-- **Discord Community**: [Join Discord](https://discord.gg/gk8jAdXWmj)
-- **GitHub Issues**: [Report bugs](https://github.com/bmadcode/bmad-method/issues)
-- **Documentation**: [Browse docs](https://github.com/bmadcode/bmad-method/docs)
-- **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode)
-
-## Conclusion
-
-Remember: BMad is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details.

package/docs/versioning-and-releases.md

@@ -1,77 +0,0 @@
-# How to Release a New Version
-
-## Automated Releases (Recommended)
-
-The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push and everything else happens automatically.
-
-### Commit Message Format
-
-Use these prefixes to control what type of release happens:
-
-```bash
-fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
-feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
-feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
-```
-
-### What Happens Automatically
-
-When you push commits with `fix:` or `feat:`, GitHub Actions will:
-
-1. ✅ Analyze your commit messages
-2. ✅ Bump version in `package.json`
-3. ✅ Generate changelog
-4. ✅ Create git tag
-5. ✅ **Publish to NPM automatically**
-6. ✅ Create GitHub release with notes
-
-### Your Simple Workflow
-
-```bash
-# Make your changes
-git add .
-git commit -m "feat: add team collaboration mode"
-git push
-
-# That's it! Release happens automatically 🎉
-# Users can now run: npx bmad-method (and get the new version)
-```
-
-### Commits That DON'T Trigger Releases
-
-These commit types won't create releases (use them for maintenance):
-
-```bash
-chore: update dependencies     # No release
-docs: fix typo in readme      # No release
-style: format code            # No release
-test: add unit tests          # No release
-```
-
-### Test Your Setup
-
-```bash
-npm run release:test    # Safe to run locally - tests the config
-```
-
----
-
-## Manual Release Methods (Exceptions Only)
-
-⚠️ Only use these methods if you need to bypass the automatic system
-
-### Quick Manual Version Bump
-
-```bash
-npm run version:patch   # 4.1.0 → 4.1.1 (bug fixes)
-npm run version:minor   # 4.1.0 → 4.2.0 (new features)
-npm run version:major   # 4.1.0 → 5.0.0 (breaking changes)
-
-# Then manually publish:
-npm publish
-git push && git push --tags
-```
-
-### Manual GitHub Actions Trigger
-
-You can also trigger releases manually through GitHub Actions workflow dispatch if needed.

package/docs/versions.md

@@ -1,48 +0,0 @@
-# Version History
-
-## Previous Versions
-
-- [Version 3](https://github.com/bmadcode/BMad-Method/tree/V3)
-- [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2)
-- [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1)
-
-## Current Version: V4 - Alpha
-
-Guiding Principles of V4:
-
-- Simple to understand, install and start using
-- Support Greenfield and Brownfield Scenarios
-- Greater configurability and more scenarios for usage - but kept out of the main package to maintain simplicity
-- Helpers for installers and web builders that will work with any OS and IDE easily
-- Align all agents to be the same for IDE and Web, without losing the power of the web versions, or the leanness of the files in the IDE to reduce context
-- Further improvements to the two most important agents - the SM and DEV
-
-## V3
-
-With the customizability of V2, there were still some issues. A PM could only easily do one thing, create a PRD. And maintaining the consistency between Web and IDE agents was a pain.
-
-V3 didn't fix the disconnect, but it did make it easier to maintain them all in a single folder, but there were only two official ide agents - all the rest were really made and optimized for the web.
-
-V3's biggest impact was a full explosion of customizability. Tasks, Personas, Agent Configurations, Doc Templates, data payloads.
-
-BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMad AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
-
-Now, instead of configuring 4+ web agents, all needing many files uploaded to create them, a single Agent called BMad, with a whole team, and the ability to switch and maintain personas evolved. Now you could in the same chat thread, talk to the whole team, or anyone on the team. No more exporting and reimporting docs to different chats - all of the sudden, you could finish the PRD, and ask Josh to pass it off to the Architect, and that was it, the architect just had it and we moved on! And all of that with just 7 total files to upload, delivering all power.
-
-But V3 had a major flaw - with massive configuration comes massive complexity - and in some ways, V3 started to get away from core principles - power through simplicity. The core system needs to do one thing well and be solid, and not stretch too thing with every possible thing.
-
-Also - while the dev is amazing and better in V3 than all the past, along with the SM - the dev started over documenting every step and really started to bloat stories with their own notes. And the SM was forgetting to add details to stories, or embellishing information. This was fixed somewhat in V3.1 - but the dev is still over explaining everything it does, instead of just capturing the changes to the story.
-
-## V2
-
-After V1 proved that the BMad method was solid and repeatable, 2 key ideas emerged. Separation of concerns, and building for the web made easier. By separating out templates - it was now much easier for the PRD fields to be customized, or the architecture.
-
-And the introduction that really supercharged everything in my opinion, the web versions! There were 4 hard coded web variants hand crafted - and we saw that we could, dirt cheap, work with agents for hours in the massive context of Gemini - from a PRD generating PM, through to an architect and even an analyst that could help us do extensive market research and brain storming.
-
-What I never expected is the names would stick, and people would keep the sample names I made that I thought people would configure. But now 4 version is, people refer to Mary, and John, and Bob! And when I randomly changed the names, I got A LOT of feedback! These have become trusted allies people are relying on, including for me!
-
-## V1
-
-Believe it or not (well you can view the link), V1 was a simple 7 file system! 7 Core agents working in harmony to help build a pretty specific type of application. But it showed its power and adaptability.
-
-Meant to be a simple Tech Demo showing how custom agents with agile personas can help streamline your project, and create rails for your dev agents that to that point had gone unmatched - while also putting a focus on the planning phases - the project sparked the imagination of many, and a seed of a potential was realized.