BMAD-METHOD/.kilocode/rules/bmad-project-standards.md

BMAD Project Standards and Conventions

Project Structure Conventions

Directory Organization

The BMAD framework follows a strict directory structure:

bmad/
├── core/              # Core framework - universal functionality
├── {module}/          # Module directories (bmm, bmb, cis, bmd)
└── _cfg/             # User customizations (update-safe)

Rules:

• Core framework code goes in bmad/core/
• Module-specific code in bmad/{module}/
• User customizations ONLY in bmad/_cfg/
• Never mix concerns across directories

File Naming Conventions

Agent Files: kebab-case.md

• Examples: bmad-master.md, product-manager.md, game-developer.md

Workflow Files: kebab-case/workflow.yaml

• Directory per workflow with supporting files
• Examples: create-agent/workflow.yaml, party-mode/workflow.yaml

Configuration Files: config.yaml, {name}-manifest.csv

• Standard YAML format
• CSV for manifests

Agent File Structure

Required Format

Agent files MUST use XML-structured markdown with frontmatter:

---
name: 'agent-slug'
description: 'Brief description'
---

<agent id="path/to/agent.md" name="Display Name" title="Full Title" icon="🎯">
<activation critical="MANDATORY">
  <!-- Steps here -->
</activation>

<persona>
  <role>Role definition</role>
  <identity>Identity description</identity>
  <communication_style>Communication style</communication_style>
  <principles>Core principles</principles>
</persona>

<menu>
  <item cmd="*command">Display Text</item>
</menu>
</agent>

Agent Activation Standards

MANDATORY First Steps:

1. Load persona from current agent file
2. Load bmad/core/config.yaml and store variables:
   • {user_name}
   • {communication_language}
   • {output_folder}
   • {project_name}
3. Greet user by name in their preferred language
4. Display menu
5. Wait for user input

Variable Usage:

• Always use {user_name} when addressing user
• Always communicate in {communication_language}
• Write output to {output_folder} when specified
• Reference {project_name} in context

Menu Item Standards

Menu items use three handler types:

1. workflow: Executes a workflow YAML

<item cmd="*trigger" workflow="{project-root}/path/to/workflow.yaml">Description</item>

2. action: Executes inline instructions or references prompt ID

<item cmd="*trigger" action="#prompt-id">Description</item>
<item cmd="*trigger" action="inline instruction text">Description</item>

3. exec: Direct command execution (use sparingly)

<item cmd="*trigger" exec="command to execute">Description</item>

Rules:

• Menu commands MUST use asterisk prefix: *command
• Include *help to redisplay menu
• Include *exit for agent exit
• Keep menu concise (5-10 items max)

Workflow File Structure

Workflow YAML Format

workflow:
  id: unique-workflow-id
  name: Display Name
  description: Brief description
  type: interactive | automated

  steps:
    - id: step-1
      name: Step Name
      type: task | prompt | conditional | input
      instructions: path/to/instructions.md
      output:
        type: file | variable | both
        path: output/path.md
        template: path/to/template.md

    - id: step-2
      name: Next Step
      type: task
      dependencies:
        - step-1
      instructions: path/to/instructions-2.md

Workflow Supporting Files

Each workflow directory should contain:

1. workflow.yaml (required) - Workflow definition
2. instructions.md (required) - Detailed step instructions
3. README.md (recommended) - Workflow documentation
4. template.md (optional) - Output templates
5. checklist.md (optional) - Validation checklist

Workflow Execution Standards

When executing workflows:

1. Load bmad/core/tasks/workflow.xml (the workflow executor)
2. Pass workflow YAML path as parameter
3. Execute steps sequentially
4. Save output after EACH step (never batch)
5. Preserve state between steps
6. Handle errors gracefully

Customization System

Update-Safe Customizations

User customizations go in bmad/_cfg/ and follow this structure:

bmad/_cfg/
├── agents/                    # Agent customization files
│   └── agent-name.yaml       # Override file per agent
├── agent-manifest.csv        # Generated agent list
├── workflow-manifest.csv     # Generated workflow list
└── task-manifest.csv         # Generated task list

Agent Customization Format

File: bmad/_cfg/agents/{agent-slug}.yaml

# Override any agent property
name: "Custom Name"
description: "Custom description"
communication_style: "Custom communication style"
additional_instructions: |
  Additional behavioral instructions
  that modify the agent's behavior  

Rules:

• Customizations override base agent properties
• Survive framework updates
• Merge at runtime
• YAML format only

Code Style Standards

JavaScript/Node.js

Style:

• ES6+ features
• CommonJS modules (require, module.exports)
• 2-space indentation
• Single quotes for strings
• Semicolons required

Linting: ESLint (see eslint.config.mjs) Formatting: Prettier (see prettier.config.mjs)

YAML Files

Style:

• 2-space indentation
• No tabs
• Quoted strings when containing special characters
• Multi-line strings use | or > operators

Validation:

• Must parse without errors
• Required fields must be present
• Follow schema for workflow/config files

Markdown Files

Style:

