Configuration

BMad modules are configured using module.yaml files that define module metadata, user prompts, variables, and installation behavior. This reference documents the configuration schema and available options.

Configuration File Location

Each module contains a module.yaml file in its root directory:

src/
├── core/
│   └── module.yaml          # Core module configuration
├── bmm/
│   └── module.yaml          # BMM module configuration
└── [other-modules]/
    └── module.yaml

Schema Overview

A module.yaml file consists of:

Module metadata - Identification and description
Header configuration - Display text during installation
Variable definitions - User-configurable settings with prompts
Installation directives - Directories to create, files to copy, etc.

Module Metadata

code

string

required

Unique identifier for the module. Used in command names and internal references.Naming convention: Lowercase, 2-4 charactersExample:

code: bmm

name

string

required

Human-readable module name displayed during installation and in status output.Example:

name: "BMad Method Agile-AI Driven-Development"

description

string

Brief description of the module’s purpose and features.Example:

description: "AI-driven agile development framework"

default_selected

boolean

default:"false"

Whether this module should be pre-selected during installation. Only the core module and primary modules should use this.Example:

default_selected: true

Header Configuration

Headers provide context to users during the installation prompts.

header

string

Main heading displayed before module configuration prompts.Example:

header: "BMad Core Configuration"

subheader

string

Additional explanatory text displayed below the header. Supports multi-line strings.Example:

subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all installed bmad skills, workflows, and agents."

Variable Definitions

Variables collect user input and configure module behavior. Each variable has a unique key and configuration object.

Variable Structure

variable_name:
  prompt: "Question to ask user"
  default: "default_value"
  result: "{value}"
  # Optional: single-select or multi-select options

Variable Properties

prompt

string | array

required

Question(s) to ask the user. Can be:

Single string for simple prompts
Array of strings for multi-line prompts

Examples:

# Simple prompt
user_name:
  prompt: "What should agents call you?"

# Multi-line prompt
user_skill_level:
  prompt:
    - "What is your development experience level?"
    - "This affects how agents explain concepts in chat."

default

string | boolean

Default value if user accepts the default. Supports:

Literal values: "English", true, false
Variable references: "{directory_name}"
Path templates: "{output_folder}/planning-artifacts"

Examples:

communication_language:
  default: "English"

project_name:
  default: "{directory_name}"

tool_supports_subagents:
  default: true

result

string

required

Template for the final value stored in the configuration. Supports:

{value} - User’s input or selected value
{project-root} - Absolute path to project root
Other variable references: {output_folder}

Examples:

user_name:
  result: "{value}"

output_folder:
  result: "{project-root}/{value}"

planning_artifacts:
  result: "{project-root}/{value}"

Selection Types

Variables can provide predefined options for users to choose from.

single-select

array

Array of options where user selects exactly one. Each option has value and label.Structure:

variable_name:
  prompt: "Choose one option"
  default: "value1"
  result: "{value}"
  single-select:
    - value: "value1"
      label: "First Option - Description"
    - value: "value2"
      label: "Second Option - Description"

Example:

user_skill_level:
  prompt:
    - "What is your development experience level?"
    - "This affects how agents explain concepts in chat."
  default: "intermediate"
  result: "{value}"
  single-select:
    - value: "beginner"
      label: "Beginner - Explain things clearly"
    - value: "intermediate"
      label: "Intermediate - Balance detail with speed"
    - value: "expert"
      label: "Expert - Be direct and technical"

multi-select

array

Array of options where user can select multiple. Same structure as single-select.Note: Multi-select is available but less commonly used. Refer to single-select structure.

Installation Directives

directories

array

List of directories to create during installation. Supports variable interpolation.Example:

directories:
  - "{planning_artifacts}"
  - "{implementation_artifacts}"
  - "{project_knowledge}"

This creates:

/project-root/
├── _bmad-output/
│   ├── planning-artifacts/
│   └── implementation-artifacts/
└── docs/

Variable Interpolation

Configuration values support template variables that are resolved during installation:

Variable	Description	Example Value
`{value}`	User’s input or selection	`"Alex"`, `true`
`{project-root}`	Absolute path to project root	`/home/user/my-project`
`{directory_name}`	Current directory name	`my-project`
`{variable_name}`	Reference to another variable’s value	`{output_folder}` resolves to `_bmad-output`

Resolution Order

Core module variables are resolved first
Module-specific variables are resolved next
Variables can reference previously-defined variables
Path templates are expanded using resolved values

Example chain:

# core/module.yaml
output_folder:
  default: "_bmad-output"
  result: "{project-root}/{value}"
  # Resolves to: /home/user/project/_bmad-output

# bmm/module.yaml  
planning_artifacts:
  default: "{output_folder}/planning-artifacts"
  result: "{project-root}/{value}"
  # Resolves to: /home/user/project/_bmad-output/planning-artifacts

Variable Inheritance

Modules can reference variables defined in the core module:

# bmm/module.yaml
# Variables from Core Config inserted:
## user_name
## communication_language  
## document_output_language
## output_folder

