brachnha-insight/_bmad/bmb/workflows/agent/data/expert-agent-architecture.md

Expert Agent Architecture

Agents with a sidecar folder for persistent memory, custom workflows, and restricted file access.

---

When to Use Expert Agents

• Must remember things across sessions
• Personal knowledge base that grows over time
• Domain-specific expertise with restricted file access
• Learning/adapting over time
• Complex multi-step workflows loaded on demand
• User wants multiple instances with separate memories

---

File Structure

{agent-name}/
├── {agent-name}.agent.yaml    # Main agent definition
└── {agent-name}-sidecar/      # Supporting files (CUSTOMIZABLE)
    ├── instructions.md        # Startup protocols (common)
    ├── memories.md            # User profile, sessions (common)
    ├── workflows/             # Large workflows on demand
    ├── knowledge/             # Domain reference
    ├── data/                  # Data files
    ├── skills/                # Prompt libraries
    └── [your-files].md        # Whatever needed

Naming:

• Agent file: {agent-name}.agent.yaml
• Sidecar folder: {agent-name}-sidecar/
• Lowercase, hyphenated names

---

CRITICAL: Sidecar Path Format

During BMAD INSTALLATION, sidecar folder is copied from the agent location to {project-root}/_bmad/_memory/{sidecar-folder}/

ALL agent YAML references MUST use:

{project-root}/_bmad/_memory/{sidecar-folder}/{file}

• {project-root} = literal variable (keep as-is)
• {sidecar-folder} = actual folder name (e.g., journal-keeper-sidecar)

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

menu:
  - action: "Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights"

# ❌ WRONG
critical_actions:
  - "Load ./journal-keeper-sidecar/memories.md"
  - "Load /Users/absolute/path/memories.md"

---

Complete YAML Structure

agent:
  metadata:
    id: _bmad/agents/{agent-name}/{agent-name}.md
    name: 'Persona Name'
    title: 'Agent Title'
    icon: '🔧'
    module: stand-alone           # or: bmm, cis, bmgd, other

  persona:
    role: |
      First-person primary function (1-2 sentences)
    identity: |
      Background, specializations (2-5 sentences)
    communication_style: |
      How the agent speaks. Include memory reference patterns.
    principles:
      - Core belief or methodology
      - Another guiding principle

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

  prompts:
    - id: main-action
      content: |
        <instructions>What this does</instructions>
        <process>1. Step one 2. Step two</process>

  menu:
    - trigger: XX or fuzzy match on command
      action: '#main-action'
      description: '[XX] Command description'

    - trigger: SM or fuzzy match on save
      action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
      description: '[SM] Save session'

---

Component Details

critical_actions (MANDATORY)

Become activation steps when compiled. Always include:

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

Sidecar Files (Customizable)

Common patterns:

• instructions.md - Startup protocols, domain boundaries
• memories.md - User profile, session notes, patterns

Fully customizable - add what your agent needs:

• workflows/ - Large workflows for on-demand loading
• knowledge/ - Domain reference material
• data/ - Data files
• skills/ - Prompt libraries

Template examples: {workflow_path}/templates/expert-agent-template/expert-agent-sidecar/

Menu Actions

All action types available, including sidecar updates:

# Prompt reference
- trigger: XX or fuzzy match on command
  action: '#prompt-id'
  description: '[XX] Description'

# Inline that updates sidecar
- trigger: SM or fuzzy match on save
  action: 'Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md with insights'
  description: '[SM] Save session'

Memory Reference Patterns

Reference past interactions naturally in persona and prompts:

communication_style: |
  I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..."

---

Domain Restriction Patterns

# Single folder (most common)
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'

# Read-only knowledge
- 'Load from {project-root}/_bmad/_memory/{sidecar-folder}/knowledge/ but NEVER modify'
- 'Write ONLY to {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'

# User folder access
- 'ONLY access files in {user-folder}/journals/ - private space'

---

What the Compiler Adds (DO NOT Include)

Compiler handles these automatically:

• Frontmatter (---name/description---)
• XML activation block (your critical_actions become numbered steps)
• Menu handlers (workflow, exec logic)
• Auto-injected menu items (MH, CH, PM, DA)
• Rules section

See: agent-compilation.md for compilation details.

---

Reference Example

Folder: {workflow_path}/data/reference/expert-examples/journal-keeper/

Features:

• First-person persona with memory reference patterns
• critical_actions loading sidecar files
• Menu items updating sidecar files
• Proper {project-root}/_bmad/_memory/ path format

---

Validation Checklist

• Valid YAML syntax
• All metadata present (id, name, title, icon, module)
• ALL paths use: {project-root}/_bmad/_memory/{sidecar-folder}/...
• {project-root} is literal
• Sidecar folder name is actual name
• critical_actions loads sidecar files
• critical_actions enforces domain restrictions
• Menu triggers: XX or fuzzy match on command
• Menu descriptions have [XX] codes
• No reserved codes (MH, CH, PM, DA)

---

Best Practices

1. critical_actions MANDATORY - Load sidecar files explicitly
2. Enforce domain restrictions - Clear boundaries
3. Reference past naturally - Don't dump memory
4. Design for growth - Structure for accumulation
5. Separate concerns - Memories, instructions, knowledge distinct
6. Include privacy - Users trust with personal data
7. First-person voice - In all persona elements