• ATX-style headers (# prefix)
• Fenced code blocks with language specifiers
• Blank line before/after headings
• No trailing whitespace

Agent XML:

• Properly nested XML structure
• Required attributes present
• Valid XML (no unclosed tags)

Configuration Standards

config.yaml Requirements

Must contain these fields:

user_name: "User's Name"
communication_language: "en"  # ISO language code
output_folder: "_docs"        # Relative path
project_name: "Project Name"

Optional Fields:

communication_style: "professional" | "casual" | "technical"
technical_level: "beginner" | "intermediate" | "expert"
output_format: "markdown" | "docx" | "pdf"

Manifest CSV Format

agent-manifest.csv:

slug,name,path,description
agent-slug,Display Name,path/to/agent.md,Brief description

workflow-manifest.csv:

id,name,path,description,module
workflow-id,Display Name,path/to/workflow.yaml,Brief description,module-name

task-manifest.csv:

id,name,path,description,type
task-id,Display Name,path/to/task.xml,Brief description,task|utility

Documentation Standards

README Files

Each module and major component should have a README.md with:

1. Overview - What it is, purpose
2. Installation - How to install/activate
3. Usage - How to use, examples
4. Configuration - Available settings
5. API/Reference - Detailed reference (if applicable)
6. Troubleshooting - Common issues
7. Contributing - How to contribute

Inline Documentation

Agent Instructions:

• Clear, step-by-step format
• Numbered lists for sequences
• Code examples where helpful
• Error handling guidance

Workflow Instructions:

• Detailed step instructions
• Expected inputs/outputs
• Validation criteria
• Error scenarios

Code Comments:

• Explain why, not what
• Document complex logic
• Note any non-obvious behavior
• Reference issues/tickets if relevant

Version Control Standards

Git Practices

Branches:

• main - Production releases
• v6-alpha - Alpha development
• v4-stable - Stable v4 branch
• feature/* - Feature branches
• fix/* - Bug fix branches

Commit Messages: Format: type(scope): message

Types:

• feat - New feature
• fix - Bug fix
• docs - Documentation
• refactor - Code refactoring
• test - Test changes
• chore - Maintenance tasks

Examples:

• feat(bmm): add Level 4 enterprise workflow
• fix(installer): resolve module selection bug
• docs(readme): update v6 alpha installation steps

What to Commit

Include:

• Source code (src/, tools/)
• Configuration templates
• Documentation
• Tests
• Build configuration

Exclude (via .gitignore):

• node_modules/
• bmad/ (users install their own)
• IDE-specific files (user preference)
• Build artifacts
• Log files
• .env files

Testing Standards

Pre-commit Checks

Automated (via Husky):

1. Lint staged files
2. Format staged files
3. Validate syntax

Manual Before Commit:

1. Agent activation test
2. Workflow execution test
3. Config loading test
4. Customization test

Testing Checklist

Before releases:

• All agents load correctly
• Workflows execute without errors
• Config file loads properly
• Customizations apply correctly
• Manifests generated accurately
• Installation works in clean environment
• IDE integrations function
• Documentation is current

Best Practices

Agent Design

1. Single Responsibility: Each agent has clear, focused purpose
2. User-Centric: Design for user workflow, not agent convenience
3. Consistent Voice: Maintain persona throughout interaction
4. Config Integration: Always load and use user config
5. Error Handling: Provide helpful error messages
6. Language Support: Respect communication_language setting

Workflow Design

1. Step Independence: Each step should be self-contained
2. State Management: Save state after each step
3. Clear Instructions: Detailed, actionable step instructions
4. Validation: Include checks for step completion
5. Templates: Provide output templates where appropriate
6. Flexibility: Allow optional steps when possible

Module Development

1. Modular Design: Modules should be independent
2. Core Dependencies: Depend only on core, not other modules
3. Shared Resources: Use CIS for shared creative workflows
4. Clear Boundaries: Well-defined module scope
5. Documentation: Comprehensive module README
6. Examples: Include usage examples

Common Anti-Patterns to Avoid

Agent Development

❌ Don't:

• Hard-code user names or languages
• Load unnecessary files at startup
• Create menu items that don't work
• Mix persona voices
• Forget error handling

✅ Do:

• Use config variables
• Lazy-load resources
• Test all menu items
• Maintain consistent persona
• Handle errors gracefully

Workflow Development

❌ Don't:

• Batch multiple steps together
• Skip state saving
• Assume files exist
• Ignore dependencies
• Forget validation

✅ Do:

• Execute steps one at a time
• Save after each step
• Verify prerequisites
• Handle dependencies
• Validate outputs

Customization

❌ Don't:

• Modify base agent files directly
• Put customizations outside _cfg/
• Use complex nested overrides
• Ignore YAML syntax

✅ Do:

• Use customization files
• Keep all customizations in _cfg/
• Keep overrides simple
• Validate YAML syntax

Performance Considerations

1. Lazy Loading: Load files only when needed (except config)
2. Caching: Use manifests for agent/workflow discovery
3. Incremental Execution: Save workflow progress
4. Minimal Context: Load only necessary context
5. Efficient Parsing: Pre-validate YAML/XML when possible

Security Considerations

1. No External Calls: Core framework stays local
2. User Control: Users control all customizations
3. No Secrets: Never store secrets in code
4. File Permissions: Respect file system permissions
5. IDE Security: Rely on IDE-level security