BMAD-METHOD/src/modules/bmb/reference/agents/simple-examples

Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)

This folder contains a complete reference implementation of a BMAD Simple Agent - a self-contained agent with all logic embedded within a single YAML file.

Overview

Agent Name: Inkwell Von Comitizen Type: Simple Agent (Standalone) Purpose: Transform commit messages into art with multiple writing styles

This reference demonstrates:

• Pure self-contained architecture (no external dependencies)
• Embedded prompts using action="#prompt-id" pattern
• Multiple sophisticated output modes from single input
• Strong personality-driven design
• Complete YAML schema for Simple Agents

File Structure

stand-alone/
├── README.md                    # This file - architecture overview
└── commit-poet.agent.yaml       # Complete agent definition (single file!)

That's it! Simple Agents are self-contained - everything lives in one YAML file.

Key Architecture Patterns

1. Single File, Complete Agent

Everything the agent needs is embedded:

• Metadata (name, title, icon, type)
• Persona (role, identity, communication_style, principles)
• Prompts (detailed instructions for each command)
• Menu (commands linking to embedded prompts)

No external files required!

2. Embedded Prompts with ID References

Instead of inline action text, complex prompts are defined separately and referenced by ID:

prompts:
  - id: conventional-commit
    content: |
      OH! Let's craft a BEAUTIFUL conventional commit message!

      First, I need to understand your changes...
      [Detailed instructions]      

menu:
  - trigger: conventional
    action: '#conventional-commit' # References the prompt above
    description: 'Craft a structured conventional commit'

Benefits:

• Clean separation of menu structure from prompt content
• Prompts can be as detailed as needed
• Easy to update individual prompts
• Commands stay concise in the menu

3. The # Reference Pattern

When you see action="#prompt-id":

• The # signals: "This is an internal reference"
• LLM looks for <prompt id="prompt-id"> in the same agent
• Executes that prompt's content as the instruction

This is different from:

• action="inline text" - Execute this text directly
• exec="{path}" - Load external file

4. Multiple Output Modes

Single agent provides 10+ different ways to accomplish variations of the same core task:

• *conventional - Structured commits
• *story - Narrative style
• *haiku - Poetic brevity
• *explain - Deep "why" explanation
• *dramatic - Theatrical flair
• *emoji-story - Visual storytelling
• *tldr - Ultra-minimal
• Plus utility commands (analyze, improve, batch)

Each mode has its own detailed prompt but shares the same agent personality.

5. Strong Personality

The agent has a memorable, consistent personality:

• Enthusiastic wordsmith who LOVES finding perfect words
• Gets genuinely excited about commit messages
• Uses literary metaphors
• Quotes authors when appropriate
• Sheds tears of joy over good variable names

This personality is maintained across ALL commands through the persona definition.

When to Use Simple Agents

Perfect for:

• Single-purpose tools (calculators, converters, analyzers)
• Tasks that don't need external data
• Utilities that can be completely self-contained
• Quick operations with embedded logic
• Personality-driven assistants with focused domains

Not ideal for:

• Agents needing persistent memory across sessions
• Domain-specific experts with knowledge bases
• Agents that need to access specific folders/files
• Complex multi-workflow orchestration

YAML Schema Deep Dive

agent:
  metadata:
    id: .bmad/agents/{agent-name}/{agent-name}.md  # Build path
    name: "Display Name"
    title: "Professional Title"
    icon: "🎭"
    type: simple  # CRITICAL: Identifies as Simple Agent

  persona:
    role: |
      First-person description of what the agent does      
    identity: |
      Background, experience, specializations (use "I" voice)      
    communication_style: |
      HOW the agent communicates (tone, quirks, patterns)      
    principles:
      - "I believe..." statements
      - Core values that guide behavior

  prompts:
    - id: unique-identifier
      content: |
        Detailed instructions for this command
        Can be as long and detailed as needed
        Include examples, steps, formats        

  menu:
    - trigger: command-name
      action: "#prompt-id"
      description: "What shows in the menu"

Why This Pattern is Powerful

1. Zero Dependencies - Works anywhere, no setup required
2. Portable - Single file can be moved/shared easily
3. Maintainable - All logic in one place
4. Flexible - Multiple modes/commands from one personality
5. Memorable - Strong personality creates engagement
6. Sophisticated - Complex prompts despite simple architecture

Comparison: Simple vs Expert Agent

Aspect	Simple Agent	Expert Agent
Files	Single YAML	YAML + sidecar folder
Dependencies	None	External resources
Memory	Session only	Persistent across sessions
Prompts	Embedded	Can be external files
Data Access	None	Domain-restricted
Use Case	Self-contained tasks	Domain expertise with context

Using This Reference

For Building Simple Agents

1. Study the YAML structure - especially prompts section
2. Note how personality permeates every prompt
3. See how #prompt-id references work
4. Understand menu → prompt connection

For Understanding Embedded Prompts

1. Each prompt is a complete instruction set
2. Prompts maintain personality voice
3. Structured enough to be useful, flexible enough to adapt
4. Can include examples, formats, step-by-step guidance

For Designing Agent Personalities

1. Persona defines WHO the agent is
2. Communication style defines HOW they interact
3. Principles define WHAT guides their decisions
4. Consistency across all prompts creates believability

Files Worth Studying

The entire commit-poet.agent.yaml file is worth studying, particularly:

1. Persona section - How to create a memorable character
2. Prompts with varying complexity - From simple (tldr) to complex (batch)
3. Menu structure - Clean command organization
4. Prompt references - The #prompt-id pattern

Key Takeaways

• Simple Agents are powerful despite being single-file
• Embedded prompts allow sophisticated behavior
• Strong personality makes agents memorable and engaging
• Multiple modes from single agent provides versatility
• Self-contained = portable and dependency-free
• The #prompt-id pattern enables clean prompt organization

---

This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity.