2.9 KiB
Repository Guidelines
Project Structure & Module Organization
The orchestrator logic lives in .claude/, with agent playbooks under .claude/agents/, reusable tasks in .claude/tasks/, and workflow automation scripts inside .claude/tools/. Runtime artifacts and validation history are kept in .claude/context/; keep generated JSON there so the CI validators can discover them. Reference material for contributors sits in docs/ (see docs/README.md for navigation), while GitHub Actions and shared issue templates reside in .github/.
Build, Test, and Development Commands
Run node .claude/tools/ci/validate-all.mjs before every commit; it sweeps all artifacts against the schemas and mirrors the Validate Artifacts workflow. Use node .claude/tools/gates/gate.mjs --schema <schema> --input <artifact> --gate <gate> when touching a specific gate, e.g., node .claude/tools/gates/gate.mjs --schema .claude/schemas/product_requirements.schema.json --input .claude/context/artifacts/prd.json --gate .claude/context/history/gates/greenfield-fullstack/02-pm.json --autofix 1. Render human-readable reports with node .claude/tools/renderers/bmad-render.mjs <type> <json> > <md>.
Coding Style & Naming Conventions
Match existing kebab-case directory names (bmad-orchestrator, system-architecture), and keep filenames lowercase with hyphens. YAML in config.yaml uses two-space indentation; mirror that in any new configuration. JSON artifacts must remain minified-friendly, double-quoted, and schema-compliant. Markdown documents favor sentence-case headings and descriptive bullet lists—ensure long lists stay scannable.
Testing Guidelines
Treat schema validation as the test suite: every artifact change requires a green run of validate-all.mjs. Store new fixtures under .claude/context/artifacts/ and schemas in .claude/schemas/; name tests after the schema they exercise (e.g., ux_spec.schema.json). When introducing a schema, add at least one representative artifact and, if behavior differs by workflow, capture each route in .claude/context/history/gates/.
Commit & Pull Request Guidelines
Commits follow lightweight Conventional Commits (feat:, Build:, documentation updates); keep the first line under 72 characters and prefer imperative verbs (“Add”, “Update”). For pull requests, include a concise change summary, validation evidence (paste the validate-all.mjs output), and links to relevant issues or workflow runs. Screenshots or rendered Markdown are required when modifying artifact renderers or documentation meant for stakeholders.
Security & Configuration Tips
Never commit API keys or tenant-specific data; redact sensitive context before placing files in .claude/context/. Configuration defaults live in .claude/config.yaml; extend them via environment variables or layered YAML files rather than hardcoding values. When sharing examples, use anonymized project names and neutral sample data to keep the enterprise presets reusable.