Repository Guidelines

Project Structure & Module Organization

src/ contains the canonical source for agents and workflows (core/ shared assets, modules/ for BMM/BMB/CIS, utility/ helpers).
bmad/ mirrors the install-ready payloads; regenerate via bundlers instead of editing files there directly.
tools/ hosts the Node CLI, bundlers, validators, and test fixtures; CLI entry points live under tools/cli.
docs/ holds contributor-facing guides—update alongside feature changes so installers and slash commands stay accurate.

npm run lint runs ESLint across JS and YAML; required before opening a PR.
npm run format:check / npm run format:fix enforces Prettier (140 width, 2-space indent).
npm run bundle rebuilds the distributable agent bundles under bmad/**; use after touching src/**.
npm run validate:bundles confirms bundle integrity and manifests stay in sync.
node tools/cli/bmad-cli.js status (npm run bmad:status) checks local installer health.

JavaScript is formatted by Prettier with semicolons and single quotes; keep folders named for agent personas (architect/, dev/, etc.).
CLI scripts in tools/** may stay CommonJS, but prefer clear filenames and avoid new abbreviations.
YAML files must use the .yaml extension and double-quoted strings per lint rules.
Markdown docs typically wrap near 140 characters and use imperative language for steps.

Jest 30 ships with the repo—run npx jest or target suites such as npx jest tools/cli/test-bundler.js.
Tests sit alongside utilities (tools/**/test-*.js); follow that pattern when adding coverage.
Add regression tests before changing bundlers or installers, covering at least one happy-path scenario.

Follow Conventional Commits (feat(installer): ..., fix: ...) as seen in recent history.
Keep PRs scoped; call out bundle or manifest impacts in the description and link relevant issues.
Before opening a PR, ensure npm run lint passes, regenerate bundles when needed, and update docs for user-facing changes.
Request review from the owning module (BMM, BMB, CIS) when editing their agents or workflows.

Never hand-edit generated content under bmad/**; modify src/** sources and rerun the bundler instead.
New agents belong in src/core/agents with installer logic in _module-installer/ to stay compatible with the CLI.