Ignore and untrack BMad directories
This commit is contained in:
Max
@@ -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
|
||||
Reference in New Issue
Block a user