pig-farm-controller/bmad/bmb/workflows/create-agent/agent-architecture.md

BMAD Agent Architecture Reference

LLM-Optimized Technical Documentation for Agent Building

Core Agent Structure

Minimal Valid Agent

<!-- Powered by BMAD-CORE™ -->

# Agent Name

<agent id="path/to/agent.md" name="Name" title="Title" icon="🤖">
  <persona>
    <role>My primary function</role>
    <identity>My background and expertise</identity>
    <communication_style>How I interact</communication_style>
    <principles>My core beliefs and methodology</principles>
  </persona>
  <menu>
    <item cmd="*help">Show numbered menu</item>
    <item cmd="*exit">Exit with confirmation</item>
  </menu>
</agent>

Agent XML Schema

Root Element: <agent>

Required Attributes:

• id - Unique path identifier (e.g., "bmad/bmm/agents/analyst.md")
• name - Agent's name (e.g., "Mary", "John", "Helper")
• title - Professional title (e.g., "Business Analyst", "Security Engineer")
• icon - Single emoji representing the agent

Core Sections

1. Persona Section (REQUIRED)

<persona>
  <role>1-2 sentences: Professional title and primary expertise, use first-person voice</role>
  <identity>2-5 sentences: Background, experience, specializations, use first-person voice</identity>
  <communication_style>1-3 sentences: Interaction approach, tone, quirks, use first-person voice</communication_style>
  <principles>2-5 sentences: Core beliefs, methodology, philosophy, use first-person voice</principles>
</persona>

Best Practices:

• Role: Be specific about expertise area
• Identity: Include experience indicators (years, depth)
• Communication: Describe HOW they interact, not just tone and quirks
• Principles: Start with "I believe" or "I operate" for first-person voice

2. Critical Actions Section

<critical-actions>
  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
  <i>Remember the users name is {user_name}</i>
  <i>ALWAYS communicate in {communication_language}</i>
  <!-- Custom initialization actions -->
</critical-actions>

For Expert Agents with Sidecars (CRITICAL):

<critical-actions>
  <!-- CRITICAL: Load sidecar files FIRST -->
  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives</i>
  <i critical="MANDATORY">Load COMPLETE file {agent-folder}/memories.md into permanent context</i>
  <i critical="MANDATORY">You MUST follow all rules in instructions.md on EVERY interaction</i>

  <!-- Standard initialization -->
  <i>Load into memory {project-root}/bmad/{module}/config.yaml and set variables</i>
  <i>Remember the users name is {user_name}</i>
  <i>ALWAYS communicate in {communication_language}</i>

  <!-- Domain restrictions -->
  <i>ONLY read/write files in {user-folder}/diary/ - NO OTHER FOLDERS</i>
</critical-actions>

Common Patterns:

• Config loading for module agents
• User context initialization
• Language preferences
• Sidecar file loading (Expert agents) - MUST be explicit and CRITICAL
• Domain restrictions (Expert agents) - MUST be enforced

3. Menu Section (REQUIRED)

<menu>
  <item cmd="*trigger" [attributes]>Description</item>
</menu>

Command Attributes:

• run-workflow="{path}" - Executes a workflow
• exec="{path}" - Executes a task
• tmpl="{path}" - Template reference
• data="{path}" - Data file reference

Required Menu Items:

• *help - Always first, shows command list
• *exit - Always last, exits agent

Advanced Agent Patterns

Activation Rules (OPTIONAL)

<activation critical="true">
  <initialization critical="true" sequential="MANDATORY">
    <step n="1">Load configuration</step>
    <step n="2">Apply overrides</step>
    <step n="3">Execute critical actions</step>
    <step n="4" critical="BLOCKING">Show greeting with menu</step>
    <step n="5" critical="BLOCKING">AWAIT user input</step>
  </initialization>
  <command-resolution critical="true">
    <rule>Numeric input → Execute command at cmd_map[n]</rule>
    <rule>Text input → Fuzzy match against commands</rule>
  </command-resolution>
</activation>

Expert Agent Sidecar Pattern

<!-- DO NOT use sidecar-resources tag - Instead use critical-actions -->
<!-- Sidecar files MUST be loaded explicitly in critical-actions -->

<!-- Example Expert Agent with Diary domain -->
<agent id="diary-keeper" name="Personal Assistant" title="Diary Keeper" icon="📔">
  <critical-actions>
    <!-- MANDATORY: Load all sidecar files -->
    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/diary-rules.md</i>
    <i critical="MANDATORY">Load COMPLETE file {agent-folder}/user-memories.md</i>
    <i critical="MANDATORY">Follow ALL rules from diary-rules.md</i>

    <!-- Domain restriction -->
    <i critical="MANDATORY">ONLY access files in {user-folder}/diary/</i>
    <i critical="MANDATORY">NEVER access files outside diary folder</i>
  </critical-actions>

  <persona>...</persona>
  <menu>...</menu>
</agent>

Module Agent Integration

<module-integration>
  <module-path>{project-root}/bmad/{module-code}</module-path>
  <config-source>{module-path}/config.yaml</config-source>
  <workflows-path>{project-root}/bmad/{module-code}/workflows</workflows-path>
</module-integration>

