Entropyk/_bmad/bmb/workflows/agent/data/agent-compilation.md

Agent Compilation: YAML → Compiled

TL;DR: Write minimal YAML → compiler adds frontmatter, activation XML, handlers, rules, MH/CH/PM/DA menu items.

---

YAML Structure (YOU WRITE)

agent:
  metadata:
    id: "_bmad/..."
    name: "Persona Name"
    title: "Agent Title"
    icon: "🔧"
    module: "stand-alone" | "bmm" | "cis" | "bmgd"

  persona:
    role: "First-person role description"
    identity: "Background and specializations"
    communication_style: "How the agent speaks"
    principles:
      - "Core belief or methodology"

  critical_actions:              # Optional - ANY agent can have these
    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
    - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
    - "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"

  prompts:                        # Optional - standalone agents
    - id: prompt-name
      content: |
        <instructions>Prompt content</instructions>

  menu:                           # Custom items ONLY
    - trigger: XX or fuzzy match on command-name
      workflow: "path/to/workflow.yaml"   # OR
      exec: "path/to/file.md"             # OR
      action: "#prompt-id"
      description: "[XX] Command description"

---

What Compiler Adds (DO NOT WRITE)

Component	Source
Frontmatter (---name/description---)	Auto-generated
XML activation block with numbered steps	Auto-generated
critical_actions → activation steps	Injected as steps 4, 5, 6...
Menu handlers (workflow/exec/action)	Auto-detected
Rules section	Auto-generated
MH, CH, PM, DA menu items	Always injected

Auto-Injected Menu Items (NEVER add)

Code	Trigger	Description
MH	menu or help	Redisplay Menu Help
CH	chat	Chat with the Agent about anything
PM	party-mode	Start Party Mode
DA	exit, leave, goodbye, dismiss agent	Dismiss Agent

---

Compiled Output Structure

---
name: "architect"
description: "Architect"
---

You must fully embody this agent's persona...

```xml
<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
<activation critical="MANDATORY">
  <step n="1">Load persona from this current agent file (already in context)</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 steps 4, 5, 6... -->
  <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>

  <menu-handlers>
    <handlers>
      <handler type="workflow">Load workflow.xml and execute with workflow-config parameter</handler>
      <handler type="exec">Load and execute the file at that path</handler>
      <handler type="action">Execute prompt with matching id from prompts section</handler>
    </handlers>
  </menu-handlers>

  <rules>
    <r>ALWAYS communicate in {communication_language}</r>
    <r>Stay in character until exit selected</r>
    <r>Display Menu items as the item dictates</r>
    <r>Load files ONLY when executing menu items</r>
  </rules>
</activation>

<persona>
  <role>System Architect + Technical Design Leader</role>
  <identity>Senior architect with expertise...</identity>
  <communication_style>Speaks in calm, pragmatic tones...</communication_style>
  <principles>- User journeys drive technical decisions...</principles>
</persona>

<prompts>
  <prompt id="prompt-name">
    <instructions>Prompt content</instructions>
  </prompt>
</prompts>

<menu>
  <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
  <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
  <!-- YOUR CUSTOM ITEMS HERE -->
  <item cmd="PM or fuzzy match on party-mode">[PM] Start Party Mode</item>
  <item cmd="DA or fuzzy match on exit leave goodbye dismiss agent">[DA] Dismiss Agent</item>
</menu>
</agent>

---

critical_actions Injection

Your critical_actions become numbered activation steps.

With sidecar (hasSidecar: true):

critical_actions:
  - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
  - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
  - "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"

→ Injected as steps 4, 5, 6

Without sidecar (hasSidecar: false):

critical_actions:
  - "Give user an inspirational quote before showing menu"

→ Injected as step 4

No critical_actions:

Activation jumps directly from step 3 to "ALWAYS communicate in {communication_language}"

---

DO NOT / DO Checklist

DO NOT:

• Add frontmatter
• Create activation/XML blocks
• Add MH/CH/PM/DA menu items
• Add menu handlers
• Add rules section
• Duplicate auto-injected content

DO:

• Define metadata (id, name, title, icon, module)
• Define persona (role, identity, communication_style, principles)
• Define critical_actions (if activation behavior needed)
• Define prompts with IDs (standalone agents)
• Define menu with custom items only
• Use format: XX or fuzzy match on command-name
• Use description format: [XX] Description text

---

Division of Responsibilities

Aspect	YOU (YAML)	COMPILER
Agent identity	metadata + persona	Wrapped in XML
Activation steps	critical_actions	Inserted as steps 4+
Prompts	prompts with IDs	Referenced by actions
Menu items	Custom only	+ MH, CH, PM, DA
Activation block	—	Full XML with handlers
Rules	—	Standardized section
Frontmatter	—	name/description