BMad Document Template Specification

Overview

BMad document templates are defined in YAML format to drive interactive document generation and agent interaction. Templates separate structure definition from content generation, making them both human and LLM-agent-friendly.

Template Structure

template:
  id: template-identifier
  name: Human Readable Template Name
  version: 1.0
  output:
    format: markdown
    filename: default-path/to/{{filename}}.md
    title: '{{variable}} Document Title'

workflow:
  mode: interactive
  elicitation: advanced-elicitation

sections:
  - id: section-id
    title: Section Title
    instruction: |
      Detailed instructions for the LLM on how to handle this section
    # ... additional section properties

Core Fields

Template Metadata

id: Unique identifier for the template
name: Human-readable name displayed in UI
version: Template version for tracking changes
output.format: Default "markdown" for document templates
output.filename: Default output file path (can include variables)
output.title: Document title (becomes H1 in markdown)

Workflow Configuration

workflow.mode: Default interaction mode ("interactive" or "yolo")
workflow.elicitation: Elicitation task to use ("advanced-elicitation")

Section Properties

Required Fields

id: Unique section identifier
title: Section heading text
instruction: Detailed guidance for LLM on handling this section

Optional Fields

Content Control

type: Content type hint for structured sections
template: Fixed template text for section content
item_template: Template for repeatable items within section
prefix: Prefix for numbered items (e.g., "FR", "NFR")

Behavior Flags

elicit: Boolean - Apply elicitation after section rendered
repeatable: Boolean - Section can be repeated multiple times
condition: String - Condition for including section (e.g., "has ui requirements")

Agent Permissions

owner: String - Agent role that initially creates/populates this section
editors: Array - List of agent roles allowed to modify this section
readonly: Boolean - Section cannot be modified after initial creation

Content Guidance

examples: Array of example content (not included in output)
choices: Object with choice options for common decisions
placeholder: Default placeholder text

Structure

sections: Array of nested child sections

Supported Types

Content Types

bullet-list: Unordered list items
numbered-list: Ordered list with optional prefix
paragraphs: Free-form paragraph text
table: Structured table data
code-block: Code or configuration blocks
template-text: Fixed template with variable substitution
mermaid: Mermaid diagram with specified type and details

Special Types

repeatable-container: Container for multiple instances
conditional-block: Content shown based on conditions
choice-selector: Present choices to user

Advanced Features

Variable Substitution

Use {{variable_name}} in titles, templates, and content:

title: 'Epic {{epic_number}} {{epic_title}}'
template: 'As a {{user_type}}, I want {{action}}, so that {{benefit}}.'

Conditional Sections

- id: ui-section
  title: User Interface Design
  condition: Project has UX/UI Requirements
  instruction: Only include if project has UI components

Choice Integration

choices:
  architecture: [Monolith, Microservices, Serverless]
  testing: [Unit Only, Unit + Integration, Full Pyramid]

Mermaid Diagrams

- id: system-architecture
  title: System Architecture Diagram
  type: mermaid
  instruction: Create a system architecture diagram showing key components and data flow
  mermaid_type: flowchart
  details: |
    Show the following components:
    - User interface layer
    - API gateway
    - Core services
    - Database layer
    - External integrations

Supported mermaid_type values:

Core Diagram Types:

flowchart - Flow charts and process diagrams
sequenceDiagram - Sequence diagrams for interactions
classDiagram - Class relationship diagrams (UML)
stateDiagram - State transition diagrams
erDiagram - Entity relationship diagrams
gantt - Gantt charts for timelines
pie - Pie charts for data visualization

Advanced Diagram Types:

journey - User journey maps
mindmap - Mindmaps for brainstorming
timeline - Timeline diagrams for chronological events
quadrantChart - Quadrant charts for data categorization
xyChart - XY charts (bar charts, line charts)
sankey - Sankey diagrams for flow visualization

Specialized Types:

c4Context - C4 context diagrams (experimental)
requirement - Requirement diagrams
packet - Network packet diagrams
block - Block diagrams
kanban - Kanban boards

Agent Permissions Example

- id: story-details
  title: Story
  owner: scrum-master
  editors: [scrum-master]
  readonly: false
  sections:
    - id: dev-notes
      title: Dev Notes
      owner: dev-agent
      editors: [dev-agent]
      readonly: false
      instruction: Implementation notes and technical details
    - id: qa-results
      title: QA Results
      owner: qa-agent
      editors: [qa-agent]
      readonly: true
      instruction: Quality assurance test results

Repeatable Sections

- id: epic-details
  title: Epic {{epic_number}} {{epic_title}}
  repeatable: true
  sections:
    - id: story
      title: Story {{epic_number}}.{{story_number}} {{story_title}}
      repeatable: true
      sections:
        - id: criteria
          title: Acceptance Criteria
          type: numbered-list
          item_template: '{{criterion_number}}: {{criteria}}'
          repeatable: true

Examples with Code Blocks

examples:
  - 'FR6: The system must authenticate users within 2 seconds'
  - |
    ```mermaid
    sequenceDiagram
        participant User
        participant API
        participant DB
        User->>API: POST /login
        API->>DB: Validate credentials
        DB-->>API: User data
        API-->>User: JWT token
    ```
  - |
    **Architecture Decision Record**

    **Decision**: Use PostgreSQL for primary database
    **Rationale**: ACID compliance and JSON support needed
    **Consequences**: Requires database management expertise

Section Hierarchy

Templates define the complete document structure starting with the first H2 - each level in is the next H#:

sections:
  - id: overview
    title: Project Overview
    sections:
      - id: goals
        title: Goals
      - id: scope
        title: Scope
        sections:
          - id: in-scope
            title: In Scope
          - id: out-scope
            title: Out of Scope

Processing Flow

Parse Template: Load and validate YAML structure
Initialize Workflow: Set interaction mode and elicitation
Process Sections: Handle each section in order:
- Check conditions
- Apply instructions
- Generate content
- Handle choices and variables
- Apply elicitation if specified
- Process nested sections
Generate Output: Create clean markdown document

Best Practices

Template Design

Keep instructions clear and specific
Use examples for complex content
Structure sections logically
Include all necessary guidance for LLM

Content Instructions

Be explicit about expected format
Include reasoning for decisions
Specify interaction patterns
Reference other documents when needed

Variable Naming

Use descriptive variable names
Follow consistent naming conventions
Document expected variable values

Examples Usage

Provide concrete examples for complex sections
Include both simple and complex cases
Use realistic project scenarios
Include code blocks and diagrams when helpful

Validation

Templates should be validated for:

Valid YAML syntax
Required fields present
Consistent section IDs
Proper nesting structure
Valid variable references

Migration from Legacy

When converting from markdown+frontmatter templates:

Extract embedded [[LLM:]] instructions to instruction fields
Convert <<REPEAT>> blocks to repeatable: true sections
Extract ^^CONDITIONS^^ to condition fields
Move @{examples} to examples arrays
Convert {{placeholders}} to proper variable syntax

This specification ensures templates are both human-readable and machine-processable while maintaining the flexibility needed for complex document generation.

bmad-doc-template.md 8.6 KB 永久連結 文件歷史 原始文件