bmad-method 1.1.0 → 4.4.0

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

@@ -0,0 +1,141 @@
+# 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. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first.
+
+## 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
+```text
+
+### 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"
+```text
+
+**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. Fill out the PR template:
+   - **Title**: Clear, descriptive title
+   - **Description**: Explain what you changed and why
+
+### 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/g6ypHytrCB) for real-time help
+- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions)
+- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues)
+- 📖 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/roo-code-guide.md

@@ -0,0 +1,140 @@
+# BMAD Method Guide for Roo Code
+
+This guide walks you through the complete BMAD workflow using Roo Code as your AI-powered IDE.
+
+## Step 1: Install BMAD in Your Project
+
+1. Navigate to your project directory
+2. Run the BMAD installer:
+   ```bash
+   npx bmad-method install
+   ```
+3. When prompted:
+   - **Installation Type**: Choose "Complete installation (recommended)"
+   - **IDE**: Select "Roo Code"
+
+This creates a `.bmad-core` folder with all agents and a `.roo/.roomodes` file with custom modes.
+
+## Step 2: Set Up Team Fullstack in Gemini
+
+For ideation and planning, use Google's Gemini with the team-fullstack configuration:
+
+1. Open [Google AI Studio (Gemini)](https://aistudio.google.com/)
+2. Create a new chat
+3. Copy the contents of `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
+4. Paste this content into Gemini to set up the team
+
+### Gemini Planning Phase
+
+In Gemini, ask the BMAD team to help you:
+
+- **Ideate** your project concept
+- **Brainstorm** features and requirements
+- **Create a PRD** (Product Requirements Document)
+- **Design the architecture**
+
+Ask questions like:
+
+- "Help me brainstorm a [type of application] that does [core functionality]"
+- "Create a comprehensive PRD for this concept"
+- "Design the technical architecture for this system"
+
+Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
+
+- `docs/prd.md`
+- `docs/architecture.md`
+
+## Step 3: Back to Roo Code - Document Sharding
+
+Once you have your PRD and architecture documents in the `docs/` folder:
+
+1. **Open your project in Roo Code**
+2. **Select the bmad-master mode** from the mode selector (usually in status bar)
+3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
+4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
+
+This creates organized folders:
+
+- `docs/prd/` - Contains broken down PRD sections
+- `docs/architecture/` - Contains broken down architecture sections
+
+## Step 4: Story Development Cycle
+
+Now begin the iterative development cycle:
+
+### Create Stories (Scrum Master)
+
+1. **Start a new chat or conversation**
+2. **Switch to SM mode**: Select `bmad-sm` from the mode selector
+3. **Create story**: Type `*create` (this runs the create-next-story task)
+4. **Review the generated story**
+5. **If approved**: Set story status to "Approved" in the story file
+
+### Implement Stories (Developer)
+
+1. **Start a new conversation**
+2. **Switch to Dev mode**: Select `bmad-dev` from the mode selector
+3. **The agent will ask which story to implement**
+4. **Follow the development tasks** the agent provides
+5. **When story is complete**: Mark status as "Done"
+
+### Repeat the Cycle
+
+1. **Switch to SM mode** (`bmad-sm`)
+2. **Create next story**: Type `*create`
+3. **Review and approve**
+4. **Switch to Dev mode** (`bmad-dev`)
+5. **Implement the story**
+6. **Repeat until project complete**
+
+## Available Custom Modes in Roo Code
+
+All BMAD agents are available as custom modes:
+
+- `bmad-bmad-master` - 🧙 Universal task executor
+- `bmad-sm` - 🏃 Scrum Master for story creation
+- `bmad-dev` - 💻 Full-stack developer for implementation
+- `bmad-architect` - 🏗️ Solution architect for design
+- `bmad-pm` - 📋 Product manager for planning
+- `bmad-analyst` - 📊 Business analyst for requirements
+- `bmad-qa` - 🧪 QA specialist for testing
+- `bmad-po` - 🎯 Product owner for prioritization
+- `bmad-ux-expert` - 🎨 UX specialist for design
+
+## Roo Code-Specific Features
+
+- **Custom modes are stored in**: `.roo/.roomodes` file
+- **Mode switching**: Use the mode selector in Roo Code's interface
+- **File permissions**: Each agent has specific file access permissions
+  - **Documentation agents** (SM, PM, PO, Analyst): Limited to `.md` and `.txt` files
+  - **Technical agents** (Dev, Architect, Master): Full file access
+  - **QA agents**: Access to test files and documentation
+  - **UX agents**: Access to design-related files
+- **Context preservation**: Modes maintain context within conversations
+
+## Key Workflow Principles
+
+1. **Switch modes instead of starting new chats** - Roo Code handles context better with mode switching
+2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
+3. **Use bmad-master mode for document management** (sharding, templates, etc.)
+4. **Follow the SM → Dev mode cycle** for consistent story development
+5. **Review and approve stories** before implementation begins
+
+## Tips for Success
+
+- **Use mode selector effectively**: Switch modes as needed for different tasks
+- **Respect file permissions**: Agents can only edit files they have permission for
+- **Use \*help command**: Every mode supports `*help` to see available commands
+- **Review generated content**: Always review and approve stories before marking them ready
+- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
+- **Leverage Roo's context**: Modes can maintain context across the conversation
+
+## File Permission Summary
+
+- **bmad-analyst, bmad-pm, bmad-po, bmad-sm**: `.md`, `.txt` files only
+- **bmad-architect**: `.md`, `.txt`, `.yml`, `.yaml`, `.json` files
+- **bmad-qa**: Test files (`.test.js`, `.spec.ts`, etc.) and `.md` files
+- **bmad-ux-expert**: `.md`, `.css`, `.scss`, `.html`, `.jsx`, `.tsx` files
+- **bmad-dev, bmad-bmad-master, bmad-orchestrator**: Full file access
+
+This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.