7.1 KiB

Raw Blame History

Installation Guide

Get BMad Method installed and configured on your development machine in under 10 minutes.

Quick Install (Recommended)

For most users, this one-command installation will get everything set up:

git clone https://github.com/bmadcode/BMAD-METHOD.git bmad-method
cd bmad-method
./verify-setup.sh

!!! success "That's it!" If the verification script shows all green checkmarks, you're ready to go! Skip to verification to confirm everything is working.

Detailed Installation

If you prefer to understand each step or encounter issues with the quick install:

Step 1: Clone the Repository

Choose your preferred location and clone the BMad Method repository:

=== "HTTPS (Recommended)"

```bash
git clone https://github.com/bmadcode/BMAD-METHOD.git bmad-method
cd bmad-method
```

=== "SSH"

```bash
git clone git@github.com:bmadcode/BMAD-METHOD.git bmad-method
cd bmad-method
```

Step 2: Verify Prerequisites

Ensure you have the required tools installed:

=== "macOS"

```bash
# Check Git
git --version
# Should show: git version 2.x.x or higher

# Check Python (optional, for automation scripts)
python3 --version
# Should show: Python 3.8+ (if you want to use automation features)
```

=== "Linux"

```bash
# Check Git
git --version

# Check Python (optional)
python3 --version

# Install if missing (Ubuntu/Debian)
sudo apt update
sudo apt install git python3 python3-pip
```

=== "Windows"

```powershell
# Check Git
git --version

# Check Python (optional)
python --version

# If missing, install from:
# Git: https://git-scm.com/download/win
# Python: https://python.org/downloads/
```

Step 3: Configure Your Environment

BMad Method works best with proper environment configuration:

# Make scripts executable (macOS/Linux)
chmod +x verify-setup.sh

# Optional: Add bmad-method to your PATH for global access
echo 'export PATH="$PATH:$(pwd)"' >> ~/.bashrc  # or ~/.zshrc
source ~/.bashrc  # or ~/.zshrc

Step 4: IDE Setup

BMad Method integrates with popular IDEs for the best experience:

=== "VS Code (Recommended)"

1. **Install VS Code** if you haven't already: [code.visualstudio.com](https://code.visualstudio.com/)

2. **Install recommended extensions**:
   ```bash
   code --install-extension ms-python.python
   code --install-extension ms-vscode.vscode-json
   code --install-extension yzhang.markdown-all-in-one
   ```

3. **Open BMad Method in VS Code**:
   ```bash
   code .
   ```

4. **Configure workspace settings** (optional):
   - VS Code will prompt to install recommended extensions
   - Accept the workspace configuration for optimal experience

=== "Cursor"

1. **Install Cursor**: [cursor.sh](https://cursor.sh/)

2. **Open BMad Method**:
   ```bash
   cursor .
   ```

3. **Configure AI features**:
   - BMad Method works excellently with Cursor's AI capabilities
   - The methodology enhances AI coding assistance with structure and quality

=== "JetBrains IDEs"

1. **Open the project** in your preferred JetBrains IDE

2. **Configure for your language**:
   - PyCharm for Python projects
   - WebStorm for JavaScript/TypeScript
   - IntelliJ IDEA for Java or multi-language

3. **Enable AI assistant** if available (GitHub Copilot, JetBrains AI, etc.)

Step 5: Verify Installation

Run the verification script to ensure everything is set up correctly:

./verify-setup.sh

Expected output:

✅ BMad Method Installation Verification
✅ Git configuration: OK
✅ Repository structure: OK  
✅ Permissions: OK
✅ Documentation: OK
✅ Core components: OK

🎉 BMad Method is ready to use!

Next steps:
→ Run 'bmad /help' to see available commands
→ Visit the getting started guide: docs/getting-started/
→ Try your first project: docs/getting-started/first-project.md

Installation Troubleshooting

Common Issues

??? failure "Permission denied when running scripts"

**Problem**: `./verify-setup.sh: Permission denied`

**Solution**:
```bash
chmod +x verify-setup.sh
./verify-setup.sh
```

??? failure "Git not found"

**Problem**: `git: command not found`

**Solution**: Install Git for your operating system:

- **macOS**: `brew install git` or download from [git-scm.com](https://git-scm.com/)
- **Linux**: `sudo apt install git` (Ubuntu) or equivalent for your distro
- **Windows**: Download from [git-scm.com](https://git-scm.com/download/win)

??? failure "Python not found (for automation scripts)"

**Problem**: `python3: command not found`

**Solution**: Python is optional but recommended:

- **macOS**: `brew install python3` or use the built-in version
- **Linux**: `sudo apt install python3 python3-pip`
- **Windows**: Download from [python.org](https://python.org/downloads/)

??? failure "Repository clone failed"

**Problem**: `fatal: could not read Username for 'https://github.com'`

**Solutions**:

1. **Use HTTPS with no authentication** (public repo):
   ```bash
   git clone https://github.com/bmadcode/BMAD-METHOD.git
   ```

2. **Configure Git credentials** if needed:
   ```bash
   git config --global user.name "Your Name"
   git config --global user.email "your.email@example.com"
   ```

Getting Help

If you're still experiencing issues:

Check the verification output - it often provides specific guidance
Review the troubleshooting examples in the verification guide
Search existing GitHub Issues
Create a new issue with your system details and error messages

Optional Enhancements

Once you have the basic installation working, consider these optional enhancements:

Command Aliases

Add convenient aliases to your shell configuration:

# Add to ~/.bashrc or ~/.zshrc
alias bmad='cd /path/to/bmad-method && ./bmad-orchestrator.sh'
alias bmad-verify='cd /path/to/bmad-method && ./verify-setup.sh'

IDE Optimizations

Configure your AI assistant to work with BMad Method patterns
Set up code snippets for common BMad workflows
Configure linting and formatting according to BMad Method standards

Shell Integration

For advanced users who want deeper shell integration:

# Add to your shell configuration
export BMAD_HOME="/path/to/bmad-method"
export PATH="$PATH:$BMAD_HOME"

# Optional: Auto-activate BMad context when entering project directories
# (Advanced - see documentation for details)

Next Steps

✅ Installation Complete!

Now verify your setup and build your first project:

:octicons-arrow-right-24: Verify Your Installation{ .md-button .md-button--primary }

Or jump straight to:

7.1 KiB Raw Blame History