mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00

Files

T

Michael Pursifull 24cf444366 feat: extend Layer 1 file-ref validator to scan CSV workflow-file references (#1573 )

* feat: extend validate-file-refs.js to scan CSV workflow-file references

Add CSV file reference extraction to the Layer 1 validation pipeline,
preventing broken _bmad/ workflow-file paths in module-help.csv files.
Closes the gap identified after PR #1529 where CSV references were
unvalidated despite being a source of repeat community issues.

Refs: #1519

* fix: include test:refs in aggregate test script

Add CSV file-ref extraction tests to the aggregate `npm test` pipeline,
matching the existing pattern for test:schemas and test:install.

Thanks to CodeRabbit for catching the omission.

* fix: address review feedback on CSV validator extension

- Surface CSV parse errors visibly instead of silently swallowing
  (no Layer 2c schema validator exists yet to catch these)
- Add explanatory comments for the !VERBOSE logging pattern
  (non-verbose prints file headers only when issues found)
- Add verbose-mode diagnostics for extensionless path handling
  ([SKIP] when nothing exists, [OK-DIR] for valid directories)

* refactor: collect-then-print to eliminate confusing !VERBOSE pattern

Replace the split header-printing logic (print early in verbose mode,
print late in non-verbose mode with a !VERBOSE guard) with a simpler
collect-then-print approach. Refs are now classified into ok[] and
broken[] arrays first, then printed in a single location with one
straightforward if/else if decision.

Addresses alexeyv's review feedback about the counterintuitive
"if not verbose, log" pattern.

* feat: promote extensionless unresolved paths from silent skip to [UNRESOLVED]

Paths without file extensions that don't exist as files or directories
are now flagged as [UNRESOLVED] — a distinct tag from [BROKEN] (which
means a file with a known extension wasn't found). Both count toward
the broken reference total and appear in CI annotations.

This catches real bugs like wrong directory names in installed_path
metadata and dead invoke-workflow references to removed workflows.
Extensionless paths that DO exist as directories are still [OK-DIR].

---------

Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
Co-authored-by: Brian <bmadcode@gmail.com>

2026-02-08 09:19:53 -06:00

5.7 KiB

Raw Permalink Blame History

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.

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

Search existing issues — Use the GitHub issue search to check if your bug or feature has already been reported
Search closed issues — Your issue may have been fixed or addressed previously
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

⚠️ 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.

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?

Fork the repository
Clone your fork: git clone https://github.com/YOUR-USERNAME/bmad-method.git
Create a branch: git checkout -b fix/description or git checkout -b feature/description
Make changes — keep them focused
Commit: git commit -m "fix: correct typo in README"
Push: git push origin fix/description
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 YAML schemas: npm run validate:schemas
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?

💬 Discord: Join the community
🐛 Bugs: Use the bug report template
💡 Features: Use the feature request template

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.

5.7 KiB Raw Permalink Blame History