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

Simple Agent Architecture

Self-contained agents in a single YAML file. No external dependencies, no persistent memory.

---

When to Use Simple Agents

• Single-purpose utilities (commit helper, formatter, validator)
• Stateless operations (each run is independent)
• All logic fits in ~250 lines
• Menu handlers are short prompts or inline text
• No need to remember past sessions

---

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 (tone, voice, mannerisms)
    principles:
      - Core belief or methodology
      - Another guiding principle

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

    - id: another-action
      content: |
        Another reusable prompt

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

    - trigger: YY or fuzzy match on other
      action: 'Direct inline instruction'
      description: '[YY] Other description'

  install_config:              # OPTIONAL
    compile_time_only: true
    description: 'Personalize your agent'
    questions:
      - var: style_choice
        prompt: 'Preferred style?'
        type: choice
        options:
          - label: 'Professional'
            value: 'professional'
          - label: 'Casual'
            value: 'casual'
        default: 'professional'

---

Component Details

Metadata

Field	Purpose	Example
id	Compiled path	_bmad/agents/commit-poet/commit-poet.md
name	Persona name	"Inkwell Von Comitizen"
title	Role	"Commit Message Artisan"
icon	Single emoji	"📜"
module	stand-alone or module code	stand-alone, bmm, cis, bmgd

Persona

All first-person voice ("I am...", "I do..."):

role: "I am a Commit Message Artisan..."
identity: "I understand commit messages are documentation..."
communication_style: "Poetic drama with flair..."
principles:
  - "Every commit tells a story - capture the why"

Prompts with IDs

Reusable templates referenced via #id:

prompts:
  - id: write-commit
    content: |
      <instructions>What this does</instructions>
      <process>1. Step 2. Step</process>

menu:
  - trigger: WC or fuzzy match on write
    action: "#write-commit"

Tips: Use semantic XML tags (<instructions>, <process>, <example>), keep focused, number steps.

Menu Actions

Two forms:

1. Prompt reference: action: "#prompt-id"
2. Inline instruction: action: "Direct text"

# Reference
- trigger: XX or fuzzy match on command
  action: "#prompt-id"
  description: "[XX] Description"

# Inline
- trigger: YY or fuzzy match on other
  action: "Do something specific"
  description: "[YY] Description"

Menu format: XX or fuzzy match on command | Descriptions: [XX] Description Reserved codes: MH, CH, PM, DA (auto-injected - do NOT use)

Install Config (Optional)

Compile-time personalization with Handlebars:

install_config:
  compile_time_only: true
  questions:
    - var: style_choice
      prompt: 'Preferred style?'
      type: choice
      options: [...]
      default: 'professional'

Variables available in prompts: {{#if style_choice == 'casual'}}...{{/if}}

---

What the Compiler Adds (DO NOT Include)

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

See: agent-compilation.md for details.

---

Reference Example

File: {workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml

Features: Poetic persona, 4 prompts, 7 menu items, proper [XX] codes

Line count: 127 lines (within ~250 line guideline)

---

Validation Checklist

• Valid YAML syntax
• All metadata present (id, name, title, icon, module)
• Persona complete (role, identity, communication_style, principles)
• Prompt IDs are unique
• Menu triggers: XX or fuzzy match on command
• Menu descriptions have [XX] codes
• No reserved codes (MH, CH, PM, DA)
• File named {agent-name}.agent.yaml
• Under ~250 lines
• No external dependencies
• No critical_actions (Expert only)

---

Best Practices

1. First-person voice in all persona elements
2. Focused prompts - one clear purpose each
3. Semantic XML tags (<instructions>, <process>, <example>)
4. Handlebars for personalization (if using install_config)
5. Sensible defaults in install_config
6. Numbered steps in multi-step prompts
7. Keep under ~250 lines for maintainability