Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
182 lines (120 loc) · 6.64 KB

CONTRIBUTING.md

File metadata and controls

182 lines (120 loc) · 6.64 KB

Contributing to BMad

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.

Before you write code: talk to us on Discord.

If your change adds features, restructures code, or touches more than a couple of files, confirm with a maintainer that it fits. A large PR out of the blue has a high chance of being closed — regardless of effort invested. A five-minute conversation can save you hours.

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

❌ 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
  • Expected vs actual behavior
  • Your environment (model, IDE, BMad version)
  • Screenshots or error messages if applicable

Feature Requests

After searching, use the feature request template and explain:

  • What the feature is
  • Why it would benefit the BMad community
  • How it strengthens human-AI collaboration

For community modules, review TRADEMARK.md for proper naming conventions (e.g., "My Module (BMad Community Module)").

Before Starting Work

Work Type Requirement
Typo / small bug fix Just open the PR
Feature or large change Confirm with a maintainer on Discord before you start

Pull Request Guidelines

Target Branch

Submit PRs to the main branch. We use trunk-based development. Every push to main auto-publishes to npm under the next tag. Stable releases are cut ~weekly to the latest tag.

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.

AI-Generated Code

Given the nature of this project, we expect most contributions involve AI assistance — that's fine. What we require is heavy human curation. You must understand every line you're submitting, have made deliberate choices about what to include, and be able to explain your reasoning.

We will reject PRs that read like raw LLM output: bulk refactors nobody asked for, unsolicited "improvements" across many files, or changes where the submitter clearly hasn't read the existing code. Using AI to write code is normal here; using AI as a substitute for thinking is not.

New to Pull Requests?

  1. Fork the repository
  2. Clone your fork: git clone https://github.com/YOUR-USERNAME/bmad-method.git
  3. Create a branch: git checkout -b fix/description or git checkout -b feature/description
  4. Make changes — keep them focused
  5. Commit: git commit -m "fix: correct typo in README"
  6. Push: 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

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

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
  • Validate file references: npm run validate:refs

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

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.