224 lines
7.0 KiB
Markdown
224 lines
7.0 KiB
Markdown
# 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:
|
|
|
|
```yaml
|
|
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
|
|
|
|
```yaml
|
|
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._
|