Skip to main content

​
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 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 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

​
Bug Reports

After searching, if the bug is unreported, use the bug report template 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: 
## 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 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 for proper naming conventions (e.g., “My Module (BMad Community Module)”).

​
Before Starting Work

⚠️ Required before submitting PRs:
Work TypeRequirement
Bug fixAn open issue (create one if it doesn’t exist)
FeatureAn open feature request issue
Large changesDiscussion 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: 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: 
    git clone https://github.com/YOUR-USERNAME/bmad-method.git
cd bmad-method
  3. Create a branch: 
    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: 
    git commit -m "fix: correct typo in README"
  6. Push to your fork: 
    git push origin fix/description
  7. Open PR from your fork on GitHub

​
PR Description Template

## 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:
  • feat: New feature
  • fix: Bug fix
  • docs: Documentation only
  • refactor: Code change (no bug/feature)
  • test: Adding tests
  • chore: Build/tools changes
Examples: 
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 PRMix unrelated changes
Clear title and descriptionVague or missing explanation
Reference related issuesReformat entire files
Small, focused commitsCopy your whole project
Work on a branchWork directly on main
Test your changesSubmit untested code
Follow existing styleIntroduce 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: 
npm run validate:schemas    # Validate YAML schemas
npm run validate:refs       # Validate file references

​
File-Pattern-to-Validator Mapping

File PatternValidatorExtraction Function
*.yaml, *.ymlvalidate-file-refs.jsextractYamlRefs
*.md, *.xmlvalidate-file-refs.jsextractMarkdownRefs
*.csvvalidate-file-refs.jsextractCsvRefs

​
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?

​
Code of Conduct

By participating, you agree to abide by our Code of Conduct.

​
License

By contributing, your contributions are licensed under the same MIT License. See CONTRIBUTORS.md for contributor attribution.
Thank you for making BMad Method better for everyone! 🎉

Build docs developers (and LLMs) love

Get started for freeTalk to us