BMAD-METHOD/CLAUDE.md

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

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

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

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

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)

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:

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:

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