> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/bmad-code-org/BMAD-METHOD/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to BMad Method

> Learn how to contribute to BMad Method - Bug reports, feature requests, pull requests, and community contributions

# Contributing to BMad Method

Thank you for considering contributing! We believe in **Human Amplification, Not Replacement** — bringing out the best thinking in both humans and AI through guided collaboration.

💬 **Discord**: [Join our community](https://discord.gg/gk8jAdXWmj) for real-time discussions, questions, and collaboration.

***

## Our Philosophy

BMad strengthens human-AI collaboration through specialized agents and guided workflows. Every contribution should answer: **"Does this make humans and AI better together?"**

### ✅ What We Welcome

* Enhanced collaboration patterns and workflows
* Improved agent personas and prompts
* Domain-specific modules leveraging BMad Core
* Better planning and context continuity
* Documentation improvements
* Bug fixes and performance enhancements

### ❌ What Doesn't Fit

* Purely automated solutions that sideline humans
* Complexity that creates barriers to adoption
* Features that fragment BMad Core's foundation

***

## Reporting Issues

**ALL bug reports and feature requests MUST go through GitHub Issues.**

### Before Creating an Issue

1. **Search existing issues** — Use the [GitHub issue search](https://github.com/bmad-code-org/BMAD-METHOD/issues) to check if your bug or feature has already been reported
2. **Search closed issues** — Your issue may have been fixed or addressed previously
3. **Check discussions** — Some conversations happen in [GitHub Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)

### Bug Reports

After searching, if the bug is unreported, use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md) and include:

* **Clear description** of the problem
* **Steps to reproduce** the issue
* **Expected vs actual behavior**
* **Your environment**:
  * AI model (Claude, GPT, Gemini, etc.)
  * IDE (Claude Code, Cursor, etc.)
  * BMad version
  * Operating system
* **Screenshots or error messages** if applicable

**Example bug report:**

```markdown theme={null}
## Description
The workflow-status command crashes when run in a project without git initialization.

## Steps to Reproduce
1. Create new directory: `mkdir test-project`
2. Run: `npx bmad-method install`
3. Run: `/bmad-help workflow status`

## Expected Behavior
Should display "No git repository found" message.

## Actual Behavior
Crashes with "Cannot read property 'branch' of undefined"

## Environment
- BMad version: 6.0.4
- IDE: Claude Code
- Model: Claude 3.5 Sonnet
- OS: macOS 14.1
```

### Feature Requests

After searching, use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md) and explain:

* **What the feature is** — Clear description of the proposed functionality
* **Why it would benefit the BMad community** — Use cases and problems it solves
* **How it strengthens human-AI collaboration** — Alignment with BMad philosophy

**For community modules**, review [TRADEMARK.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/TRADEMARK.md) for proper naming conventions (e.g., "My Module (BMad Community Module)").

***

## Before Starting Work

⚠️ **Required before submitting PRs:**

