brachnha-insight/_bmad/bmb/workflows/module/data/module-yaml-conventions.md

module.yaml Conventions

Purpose: Defines how module.yaml works, including variables, templates, and how they provide context to agents and workflows.

---

Overview

module.yaml is the configuration file for a BMAD module. It:

• Defines module metadata (code, name, description)
• Collects user input via prompts during installation
• Makes those inputs available to agents and workflows as variables
• Specifies which module should be selected by default

---

Frontmatter Fields

Required Fields

code: {module-code}              # kebab-case identifier
name: "Display Name"             # Human-readable name
header: "Brief description"      # One-line summary
subheader: "Additional context"  # More detail
default_selected: false          # Auto-select on install?

default_selected Guidelines

Module Type	default_selected	Example
Core/Primary	true	BMM (agile software delivery)
Specialized	false	CIS (creative innovation), BMGD (game dev)
Experimental	false	New modules in development

---

Variables System

Core Config Variables (Always Available)

These variables are automatically available to ALL modules:

# Variables from Core Config inserted:
## user_name                  # User's name
## communication_language     # Preferred language
## document_output_language    # Output document language
## output_folder             # Default output location

No need to define these — they're injected automatically.

---

Custom Variables

Define custom variables for user input:

variable_name:
  prompt: "Question to ask the user?"
  default: "{default_value}"
  result: "{template_for_final_value}"

Example:

project_name:
  prompt: "What is the title of your project?"
  default: "{directory_name}"
  result: "{value}"

Variable Templates

In prompt and result, you can use templates:

Template	Expands To
{value}	The user's input
{directory_name}	Current directory name
{output_folder}	Output folder from core config
{project-root}	Project root path
{variable_name}	Another variable's value

---

Variable Types

1. Simple Text Input

project_name:
  prompt: "What is the title of your project?"
  default: "{directory_name}"
  result: "{value}"

---

2. Boolean/Flag

enable_feature:
  prompt: "Enable this feature?"
  default: false
  result: "{value}"

---

3. Single Select

skill_level:
  prompt: "What is your experience level?"
  default: "intermediate"
  result: "{value}"
  single-select:
    - value: "beginner"
      label: "Beginner - Explains concepts clearly"
    - value: "intermediate"
      label: "Intermediate - Balanced approach"
    - value: "expert"
      label: "Expert - Direct and technical"

---

4. Multi Select

platforms:
  prompt: "Which platforms do you need?"
  default: ["unity", "unreal"]
  result: "{value}"
  multi-select:
    - value: "unity"
      label: "Unity"
    - value: "unreal"
      label: "Unreal Engine"
    - value: "godot"
      label: "Godot"

---

5. Multi-Line Prompt

complex_variable:
  prompt:
    - "First question?"
    - "Second context?"
    - "Third detail?"
  default: "default_value"
  result: "{value}"

---

6. Required Variable

critical_variable:
  prompt: "Required information:"
  required: true
  result: "{value}"

---

7. Path Variable

artifacts_folder:
  prompt: "Where should artifacts be stored?"
  default: "{output_folder}/artifacts"
  result: "{project-root}/{value}"

---

Variable Inheritance / Aliasing

Create an alias for another variable:

primary_artifacts:
  prompt: "Where should primary artifacts be stored?"
  default: "{output_folder}/artifacts"
  result: "{project-root}/{value}"

# Alias for workflow compatibility
sprint_artifacts:
  inherit: "primary_artifacts"

Now sprint_artifacts and primary_artifacts reference the same value.

---

How Variables Become Available

To Agents

After installation, variables are available in agent frontmatter/context:

# In agent.agent.yaml or workflow execution
{variable_name}  # Expands to the user's configured value

Example: If the user configured project_name: "MyApp", agents can reference {project_name} and it will expand to "MyApp".

To Workflows

Workflows can reference module variables in their step files:

---
outputFile: '{implementation_artifacts}/my-output.md'
---

This expands the implementation_artifacts variable from module.yaml.

---

Real-World Examples

BMM (BMad Method) — Complex Configuration

code: bmm
name: "BMM: BMad Method Agile-AI Driven-Development"
header: "BMad Method™: Breakthrough Method of Agile-Ai Driven-Dev"
subheader: "Agent and Workflow Configuration for this module"
default_selected: true

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

project_name:
  prompt: "What is the title of your project?"
  default: "{directory_name}"
  result: "{value}"

user_skill_level:
  prompt:
    - "What is your development experience level?"
    - "This affects how agents explain concepts."
  default: "intermediate"
  result: "{value}"
  single-select:
    - value: "beginner"
      label: "Beginner - Explain concepts clearly"
    - value: "intermediate"
      label: "Intermediate - Balanced approach"
    - value: "expert"
      label: "Expert - Direct and technical"

planning_artifacts:
  prompt: "Where should planning artifacts be stored?"
  default: "{output_folder}/planning-artifacts"
  result: "{project-root}/{value}"

implementation_artifacts:
  prompt: "Where should implementation artifacts be stored?"
  default: "{output_folder}/implementation-artifacts"
  result: "{project-root}/{value}"

project_knowledge:
  prompt: "Where should project knowledge be stored?"
  default: "docs"
  result: "{project-root}/{value}"

tea_use_mcp_enhancements:
  prompt: "Enable MCP enhancements in Test Architect?"
  default: false
  result: "{value}"

---

CIS (Creative Innovation Suite) — Minimal Configuration

code: cis
name: "CIS: Creative Innovation Suite"
header: "Creative Innovation Suite (CIS) Module"
subheader: "No custom configuration - uses Core settings only"
default_selected: false

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

Some modules don't need custom variables — core config is enough!

---

BMGD (Game Development) — Multi-Select Example

code: bmgd
name: "BMGD: BMad Game Development"
header: "BMad Game Development Module"
subheader: "Configure game development settings"
default_selected: false

project_name:
  prompt: "What is the name of your game project?"
  default: "{directory_name}"
  result: "{value}"

primary_platform:
  prompt: "Which game engine do you use?"
  default: ["unity", "unreal"]
  required: true
  result: "{value}"
  multi-select:
    - value: "unity"
      label: "Unity"
    - value: "unreal"
      label: "Unreal Engine"
    - value: "godot"
      label: "Godot"
    - value: "other"
      label: "Custom / Other"

---

Best Practices

DO:

• Keep prompts clear and concise
• Provide sensible defaults
• Use result: "{project-root}/{value}" for paths
• Use single/multi-select for structured choices
• Group related variables logically

DON'T:

• Overwhelm users with too many questions
• Ask for information that could be inferred
• Use technical jargon in prompts
• Create variables that are never used

---

Variable Naming

• kebab-case (e.g., planning_artifacts, user_skill_level)
• Descriptive but concise
• Avoid conflicts with core variables

---

Testing Your module.yaml

After creating module.yaml, test it:

1. Run bmad install in a test project
2. Verify prompts appear correctly
3. Check that variables expand in agents/workflows
4. Test default values
5. Validate path templates resolve correctly

---

Quick Reference

Pattern	Use Case
Simple text input	Names, titles, descriptions
Boolean/Flag	Enable/disable features
Single select	Experience levels, categories
Multi select	Platforms, frameworks, options
Multi-line prompt	Complex questions needing context
Required	Must-have information
Path variable	Directory locations
Inherit/Alias	Compatibility, references