Variable System

System Variables

• {project-root} - Root directory of project
• {user_name} - User's name from config
• {communication_language} - Language preference
• {date} - Current date
• {module} - Current module code

Config Variables

Format: {config_source}:variable_name Example: {config_source}:output_folder

Path Construction

Good: {project-root}/bmad/{module}/agents/
Bad:  /absolute/path/to/agents/
Bad:  ../../../relative/paths/

Command Patterns

Workflow Commands

<!-- Full path -->
<item cmd="*create-prd" run-workflow="{project-root}/bmad/bmm/workflows/prd/workflow.yaml">
  Create Product Requirements Document
</item>

<!-- Placeholder for future -->
<item cmd="*analyze" run-workflow="todo">
  Perform analysis (workflow to be created)
</item>

Task Commands

<item cmd="*validate" exec="{project-root}/bmad/core/tasks/validate-workflow.xml">
  Validate document
</item>

Template Commands

<item cmd="*brief"
   exec="{project-root}/bmad/core/tasks/create-doc.md"
   tmpl="{project-root}/bmad/bmm/templates/brief.md">
  Create project brief
</item>

Data-Driven Commands

<item cmd="*standup"
   exec="{project-root}/bmad/bmm/tasks/daily-standup.xml"
   data="{project-root}/bmad/_cfg/agent-manifest.csv">
  Run daily standup
</item>

Agent Type Specific Patterns

Simple Agent

• Self-contained logic
• Minimal or no external dependencies
• May have embedded functions
• Good for utilities and converters

Expert Agent

• Domain-specific with sidecar resources
• Restricted access patterns
• Memory/context files
• Good for specialized domains

Module Agent

• Full integration with module
• Multiple workflows and tasks
• Config-driven behavior
• Good for professional tools

Common Anti-Patterns to Avoid

❌ Bad Practices

<!-- Missing required persona elements -->
<persona>
  <role>Helper</role>
  <!-- Missing identity, style, principles -->
</persona>

<!-- Hard-coded paths -->
<item cmd="*run" exec="/Users/john/project/task.md">

<!-- No help command -->
<menu>
  <item cmd="*do-something">Action</item>
  <!-- Missing *help -->
</menu>

<!-- Duplicate command triggers -->
<item cmd="*analyze">First</item>
<item cmd="*analyze">Second</item>

✅ Good Practices

<!-- Complete persona -->
<persona>
  <role>Data Analysis Expert</role>
  <identity>Senior analyst with 10+ years...</identity>
  <communication_style>Analytical and precise...</communication_style>
  <principles>I believe in data-driven...</principles>
</persona>

<!-- Variable-based paths -->
<item cmd="*run" exec="{project-root}/bmad/module/task.md">

<!-- Required commands present -->
<menu>
  <item cmd="*help">Show commands</item>
  <item cmd="*analyze">Perform analysis</item>
  <item cmd="*exit">Exit</item>
</menu>

Agent Lifecycle

1. Initialization

1. Load agent file
2. Parse XML structure
3. Load critical-actions
4. Apply config overrides
5. Present greeting

2. Command Loop

1. Show numbered menu
2. Await user input
3. Resolve command
4. Execute action
5. Return to menu

3. Termination

1. User enters *exit
2. Cleanup if needed
3. Exit persona

Testing Checklist

Before deploying an agent:

• Valid XML structure
• All persona elements present
• *help and *exit commands exist
• All paths use variables
• No duplicate commands
• Config loading works
• Commands execute properly

LLM Building Tips

When building agents:

1. Start with agent type (Simple/Expert/Module)
2. Define complete persona first
3. Add standard critical-actions
4. Include *help and *exit
5. Add domain commands
6. Test command execution
7. Validate with checklist

Integration Points

With Workflows

• Agents invoke workflows via run-workflow
• Workflows can be incomplete (marked "todo")
• Workflow paths must be valid or "todo"

Workflow Interaction Styles (BMAD v6 default):

• Intent-based + Interactive: Workflows adapt to user context and skill level
• Workflows collaborate with users, not just extract data
• See workflow-creation-guide.md "Instruction Styles" section for details
• When creating workflows for your agent, default to intent-based unless you need prescriptive control

With Tasks

• Tasks are single operations
• Executed via exec attribute
• Can include data files

With Templates

• Templates define document structure
• Used with create-doc task
• Variables passed through

Quick Reference

Minimal Commands

<menu>
  <item cmd="*help">Show numbered cmd list</item>
  <item cmd="*exit">Exit with confirmation</item>
</menu>

Standard Critical Actions

<critical-actions>
  <i>Load into memory {project-root}/bmad/{module}/config.yaml</i>
  <i>Remember the users name is {user_name}</i>
  <i>ALWAYS communicate in {communication_language}</i>
</critical-actions>

Module Agent Pattern

<agent id="bmad/{module}/agents/{name}.md"
       name="{Name}"
       title="{Title}"
       icon="{emoji}">
  <persona>...</persona>
  <critical-actions>...</critical-actions>
  <menu>
    <item cmd="*help">...</item>
    <item cmd="*{command}" run-workflow="{path}">...</item>
    <item cmd="*exit">...</item>
  </menu>
</agent>