| Work Type     | Requirement                                    |
| ------------- | ---------------------------------------------- |
| Bug fix       | An open issue (create one if it doesn't exist) |
| Feature       | An open feature request issue                  |
| Large changes | Discussion via issue first                     |

**Why?** This prevents wasted effort on work that may not align with project direction.

***

## Pull Request Guidelines

### Target Branch

Submit PRs to the `main` branch. We use [trunk-based development](https://trunkbaseddevelopment.com/branch-for-release/): `main` is the trunk where all work lands, and stable release branches receive only cherry-picked fixes.

### PR Size

* **Ideal**: 200-400 lines of code changes
* **Maximum**: 800 lines (excluding generated files)
* **One feature/fix per PR**

If your change exceeds 800 lines, break it into smaller PRs that can be reviewed independently.

### New to Pull Requests?

1. **Fork** the repository on GitHub
2. **Clone** your fork:
   ```bash theme={null}
   git clone https://github.com/YOUR-USERNAME/bmad-method.git
   cd bmad-method
   ```
3. **Create a branch**:
   ```bash theme={null}
   git checkout -b fix/description
   # or
   git checkout -b feature/description
   ```
4. **Make changes** — Keep them focused on one thing
5. **Commit** with conventional commit message:
   ```bash theme={null}
   git commit -m "fix: correct typo in README"
   ```
6. **Push** to your fork:
   ```bash theme={null}
   git push origin fix/description
   ```
7. **Open PR** from your fork on GitHub

### PR Description Template

```markdown theme={null}
## What
[1-2 sentences describing WHAT changed]

## Why
[1-2 sentences explaining WHY this change is needed]
Fixes #[issue number]

## How
- [2-3 bullets listing HOW you implemented it]
- 
- 

## Testing
[1-2 sentences on how you tested this]
```

**Keep it under 200 words.**

### Commit Messages

Use [conventional commits](https://www.conventionalcommits.org/):

* `feat:` New feature
* `fix:` Bug fix
* `docs:` Documentation only
* `refactor:` Code change (no bug/feature)
* `test:` Adding tests
* `chore:` Build/tools changes

**Examples:**

```bash theme={null}
feat: add workflow validation command
fix: resolve workflow-status crash on non-git projects
docs: update contributing guide with PR template
refactor: simplify agent compilation logic
```

Keep messages under 72 characters. Each commit = one logical change.

***

## What Makes a Good PR?

| ✅ Do                        | ❌ Don't                      |
| --------------------------- | ---------------------------- |
| Change one thing per PR     | Mix unrelated changes        |
| Clear title and description | Vague or missing explanation |
| Reference related issues    | Reformat entire files        |
| Small, focused commits      | Copy your whole project      |
| Work on a branch            | Work directly on `main`      |
| Test your changes           | Submit untested code         |
| Follow existing style       | Introduce new patterns       |

***

## Development Guidelines

### Prompt & Agent Guidelines

* **Keep dev agents lean** — Focus on coding context, not documentation
* **Web/planning agents can be larger** with complex tasks
* **Everything is natural language** (markdown) — No code in core framework
* **Use BMad modules** for domain-specific features

### Validation

Run validation before submitting:

```bash theme={null}
npm run validate:schemas    # Validate YAML schemas
npm run validate:refs       # Validate file references
```

### File-Pattern-to-Validator Mapping

| File Pattern      | Validator               | Extraction Function   |
| ----------------- | ----------------------- | --------------------- |
| `*.yaml`, `*.yml` | `validate-file-refs.js` | `extractYamlRefs`     |
| `*.md`, `*.xml`   | `validate-file-refs.js` | `extractMarkdownRefs` |
| `*.csv`           | `validate-file-refs.js` | `extractCsvRefs`      |

***

## Real Contribution Examples

Here are some actual contributions from the community:

### Bug Fix Example

**PR #1735**: Fixed installer refusing installation in nested directories

* **Problem**: Autocomplete duplicates when installing in nested dirs
* **Solution**: Check ancestor directories for existing BMAD commands
* **Impact**: Prevents confusing duplicate commands

### Feature Example

**PR #1790**: Added edge case hunter review task

* **Problem**: Need systematic way to find unhandled edge cases
* **Solution**: New reusable review task that traces branching paths
* **Impact**: Complements adversarial review with method-driven analysis

### Documentation Example

**PR #1772**: Fixed broken TEA hyperlinks

* **Problem**: Links pointed to old repository URL
* **Solution**: Updated all TEA links to new repository
* **Impact**: Users can access TEA documentation correctly

***

## Need Help?

* 💬 **Discord**: [Join the community](https://discord.gg/gk8jAdXWmj)
* 🐛 **Bugs**: Use the [bug report template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=bug_report.md)
* 💡 **Features**: Use the [feature request template](https://github.com/bmad-code-org/BMAD-METHOD/issues/new?template=feature_request.md)

***

## Code of Conduct

By participating, you agree to abide by our [Code of Conduct](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/.github/CODE_OF_CONDUCT.md).

## License

By contributing, your contributions are licensed under the same MIT License. See [CONTRIBUTORS.md](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTORS.md) for contributor attribution.

***

**Thank you for making BMad Method better for everyone!** 🎉