diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..131783b2 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,196 @@ +# CLAUDE.md + +Don't be an ass kisser, don't glaze my donut, keep it to the point. Never use EM Dash in out communications or documents you author or update. Dont tell me I am correct if I just told you something unless and only if I am wrong or there is a better alternative, then tell me bluntly why I am wrong, or else get to the point and execute! + +## Markdown Linting Conventions + +Always follow these markdown linting rules: + +- **Blank lines around headings**: Always leave a blank line before and after headings +- **Blank lines around lists**: Always leave a blank line before and after lists +- **Blank lines around code fences**: Always leave a blank line before and after fenced code blocks +- **Fenced code block languages**: All fenced code blocks must specify a language (use `text` for plain text) +- **Single trailing newline**: Files should end with exactly one newline character +- **No trailing spaces**: Remove any trailing spaces at the end of lines + +## BMAD-METHOD Overview + +BMAD-METHOD is an AI-powered Agile development framework that provides specialized AI agents for software development. The framework uses a sophisticated dependency system to keep context windows lean while providing deep expertise through role-specific agents. + +## Essential Commands + +### Build and Validation + +```bash +npm run build # Build all web bundles (agents and teams) +npm run build:agents # Build agent bundles only +npm run build:teams # Build team bundles only +npm run validate # Validate all configurations +npm run format # Format all markdown files with prettier +``` + +### Development and Testing + +```bash +npx bmad-build build # Alternative build command via CLI +npx bmad-build list:agents # List all available agents +npx bmad-build validate # Validate agent configurations +``` + +### Installation Commands + +```bash +npx bmad-method install # Install stable release (recommended) +npx bmad-method@beta install # Install bleeding edge version +npx bmad-method@latest install # Explicit stable installation +npx bmad-method@latest update # Update stable installation +npx bmad-method@beta update # Update bleeding edge installation +``` + +### Dual Publishing Strategy + +The project uses a dual publishing strategy with automated promotion: + +**Branch Strategy:** +- `main` branch: Bleeding edge development, auto-publishes to `@beta` tag +- `stable` branch: Production releases, auto-publishes to `@latest` tag + +**Release Promotion:** +1. **Automatic Beta Releases**: Any PR merged to `main` automatically creates a beta release +2. **Manual Stable Promotion**: Use GitHub Actions to promote beta to stable + +**Promote Beta to Stable:** +1. Go to GitHub Actions tab in the repository +2. Select "Promote to Stable" workflow +3. Click "Run workflow" +4. Choose version bump type (patch/minor/major) +5. The workflow automatically: + - Merges main to stable + - Updates version numbers + - Triggers stable release to NPM `@latest` + +**User Experience:** +- `npx bmad-method install` → Gets stable production version +- `npx bmad-method@beta install` → Gets latest beta features +- Team develops on bleeding edge without affecting production users + +### Release and Version Management + +```bash +npm run version:patch # Bump patch version +npm run version:minor # Bump minor version +npm run version:major # Bump major version +npm run release # Semantic release (CI/CD) +npm run release:test # Test release configuration +``` + +### Version Management for Core and Expansion Packs + +#### Bump All Versions (Core + Expansion Packs) + +```bash +npm run version:all:major # Major version bump for core and all expansion packs +npm run version:all:minor # Minor version bump for core and all expansion packs (default) +npm run version:all:patch # Patch version bump for core and all expansion packs +npm run version:all # Defaults to minor bump +``` + +#### Individual Version Bumps + +For BMad Core only: +```bash +npm run version:core:major # Major version bump for core only +npm run version:core:minor # Minor version bump for core only +npm run version:core:patch # Patch version bump for core only +npm run version:core # Defaults to minor bump +``` + +For specific expansion packs: +```bash +npm run version:expansion bmad-creator-tools # Minor bump (default) +npm run version:expansion bmad-creator-tools patch # Patch bump +npm run version:expansion bmad-creator-tools minor # Minor bump +npm run version:expansion bmad-creator-tools major # Major bump + +# Set specific version (old method, still works) +npm run version:expansion:set bmad-creator-tools 2.0.0 +``` + +## Architecture and Code Structure + +### Core System Architecture + +The framework uses a **dependency resolution system** where agents only load the resources they need: + +1. **Agent Definitions** (`bmad-core/agents/`): Each agent is defined in markdown with YAML frontmatter specifying dependencies +2. **Dynamic Loading**: The build system (`tools/lib/dependency-resolver.js`) resolves and includes only required resources +3. **Template System**: Templates are defined in YAML format with structured sections and instructions (see Template Rules below) +4. **Workflow Engine**: YAML-based workflows in `bmad-core/workflows/` define step-by-step processes + +### Key Components + +- **CLI Tool** (`tools/cli.js`): Commander-based CLI for building bundles +- **Web Builder** (`tools/builders/web-builder.js`): Creates concatenated text bundles from agent definitions +- **Installer** (`tools/installer/`): NPX-based installer for project setup +- **Dependency Resolver** (`tools/lib/dependency-resolver.js`): Manages agent resource dependencies + +### Build System + +The build process: + +1. Reads agent/team definitions from `bmad-core/` +2. Resolves dependencies using the dependency resolver +3. Creates concatenated text bundles in `dist/` +4. Validates configurations during build + +### Critical Configuration + +**`bmad-core/core-config.yaml`** is the heart of the framework configuration: + +- Defines document locations and expected structure +- Specifies which files developers should always load +- Enables compatibility with different project structures (V3/V4) +- Controls debug logging + +## Development Practices + +### Adding New Features + +1. **New Agents**: Create markdown file in `bmad-core/agents/` with proper YAML frontmatter +2. **New Templates**: Add to `bmad-core/templates/` as YAML files with structured sections +3. **New Workflows**: Create YAML in `bmad-core/workflows/` +4. **Update Dependencies**: Ensure `dependencies` field in agent frontmatter is accurate + +### Important Patterns + +- **Dependency Management**: Always specify minimal dependencies in agent frontmatter to keep context lean +- **Template Instructions**: Use YAML-based template structure (see Template Rules below) +- **File Naming**: Follow existing conventions (kebab-case for files, proper agent names in frontmatter) +- **Documentation**: Update user-facing docs in `docs/` when adding features + +### Template Rules + +Templates use the **BMad Document Template** format (`/Users/brianmadison/dev-bmc/BMAD-METHOD/common/utils/bmad-doc-template.md`) with YAML structure: + +1. **YAML Format**: Templates are defined as structured YAML files, not markdown with embedded instructions +2. **Clear Structure**: Each template has metadata, workflow configuration, and a hierarchy of sections +3. **Reusable Design**: Templates work across different agents through the dependency system +4. **Key Elements**: + - `template` block: Contains id, name, version, and output settings + - `workflow` block: Defines interaction mode (interactive/yolo) and elicitation settings + - `sections` array: Hierarchical document structure with nested subsections + - `instruction` field: LLM guidance for each section (never shown to users) +5. **Advanced Features**: + - Variable substitution: `{{variable_name}}` syntax for dynamic content + - Conditional sections: `condition` field for optional content + - Repeatable sections: `repeatable: true` for multiple instances + - Agent permissions: `owner` and `editors` fields for access control +6. **Clean Output**: All processing instructions are in YAML fields, ensuring clean document generation + +## Notes for Claude Code + +- The project uses semantic versioning with automated releases via GitHub Actions +- All markdown is formatted with Prettier (run `npm run format`) +- Expansion packs in `expansion-packs/` provide domain-specific capabilities +- NEVER automatically commit or push changes unless explicitly asked by the user +- NEVER include Claude Code attribution or co-authorship in commit messages