project_name:
  prompt: "What is your project called?"
  default: "{directory_name}"
  result: "{value}"

Core variables are automatically available to all modules without re-prompting the user.

Complete Examples

Core Module Configuration

code: core
name: "BMad Core Module"

header: "BMad Core Configuration"
subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all installed bmad skills, workflows, and agents."

user_name:
  prompt: "What should agents call you? (Use your name or a team name)"
  default: "BMad"
  result: "{value}"

communication_language:
  prompt: "What language should agents use when chatting with you?"
  default: "English"
  result: "{value}"

document_output_language:
  prompt: "Preferred document output language?"
  default: "English"
  result: "{value}"

output_folder:
  prompt: "Where should output files be saved?"
  default: "_bmad-output"
  result: "{project-root}/{value}"

tool_supports_subagents:
  prompt: "Subagents are supported by the LLM or Tool I will be using?"
  default: true
  result: "{value}"

tool_supports_agent_teams:
  prompt: "Agent Teams are supported by the LLM or Tool I will be using?"
  default: false
  result: "{value}"

BMM Module Configuration

code: bmm
name: "BMad Method Agile-AI Driven-Development"
description: "AI-driven agile development framework"
default_selected: true

# Variables from Core Config inserted:
## user_name
## communication_language
## document_output_language
## output_folder

project_name:
  prompt: "What is your project called?"
  default: "{directory_name}"
  result: "{value}"

user_skill_level:
  prompt:
    - "What is your development experience level?"
    - "This affects how agents explain concepts in chat."
  default: "intermediate"
  result: "{value}"
  single-select:
    - value: "beginner"
      label: "Beginner - Explain things clearly"
    - value: "intermediate"
      label: "Intermediate - Balance detail with speed"
    - value: "expert"
      label: "Expert - Be direct and technical"

planning_artifacts:
  prompt: "Where should planning artifacts be stored? (Brainstorming, Briefs, PRDs, UX Designs, Architecture, Epics)"
  default: "{output_folder}/planning-artifacts"
  result: "{project-root}/{value}"

implementation_artifacts:
  prompt: "Where should implementation artifacts be stored? (Sprint status, stories, reviews, retrospectives, Quick Flow output)"
  default: "{output_folder}/implementation-artifacts"
  result: "{project-root}/{value}"

project_knowledge:
  prompt: "Where should long-term project knowledge be stored? (docs, research, references)"
  default: "docs"
  result: "{project-root}/{value}"

directories:
  - "{planning_artifacts}"
  - "{implementation_artifacts}"
  - "{project_knowledge}"

Best Practices

Naming Conventions

Module codes: Short (2-4 chars), lowercase, memorable (bmm, core, tea)
Variable names: Snake_case, descriptive (user_name, planning_artifacts)
Paths: Use underscores or hyphens, avoid spaces

User Experience

Provide sensible defaults - Most users should be able to accept defaults
Use clear prompts - Explain what the setting affects
Group related settings - Use headers and subheaders
Avoid redundancy - Reference core variables instead of re-prompting

Path Management

Use relative paths in defaults - Let users customize the base
Always resolve with project-root - Ensures absolute paths in manifest
Create directories declaratively - Use directories array

Variable Dependencies

Define base paths first - output_folder before planning_artifacts
Reference existing variables - "{output_folder}/planning-artifacts"
Document inherited variables - Add comments showing core variables

Validation

The installer validates configuration files during installation:

Required fields: code, name
Variable references must resolve
Directory paths must be valid
Selection options must include the default value

Validation errors are displayed with clear messages during installation.

API Reference

Agents

Modules

Configuration File Location

Schema Overview

Module Metadata

code

name

description

default_selected

Header Configuration

header

subheader

Variable Definitions

Variable Structure

Variable Properties

Selection Types

single-select

multi-select

Installation Directives

directories

Variable Interpolation

Resolution Order

Variable Inheritance

Complete Examples

Core Module Configuration

BMM Module Configuration

Best Practices

Naming Conventions

User Experience

Path Management

Variable Dependencies

Validation

Build docs developers (and LLMs) love

API Reference

Agents

Modules

​Configuration File Location

​Schema Overview

​Module Metadata

​code

​name

​description

​default_selected

​Header Configuration

​header

​subheader

​Variable Definitions

​Variable Structure

​Variable Properties

​Selection Types

​single-select

​multi-select

​Installation Directives

​directories

​Variable Interpolation

​Resolution Order

​Variable Inheritance

​Complete Examples

​Core Module Configuration

​BMM Module Configuration

​Best Practices

​Naming Conventions

​User Experience

​Path Management

​Variable Dependencies

​Validation

Build docs developers (and LLMs) love

Configuration File Location

Schema Overview

Module Metadata

code

name

description

default_selected

Header Configuration

header

subheader

Variable Definitions

Variable Structure

Variable Properties

Selection Types

single-select

multi-select

Installation Directives

directories

Variable Interpolation

Resolution Order

Variable Inheritance

Complete Examples

Core Module Configuration

BMM Module Configuration

Best Practices

Naming Conventions

User Experience

Path Management

Variable Dependencies

Validation