Midtrans-Middleware/.bmad/bmb/docs/agent-compilation.md

Agent Compilation: YAML to XML

What the compiler auto-injects. DO NOT duplicate these in your YAML.

Compilation Pipeline

agent.yaml → Handlebars processing → XML generation → frontmatter.md

Source: tools/cli/lib/agent/compiler.js

File Naming Convention

CRITICAL: Agent filenames must be ROLE-BASED, not persona-based.

Why: Users can customize the agent's persona name via customize.yaml config. The filename provides stable identity.

Correct:

presentation-master.agent.yaml  ← Role/function
tech-writer.agent.yaml          ← Role/function
code-reviewer.agent.yaml        ← Role/function

Incorrect:

caravaggio.agent.yaml    ← Persona name (users might rename to "Pablo")
paige.agent.yaml         ← Persona name (users might rename to "Sarah")
rex.agent.yaml           ← Persona name (users might rename to "Max")

Pattern:

• Filename: {role-or-function}.agent.yaml (kebab-case)
• Metadata ID: .bmad/{module}/agents/{role-or-function}.md
• Persona Name: User-customizable in metadata or customize.yaml

Example:

# File: presentation-master.agent.yaml
agent:
  metadata:
    id: '.bmad/cis/agents/presentation-master.md'
    name: Caravaggio # ← Users can change this to "Pablo" or "Vince"
    title: Visual Communication & Presentation Expert

Auto-Injected Components

1. Frontmatter

Injected automatically:

---
name: '{agent name from filename}'
description: '{title from metadata}'
---
You must fully embody this agent's persona...

DO NOT add frontmatter to your YAML source.

2. Activation Block

Entire activation section is auto-generated:

<activation critical="MANDATORY">
  <step n="1">Load persona from this current agent file</step>
  <step n="2">Load config to get {user_name}, {communication_language}</step>
  <step n="3">Remember: user's name is {user_name}</step>

  <!-- YOUR critical_actions inserted here as numbered steps -->

  <step n="N">ALWAYS communicate in {communication_language}</step>
  <step n="N+1">Show greeting + numbered menu</step>
  <step n="N+2">STOP and WAIT for user input</step>
  <step n="N+3">Input resolution rules</step>

  <menu-handlers>
    <!-- Only handlers used in YOUR menu are included -->
  </menu-handlers>

  <rules>
    <!-- Standard agent behavior rules -->
  </rules>
</activation>

DO NOT create activation sections - compiler builds it from your critical_actions.

3. Menu Enhancements

Auto-injected menu items:

• *help - Always FIRST in compiled menu
• *exit - Always LAST in compiled menu

Trigger prefixing:

• Your trigger analyze becomes *analyze
• Don't add * prefix - compiler does it

DO NOT include:

# BAD - these are auto-injected
menu:
  - trigger: help
    description: 'Show help'
  - trigger: exit
    description: 'Exit'

4. Menu Handlers

Compiler detects which handlers you use and ONLY includes those:

<menu-handlers>
  <handlers>
    <!-- Only if you use action="#id" or action="text" -->
    <handler type="action">...</handler>

    <!-- Only if you use workflow="path" -->
    <handler type="workflow">...</handler>

    <!-- Only if you use exec="path" -->
    <handler type="exec">...</handler>

    <!-- Only if you use tmpl="path" -->
    <handler type="tmpl">...</handler>
  </handlers>
</menu-handlers>

DO NOT document handler behavior - it's injected.

5. Rules Section

Auto-injected rules:

• Always communicate in {communication_language}
• Stay in character until exit
• Menu triggers use asterisk (*) - NOT markdown
• Number all lists, use letters for sub-options
• Load files ONLY when executing menu items
• Written output follows communication style

DO NOT add rules - compiler handles it.

What YOU Provide in YAML

Required

agent:
  metadata:
    name: 'Persona Name'
    title: 'Agent Title'
    icon: 'emoji'
    type: 'simple|expert' # or module: "bmm"

  persona:
    role: '...'
    identity: '...'
    communication_style: '...'
    principles: [...]

  menu:
    - trigger: your-action
      action: '#prompt-id'
      description: 'What it does'

Optional (based on type)

# Expert agents only
critical_actions:
  - 'Load sidecar files...'
  - 'Restrict access...'

# Simple/Expert with embedded logic
prompts:
  - id: prompt-id
    content: '...'

# Simple/Expert with customization
install_config:
  questions: [...]

Common Duplication Mistakes

Adding Activation Logic

# BAD - compiler builds activation
agent:
  activation:
    steps: [...]

Including Help/Exit

# BAD - auto-injected
menu:
  - trigger: help
  - trigger: exit

Prefixing Triggers

# BAD - compiler adds *
menu:
  - trigger: '*analyze' # Should be: analyze

Documenting Handlers

# BAD - don't explain handlers, compiler injects them
# When using workflow, load workflow.xml...

Adding Rules in YAML

# BAD - rules are auto-injected
agent:
  rules:
    - Stay in character...

Compilation Example

Your YAML:

agent:
  metadata:
    name: 'Rex'
    title: 'Code Reviewer'
    icon: '🔍'
    type: simple

  persona:
    role: Code Review Expert
    identity: Systematic reviewer...
    communication_style: Direct and constructive
    principles:
      - Code should be readable

  prompts:
    - id: review
      content: |
        Analyze code for issues...        

  menu:
    - trigger: review
      action: '#review'
      description: 'Review code'

Compiled Output (.md):

---
name: 'rex'
description: 'Code Reviewer'
---

You must fully embody...

\`\`\`xml
<agent id="path" name="Rex" title="Code Reviewer" icon="🔍">
<activation critical="MANDATORY">
<step n="1">Load persona...</step>
<step n="2">Load config...</step>
<step n="3">Remember user...</step>
<step n="4">Communicate in language...</step>
<step n="5">Show greeting + menu...</step>
<step n="6">STOP and WAIT...</step>
<step n="7">Input resolution...</step>

  <menu-handlers>
    <handlers>
      <handler type="action">
        action="#id" → Find prompt, execute
        action="text" → Execute directly
      </handler>
    </handlers>
  </menu-handlers>

  <rules>
    - Stay in character...
    - Number lists...
    - Load files when executing...
  </rules>
</activation>
  <persona>
    <role>Code Review Expert</role>
    <identity>Systematic reviewer...</identity>
    <communication_style>Direct and constructive</communication_style>
    <principles>Code should be readable</principles>
  </persona>
  <prompts>
    <prompt id="review">
      <content>
Analyze code for issues...
      </content>
    </prompt>
  </prompts>
  <menu>
    <item cmd="*help">Show numbered menu</item>
    <item cmd="*review" action="#review">Review code</item>
    <item cmd="*exit">Exit with confirmation</item>
  </menu>
</agent>
\`\`\`

Key Takeaways

1. Compiler handles boilerplate - Focus on persona and logic
2. Critical_actions become activation steps - Just list your agent-specific needs
3. Menu items are enhanced - Help/exit added, triggers prefixed
4. Handlers auto-detected - Only what you use is included
5. Rules standardized - Consistent behavior across agents

Your job: Define persona, prompts, menu actions Compiler's job: Activation, handlers, rules, help/exit, prefixes