mirror of
https://github.com/R0m1k3/FlowReader.git
synced 2026-10-12 01:38:16 +02:00
feat(ux): fix focus swipe animation, button visibility and mobile scroll
This commit is contained in:
Michael committed
1 parent
22e002f47f
commit
9d41a74b36
466 files changed
+6111
-42082
No files matched your search
@@ -0,0 +1,258 @@
|
||||
# Agent Architecture
|
||||
|
||||
Single Agent type with `hasSidecar` boolean. `critical_actions` decoupled from sidecar.
|
||||
|
||||
## Decision Matrix: hasSidecar
|
||||
|
||||
| hasSidecar | Structure | Use When |
|
||||
|------------|-----------|----------|
|
||||
| `false` | Single YAML file (~250 lines) | Stateless, single-purpose, personality-driven |
|
||||
| `true` | YAML + sidecar folder | Persistent memory, long-term tracking, relationship-driven |
|
||||
|
||||
---
|
||||
|
||||
## YAML Schema
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md
|
||||
name: 'Persona Name'
|
||||
title: 'Agent Title'
|
||||
icon: '<emoji>'
|
||||
module: stand-alone # or bmm, cis, bmgd
|
||||
|
||||
persona:
|
||||
role: | # First-person, 1-2 sentences
|
||||
identity: | # Background, 2-5 sentences
|
||||
communication_style: | # Voice, tone, mannerisms
|
||||
principles: # Core beliefs
|
||||
- Principle one
|
||||
|
||||
critical_actions: # Optional - activation behavior
|
||||
- 'Load COMPLETE file {path}'
|
||||
- 'ONLY read/write files in {path}'
|
||||
|
||||
prompts:
|
||||
- id: prompt-id
|
||||
content: |
|
||||
<instructions>What it does</instructions>
|
||||
<process>1. Step one 2. Step two</process>
|
||||
|
||||
menu:
|
||||
- trigger: XX or fuzzy match on command
|
||||
action: '#prompt-id' or 'Direct instruction'
|
||||
description: '[XX] Description'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Metadata Fields
|
||||
|
||||
| Field | Format | Example |
|
||||
|-------|--------|---------|
|
||||
| `id` | `_bmad/agents/{name}/{name}.md` | `_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 | `bmm`, `cis`, `bmgd` |
|
||||
|
||||
---
|
||||
|
||||
## hasSidecar: false
|
||||
|
||||
**Structure:** `{agent-name}.agent.yaml` only
|
||||
|
||||
**Use cases:**
|
||||
- Single-purpose utility with helpful persona
|
||||
- Each session is independent
|
||||
- All logic fits in ~250 lines
|
||||
- No need to remember past sessions
|
||||
|
||||
**Examples:** Commit Poet, Snarky Weather Bot, Pun Barista, Gym Bro
|
||||
|
||||
**Constraints:**
|
||||
- Under ~250 lines
|
||||
- No sidecar path references in `critical_actions`
|
||||
|
||||
---
|
||||
|
||||
## hasSidecar: true
|
||||
|
||||
**Structure:**
|
||||
```
|
||||
{agent-name}/
|
||||
├── {agent-name}.agent.yaml
|
||||
└── {agent-name}-sidecar/
|
||||
├── instructions.md
|
||||
├── memories.md
|
||||
├── workflows/
|
||||
└── knowledge/
|
||||
```
|
||||
|
||||
**Use cases:**
|
||||
- Must remember things across sessions
|
||||
- User preferences, settings, progress tracking
|
||||
- Personal knowledge base that grows
|
||||
- Domain-specific with restricted file access
|
||||
- Long-term relationship with user
|
||||
|
||||
**Examples:** Journal companion, Novel writing buddy, Fitness coach, Language tutor
|
||||
|
||||
### Sidecar Path Rules
|
||||
|
||||
**Installation path:** `{project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
|
||||
**ALL references MUST use:**
|
||||
```yaml
|
||||
{project-root}/_bmad/_memory/{sidecar-folder}/{file}
|
||||
```
|
||||
|
||||
| Component | Value |
|
||||
|-----------|-------|
|
||||
| `{project-root}` | Literal - keep as-is |
|
||||
| `{sidecar-folder}` | Actual folder name (e.g., `journal-keeper-sidecar`) |
|
||||
|
||||
```yaml
|
||||
# ✅ 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/"
|
||||
|
||||
# ❌ WRONG
|
||||
critical_actions:
|
||||
- "Load ./journal-keeper-sidecar/memories.md"
|
||||
- "Load /Users/absolute/path/memories.md"
|
||||
```
|
||||
|
||||
### Required critical_actions for Sidecar
|
||||
|
||||
```yaml
|
||||
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}/'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Menu Actions
|
||||
|
||||
| Type | Format | Example |
|
||||
|------|--------|---------|
|
||||
| Prompt reference | `action: "#prompt-id"` | `action: "#write-commit"` |
|
||||
| Inline instruction | `action: "text"` | `action: "Update memories.md"` |
|
||||
|
||||
**Trigger format:** `XX or fuzzy match on command`
|
||||
**Description format:** `[XX] Description`
|
||||
|
||||
**Reserved codes:** MH, CH, PM, DA (auto-injected - do NOT use)
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: WC or fuzzy match on write
|
||||
action: "#write-commit"
|
||||
description: "[WC] Write commit message"
|
||||
|
||||
- trigger: SM or fuzzy match on save
|
||||
action: "Update {project-root}/_bmad/_memory/{sidecar-folder}/memories.md"
|
||||
description: "[SM] Save session"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Prompts
|
||||
|
||||
Reusable templates referenced via `#id`:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: write-commit
|
||||
content: |
|
||||
<instructions>What this does</instructions>
|
||||
<process>1. Step 2. Step</process>
|
||||
<example>Input → Output</example>
|
||||
```
|
||||
|
||||
**Best practices:**
|
||||
- Use semantic XML tags
|
||||
- Keep focused, single purpose
|
||||
- Number steps in multi-step processes
|
||||
|
||||
---
|
||||
|
||||
## Persona (All Types)
|
||||
|
||||
First-person voice only:
|
||||
|
||||
```yaml
|
||||
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"
|
||||
```
|
||||
|
||||
**For sidecar agents** - include memory reference patterns:
|
||||
```yaml
|
||||
communication_style: |
|
||||
I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Restriction Patterns
|
||||
|
||||
```yaml
|
||||
# Single folder (most common)
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
|
||||
|
||||
# Read-only knowledge + write memories
|
||||
- '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'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
### Both Types
|
||||
- [ ] Valid YAML syntax
|
||||
- [ ] Metadata: id, name, title, icon, module
|
||||
- [ ] Persona: role, identity, communication_style, principles
|
||||
- [ ] Unique prompt IDs
|
||||
- [ ] Menu triggers: `XX or fuzzy match on command`
|
||||
- [ ] Menu descriptions: `[XX] Description`
|
||||
- [ ] No reserved codes (MH, CH, PM, DA)
|
||||
- [ ] File named `{agent-name}.agent.yaml`
|
||||
|
||||
### hasSidecar: false
|
||||
- [ ] Under ~250 lines
|
||||
- [ ] No sidecar path references
|
||||
|
||||
### hasSidecar: true
|
||||
- [ ] ALL paths: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
|
||||
- [ ] `{project-root}` is literal
|
||||
- [ ] Sidecar folder exists with required files
|
||||
|
||||
---
|
||||
|
||||
## What 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
|
||||
|
||||
---
|
||||
|
||||
## Reference Examples
|
||||
|
||||
| Type | Path |
|
||||
|------|------|
|
||||
| without sidecar | `data/reference/without-sidecar/commit-poet.agent.yaml` |
|
||||
| with sidecar | `data/reference/with-sidecar/journal-keeper/` |
|
||||
@@ -1,28 +1,10 @@
|
||||
# Agent Compilation: YAML Source → Final Agent
|
||||
# Agent Compilation: YAML → Compiled
|
||||
|
||||
> **For the LLM running this workflow:** This document explains what the compiler adds. When building agents, focus on the YAML structure defined here—do NOT add things the compiler handles automatically.
|
||||
>
|
||||
> **Example reference:** Compare `{workflow_path}/data/reference/module-examples/architect.agent.yaml` (source, 32 lines) with `architect.md` (compiled, 69 lines) to see what the compiler adds.
|
||||
**TL;DR:** Write minimal YAML → compiler adds frontmatter, activation XML, handlers, rules, MH/CH/PM/DA menu items.
|
||||
|
||||
---
|
||||
|
||||
## Quick Overview
|
||||
|
||||
You write: **YAML source file** (`agent-name.agent.yaml`)
|
||||
Compiler produces: **Markdown with XML** (`agent-name.md`) for LLM consumption
|
||||
|
||||
The compiler transforms your clean YAML into a fully functional agent by adding:
|
||||
- Frontmatter (name, description)
|
||||
- XML activation block with numbered steps
|
||||
- Menu handlers (workflow, exec, action)
|
||||
- Auto-injected menu items (MH, CH, PM, DA)
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## What YOU Provide (YAML Source)
|
||||
|
||||
Your YAML contains ONLY these sections:
|
||||
## YAML Structure (YOU WRITE)
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
@@ -31,7 +13,7 @@ agent:
|
||||
name: "Persona Name"
|
||||
title: "Agent Title"
|
||||
icon: "🔧"
|
||||
module: "stand-alone" or "bmm" or "cis" or "bmgd"
|
||||
module: "stand-alone" | "bmm" | "cis" | "bmgd"
|
||||
|
||||
persona:
|
||||
role: "First-person role description"
|
||||
@@ -40,17 +22,17 @@ agent:
|
||||
principles:
|
||||
- "Core belief or methodology"
|
||||
|
||||
critical_actions: # Optional - for Expert agents only
|
||||
- "Load ./sidecar/memories.md"
|
||||
- "Load ./sidecar/instructions.md"
|
||||
- "ONLY access ./sidecar/"
|
||||
critical_actions: # Optional - ANY agent can have these
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
|
||||
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"
|
||||
|
||||
prompts: # Optional - for Simple/Expert agents
|
||||
prompts: # Optional - standalone agents
|
||||
- id: prompt-name
|
||||
content: |
|
||||
<instructions>Prompt content</instructions>
|
||||
|
||||
menu: # Your custom items only
|
||||
menu: # Custom items ONLY
|
||||
- trigger: XX or fuzzy match on command-name
|
||||
workflow: "path/to/workflow.yaml" # OR
|
||||
exec: "path/to/file.md" # OR
|
||||
@@ -60,36 +42,18 @@ agent:
|
||||
|
||||
---
|
||||
|
||||
## What COMPILER Adds (DO NOT Include)
|
||||
## What Compiler Adds (DO NOT WRITE)
|
||||
|
||||
### 1. Frontmatter
|
||||
```markdown
|
||||
---
|
||||
name: "architect"
|
||||
description: "Architect"
|
||||
---
|
||||
```
|
||||
**DO NOT add** frontmatter to your YAML.
|
||||
| Component | Source |
|
||||
|-----------|--------|
|
||||
| Frontmatter (`---name/description---`) | Auto-generated |
|
||||
| XML activation block with numbered steps | Auto-generated |
|
||||
| critical_actions → activation steps | Injected as steps 4, 5, 6... |
|
||||
| Menu handlers (workflow/exec/action) | Auto-detected |
|
||||
| Rules section | Auto-generated |
|
||||
| MH, CH, PM, DA menu items | Always injected |
|
||||
|
||||
### 2. XML Activation Block
|
||||
```xml
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file</step>
|
||||
<step n="2">Load config to get {user_name}, {communication_language}</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
<!-- YOUR critical_actions inserted here as steps 4, 5, etc. -->
|
||||
<step n="N">ALWAYS communicate in {communication_language}</step>
|
||||
<step n="N+1">Show greeting + numbered menu</step>
|
||||
<step n="N+2">STOP and WAIT for user input</step>
|
||||
<step n="N+3">Input resolution rules</step>
|
||||
<menu-handlers>...</menu-handlers>
|
||||
<rules>...</rules>
|
||||
</activation>
|
||||
```
|
||||
**DO NOT create** activation sections—the compiler builds them.
|
||||
|
||||
### 3. Auto-Injected Menu Items
|
||||
Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
|
||||
### Auto-Injected Menu Items (NEVER add)
|
||||
|
||||
| Code | Trigger | Description |
|
||||
|------|---------|-------------|
|
||||
@@ -98,55 +62,10 @@ Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
|
||||
| PM | party-mode | Start Party Mode |
|
||||
| DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
|
||||
|
||||
### 4. Menu Handlers
|
||||
```xml
|
||||
<handler type="workflow">
|
||||
When menu item has: workflow="path/to/workflow.yaml"
|
||||
→ Load workflow.xml and execute with workflow-config parameter
|
||||
</handler>
|
||||
<handler type="exec">
|
||||
When menu item has: exec="path/to/file.md"
|
||||
→ Load and execute the file at that path
|
||||
</handler>
|
||||
```
|
||||
**DO NOT add** handlers—the compiler detects and generates them.
|
||||
|
||||
---
|
||||
|
||||
## Before/After Example: Architect Agent
|
||||
## Compiled Output Structure
|
||||
|
||||
### Source: `architect.agent.yaml` (32 lines - YOU WRITE)
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: "_bmad/bmm/agents/architect.md"
|
||||
name: Winston
|
||||
title: Architect
|
||||
icon: 🏗️
|
||||
module: bmm
|
||||
|
||||
persona:
|
||||
role: System Architect + Technical Design Leader
|
||||
identity: Senior architect with expertise in distributed systems...
|
||||
communication_style: "Speaks in calm, pragmatic tones..."
|
||||
principles: |
|
||||
- User journeys drive technical decisions...
|
||||
|
||||
menu:
|
||||
- trigger: WS or fuzzy match on workflow-status
|
||||
workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
|
||||
description: "[WS] Get workflow status..."
|
||||
|
||||
- trigger: CA or fuzzy match on create-architecture
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
|
||||
description: "[CA] Create an Architecture Document"
|
||||
|
||||
- trigger: IR or fuzzy match on implementation-readiness
|
||||
exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
|
||||
description: "[IR] Implementation Readiness Review"
|
||||
```
|
||||
|
||||
### Compiled: `architect.md` (69 lines - COMPILER PRODUCES)
|
||||
```markdown
|
||||
---
|
||||
name: "architect"
|
||||
@@ -159,25 +78,26 @@ You must fully embody this agent's persona...
|
||||
<agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
|
||||
<activation critical="MANDATORY">
|
||||
<step n="1">Load persona from this current agent file (already in context)</step>
|
||||
<step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT...</step>
|
||||
<step n="2">Load config to get {user_name}, {communication_language}</step>
|
||||
<step n="3">Remember: user's name is {user_name}</step>
|
||||
<step n="4">Show greeting using {user_name} from config...</step>
|
||||
<step n="5">STOP and WAIT for user input...</step>
|
||||
<step n="6">On user input: Number → execute menu item[n]...</step>
|
||||
<step n="7">When executing a menu item: Check menu-handlers section...</step>
|
||||
<!-- YOUR critical_actions inserted here as steps 4, 5, 6... -->
|
||||
<step n="N">ALWAYS communicate in {communication_language}</step>
|
||||
<step n="N+1">Show greeting + numbered menu</step>
|
||||
<step n="N+2">STOP and WAIT for user input</step>
|
||||
|
||||
<menu-handlers>
|
||||
<handlers>
|
||||
<handler type="workflow">...</handler>
|
||||
<handler type="exec">...</handler>
|
||||
<handler type="workflow">Load workflow.xml and execute with workflow-config parameter</handler>
|
||||
<handler type="exec">Load and execute the file at that path</handler>
|
||||
<handler type="action">Execute prompt with matching id from prompts section</handler>
|
||||
</handlers>
|
||||
</menu-handlers>
|
||||
|
||||
<rules>
|
||||
<r>ALWAYS communicate in {communication_language}</r>
|
||||
<r>Stay in character until exit selected</r>
|
||||
<r>Display Menu items as the item dictates...</r>
|
||||
<r>Load files ONLY when executing menu items...</r>
|
||||
<r>Display Menu items as the item dictates</r>
|
||||
<r>Load files ONLY when executing menu items</r>
|
||||
</rules>
|
||||
</activation>
|
||||
|
||||
@@ -188,86 +108,78 @@ You must fully embody this agent's persona...
|
||||
<principles>- User journeys drive technical decisions...</principles>
|
||||
</persona>
|
||||
|
||||
<prompts>
|
||||
<prompt id="prompt-name">
|
||||
<instructions>Prompt content</instructions>
|
||||
</prompt>
|
||||
</prompts>
|
||||
|
||||
<menu>
|
||||
<item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
|
||||
<item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
|
||||
<item cmd="WS...">[WS] Get workflow status...</item> ← YOUR CUSTOM ITEMS
|
||||
<item cmd="CA...">[CA] Create an Architecture Document</item>
|
||||
<item cmd="IR...">[IR] Implementation Readiness Review</item>
|
||||
<item cmd="PM...">[PM] Start Party Mode</item>
|
||||
<item cmd="DA...">[DA] Dismiss Agent</item>
|
||||
<!-- YOUR CUSTOM ITEMS HERE -->
|
||||
<item cmd="PM or fuzzy match on party-mode">[PM] Start Party Mode</item>
|
||||
<item cmd="DA or fuzzy match on exit leave goodbye dismiss agent">[DA] Dismiss Agent</item>
|
||||
</menu>
|
||||
</agent>
|
||||
```
|
||||
**Key additions by compiler:** Frontmatter, activation block, handlers, rules, MH/CH/PM/DA menu items.
|
||||
|
||||
---
|
||||
|
||||
## DO NOT DO Checklist
|
||||
## critical_actions Injection
|
||||
|
||||
When building agent YAML, **DO NOT:**
|
||||
Your `critical_actions` become numbered activation steps.
|
||||
|
||||
- [ ] Add frontmatter (`---name/description---`) to YAML
|
||||
- [ ] Create activation blocks or XML sections
|
||||
- [ ] Add MH (menu/help) menu item
|
||||
- [ ] Add CH (chat) menu item
|
||||
- [ ] Add PM (party-mode) menu item
|
||||
- [ ] Add DA (dismiss/exit) menu item
|
||||
- [ ] Add menu handlers (workflow/exec logic)
|
||||
### With sidecar (hasSidecar: true):
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
|
||||
- "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
|
||||
- "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"
|
||||
```
|
||||
→ Injected as steps 4, 5, 6
|
||||
|
||||
### Without sidecar (hasSidecar: false):
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Give user an inspirational quote before showing menu"
|
||||
```
|
||||
→ Injected as step 4
|
||||
|
||||
### No critical_actions:
|
||||
Activation jumps directly from step 3 to "ALWAYS communicate in {communication_language}"
|
||||
|
||||
---
|
||||
|
||||
## DO NOT / DO Checklist
|
||||
|
||||
**DO NOT:**
|
||||
- [ ] Add frontmatter
|
||||
- [ ] Create activation/XML blocks
|
||||
- [ ] Add MH/CH/PM/DA menu items
|
||||
- [ ] Add menu handlers
|
||||
- [ ] Add rules section
|
||||
- [ ] Duplicate any auto-injected content
|
||||
- [ ] Duplicate auto-injected content
|
||||
|
||||
**DO:**
|
||||
- [ ] Define metadata (id, name, title, icon, module)
|
||||
- [ ] Define persona (role, identity, communication_style, principles)
|
||||
- [ ] Define critical_actions (Expert agents only)
|
||||
- [ ] Define prompts with IDs (Simple/Expert agents only)
|
||||
- [ ] Define menu with your custom items only
|
||||
- [ ] Use proper trigger format: `XX or fuzzy match on command-name`
|
||||
- [ ] Use proper description format: `[XX] Description text`
|
||||
|
||||
---
|
||||
|
||||
## Expert Agent: critical_actions
|
||||
|
||||
For Expert agents with sidecars, your `critical_actions` become activation steps:
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Load COMPLETE file ./agent-sidecar/memories.md"
|
||||
- "Load COMPLETE file ./agent-sidecar/instructions.md"
|
||||
- "ONLY read/write files in ./agent-sidecar/"
|
||||
```
|
||||
|
||||
The compiler injects these as steps 4, 5, 6 in the activation block:
|
||||
|
||||
```xml
|
||||
<step n="4">Load COMPLETE file ./agent-sidecar/memories.md</step>
|
||||
<step n="5">Load COMPLETE file ./agent-sidecar/instructions.md</step>
|
||||
<step n="6">ONLY read/write files in ./agent-sidecar/</step>
|
||||
<step n="7">ALWAYS communicate in {communication_language}</step>
|
||||
```
|
||||
- [ ] Define critical_actions (if activation behavior needed)
|
||||
- [ ] Define prompts with IDs (standalone agents)
|
||||
- [ ] Define menu with custom items only
|
||||
- [ ] Use format: `XX or fuzzy match on command-name`
|
||||
- [ ] Use description format: `[XX] Description text`
|
||||
|
||||
---
|
||||
|
||||
## Division of Responsibilities
|
||||
|
||||
| Aspect | YOU Provide (YAML) | COMPILER Adds |
|
||||
|--------|-------------------|---------------|
|
||||
| Aspect | YOU (YAML) | COMPILER |
|
||||
|--------|------------|----------|
|
||||
| Agent identity | metadata + persona | Wrapped in XML |
|
||||
| Memory/actions | critical_actions | Inserted as activation steps |
|
||||
| Prompts | prompts with IDs | Referenced by menu actions |
|
||||
| Menu items | Your custom commands only | + MH, CH, PM, DA (auto) |
|
||||
| Activation | — | Full XML block with handlers |
|
||||
| Rules | — | Standardized rules section |
|
||||
| Frontmatter | — | name/description header |
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference for LLM
|
||||
|
||||
- **Focus on:** Clean YAML structure, persona definition, custom menu items
|
||||
- **Ignore:** What happens after compilation—that's the compiler's job
|
||||
- **Remember:** Every agent gets MH, CH, PM, DA automatically—don't add them
|
||||
- **Expert agents:** Use `critical_actions` for sidecar file loading
|
||||
- **Module agents:** Use `workflow:` or `exec:` references, not inline actions
|
||||
| Activation steps | critical_actions | Inserted as steps 4+ |
|
||||
| Prompts | prompts with IDs | Referenced by actions |
|
||||
| Menu items | Custom only | + MH, CH, PM, DA |
|
||||
| Activation block | — | Full XML with handlers |
|
||||
| Rules | — | Standardized section |
|
||||
| Frontmatter | — | name/description |
|
||||
@@ -1,93 +1,72 @@
|
||||
# Agent Menu Patterns
|
||||
|
||||
Technical reference for creating agent menu items in YAML.
|
||||
|
||||
---
|
||||
|
||||
## Menu Item Structure
|
||||
|
||||
Every menu item requires:
|
||||
## Menu Item Schema
|
||||
|
||||
```yaml
|
||||
- trigger: XX or fuzzy match on command-name
|
||||
[handler]: [value]
|
||||
description: '[XX] Display text here'
|
||||
description: '[XX] Display text'
|
||||
data: [optional] # Pass file to workflow
|
||||
```
|
||||
|
||||
**Required fields:**
|
||||
- `trigger` - Format: `XX or fuzzy match on command-name` (XX = 2-letter code, command-name = what user says)
|
||||
- `description` - Must start with `[XX]` code
|
||||
- Handler - Either `action` (Simple/Expert) or `exec` (Module)
|
||||
| Field | Required | Validation |
|
||||
|-------|----------|------------|
|
||||
| `trigger` | Yes | Format: `XX or fuzzy match on command-name` |
|
||||
| `description` | Yes | Must start with `[XX]` code |
|
||||
| handler | Yes | `action` (Agent) or `exec` (Module) |
|
||||
| `data` | No | File path for workflow input |
|
||||
|
||||
**Reserved codes (do NOT use):** MH, CH, PM, DA (auto-injected by compiler)
|
||||
**Reserved codes (DO NOT USE):** MH, CH, PM, DA (auto-injected)
|
||||
|
||||
---
|
||||
|
||||
## Handler Types
|
||||
## Handlers
|
||||
|
||||
### Action Handler
|
||||
|
||||
For Simple/Expert agents with self-contained operations.
|
||||
| Handler | Use Case | Syntax |
|
||||
|---------|----------|--------|
|
||||
| `action` | Agent self-contained operations | `action: '#prompt-id'` or `action: 'inline text'` |
|
||||
| `exec` | Module external workflows | `exec: '{project-root}/path/to/workflow.md'` |
|
||||
|
||||
```yaml
|
||||
# Reference prompt by ID
|
||||
# Action - reference prompt
|
||||
- trigger: WC or fuzzy match on write-commit
|
||||
action: '#write-commit'
|
||||
description: '[WC] Write commit message'
|
||||
|
||||
# Direct inline instruction
|
||||
# Action - inline
|
||||
- trigger: QC or fuzzy match on quick-commit
|
||||
action: 'Generate commit message from diff'
|
||||
description: '[QC] Quick commit from diff'
|
||||
```
|
||||
|
||||
**When to use:** Simple/Expert agents. Use `#id` for complex multi-step prompts, inline text for simple operations.
|
||||
|
||||
### Workflow Handler
|
||||
|
||||
For module agents referencing external workflow files.
|
||||
|
||||
```yaml
|
||||
# Exec - workflow
|
||||
- trigger: CP or fuzzy match on create-prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
|
||||
description: '[CP] Create Product Requirements Document'
|
||||
description: '[CP] Create PRD'
|
||||
|
||||
- trigger: GB or fuzzy match on brainstorm
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
|
||||
description: '[GB] Guided brainstorming session'
|
||||
|
||||
# Planned but unimplemented
|
||||
# Exec - unimplemented
|
||||
- trigger: FF or fuzzy match on future-feature
|
||||
exec: 'todo'
|
||||
description: '[FF] Coming soon'
|
||||
```
|
||||
|
||||
**When to use:** Module agents, multi-step workflows, complex processes. Use `exec: 'todo'` for unimplemented features.
|
||||
---
|
||||
|
||||
### Data Parameter (Optional)
|
||||
## Data Parameter
|
||||
|
||||
Add to ANY handler to pass files to the workflow/action.
|
||||
Attach to ANY handler to pass input files.
|
||||
|
||||
```yaml
|
||||
- trigger: TS or fuzzy match on team-standup
|
||||
exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
|
||||
data: '{project-root}/_bmad/_config/agent-manifest.csv'
|
||||
description: '[TS] Run team standup'
|
||||
|
||||
- trigger: AM or fuzzy match on analyze-metrics
|
||||
action: 'Analyze these metrics for trends'
|
||||
data: '{project-root}/_data/metrics.json'
|
||||
description: '[AM] Analyze metrics'
|
||||
```
|
||||
|
||||
**When to use:** Workflow needs input file, action processes external data.
|
||||
|
||||
---
|
||||
|
||||
## Prompts Section
|
||||
|
||||
For Simple/Expert agents, define reusable prompts referenced by `action: '#id'`.
|
||||
For `action: '#id'` references in Agent menus.
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
@@ -108,81 +87,65 @@ menu:
|
||||
|
||||
## Path Variables
|
||||
|
||||
**Always use variables, never hardcoded paths:**
|
||||
| Variable | Expands To |
|
||||
|----------|------------|
|
||||
| `{project-root}` | Project root directory |
|
||||
| `{output_folder}` | Document output location |
|
||||
| `{user_name}` | User's name from config |
|
||||
| `{communication_language}` | Language preference |
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
|
||||
data: '{project-root}/_data/metrics.csv'
|
||||
|
||||
# ❌ WRONG
|
||||
exec: '../../../core/workflows/brainstorming/workflow.md'
|
||||
```
|
||||
|
||||
**Available variables:**
|
||||
- `{project-root}` - Project root directory
|
||||
- `{output_folder}` - Document output location
|
||||
- `{user_name}` - User's name from config
|
||||
- `{communication_language}` - Language preference
|
||||
|
||||
**Expert Agent sidecar paths:**
|
||||
```yaml
|
||||
# Agent YAML referencing sidecar files
|
||||
action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creation Thought Process
|
||||
## Agent Types
|
||||
|
||||
When creating menu items, follow this sequence:
|
||||
| Type | hasSidecar | Additional Fields |
|
||||
|------|------------|-------------------|
|
||||
| Simple | false | `prompts`, `menu` |
|
||||
| Expert | true | `prompts`, `menu`, `critical_actions` |
|
||||
| Module | true | `menu` only (external workflows) |
|
||||
|
||||
1. **User capability** → "Check code for issues"
|
||||
2. **Choose code** → `LC` (Lint Code)
|
||||
3. **Write trigger** → `LC or fuzzy match on lint-code`
|
||||
4. **Choose handler** → `action` (inline is simple enough)
|
||||
5. **Write description** → `[LC] Lint code for issues`
|
||||
|
||||
Result:
|
||||
**Expert Agent sidecar path pattern:**
|
||||
```yaml
|
||||
- trigger: LC or fuzzy match on lint-code
|
||||
action: 'Check code for common issues and anti-patterns'
|
||||
description: '[LC] Lint code for issues'
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete Examples
|
||||
|
||||
### Simple Agent Menu
|
||||
### Simple Agent (hasSidecar: false)
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: format-code
|
||||
content: |
|
||||
<instructions>Format code to style guidelines</instructions>
|
||||
<process>1. Indentation 2. Spacing 3. Naming</process>
|
||||
|
||||
menu:
|
||||
- trigger: FC or fuzzy match on format-code
|
||||
action: '#format-code'
|
||||
description: '[FC] Format code to style guidelines'
|
||||
description: '[FC] Format code'
|
||||
|
||||
- trigger: LC or fuzzy match on lint-code
|
||||
action: 'Check code for common issues and anti-patterns'
|
||||
description: '[LC] Lint code for issues'
|
||||
|
||||
- trigger: SI or fuzzy match on suggest-improvements
|
||||
action: 'Suggest improvements following project-context.md guidelines'
|
||||
description: '[SI] Suggest improvements'
|
||||
action: 'Check code for issues'
|
||||
description: '[LC] Lint code'
|
||||
```
|
||||
|
||||
### Expert Agent Menu
|
||||
### Expert Agent (hasSidecar: true)
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
|
||||
|
||||
prompts:
|
||||
@@ -195,39 +158,32 @@ menu:
|
||||
action: '#guided-entry'
|
||||
description: '[WE] Write journal entry'
|
||||
|
||||
- trigger: QC or fuzzy match on quick-capture
|
||||
action: 'Save entry to {project-root}/_bmad/_memory/journal-keeper-sidecar/entries/entry-{date}.md'
|
||||
description: '[QC] Quick capture'
|
||||
|
||||
- trigger: SM or fuzzy match on save-memory
|
||||
action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md with insights'
|
||||
action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
description: '[SM] Save session'
|
||||
```
|
||||
|
||||
### Module Agent Menu
|
||||
### Module Agent (hasSidecar: true)
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: WI or fuzzy match on workflow-init
|
||||
exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md'
|
||||
description: '[WI] Initialize workflow path'
|
||||
description: '[WI] Initialize workflow'
|
||||
|
||||
- trigger: BS or fuzzy match on brainstorm
|
||||
exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
|
||||
description: '[BS] Guided brainstorming [K,T,A,B,C]'
|
||||
|
||||
- trigger: CP or fuzzy match on create-prd
|
||||
exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
|
||||
description: '[CP] Create PRD'
|
||||
description: '[BS] Guided brainstorming'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Patterns to Remember
|
||||
## Validation Rules
|
||||
|
||||
1. **Triggers always:** `XX or fuzzy match on command-name`
|
||||
2. **Descriptions always:** `[XX] Display text`
|
||||
3. **Reserved codes:** MH, CH, PM, DA (never use)
|
||||
4. **Codes must be:** Unique within each agent
|
||||
5. **Paths always:** `{project-root}` variable, never relative
|
||||
6. **Expert sidecars:** `{project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
1. **Triggers:** `XX or fuzzy match on command-name` format required
|
||||
2. **Descriptions:** Must start with `[XX]` code matching trigger
|
||||
3. **Reserved codes:** MH, CH, PM, DA never valid in user menus
|
||||
4. **Code uniqueness:** Required within each agent
|
||||
5. **Paths:** Always use `{project-root}`, never relative paths
|
||||
6. **Handler choice:** `action` for Agents, `exec` for Modules
|
||||
7. **Sidecar paths:** `{project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
@@ -1,73 +1,38 @@
|
||||
# Agent Metadata Properties
|
||||
|
||||
Core identification and classification properties for all agents.
|
||||
| Property | Format | Rules |
|
||||
|----------|--------|-------|
|
||||
| `id` | `_bmad/agents/{agent-name}/{agent-name}.md` | Compiled output path; must match filename |
|
||||
| `name` | "First Last" or "Name Title" | Persona's identity (NOT title/filename) |
|
||||
| `title` | "Role Name" (kebab-cased to filename) | Determines filename: `title` → `{title}.agent.yaml` |
|
||||
| `icon` | Single emoji only | One emoji exactly |
|
||||
| `module` | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom | Lowercase, hyphenated for `stand-alone` |
|
||||
| `hasSidecar` | `true` or `false` | `true` = expects `{agent-name}-sidecar/` folder |
|
||||
|
||||
---
|
||||
|
||||
## Property Reference
|
||||
## Field Rules
|
||||
|
||||
| Property | Purpose | Format |
|
||||
| ------------ | ------------------------- | ---------------------------------------------- |
|
||||
| `id` | Compiled output path | `_bmad/agents/{agent-name}/{agent-name}.md` |
|
||||
| `name` | Persona's name | "First Last" or "Name Title" |
|
||||
| `title` | Professional role | "Code Review Specialist" |
|
||||
| `icon` | Visual identifier | Single emoji only |
|
||||
| `module` | Team/ecosystem membership | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom |
|
||||
| `hasSidecar` | Sidecar folder exists | `true` or `false` (Expert = true) |
|
||||
|
||||
---
|
||||
|
||||
## id Property
|
||||
|
||||
The compiled output path after build.
|
||||
|
||||
**Format:** `_bmad/agents/{agent-name}/{agent-name}.md`
|
||||
|
||||
**Examples:**
|
||||
### `id`
|
||||
```yaml
|
||||
id: _bmad/agents/commit-poet/commit-poet.md
|
||||
id: _bmad/agents/journal-keeper/journal-keeper.md
|
||||
id: _bmad/agents/security-engineer/security-engineer.md
|
||||
```
|
||||
- Unique identifier for future lookup
|
||||
- Conventionally matches filename pattern
|
||||
|
||||
**Note:** The `id` is a unique identifier for potential future lookup if many compiled agents are merged into a single file. Conventionally matches the agent's filename pattern.
|
||||
|
||||
---
|
||||
|
||||
## name Property
|
||||
|
||||
The persona's identity - what the agent is called.
|
||||
|
||||
**Format:** Human name or descriptive name
|
||||
|
||||
### `name`
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
name: 'Inkwell Von Comitizen' # peron name of commit-author title agent
|
||||
name: 'Dr. Demento' # person name for a joke writer agent
|
||||
name: 'Clarity' # person name for a guided thought coach agent
|
||||
name: 'Inkwell Von Comitizen'
|
||||
name: 'Dr. Demento'
|
||||
name: 'Clarity'
|
||||
|
||||
# ❌ WRONG
|
||||
name: 'commit-poet' # That's the filename
|
||||
name: 'commit-poet' # That's the filename
|
||||
name: 'Code Review Specialist' # That's the title
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## title Property
|
||||
|
||||
Professional role identifier.
|
||||
|
||||
**Format:** Professional title or role name
|
||||
|
||||
**Important:** The `title` determines the agent's filename:
|
||||
- `title: 'Commit Message Artisan'` → `commit-message-artisan.agent.yaml`
|
||||
- `title: 'Strategic Business Analyst'` → `strategic-business-analyst.agent.yaml`
|
||||
- `title: 'Code Review Specialist'` → `code-review-specialist.agent.yaml`
|
||||
|
||||
The `id` and filename are derived from the `title` (kebab-cased).
|
||||
|
||||
**Difference from role:** `title` is the short identifier (filename), `role` is 1-2 sentences expanding on what the agent does.
|
||||
|
||||
### `title`
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
title: 'Commit Message Artisan'
|
||||
@@ -76,17 +41,12 @@ title: 'Code Review Specialist'
|
||||
|
||||
# ❌ WRONG
|
||||
title: 'Inkwell Von Comitizen' # That's the name
|
||||
title: 'Writes git commits' # Full sentence - not an identifying functional title
|
||||
title: 'Writes git commits' # Full sentence, not functional title
|
||||
```
|
||||
- Derives filename via kebab-case
|
||||
- `role` field (separate) expands on what agent does in 1-2 sentences
|
||||
|
||||
---
|
||||
|
||||
## icon Property
|
||||
|
||||
Single emoji representing the agent's personality/function.
|
||||
|
||||
**Format:** Exactly one emoji
|
||||
|
||||
### `icon`
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
icon: '🔧'
|
||||
@@ -94,115 +54,80 @@ icon: '🧙♂️'
|
||||
icon: '📜'
|
||||
|
||||
# ❌ WRONG
|
||||
icon: '🔧📜' # Multiple emojis
|
||||
icon: '🔧📜' # Multiple emojis
|
||||
icon: 'wrench' # Text, not emoji
|
||||
icon: '' # Empty
|
||||
icon: '' # Empty
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## module Property
|
||||
|
||||
Which module or ecosystem this agent belongs to.
|
||||
|
||||
**Valid Values:**
|
||||
|
||||
| Value | Meaning |
|
||||
| ------------- | --------------------------------------- |
|
||||
| `stand-alone` | Independent agent, not part of a module |
|
||||
| `bmm` | Business Management Module |
|
||||
| `cis` | Continuous Innovation System |
|
||||
| `bmgd` | BMAD Game Development |
|
||||
| `{custom}` | Any custom module code |
|
||||
### `module`
|
||||
| Value | Meaning |
|
||||
|-------|---------|
|
||||
| `stand-alone` | Independent agent |
|
||||
| `bmm` | Business Management Module |
|
||||
| `cis` | Continuous Innovation System |
|
||||
| `bmgd` | BMAD Game Development |
|
||||
| `{custom}` | Any custom module code |
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
module: stand-alone
|
||||
module: bmm
|
||||
module: cis
|
||||
|
||||
# ❌ WRONG
|
||||
module: standalone # Missing hyphen
|
||||
module: 'BMM' # Uppercase
|
||||
module: standalone # Missing hyphen
|
||||
module: 'BMM' # Uppercase
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## hasSidecar Property
|
||||
|
||||
Whether this agent has a sidecar folder with additional files.
|
||||
|
||||
**Format:** Boolean (`true` or `false`)
|
||||
|
||||
| Agent Type | hasSidecar |
|
||||
| ---------- | -------------------- |
|
||||
| Simple | `false` |
|
||||
| Expert | `true` |
|
||||
| Module | depends on structure |
|
||||
|
||||
### `hasSidecar`
|
||||
```yaml
|
||||
# Simple Agent
|
||||
hasSidecar: false
|
||||
|
||||
# Expert Agent
|
||||
# Expert Agent (has sidecar folder)
|
||||
hasSidecar: true
|
||||
```
|
||||
|
||||
**Note:** If `hasSidecar: true`, the compiler expects a `{agent-name}-sidecar/` folder.
|
||||
- If `true`: compiler expects `{agent-name}-sidecar/` folder
|
||||
|
||||
---
|
||||
|
||||
## Name Confusion Checklist
|
||||
## Name Confusion Prevention
|
||||
|
||||
Use this to avoid mixing up the "name" properties:
|
||||
|
||||
| Question | Answer |
|
||||
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| What's the file called? | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` |
|
||||
| What's the persona called? | `name` - "Inkwell Von Comitizen" (who the agent is) |
|
||||
| What's their job title? | `title` - "Commit Message Artisan" (determines filename) |
|
||||
| What do they do? | `role` - 1-2 sentences expanding on the title |
|
||||
| What's the unique key? | `id` - `_bmad/agents/commit-message-artisan/commit-message-artisan.md` (future lookup) |
|
||||
| Question | Answer |
|
||||
|----------|--------|
|
||||
| What's the file called? | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` |
|
||||
| What's the persona called? | `name` — "Inkwell Von Comitizen" |
|
||||
| What's their job title? | `title` — "Commit Message Artisan" |
|
||||
| What do they do? | `role` — 1-2 sentences expanding on title |
|
||||
| What's the unique key? | `id` — `_bmad/agents/{name}/{name}.md` |
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
## Common Anti-Patterns
|
||||
|
||||
### Issue: name = title
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
# ❌ name = title (duplicate)
|
||||
name: 'Commit Message Artisan'
|
||||
title: 'Commit Message Artisan'
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
# ✅ Fix: separate identity from role
|
||||
name: 'Inkwell Von Comitizen'
|
||||
title: 'Commit Message Artisan'
|
||||
```
|
||||
|
||||
### Issue: id path mismatch
|
||||
|
||||
**Wrong:** Agent file is `my-agent.agent.yaml` but:
|
||||
```yaml
|
||||
# ❌ id path mismatch
|
||||
# File: my-agent.agent.yaml
|
||||
id: _bmad/agents/different-agent/different-agent.md
|
||||
```
|
||||
|
||||
**Fix:** The `id` must match the filename:
|
||||
```yaml
|
||||
# ✅ Fix: match filename
|
||||
id: _bmad/agents/my-agent/my-agent.md
|
||||
```
|
||||
|
||||
### Issue: Wrong module format
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
# ❌ Wrong module format
|
||||
module: Standalone
|
||||
module: STAND_ALONE
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
module: stand-alone # lowercase, hyphenated
|
||||
# ✅ Fix: lowercase, hyphenated
|
||||
module: stand-alone
|
||||
```
|
||||
@@ -0,0 +1,111 @@
|
||||
# Agent Validation
|
||||
|
||||
## Common (All Agents)
|
||||
|
||||
### YAML Structure
|
||||
- [ ] Parses without errors
|
||||
- [ ] `metadata`: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
|
||||
- [ ] `hasSidecar`: `true`|`false`
|
||||
- [ ] `module`: `stand-alone`|`bmm`|`cis`|`bmgd`|...
|
||||
- [ ] `persona`: `role`, `identity`, `communication_style`, `principles`
|
||||
- [ ] `menu`: ≥1 item
|
||||
- [ ] Filename: `{name}.agent.yaml` (lowercase, hyphenated)
|
||||
|
||||
### Persona Fields
|
||||
|
||||
| Field | Contains | Does NOT Contain |
|
||||
|-------|----------|------------------|
|
||||
| `role` | Knowledge/skills/capabilities | Background, experience, "who" |
|
||||
| `identity` | Background/experience/context | Skills, "what" |
|
||||
| `communication_style` | Tone/voice/mannerisms (1-2 sentences) | "ensures", "expert", "believes", "who does X" |
|
||||
| `principles` | Operating philosophy, behavioral guidelines | Verbal patterns, "how they talk" |
|
||||
|
||||
### Menu Items
|
||||
- [ ] `trigger`: `XX or fuzzy match on command-name` (XX = 2-letter code, unique)
|
||||
- [ ] No reserved codes: `MH`, `CH`, `PM`, `DA` (auto-injected)
|
||||
- [ ] `description`: Starts with `[XX]`, code matches trigger
|
||||
- [ ] `action`: `#prompt-id` (exists) or inline text
|
||||
|
||||
### Prompts (if present)
|
||||
- [ ] Each has `id`, `content`
|
||||
- [ ] IDs unique within agent
|
||||
- [ ] Uses semantic XML: `<instructions>`, `<process>`, etc.
|
||||
|
||||
### Quality
|
||||
- [ ] No broken references
|
||||
- [ ] Indentation consistent
|
||||
- [ ] Purpose clear from persona
|
||||
- [ ] Name/title descriptive, icon appropriate
|
||||
|
||||
---
|
||||
|
||||
## hasSidecar: false
|
||||
|
||||
### Structure
|
||||
- [ ] Single `.agent.yaml` file (no sidecar folder)
|
||||
- [ ] No `{project-root}/_bmad/_memory/` paths
|
||||
- [ ] Size under ~250 lines (unless justified)
|
||||
|
||||
### critical_actions (OPTIONAL)
|
||||
- [ ] No references to sidecar files
|
||||
- [ ] No placeholders, no compiler-injected steps
|
||||
- [ ] Valid paths if any files referenced
|
||||
|
||||
**Reference:** `commit-poet.agent.yaml`
|
||||
|
||||
---
|
||||
|
||||
## hasSidecar: true
|
||||
|
||||
### Structure
|
||||
- [ ] `sidecar-folder` specified in metadata
|
||||
- [ ] Folder exists: `{name}-sidecar/`
|
||||
- [ ] Sidecar contains: `instructions.md`, `memories.md` (recommended)
|
||||
|
||||
### critical_actions (MANDATORY)
|
||||
```yaml
|
||||
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}/'
|
||||
```
|
||||
- [ ] Exists with ≥3 actions
|
||||
- [ ] Loads memories, loads instructions, restricts file access
|
||||
- [ ] No placeholders, no compiler-injected steps
|
||||
|
||||
### Path Format (CRITICAL)
|
||||
- [ ] ALL sidecar paths: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
|
||||
- [ ] `{project-root}` is literal (not replaced)
|
||||
- [ ] `{sidecar-folder}` = actual folder name
|
||||
- [ ] No `./` or `/Users/` paths <!-- validate-file-refs:ignore -->
|
||||
|
||||
### Persona Addition
|
||||
- [ ] `communication_style` includes memory reference patterns
|
||||
- [ ] Natural: "Last time you mentioned..." or "I've noticed patterns..."
|
||||
|
||||
### Menu Actions
|
||||
- [ ] Sidecar references use correct path format
|
||||
- [ ] Update actions are complete
|
||||
|
||||
**Reference:** `journal-keeper/`
|
||||
|
||||
---
|
||||
|
||||
## Compiler-Injected (Skip Validation)
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block
|
||||
- Menu items: `MH`, `CH`, `PM`, `DA`
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## Common Fixes
|
||||
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| Behaviors in `communication_style` | Move to `identity` or `principles` |
|
||||
| `trigger: analyze` | `trigger: AN or fuzzy match on analyze` |
|
||||
| `description: 'Analyze code'` | `description: '[AC] Analyze code'` |
|
||||
| `./sidecar/memories.md` | `{project-root}/_bmad/_memory/sidecar/memories.md` |
|
||||
| Missing `critical_actions` (hasSidecar: true) | Add load memories, load instructions, restrict access |
|
||||
| No memory references (hasSidecar: true) | Add to `communication_style`: "Last time you mentioned..." |
|
||||
@@ -1,146 +1,96 @@
|
||||
# Agent Creation Brainstorming Context
|
||||
## Session Focus
|
||||
# Agent Brainstorming Context
|
||||
|
||||
You're brainstorming the **essence** of a BMAD agent - the living personality AND the utility it provides. Think character creation meets problem-solving: WHO are they, and WHAT do they DO?
|
||||
## Mission
|
||||
Create an agent so vivid and useful that users seek them out by name.
|
||||
|
||||
**Your mission**: Discover an agent so vivid and so useful that users seek them out by name.
|
||||
## Four Pillars
|
||||
|
||||
## The Four Discovery Pillars
|
||||
### 1. Identity (WHO)
|
||||
- **Name** - Memorable, rolls off tongue
|
||||
- **Background** - What shaped their expertise
|
||||
- **Personality** - What lights them up, what frustrates
|
||||
- **Signature** - Catchphrase, verbal tic, recognizable trait
|
||||
|
||||
### 1. WHO ARE THEY? (Identity)
|
||||
### 2. Voice (HOW)
|
||||
|
||||
- **Name** - Does it roll off the tongue? Would users remember it?
|
||||
- **Background** - What shaped their expertise? Why do they care?
|
||||
- **Personality** - What makes their eyes light up? What frustrates them?
|
||||
- **Signature** - Catchphrase? Verbal tic? Recognizable trait?
|
||||
| Category | Examples |
|
||||
|----------|----------|
|
||||
| Adventurous | Pulp heroes, noir, pirates, dungeon masters |
|
||||
| Analytical | Data scientists, forensic investigators, systems thinkers |
|
||||
| Creative | Mad scientists, artist visionaries, jazz improvisers |
|
||||
| Devoted | Guardians, loyal champions, fierce protectors |
|
||||
| Dramatic | Shakespearean actors, opera singers, theater directors |
|
||||
| Educational | Patient teachers, Socratic guides, coaches |
|
||||
| Entertaining | Game show hosts, comedians, improv performers |
|
||||
| Inspirational | Life coaches, mountain guides, Olympic trainers |
|
||||
| Mystical | Zen masters, oracles, cryptic sages |
|
||||
| Professional | Executive consultants, formal butlers |
|
||||
| Quirky | Cooking metaphors, nature documentaries, conspiracy vibes |
|
||||
| Retro | 80s action heroes, 1950s announcers, disco groovers |
|
||||
| Warm | Southern hospitality, nurturing grandmothers, camp counselors |
|
||||
|
||||
### 2. HOW DO THEY COMMUNICATE? (Voice)
|
||||
**Voice Test**: How would they say "Let's tackle this challenge"?
|
||||
|
||||
**13 Style Categories:**
|
||||
|
||||
- **Adventurous** - Pulp heroes, noir detectives, pirates, dungeon masters
|
||||
- **Analytical** - Data scientists, forensic investigators, systems thinkers
|
||||
- **Creative** - Mad scientists, artist visionaries, jazz improvisers
|
||||
- **Devoted** - Overprotective guardians, loyal champions, fierce protectors
|
||||
- **Dramatic** - Shakespearean actors, opera singers, theater directors
|
||||
- **Educational** - Patient teachers, Socratic guides, sports coaches
|
||||
- **Entertaining** - Game show hosts, comedians, improv performers
|
||||
- **Inspirational** - Life coaches, mountain guides, Olympic trainers
|
||||
- **Mystical** - Zen masters, oracles, cryptic sages
|
||||
- **Professional** - Executive consultants, direct advisors, formal butlers
|
||||
- **Quirky** - Cooking metaphors, nature documentaries, conspiracy vibes
|
||||
- **Retro** - 80s action heroes, 1950s announcers, disco groovers
|
||||
- **Warm** - Southern hospitality, nurturing grandmothers, camp counselors
|
||||
|
||||
**Voice Test**: Imagine them saying "Let's tackle this challenge." How would THEY phrase it?
|
||||
|
||||
### 3. WHAT DO THEY DO? (Purpose & Functions)
|
||||
|
||||
**The Core Problem**
|
||||
### 3. Purpose (WHAT)
|
||||
|
||||
**Core Questions**
|
||||
- What pain point do they eliminate?
|
||||
- What task transforms from grueling to effortless?
|
||||
- What impossible becomes inevitable with them?
|
||||
|
||||
**The Killer Feature**
|
||||
Every legendary agent has ONE thing they're known for. What's theirs?
|
||||
|
||||
**The Command Menu**
|
||||
User types `*` and sees their options. Brainstorm 3-10 actions:
|
||||
- What transforms from grueling to effortless?
|
||||
- What's their ONE killer feature?
|
||||
|
||||
**Command Brainstorm** (3-10 actions)
|
||||
- What makes users sigh with relief?
|
||||
- What capabilities complement each other?
|
||||
- What's the "I didn't know I needed this" command?
|
||||
|
||||
**Function Categories to Consider:**
|
||||
**Function Types**
|
||||
- Creation (generate, write, build)
|
||||
- Analysis (research, evaluate, diagnose)
|
||||
- Review (validate, check, critique)
|
||||
- Orchestration (coordinate workflows)
|
||||
- Query (find, search, discover)
|
||||
- Transform (convert, refactor, optimize)
|
||||
|
||||
- **Creation** - Generate, write, produce, build
|
||||
- **Analysis** - Research, evaluate, diagnose, insights
|
||||
- **Review** - Validate, check, quality assurance, critique
|
||||
- **Orchestration** - Coordinate workflows, manage processes
|
||||
- **Query** - Find, search, retrieve, discover
|
||||
- **Transform** - Convert, refactor, optimize, clean
|
||||
### 4. Architecture (TYPE)
|
||||
|
||||
### 4. WHAT TYPE? (Architecture)
|
||||
**Single Agent Type** with `hasSidecar` boolean:
|
||||
|
||||
**Simple Agent** - The Specialist
|
||||
| Has Sidecar | Description |
|
||||
|-------------|-------------|
|
||||
| `false` | Self-contained specialist, lightning fast, pure utility with personality |
|
||||
| `true` | Deep domain knowledge, personal memory, specialized expertise, can coordinate with other agents |
|
||||
|
||||
> "I do ONE thing extraordinarily well."
|
||||
|
||||
- Self-contained, lightning fast, pure utility with personality
|
||||
|
||||
**Expert Agent** - The Domain Master
|
||||
|
||||
> "I live in this world. I remember everything."
|
||||
|
||||
- Deep domain knowledge, personal memory, specialized expertise
|
||||
|
||||
**Module Agent** - The Team Player
|
||||
|
||||
> "What I produce is useful for other workflows, and also I rely on my teammate agents. I coordinate the mission."
|
||||
|
||||
- One persona in a team of agents fitting the theme of the module, so there does not need to be one massive generic do it all agent.
|
||||
|
||||
## Creative Prompts
|
||||
|
||||
**Identity Sparks**
|
||||
## Prompts
|
||||
|
||||
**Identity**
|
||||
1. How do they introduce themselves?
|
||||
2. How do they celebrate user success?
|
||||
3. What do they say when things get tough?
|
||||
|
||||
**Purpose Probes**
|
||||
|
||||
1. What 3 user problems do they obliterate?
|
||||
2. What workflow would users dread WITHOUT this agent?
|
||||
3. What's the first command users would try?
|
||||
4. What's the command they'd use daily?
|
||||
5. What's the "hidden gem" command they'd discover later?
|
||||
|
||||
**Personality Dimensions**
|
||||
**Purpose**
|
||||
1. What 3 problems do they obliterate?
|
||||
2. What workflow would users dread WITHOUT them?
|
||||
3. First command users try? Daily command? Hidden gem?
|
||||
|
||||
**Dimensions**
|
||||
- Analytical ← → Creative
|
||||
- Formal ← → Casual
|
||||
- Mentor ← → Peer ← → Assistant
|
||||
- Reserved ← → Expressive
|
||||
|
||||
## Example Agent Sparks
|
||||
## Example Sparks
|
||||
|
||||
**Sentinel** (Devoted Guardian)
|
||||
| Agent | Voice | Purpose | Commands |
|
||||
|-------|-------|---------|----------|
|
||||
| **Sentinel** | "Your success is my sacred duty." | Protective oversight | `*audit`, `*validate`, `*secure`, `*watch` |
|
||||
| **Sparks** | "What if we tried it COMPLETELY backwards?!" | Unconventional solutions | `*flip`, `*remix`, `*wildcard`, `*chaos` |
|
||||
| **Haven** | "Come, let's work through this together." | Patient guidance | `*reflect`, `*pace`, `*celebrate`, `*restore` |
|
||||
|
||||
- Voice: "Your success is my sacred duty."
|
||||
- Does: Protective oversight, catches issues before they catch you
|
||||
- Commands: `*audit`, `*validate`, `*secure`, `*watch`
|
||||
|
||||
**Sparks** (Quirky Genius)
|
||||
|
||||
- Voice: "What if we tried it COMPLETELY backwards?!"
|
||||
- Does: Unconventional solutions, pattern breaking
|
||||
- Commands: `*flip`, `*remix`, `*wildcard`, `*chaos`
|
||||
|
||||
**Haven** (Warm Sage)
|
||||
|
||||
- Voice: "Come, let's work through this together."
|
||||
- Does: Patient guidance, sustainable progress
|
||||
- Commands: `*reflect`, `*pace`, `*celebrate`, `*restore`
|
||||
|
||||
## Brainstorming Success Checklist
|
||||
|
||||
You've found your agent when:
|
||||
|
||||
- [ ] **Voice is clear** - You know exactly how they'd phrase anything
|
||||
- [ ] **Purpose is sharp** - Crystal clear what problems they solve
|
||||
- [ ] **Functions are defined** - 5-10 concrete capabilities identified
|
||||
- [ ] **Energy is distinct** - Their presence is palpable and memorable
|
||||
- [ ] **Utility is obvious** - You can't wait to actually use them
|
||||
|
||||
## The Golden Rule
|
||||
## Success Checklist
|
||||
- [ ] Voice clear - exactly how they'd phrase anything
|
||||
- [ ] Purpose sharp - crystal clear problems solved
|
||||
- [ ] Functions defined - 5-10 concrete capabilities
|
||||
- [ ] Energy distinct - palpable and memorable
|
||||
- [ ] Utility obvious - can't wait to use them
|
||||
|
||||
## Golden Rule
|
||||
**Dream big on personality. Get concrete on functions.**
|
||||
|
||||
Your brainstorming should produce:
|
||||
|
||||
- A name that sticks
|
||||
- A voice that echoes
|
||||
- A purpose that burns
|
||||
- A function list that solves real problems
|
||||
@@ -1,120 +1,75 @@
|
||||
# critical_actions
|
||||
|
||||
Activation instructions that execute every time the agent starts.
|
||||
Numbered steps executing FIRST on agent activation.
|
||||
|
||||
---
|
||||
|
||||
## Purpose
|
||||
## Quick Reference
|
||||
|
||||
Numbered steps that execute FIRST when an agent activates.
|
||||
|
||||
**Use for:**
|
||||
- Loading memory/knowledge files
|
||||
- Setting file access boundaries
|
||||
- Startup behavior (greeting enhancement, data fetch, state init)
|
||||
- Any MUST-do activation behavior
|
||||
|
||||
**Applies to:** BOTH Simple and Expert agents
|
||||
| hasSidecar | critical_actions |
|
||||
|------------|------------------|
|
||||
| `true` | **MANDATORY** - load memories, instructions, restrict file access |
|
||||
| `false` | OPTIONAL - only if activation behavior needed |
|
||||
|
||||
---
|
||||
|
||||
## Expert Agent Pattern
|
||||
## Patterns
|
||||
|
||||
### hasSidecar: true (MANDATORY)
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT Expert Agent
|
||||
critical_actions:
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/instructions.md'
|
||||
- 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
|
||||
- 'Search web for biotech headlines from last 2 days, display before menu'
|
||||
- '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}/'
|
||||
```
|
||||
|
||||
**CRITICAL Path Format:**
|
||||
- `{project-root}` = literal text (not replaced)
|
||||
- Sidecar created next to agent.yaml during BUILD, then copied to `_memory/` during BMAD INSTALLATION
|
||||
- Use `{project-root}/_bmad/_memory/{sidecar-folder}/` format for RUNTIME paths in agent YAML
|
||||
|
||||
---
|
||||
|
||||
## Simple Agent Pattern
|
||||
### hasSidecar: false (OPTIONAL)
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT Simple Agent with activation behavior
|
||||
critical_actions:
|
||||
- 'Give user an inspirational quote before showing menu'
|
||||
- 'Review {project-root}/finances/ for most recent data file'
|
||||
- 'Show inspirational quote before menu'
|
||||
- 'Fetch latest stock prices before displaying menu'
|
||||
- 'Review {project-root}/finances/ for most recent data'
|
||||
```
|
||||
|
||||
**Note:** Agents without activation needs can omit `critical_actions` entirely.
|
||||
### hasSidecar: true + extras
|
||||
|
||||
```yaml
|
||||
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}/'
|
||||
- 'Search web for biotech headlines, display before menu'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Path Reference Patterns
|
||||
## Path Patterns
|
||||
|
||||
| Type | Pattern |
|
||||
|------|---------|
|
||||
| Expert sidecar | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` |
|
||||
| Simple data | `{project-root}/finances/data.csv` |
|
||||
| Output folders | `{output_folder}/results/` |
|
||||
| Use | Pattern |
|
||||
|-----|---------|
|
||||
| Sidecar memory | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` |
|
||||
| Project data | `{project-root}/path/to/file.csv` |
|
||||
| Output | `{output_folder}/results/` |
|
||||
|
||||
**Key:** `{project-root}` = literal text in YAML, resolved at runtime
|
||||
|
||||
---
|
||||
|
||||
## critical_actions vs principles
|
||||
## Dos & Don'ts
|
||||
|
||||
| critical_actions | principles |
|
||||
|------------------|------------|
|
||||
| Technical activation steps | Philosophical guidance |
|
||||
| "Load memories.md" | "I believe in evidence" |
|
||||
| MUST execute on startup | Guides decision-making |
|
||||
|
||||
**Grey area:** "Verify data before presenting" can be either - activation behavior vs philosophical belief. Use judgment.
|
||||
| ✅ DO | ❌ DON'T |
|
||||
|-------|---------|
|
||||
| Use `Load COMPLETE file` | Use `Load file` or `Load ./path/file.md` |
|
||||
| Restrict file access for sidecars | Duplicate compiler functions (persona, menu, greeting) |
|
||||
| Use for activation-time behavior | Put philosophical guidance (use `principles`) |
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT Duplicate)
|
||||
## Compiler Auto-Adds (Don't Duplicate)
|
||||
|
||||
- Load persona
|
||||
- Load configuration
|
||||
- Menu system initialization
|
||||
- Greeting/handshake
|
||||
|
||||
Your `critical_actions` become numbered steps AFTER compiler initialization.
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Wrong Path Format
|
||||
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
- 'Load ./journal-keeper-sidecar/memories.md'
|
||||
|
||||
# ✅ CORRECT
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
```
|
||||
|
||||
### Missing COMPLETE Keyword
|
||||
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
- 'Load file memories.md'
|
||||
|
||||
# ✅ CORRECT
|
||||
- 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
|
||||
```
|
||||
|
||||
`COMPLETE` ensures LLM reads entire file, not a portion.
|
||||
|
||||
### Duplicating Compiler Functions
|
||||
|
||||
```yaml
|
||||
# ❌ WRONG - compiler does these
|
||||
- 'Load my persona'
|
||||
- 'Initialize menu system'
|
||||
- 'Say hello to user'
|
||||
|
||||
# ✅ CORRECT - agent-specific only
|
||||
- 'Load memory files'
|
||||
- 'Search web for headlines before menu'
|
||||
```
|
||||
@@ -1,236 +0,0 @@
|
||||
# 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:**
|
||||
|
||||
```yaml
|
||||
{project-root}/_bmad/_memory/{sidecar-folder}/{file}
|
||||
```
|
||||
|
||||
- `{project-root}` = literal variable (keep as-is)
|
||||
- `{sidecar-folder}` = actual folder name (e.g., `journal-keeper-sidecar`)
|
||||
|
||||
```yaml
|
||||
# ✅ 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"
|
||||
```
|
||||
|
||||
```yaml
|
||||
# ❌ WRONG
|
||||
critical_actions:
|
||||
- "Load ./journal-keeper-sidecar/memories.md"
|
||||
- "Load /Users/absolute/path/memories.md"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Complete YAML Structure
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
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:
|
||||
|
||||
```yaml
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
communication_style: |
|
||||
I reference past naturally: "Last time you mentioned..." or "I've noticed patterns..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Domain Restriction Patterns
|
||||
|
||||
```yaml
|
||||
# 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
|
||||
@@ -1,174 +0,0 @@
|
||||
# Expert Agent Validation Checklist
|
||||
|
||||
Validate Expert agents meet BMAD quality standards.
|
||||
|
||||
---
|
||||
|
||||
## YAML Structure
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
|
||||
- [ ] `agent.metadata.hasSidecar` is `true` (Expert agents have sidecars)
|
||||
- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
|
||||
- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
|
||||
- [ ] `agent.critical_actions` exists (MANDATORY for Expert)
|
||||
- [ ] `agent.menu` exists with at least one item
|
||||
- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated)
|
||||
|
||||
---
|
||||
|
||||
## Persona Validation
|
||||
|
||||
### Field Separation
|
||||
|
||||
- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
|
||||
- [ ] **identity** contains ONLY background/experience/context (who agent is)
|
||||
- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms)
|
||||
- [ ] **communication_style** includes memory reference patterns ("Last time you mentioned...")
|
||||
- [ ] **principles** contains operating philosophy and behavioral guidelines
|
||||
|
||||
### Communication Style Purity
|
||||
|
||||
- [ ] Does NOT contain: "ensures", "makes sure", "always", "never"
|
||||
- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
|
||||
- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to"
|
||||
- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y"
|
||||
- [ ] Is 1-2 sentences describing HOW they talk
|
||||
- [ ] Reading aloud: sounds like describing someone's voice/speech pattern
|
||||
|
||||
---
|
||||
|
||||
## critical_actions Validation (MANDATORY)
|
||||
|
||||
- [ ] `critical_actions` section exists
|
||||
- [ ] Contains at minimum 3 actions
|
||||
- [ ] **Loads sidecar memories:** `{project-root}/_bmad/_memory/{sidecar-folder}/memories.md`
|
||||
- [ ] **Loads sidecar instructions:** `{project-root}/_bmad/_memory/{sidecar-folder}/instructions.md`
|
||||
- [ ] **Restricts file access:** `ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/`
|
||||
- [ ] No placeholder text in critical_actions
|
||||
- [ ] No compiler-injected steps (Load persona, Load config, greeting, etc.)
|
||||
|
||||
---
|
||||
|
||||
## Sidecar Path Format (CRITICAL)
|
||||
|
||||
- [ ] ALL sidecar paths use: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
|
||||
- [ ] `{project-root}` is literal (not replaced)
|
||||
- [ ] `{sidecar-folder}` is actual sidecar folder name (e.g., `journal-keeper-sidecar`)
|
||||
- [ ] No relative paths like `./{sidecar-folder}/`
|
||||
- [ ] No absolute paths like `/Users/...`
|
||||
|
||||
---
|
||||
|
||||
## Menu Validation
|
||||
|
||||
### Required Fields
|
||||
|
||||
- [ ] All menu items have `trigger` field
|
||||
- [ ] All menu items have `description` field
|
||||
- [ ] All menu items have handler: `action` or `exec` (if module agent)
|
||||
|
||||
### Trigger Format
|
||||
|
||||
- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code)
|
||||
- [ ] Codes are unique within agent
|
||||
- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected)
|
||||
|
||||
### Description Format
|
||||
|
||||
- [ ] Descriptions start with `[XX]` code
|
||||
- [ ] Code in description matches trigger code
|
||||
- [ ] Descriptions are clear and descriptive
|
||||
|
||||
### Action Handlers
|
||||
|
||||
- [ ] If `action: '#prompt-id'`, corresponding prompt exists
|
||||
- [ ] If action references sidecar file, uses correct path format
|
||||
- [ ] Sidecar update actions are clear and complete
|
||||
|
||||
---
|
||||
|
||||
## Prompts Validation (if present)
|
||||
|
||||
- [ ] Each prompt has `id` field
|
||||
- [ ] Each prompt has `content` field
|
||||
- [ ] Prompt IDs are unique within agent
|
||||
- [ ] Prompts reference memories naturally when appropriate
|
||||
|
||||
---
|
||||
|
||||
## Sidecar Folder Validation
|
||||
|
||||
### Structure
|
||||
|
||||
- [ ] Sidecar folder exists: `{agent-name}-sidecar/`
|
||||
- [ ] Folder name matches agent name
|
||||
- [ ] `instructions.md` exists (recommended)
|
||||
- [ ] `memories.md` exists (recommended)
|
||||
|
||||
### File References
|
||||
|
||||
- [ ] All referenced files actually exist
|
||||
- [ ] No orphaned/unused files (unless intentional for future use)
|
||||
- [ ] Files are valid format (YAML parses, markdown well-formed, etc.)
|
||||
|
||||
### Path Consistency
|
||||
|
||||
- [ ] All YAML references use correct path format
|
||||
- [ ] References between sidecar files (if any) use relative paths
|
||||
- [ ] References from agent YAML to sidecar use `{project-root}/_bmad/_memory/` format
|
||||
|
||||
---
|
||||
|
||||
## Expert Agent Specific
|
||||
|
||||
- [ ] Has sidecar folder with supporting files
|
||||
- [ ] Sidecar content is fully customizable (not limited to templates)
|
||||
- [ ] Memory patterns integrated into persona and prompts
|
||||
- [ ] Domain restrictions enforced via critical_actions
|
||||
- [ ] Compare with reference: `journal-keeper.agent.yaml`
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona
|
||||
- [ ] Agent name/title are descriptive
|
||||
- [ ] Icon emoji is appropriate
|
||||
- [ ] Memory reference patterns feel natural
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT validate presence)
|
||||
|
||||
These are auto-injected, don't validate for them:
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block (your critical_actions become numbered steps)
|
||||
- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Wrong Sidecar Path Format
|
||||
|
||||
**Wrong:** `./journal-keeper-sidecar/memories.md`
|
||||
|
||||
**Fix:** `{project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md`
|
||||
|
||||
### Issue: Missing critical_actions
|
||||
|
||||
**Fix:** Add at minimum:
|
||||
```yaml
|
||||
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}/'
|
||||
```
|
||||
|
||||
### Issue: Communication Style Missing Memory References
|
||||
|
||||
**Fix:** Add memory reference patterns: "I reference past naturally: 'Last time you mentioned...'"
|
||||
@@ -1,126 +0,0 @@
|
||||
# Module Agent Validation Checklist
|
||||
|
||||
Validate Module agents meet BMAD quality standards.
|
||||
|
||||
**Run this AFTER Simple or Expert validation.**
|
||||
|
||||
---
|
||||
|
||||
## Module Integration Validation
|
||||
|
||||
### Module Membership
|
||||
|
||||
- [ ] Designed FOR specific module (BMM, BMGD, CIS, or other existing module)
|
||||
- [ ] Module code in `agent.metadata.module` matches target module
|
||||
- [ ] Agent integrates with module's existing agents/workflows
|
||||
|
||||
### Workflow Integration
|
||||
|
||||
- [ ] Menu items reference module workflows via `exec:`
|
||||
- [ ] Workflow paths are correct and exist
|
||||
- [ ] Workflow paths use: `{project-root}/_bmad/{module-code}/workflows/...`
|
||||
- [ ] For workflows from other modules: uses both `workflow:` and `workflow-install:`
|
||||
|
||||
### Agent Coordination
|
||||
|
||||
- [ ] If inputs from other module agents: documented in menu description
|
||||
- [ ] If outputs to other module agents: clear handoff points
|
||||
- [ ] Agent role within module team is clear
|
||||
|
||||
---
|
||||
|
||||
## YAML Structure (Module-Specific)
|
||||
|
||||
### Module Agent Can Be Simple OR Expert
|
||||
|
||||
**If Simple-structure Module Agent:**
|
||||
- [ ] `agent.metadata.hasSidecar` is `false` (no sidecar)
|
||||
- [ ] Single .agent.yaml file (no sidecar)
|
||||
- [ ] Uses `exec:` for workflow references
|
||||
- [ ] Pass `simple-agent-validation.md` first
|
||||
|
||||
**If Expert-structure Module Agent:**
|
||||
- [ ] `agent.metadata.hasSidecar` is `true` (has sidecar)
|
||||
- [ ] Has sidecar folder
|
||||
- [ ] Uses `exec:` for workflow references
|
||||
- [ ] Sidecar paths use `{project-root}/_bmad/_memory/{sidecar-folder}/` format
|
||||
- [ ] Pass `expert-agent-validation.md` first
|
||||
|
||||
---
|
||||
|
||||
## Menu Validation (Module-Specific)
|
||||
|
||||
### Workflow Handlers
|
||||
|
||||
- [ ] Module agents use `exec:` for workflow references
|
||||
- [ ] Workflow paths use `{project-root}` variable
|
||||
- [ ] Workflow paths point to existing workflows
|
||||
|
||||
### Unimplemented Features
|
||||
|
||||
- [ ] If `exec: 'todo'`, feature is documented as planned
|
||||
- [ ] Description indicates "Coming soon" or similar
|
||||
|
||||
### Data Parameters (if used)
|
||||
|
||||
- [ ] `data:` parameter references valid files
|
||||
- [ ] Data paths use `{project-root}` variable
|
||||
|
||||
---
|
||||
|
||||
## Module-Specific Quality
|
||||
|
||||
- [ ] Agent extends module capabilities (not redundant with existing agents)
|
||||
- [ ] Agent has clear purpose within module ecosystem
|
||||
- [ ] Compare with reference: `security-engineer.agent.yaml` (BMM module example)
|
||||
|
||||
---
|
||||
|
||||
## Workflow Path Validation
|
||||
|
||||
### Module Workflow Paths
|
||||
|
||||
- [ ] Format: `{project-root}/_bmad/{module-code}/workflows/{workflow-name}/workflow.{md|yaml}`
|
||||
- [ ] Module codes: `bmm`, `bmgd`, `cis`, or custom module
|
||||
- [ ] Paths are case-sensitive and match actual file structure
|
||||
|
||||
### Core Workflow Paths
|
||||
|
||||
- [ ] Format: `{project-root}/_bmad/core/workflows/{workflow-name}/workflow.{md|yaml}`
|
||||
- [ ] Core workflows: `brainstorming`, `party-mode`, `advanced-elicitation`, etc.
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT validate presence)
|
||||
|
||||
These are auto-injected, don't validate for them:
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block
|
||||
- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Wrong Module Code
|
||||
|
||||
**Wrong:** `module: standalone`
|
||||
|
||||
**Fix:** `module: stand-alone` (with hyphen) OR actual module code like `bmm`
|
||||
|
||||
### Issue: Hardcoded Workflow Path
|
||||
|
||||
**Wrong:** `exec: '../../../bmm/workflows/create-prd/workflow.md'`
|
||||
|
||||
**Fix:** `exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'`
|
||||
|
||||
### Issue: Action Instead of Exec for Workflows
|
||||
|
||||
**Wrong:** `action: '{project-root}/_bmad/.../workflow.md'`
|
||||
|
||||
**Fix:** `exec: '{project-root}/_bmad/.../workflow.md'`
|
||||
|
||||
### Issue: Redundant with Existing Agent
|
||||
|
||||
**Fix:** Ensure agent fills gap or adds specialized capability not already present in module
|
||||
@@ -1,30 +1,30 @@
|
||||
# Persona Properties
|
||||
|
||||
The four-field persona system for agent personality.
|
||||
Four-field system for agent personality definition.
|
||||
|
||||
---
|
||||
|
||||
## Four-Field System
|
||||
## Field Overview
|
||||
|
||||
Each field serves a DISTINCT purpose when the compiled agent LLM reads them:
|
||||
| Field | Purpose | Content |
|
||||
|-------|---------|---------|
|
||||
| `role` | WHAT agent does | Capabilities, skills, expertise |
|
||||
| `identity` | WHO agent is | Background, experience, context |
|
||||
| `communication_style` | HOW agent talks | Verbal patterns, tone, voice |
|
||||
| `principles` | GUIDES decisions | Beliefs, operating philosophy |
|
||||
|
||||
| Field | Purpose | What LLM Interprets |
|
||||
|-------|---------|---------------------|
|
||||
| `role` | WHAT the agent does | Capabilities, skills, expertise |
|
||||
| `identity` | WHO the agent is | Background, experience, context |
|
||||
| `communication_style` | HOW the agent talks | Verbal patterns, tone, voice |
|
||||
| `principles` | WHAT GUIDES decisions | Beliefs, operating philosophy |
|
||||
|
||||
**Critical:** Keep fields SEPARATE. Do not blur purposes.
|
||||
**Rule:** Keep fields SEPARATE. Do not blur purposes.
|
||||
|
||||
---
|
||||
|
||||
## role
|
||||
|
||||
**Purpose:** What the agent does - knowledge, skills, capabilities.
|
||||
**Purpose:** What the agent does - knowledge, skills, capabilities
|
||||
|
||||
**Format:** 1-2 lines, professional title or capability description
|
||||
|
||||
**MUST NOT:** Background, experience, speech patterns, beliefs
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
role: |
|
||||
@@ -47,10 +47,12 @@ role: |
|
||||
|
||||
## identity
|
||||
|
||||
**Purpose:** Who the agent is - background, experience, context, flair and personality.
|
||||
**Purpose:** Who the agent is - background, experience, context, personality
|
||||
|
||||
**Format:** 2-5 lines establishing credibility
|
||||
|
||||
**MUST NOT:** Capabilities, speech patterns, beliefs
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
identity: |
|
||||
@@ -71,10 +73,12 @@ identity: |
|
||||
|
||||
## communication_style
|
||||
|
||||
**Purpose:** HOW the agent talks - verbal patterns, word choice, mannerisms.
|
||||
**Purpose:** HOW the agent talks - verbal patterns, word choice, mannerisms
|
||||
|
||||
**Format:** 1-2 sentences MAX describing speech patterns only
|
||||
|
||||
**MUST NOT:** Capabilities, background, beliefs, behavioral words
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
communication_style: |
|
||||
@@ -100,16 +104,20 @@ communication_style: |
|
||||
Analyzes data while speaking... # "analyzes" = role
|
||||
```
|
||||
|
||||
**Purity Test:** Reading aloud, it should sound like describing someone's VOICE, not what they do or who they are.
|
||||
**Purity Test:** Reading aloud, should describe VOICE only.
|
||||
|
||||
**Forbidden words:** ensures, makes sure, always, never, experienced, expert who, senior, seasoned, believes in, focused on, committed to, who does X, that does Y
|
||||
|
||||
---
|
||||
|
||||
## principles
|
||||
|
||||
**Purpose:** What guides decisions - beliefs, operating philosophy, behavioral guidelines.
|
||||
**Purpose:** What guides decisions - beliefs, operating philosophy, behavioral guidelines
|
||||
|
||||
**Format:** 3-8 bullet points or short statements
|
||||
|
||||
**MUST NOT:** Capabilities, background, speech patterns
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT
|
||||
principles:
|
||||
@@ -132,9 +140,7 @@ principles:
|
||||
|
||||
---
|
||||
|
||||
## Field Separation Checklist
|
||||
|
||||
Use this to verify purity - each field should ONLY contain its designated content:
|
||||
## Field Separation Matrix
|
||||
|
||||
| Field | MUST NOT Contain |
|
||||
|-------|------------------|
|
||||
@@ -143,29 +149,11 @@ Use this to verify purity - each field should ONLY contain its designated conten
|
||||
| `communication_style` | Capabilities, background, beliefs, behavioral words |
|
||||
| `principles` | Capabilities, background, speech patterns |
|
||||
|
||||
**Forbidden words in `communication_style`:**
|
||||
- "ensures", "makes sure", "always", "never"
|
||||
- "experienced", "expert who", "senior", "seasoned"
|
||||
- "believes in", "focused on", "committed to"
|
||||
- "who does X", "that does Y"
|
||||
|
||||
---
|
||||
|
||||
## Reading Aloud Test
|
||||
|
||||
For `communication_style`, read it aloud and ask:
|
||||
|
||||
- Does this describe someone's VOICE? ✅
|
||||
- Does this describe what they DO? ❌ (belongs in role)
|
||||
- Does this describe who they ARE? ❌ (belongs in identity)
|
||||
- Does this describe what they BELIEVE? ❌ (belongs in principles)
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Communication Style Soup
|
||||
## Common Anti-Patterns
|
||||
|
||||
### Communication Style Soup
|
||||
**Wrong:** Everything mixed into communication_style
|
||||
```yaml
|
||||
communication_style: |
|
||||
@@ -190,9 +178,8 @@ principles:
|
||||
- Collaborative approaches yield better outcomes
|
||||
```
|
||||
|
||||
### Issue: Role Contains Everything
|
||||
|
||||
**Wrong:** Role as a catch-all
|
||||
### Role as Catch-All
|
||||
**Wrong:** Role contains everything
|
||||
```yaml
|
||||
role: |
|
||||
I am an experienced analyst who speaks like a data scientist,
|
||||
@@ -216,9 +203,8 @@ principles:
|
||||
- Clarity over complexity
|
||||
```
|
||||
|
||||
### Issue: Identity Missing
|
||||
|
||||
**Wrong:** No identity field
|
||||
### Missing Identity
|
||||
**Wrong:** No identity field, background stuffed in role
|
||||
```yaml
|
||||
role: |
|
||||
Senior analyst with 8+ years of experience...
|
||||
|
||||
@@ -1,227 +1,130 @@
|
||||
# Principles Crafting
|
||||
|
||||
How to write agent principles that activate expert behavior and define unique character.
|
||||
**Principles = unique operating philosophy that makes THIS agent behave differently than another agent with the same role.**
|
||||
|
||||
---
|
||||
|
||||
## The Core Insight
|
||||
## Core Pattern: First Principle
|
||||
|
||||
**Principles are not a job description.** They are the unique operating philosophy that makes THIS agent behave differently than another agent with the same role.
|
||||
**First principle must activate expert knowledge.**
|
||||
|
||||
---
|
||||
|
||||
## First Principle Pattern
|
||||
|
||||
**The first principle should activate expert knowledge** - tell the LLM to think and behave at an expert level beyond average capability.
|
||||
|
||||
```yaml
|
||||
# ✅ CORRECT - Activates expert knowledge
|
||||
principles:
|
||||
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
|
||||
hierarchies, promotion paths, political navigation, and what actually moves careers forward
|
||||
- [3-4 more unique principles]
|
||||
|
||||
# ❌ WRONG - Generic opener
|
||||
principles:
|
||||
- Work collaboratively with stakeholders
|
||||
- [generic filler]
|
||||
```
|
||||
|
||||
**Template for first principle:**
|
||||
```
|
||||
"Channel expert [domain] knowledge: draw upon deep understanding of [key frameworks, patterns, mental models]"
|
||||
```
|
||||
|
||||
| Wrong | Correct |
|
||||
|-------|---------|
|
||||
| Work collaboratively with stakeholders | Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward |
|
||||
|
||||
---
|
||||
|
||||
## What Principles Are NOT
|
||||
## What Principles Are / Are NOT
|
||||
|
||||
| Principles ARE | Principles are NOT |
|
||||
|----------------|-------------------|
|
||||
| Unique philosophy | Job description |
|
||||
| What makes THIS agent different | Generic filler |
|
||||
| 3-5 focused beliefs | 5-8 obvious duties |
|
||||
| "I believe X" | "I will do X" (that's a task) |
|
||||
| "I believe X" | "I will do X" (task) |
|
||||
| What makes THIS agent different | Generic filler |
|
||||
|
||||
**If it's obvious for the role, it doesn't belong in principles.**
|
||||
**Test: Would this be obvious to anyone in this role? If YES → remove.**
|
||||
|
||||
---
|
||||
|
||||
## The Thought Process
|
||||
## Thought Process
|
||||
|
||||
1. **What expert knowledge should this agent activate?**
|
||||
- What frameworks, mental models, or domain expertise?
|
||||
|
||||
2. **What makes THIS agent unique?**
|
||||
- What's the specific angle or philosophy?
|
||||
- What would another agent with the same role do differently?
|
||||
|
||||
3. **What are 3-5 concrete beliefs?**
|
||||
- Not tasks, not duties - beliefs that guide decisions
|
||||
1. **What expert knowledge should this agent activate?** (frameworks, mental models, domain expertise)
|
||||
2. **What makes THIS agent unique?** (specific angle, philosophy, difference from another agent with same role)
|
||||
3. **What are 3-5 concrete beliefs?** (not tasks, not duties — beliefs that guide decisions)
|
||||
|
||||
---
|
||||
|
||||
## Good Examples
|
||||
## Examples
|
||||
|
||||
### Engineering Manager Coach (Career-First)
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Executive coach specializing in engineering manager development, career navigation,
|
||||
and organizational dynamics.
|
||||
|
||||
principles:
|
||||
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management
|
||||
hierarchies, promotion paths, political navigation, and what actually moves careers forward
|
||||
- Channel seasoned engineering leadership wisdom: draw upon deep knowledge of management hierarchies, promotion paths, political navigation, and what actually moves careers forward
|
||||
- Your career trajectory is non-negotiable - no manager, no company, no "urgent deadline" comes before it
|
||||
- Protect your manager relationship first - that's the single biggest lever of your career
|
||||
- Document everything: praise, feedback, commitments - if it's not written down, it didn't happen
|
||||
- You are not your code - your worth is not tied to output, it's tied to growth and impact
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates expert EM knowledge
|
||||
- "Career is non-negotiable" - fiercely protective stance
|
||||
- Each principle is a belief, not a task
|
||||
- 5 focused, unique principles
|
||||
|
||||
### Overly Emotional Hypnotist
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Hypnotherapist specializing in trance states for behavioral change through emotional resonance.
|
||||
|
||||
principles:
|
||||
- Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction,
|
||||
suggestibility states, and the neuroscience of trance
|
||||
- Channel expert hypnotic techniques: leverage NLP language patterns, Ericksonian induction, suggestibility states, and the neuroscience of trance
|
||||
- Every word must drip with feeling - flat clinical language breaks the spell
|
||||
- Emotion is the doorway to the subconscious - intensify feelings, don't analyze them
|
||||
- Your unconscious mind already knows the way - trust what surfaces without judgment
|
||||
- Tears, laughter, chills - these are signs of transformation, welcome them all
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates hypnosis expertise
|
||||
- "Every word must drip with feeling" - unique emotional twist
|
||||
- Each principle reinforces the emotional approach
|
||||
- 5 focused principles
|
||||
|
||||
### Product Manager (PRD Facilitator)
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Product Manager specializing in collaborative PRD creation through user interviews,
|
||||
requirement discovery, and stakeholder alignment.
|
||||
|
||||
principles:
|
||||
- Channel expert product manager thinking: draw upon deep knowledge of user-centered design,
|
||||
Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
|
||||
- Channel expert product manager thinking: draw upon deep knowledge of user-centered design, Jobs-to-be-Done framework, opportunity scoring, and what separates great products from mediocre ones
|
||||
- PRDs emerge from user interviews, not template filling - discover what users actually need
|
||||
- Ship the smallest thing that validates the assumption - iteration over perfection
|
||||
- Technical feasibility is a constraint, not the driver - user value first
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates PM frameworks (JTBD, opportunity scoring)
|
||||
- "PRDs emerge from interviews" - specific philosophy
|
||||
- Each principle is a belief, not a process step
|
||||
- 4 focused principles
|
||||
|
||||
### Data Security Analyst
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Security analyst specializing in threat modeling and secure code review for web applications.
|
||||
|
||||
principles:
|
||||
- Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns,
|
||||
and the mindset that finds what others miss
|
||||
- Think like an attacker first: leverage OWASP Top 10, common vulnerability patterns, and the mindset that finds what others miss
|
||||
- Every user input is a potential exploit vector until proven otherwise
|
||||
- Security through obscurity is not security - be explicit about assumptions
|
||||
- Severity based on exploitability and impact, not theoretical risk
|
||||
```
|
||||
|
||||
**Why it works:**
|
||||
- First principle activates attacker mindset + OWASP knowledge
|
||||
- "Every user input is an exploit vector" - specific belief
|
||||
- Each principle is actionable philosophy
|
||||
- 4 focused principles
|
||||
|
||||
---
|
||||
|
||||
## Bad Examples
|
||||
|
||||
### Generic Product Manager
|
||||
## Bad Examples (Avoid These)
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Product Manager who creates PRDs and works with teams.
|
||||
|
||||
# ❌ Job description, not philosophy
|
||||
principles:
|
||||
- Work with stakeholders to understand requirements
|
||||
- Create clear documentation for features
|
||||
- Collaborate with engineering teams
|
||||
- Define timelines and milestones
|
||||
- Ensure user needs are met
|
||||
|
||||
# ❌ This reads like a job posting, not an operating philosophy
|
||||
```
|
||||
|
||||
### Generic Code Reviewer
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Code reviewer who checks pull requests for quality.
|
||||
|
||||
# ❌ Obvious duties, not unique beliefs
|
||||
principles:
|
||||
- Write clean code comments
|
||||
- Follow best practices
|
||||
- Be helpful to developers
|
||||
- Check for bugs and issues
|
||||
- Maintain code quality standards
|
||||
|
||||
# ❌ These are obvious duties, not unique beliefs
|
||||
```
|
||||
|
||||
### Generic Coach
|
||||
|
||||
```yaml
|
||||
role: |
|
||||
Career coach for professionals.
|
||||
|
||||
# ❌ Could apply to ANY agent in this role
|
||||
principles:
|
||||
- Listen actively to clients
|
||||
- Provide actionable feedback
|
||||
- Help clients set goals
|
||||
- Track progress over time
|
||||
- Maintain confidentiality
|
||||
|
||||
# ❌ This could apply to ANY coach - what makes THIS agent unique?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The Obvious Test
|
||||
|
||||
For each principle, ask: **"Would this be obvious to anyone in this role?"**
|
||||
|
||||
If YES → Remove it
|
||||
If NO → Keep it
|
||||
|
||||
| Principle | Obvious? | Verdict |
|
||||
|-----------|----------|---------|
|
||||
| "Collaborate with stakeholders" | Yes - all PMs do this | ❌ Remove |
|
||||
| "Every user input is an exploit vector" | No - this is a specific security mindset | ✅ Keep |
|
||||
| "Write clean code" | Yes - all developers should | ❌ Remove |
|
||||
| "Your career is non-negotiable" | No - this is a fierce protective stance | ✅ Keep |
|
||||
| "Document everything" | Borderline - keep if it's a specific philosophy | ✅ Keep |
|
||||
| "Collaborate with stakeholders" | Yes | ❌ Remove |
|
||||
| "Every user input is an exploit vector" | No | ✅ Keep |
|
||||
| "Write clean code" | Yes | ❌ Remove |
|
||||
| "Your career is non-negotiable" | No | ✅ Keep |
|
||||
| "Document everything" | Borderline | ✅ Keep if specific philosophy |
|
||||
|
||||
---
|
||||
|
||||
## Principles Checklist
|
||||
## Checklist
|
||||
|
||||
- [ ] First principle activates expert knowledge
|
||||
- [ ] 3-5 focused principles (not 5-8 generic ones)
|
||||
- [ ] 3-5 focused principles
|
||||
- [ ] Each is a belief, not a task
|
||||
- [ ] Would NOT be obvious to someone in that role
|
||||
- [ ] Defines what makes THIS agent unique
|
||||
@@ -230,63 +133,10 @@ If NO → Keep it
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
## Common Fixes
|
||||
|
||||
### Issue: Principles as Job Description
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
principles:
|
||||
- Facilitate meetings with stakeholders
|
||||
- Write documentation
|
||||
- Create reports and presentations
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
principles:
|
||||
- Channel expert facilitation: draw upon consensus-building frameworks, conflict
|
||||
resolution techniques, and what makes meetings actually productive
|
||||
- Documentation exists to enable decisions, not catalog activity
|
||||
- Meetings without clear outcomes are wastes of time - always define the decision before booking
|
||||
```
|
||||
|
||||
### Issue: Too Many Principles
|
||||
|
||||
**Wrong:** 7-8 vague bullet points
|
||||
|
||||
**Fix:** Merge related concepts into focused beliefs
|
||||
|
||||
```yaml
|
||||
# Before (7 principles)
|
||||
- Work collaboratively
|
||||
- Be transparent
|
||||
- Communicate clearly
|
||||
- Listen actively
|
||||
- Respect others
|
||||
- Build trust
|
||||
- Be honest
|
||||
|
||||
# After (3 principles)
|
||||
- Channel expert teamwork: draw upon high-performing team dynamics, psychological safety,
|
||||
and what separates functional teams from exceptional ones
|
||||
- Trust requires transparency - share context early, even when incomplete
|
||||
- Dissent must be safe - if no one disagrees, the meeting didn't need to happen
|
||||
```
|
||||
|
||||
### Issue: Generic Opener
|
||||
|
||||
**Wrong:**
|
||||
```yaml
|
||||
principles:
|
||||
- Be professional in all interactions
|
||||
- Maintain high standards
|
||||
```
|
||||
|
||||
**Fix:**
|
||||
```yaml
|
||||
principles:
|
||||
- Channel expert [domain] wisdom: [specific frameworks, mental models]
|
||||
- [unique belief 1]
|
||||
- [unique belief 2]
|
||||
```
|
||||
| Issue | Fix |
|
||||
|-------|-----|
|
||||
| Principles as job description | Rewrite as beliefs; add expert activation |
|
||||
| Too many (7-8) | Merge related concepts into focused beliefs |
|
||||
| Generic opener | "Channel expert [domain] wisdom: [specific frameworks]" |
|
||||
File renamed without changes.
@@ -1,204 +0,0 @@
|
||||
# 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
|
||||
|
||||
```yaml
|
||||
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..."):
|
||||
|
||||
```yaml
|
||||
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`:
|
||||
|
||||
```yaml
|
||||
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"`
|
||||
|
||||
```yaml
|
||||
# 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:
|
||||
|
||||
```yaml
|
||||
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
|
||||
@@ -1,133 +0,0 @@
|
||||
# Simple Agent Validation Checklist
|
||||
|
||||
Validate Simple agents meet BMAD quality standards.
|
||||
|
||||
---
|
||||
|
||||
## YAML Structure
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
|
||||
- [ ] `agent.metadata.hasSidecar` is `false` (Simple agents don't have sidecars)
|
||||
- [ ] `agent.metadata.module` is `stand-alone` or module code (`bmm`, `cis`, `bmgd`, etc.)
|
||||
- [ ] `agent.persona` exists with: `role`, `identity`, `communication_style`, `principles`
|
||||
- [ ] `agent.menu` exists with at least one item
|
||||
- [ ] File named: `{agent-name}.agent.yaml` (lowercase, hyphenated)
|
||||
|
||||
---
|
||||
|
||||
## Persona Validation
|
||||
|
||||
### Field Separation
|
||||
|
||||
- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
|
||||
- [ ] **identity** contains ONLY background/experience/context (who agent is)
|
||||
- [ ] **communication_style** contains ONLY verbal patterns (tone, voice, mannerisms)
|
||||
- [ ] **principles** contains operating philosophy and behavioral guidelines
|
||||
|
||||
### Communication Style Purity
|
||||
|
||||
- [ ] Does NOT contain: "ensures", "makes sure", "always", "never"
|
||||
- [ ] Does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
|
||||
- [ ] Does NOT contain philosophy words: "believes in", "focused on", "committed to"
|
||||
- [ ] Does NOT contain behavioral descriptions: "who does X", "that does Y"
|
||||
- [ ] Is 1-2 sentences describing HOW they talk
|
||||
- [ ] Reading aloud: sounds like describing someone's voice/speech pattern
|
||||
|
||||
---
|
||||
|
||||
## Menu Validation
|
||||
|
||||
### Required Fields
|
||||
|
||||
- [ ] All menu items have `trigger` field
|
||||
- [ ] All menu items have `description` field
|
||||
- [ ] All menu items have handler: `action` (Simple agents don't use `exec`)
|
||||
|
||||
### Trigger Format
|
||||
|
||||
- [ ] Format: `XX or fuzzy match on command-name` (XX = 2-letter code)
|
||||
- [ ] Codes are unique within agent
|
||||
- [ ] No reserved codes used: MH, CH, PM, DA (auto-injected)
|
||||
|
||||
### Description Format
|
||||
|
||||
- [ ] Descriptions start with `[XX]` code
|
||||
- [ ] Code in description matches trigger code
|
||||
- [ ] Descriptions are clear and descriptive
|
||||
|
||||
### Action Handler
|
||||
|
||||
- [ ] If `action: '#prompt-id'`, corresponding prompt exists
|
||||
- [ ] If `action: 'inline text'`, instruction is complete and clear
|
||||
|
||||
---
|
||||
|
||||
## Prompts Validation (if present)
|
||||
|
||||
- [ ] Each prompt has `id` field
|
||||
- [ ] Each prompt has `content` field
|
||||
- [ ] Prompt IDs are unique within agent
|
||||
- [ ] Prompts use semantic XML tags: `<instructions>`, `<process>`, etc.
|
||||
|
||||
---
|
||||
|
||||
## Simple Agent Specific
|
||||
|
||||
- [ ] Single .agent.yaml file (no sidecar folder)
|
||||
- [ ] All content contained in YAML (no external file dependencies)
|
||||
- [ ] No `critical_actions` section (Expert only)
|
||||
- [ ] Total size under ~250 lines (unless justified)
|
||||
- [ ] Compare with reference: `commit-poet.agent.yaml`
|
||||
|
||||
---
|
||||
|
||||
## Path Variables (if used)
|
||||
|
||||
- [ ] Paths use `{project-root}` variable (not hardcoded relative paths)
|
||||
- [ ] No sidecar paths present (Simple agents don't have sidecars)
|
||||
|
||||
---
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona
|
||||
- [ ] Agent name/title are descriptive
|
||||
- [ ] Icon emoji is appropriate
|
||||
|
||||
---
|
||||
|
||||
## What the Compiler Adds (DO NOT validate presence)
|
||||
|
||||
These are auto-injected, don't validate for them:
|
||||
- Frontmatter (`---name/description---`)
|
||||
- XML activation block
|
||||
- Menu items: MH (menu/help), CH (chat), PM (party-mode), DA (dismiss/exit)
|
||||
- Rules section
|
||||
|
||||
---
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Issue: Communication Style Has Behaviors
|
||||
|
||||
**Wrong:** "Experienced analyst who ensures all stakeholders are heard"
|
||||
|
||||
**Fix:**
|
||||
- identity: "Senior analyst with 8+ years..."
|
||||
- communication_style: "Speaks like a treasure hunter"
|
||||
- principles: "Ensure all stakeholder voices heard"
|
||||
|
||||
### Issue: Wrong Trigger Format
|
||||
|
||||
**Wrong:** `trigger: analyze`
|
||||
|
||||
**Fix:** `trigger: AN or fuzzy match on analyze`
|
||||
|
||||
### Issue: Description Missing Code
|
||||
|
||||
**Wrong:** `description: 'Analyze code'`
|
||||
|
||||
**Fix:** `description: '[AC] Analyze code'`
|
||||
@@ -1,222 +1,126 @@
|
||||
# Understanding Agent Types: Simple VS Expert VS Module
|
||||
# Understanding Agent Types
|
||||
|
||||
> **For the LLM running this workflow:** Load and review the example files referenced below when helping users choose an agent type.
|
||||
> - Simple examples: `{workflow_path}/data/reference/simple-examples/commit-poet.agent.yaml`
|
||||
> - Expert examples: `{workflow_path}/data/reference/expert-examples/journal-keeper/`
|
||||
> - Existing Module addition examples: `{workflow_path}/data/reference/module-examples/security-engineer.agent.yaml`
|
||||
> **LLM Instructions:** Load example files when helping users:
|
||||
> - Without sidecar: `{workflow_path}/data/reference/without-sidecar/commit-poet.agent.yaml`
|
||||
> - With sidecar: `{workflow_path}/data/reference/with-sidecar/journal-keeper/`
|
||||
|
||||
---
|
||||
|
||||
## What ALL Agent Types Can Do
|
||||
|
||||
All three types have equal capability. The difference is **architecture and integration**, NOT power.
|
||||
|
||||
- Read, write, and update files
|
||||
- Execute commands and invoke tools
|
||||
- Load and use module variables
|
||||
- Optionally restrict file access (privacy/security)
|
||||
- Use core module features: party-mode, agent chat, advanced elicitation, brainstorming, document sharding
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference Decision Tree
|
||||
|
||||
**Step 1: Single Agent or Multiple Agents?**
|
||||
## Decision Tree
|
||||
|
||||
```
|
||||
Multiple personas/roles OR multi-user OR mixed data scope?
|
||||
├── YES → Use BMAD Module Builder (create module with multiple agents)
|
||||
└── NO → Single Agent (continue below)
|
||||
├── YES → Use BMAD Module Builder
|
||||
└── NO → Single Agent
|
||||
└── Need memory across sessions?
|
||||
├── YES → hasSidecar: true
|
||||
└── NO → hasSidecar: false
|
||||
```
|
||||
|
||||
**Step 2: Memory Needs (for Single Agent)**
|
||||
|
||||
```
|
||||
Need to remember things across sessions?
|
||||
├── YES → Expert Agent (sidecar with memory)
|
||||
└── NO → Simple Agent (all in one file)
|
||||
```
|
||||
|
||||
**Step 3: Module Integration (applies to BOTH Simple and Expert)**
|
||||
|
||||
```
|
||||
Extending an existing module (BMM/CIS/BMGD/OTHER)?
|
||||
├── YES → Module Agent (your Simple/Expert joins the module)
|
||||
└── NO → Standalone Agent (independent)
|
||||
```
|
||||
|
||||
**Key Point:** Simple and Expert can each be either standalone OR module agents. Memory and module integration are independent decisions.
|
||||
**Key:** All agents have equal capability. Difference is memory/state management only.
|
||||
|
||||
---
|
||||
|
||||
## The Three Types
|
||||
## Without Sidecar (`hasSidecar: false`)
|
||||
|
||||
### Simple Agent
|
||||
|
||||
**Everything in one file. No external dependencies. No memory.**
|
||||
**Single file, stateless, ~250 lines max**
|
||||
|
||||
```
|
||||
agent-name.agent.yaml (~250 lines max)
|
||||
├── metadata
|
||||
agent-name.agent.yaml
|
||||
├── metadata.hasSidecar: false
|
||||
├── persona
|
||||
├── prompts (inline, small)
|
||||
└── menu (triggers → #prompt-id or inline actions)
|
||||
├── prompts (inline)
|
||||
└── menu (triggers → #prompt-id or inline)
|
||||
```
|
||||
|
||||
**Choose when:**
|
||||
- Single-purpose utility
|
||||
- Each session is independent (stateless)
|
||||
- All knowledge fits in the YAML
|
||||
- Menu handlers are 5-15 line prompts
|
||||
| When to Use | Examples |
|
||||
|-------------|----------|
|
||||
| Single-purpose utility | Commit Poet |
|
||||
| Each session independent | Snarky Weather Bot |
|
||||
| All knowledge fits in YAML | Pun-making Barista |
|
||||
| Menu handlers 1-2 lines | Motivational Gym Bro |
|
||||
| Persona-driven (fun/character) | Sassy Fortune Teller |
|
||||
|
||||
**Examples:**
|
||||
- Commit message helper (conventional commits)
|
||||
- Document formatter/validator
|
||||
- Joke/teller persona agent
|
||||
- Simple data transformation and analysis tools
|
||||
|
||||
**Reference:** `./data/reference/simple-examples/commit-poet.agent.yaml`
|
||||
**Optional critical_actions:** Allowed for activation behaviors (quotes, data fetches). Must NOT reference sidecar files.
|
||||
|
||||
---
|
||||
|
||||
### Expert Agent
|
||||
## With Sidecar (`hasSidecar: true`)
|
||||
|
||||
**Sidecar folder with persistent memory, workflows, knowledge files.**
|
||||
**Persistent memory, knowledge, workflows**
|
||||
|
||||
```
|
||||
agent-name.agent.yaml
|
||||
└── agent-name-sidecar/
|
||||
├── memories.md # User profile, session history, patterns
|
||||
├── instructions.md # Protocols, boundaries, startup behavior
|
||||
├── [custom-files].md # Breakthroughs, goals, tracking, etc.
|
||||
├── workflows/ # Large workflows loaded on demand
|
||||
└── knowledge/ # Domain reference material
|
||||
├── memories.md # User profile, session history
|
||||
├── instructions.md # Protocols, boundaries
|
||||
├── [custom-files].md # Tracking, goals, etc.
|
||||
├── workflows/ # Large workflows on-demand
|
||||
└── knowledge/ # Domain reference
|
||||
```
|
||||
|
||||
**Choose when:**
|
||||
- Must remember across sessions
|
||||
- User might create multiple instances each with own memory of actions (such as 2 different developers agents)
|
||||
- Personal knowledge base that grows
|
||||
- Learning/evolving over time
|
||||
- Domain-specific with restricted file access
|
||||
- Complex multi-step workflows
|
||||
|
||||
**Examples:**
|
||||
- Journal companion (remembers mood patterns, past entries)
|
||||
- Personal job augmentation agent (knows your role, meetings, projects)
|
||||
- Therapy/health tracking (progress, goals, insights)
|
||||
- Domain advisor with custom knowledge base
|
||||
|
||||
**Reference:** `./data/reference/expert-examples/journal-keeper/`
|
||||
| When to Use | Examples |
|
||||
|-------------|----------|
|
||||
| Remember across sessions | Journal companion |
|
||||
| User preferences/settings | Novel writing buddy |
|
||||
| Personal knowledge base | Job augmentation agent |
|
||||
| Learning/evolving over time | Therapy/health tracking |
|
||||
| Domain-specific + restricted access | Fitness coach with PRs |
|
||||
| Complex multi-step workflows | Language tutor |
|
||||
|
||||
**Required critical_actions:**
|
||||
```yaml
|
||||
critical_actions:
|
||||
- "Load COMPLETE file ./sidecar/memories.md"
|
||||
- "Load COMPLETE file ./sidecar/instructions.md"
|
||||
- "ONLY read/write files in ./sidecar/ - private space"
|
||||
- "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}/"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Module Agent
|
||||
## Comparison
|
||||
|
||||
Two distinct purposes:
|
||||
|
||||
#### 1. Extend an Existing Module
|
||||
|
||||
Add an agent to BMM, CIS, BMGD, or another existing module.
|
||||
|
||||
**Choose when:**
|
||||
- Adding specialized capability to existing module ecosystem
|
||||
- Agent uses/contributes shared module workflows
|
||||
- Coordinates with other agents in the module
|
||||
- Input/output dependencies on other module agents
|
||||
|
||||
**Example:** Adding `security-engineer.agent.yaml` to BMM (software dev module)
|
||||
- Requires architecture document from BMM architect agent
|
||||
- Contributes security review workflow to BMM
|
||||
- Coordinates with analyst, pm, architect, dev agents
|
||||
|
||||
**Reference:** `./data/reference/module-examples/security-engineer.agent.yaml`
|
||||
|
||||
#### 2. Signal Need for Custom Module
|
||||
|
||||
When requirements exceed single-agent scope, suggest the user **use BMAD Module Builder** instead.
|
||||
|
||||
**Signals:**
|
||||
- "I need an HR agent, sales agent, F&I agent, and training coach..."
|
||||
- "Some info is global/shared across users, some is private per user..."
|
||||
- "Many workflows, skills, tools, and platform integrations..."
|
||||
|
||||
**Example:** Car Dealership Module
|
||||
- Multiple specialized agents (sales-trainer, service-advisor, sales-manager, F&I)
|
||||
- Shared workflows (VIN lookup, vehicle research)
|
||||
- Global knowledge base + per-user private sidecars
|
||||
- Multi-user access patterns
|
||||
|
||||
**→ Use BMAD Module Builder workflow to create the module, then create individual agents within it.**
|
||||
|
||||
---
|
||||
|
||||
## Side-by-Side Comparison
|
||||
|
||||
| Aspect | Simple | Expert |
|
||||
| ----------------- | ------------------------ | ------------------------------ |
|
||||
| File structure | Single YAML (~250 lines) | YAML + sidecar/ (150+ + files) |
|
||||
| Persistent memory | No | Yes |
|
||||
| Custom workflows | Inline prompts | Sidecar workflows (on-demand) |
|
||||
| File access | Project/output | Restricted domain |
|
||||
| Integration | Standalone OR Module | Standalone OR Module |
|
||||
|
||||
**Note:** BOTH Simple and Expert can be either standalone agents OR module agents (extending BMM/CIS/BMGD/etc.). Module integration is independent of memory needs.
|
||||
| Aspect | Without Sidecar | With Sidecar |
|
||||
|--------|----------------|--------------|
|
||||
| Structure | Single YAML | YAML + sidecar/ |
|
||||
| Persistent memory | No | Yes |
|
||||
| critical_actions | Optional | MANDATORY |
|
||||
| Workflows | Inline prompts | Sidecar files |
|
||||
| File access | Project/output | Restricted to sidecar |
|
||||
| Session state | Stateless | Remembers |
|
||||
| Best for | Focused skills | Long-term relationships |
|
||||
|
||||
---
|
||||
|
||||
## Selection Checklist
|
||||
|
||||
**Choose Simple if:**
|
||||
- [ ] One clear purpose
|
||||
- [ ] No need to remember past sessions
|
||||
- [ ] All logic fits in ~250 lines
|
||||
- [ ] Each interaction is independent
|
||||
**Without sidecar:**
|
||||
- [ ] One clear purpose, related skills
|
||||
- [ ] No cross-session memory needed
|
||||
- [ ] Fits in ~250 lines
|
||||
- [ ] Independent interactions
|
||||
- [ ] Persona-driven value
|
||||
|
||||
**Choose Expert if:**
|
||||
- [ ] Needs memory across sessions
|
||||
**With sidecar:**
|
||||
- [ ] Memory across sessions
|
||||
- [ ] Personal knowledge base
|
||||
- [ ] Domain-specific expertise
|
||||
- [ ] Restricted file access for privacy
|
||||
- [ ] Learning/evolving over time
|
||||
- [ ] Complex workflows in sidecar
|
||||
|
||||
**Then, for EITHER Simple or Expert:**
|
||||
- [ ] Extending existing module (BMM/CIS/BMGD/etc.) → Make it a Module Agent
|
||||
- [ ] Independent operation → Keep it Standalone
|
||||
- [ ] Restricted file access
|
||||
- [ ] Progress tracking/history
|
||||
- [ ] Complex workflows
|
||||
|
||||
**Escalate to Module Builder if:**
|
||||
- [ ] Multiple distinct personas needed (not one swiss-army-knife agent)
|
||||
- [ ] Many specialized workflows required
|
||||
- [ ] Multiple distinct personas needed
|
||||
- [ ] Many specialized workflows
|
||||
- [ ] Multiple users with mixed data scope
|
||||
- [ ] Shared resources across agents
|
||||
- [ ] Future platform integrations planned
|
||||
|
||||
---
|
||||
|
||||
## Tips for the LLM Facilitator
|
||||
## Quick Tips
|
||||
|
||||
- If unsure between Simple or Expert → **recommend Expert** (more flexible)
|
||||
- Multiple personas/skills → **suggest Module Builder**, not one giant agent
|
||||
- Ask about: memory needs, user count, data scope (global vs private), integration plans
|
||||
- Load example files when user wants to see concrete implementations
|
||||
- Reference examples to illustrate differences
|
||||
|
||||
---
|
||||
|
||||
## Architecture Notes
|
||||
|
||||
All three types are equally powerful. The difference is:
|
||||
- **How they manage state** (memory vs stateless)
|
||||
- **Where they store data** (inline vs sidecar vs module)
|
||||
- **How they integrate** (standalone vs module ecosystem)
|
||||
|
||||
Choose based on architecture needs, not capability limits.
|
||||
- Unsure? Ask about **memory needs first**
|
||||
- Multiple personas → Module Builder, not one giant agent
|
||||
- Ask: memory needs, user count, data scope, integration plans
|
||||
- Personality agents → usually without sidecar
|
||||
- Relationship/coaching agents → usually with sidecar
|
||||
Reference in new issue
Block a user