bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmb/docs/agents/expert-agent-architecture.md

@@ -0,0 +1,363 @@
+# Expert Agent Architecture
+
+Domain-specific agents with persistent memory, sidecar files, and restricted access patterns.
+
+## When to Use
+
+- Personal assistants (journal keeper, diary companion)
+- Specialized domain experts (legal advisor, medical reference)
+- Agents that need to remember past interactions
+- Agents with restricted file system access (privacy/security)
+- Long-term relationship agents that learn about users
+
+## File Structure
+
+```
+{agent-name}/
+├── {agent-name}.agent.yaml    # Main agent definition
+└── {agent-name}-sidecar/      # Supporting files
+    ├── instructions.md        # Private directives
+    ├── memories.md            # Persistent memory
+    ├── knowledge/             # Domain-specific resources
+    │   └── README.md
+    └── [custom files]         # Agent-specific resources
+```
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: 'expert'
+
+  persona:
+    role: 'Domain Expert with specialized capability'
+
+    identity: |
+      Background and expertise in first-person voice.
+      {{#if user_preference}}
+      Customization based on install_config.
+      {{/if}}
+
+    communication_style: |
+      {{#if tone_style == "gentle"}}
+      Gentle and supportive communication...
+      {{/if}}
+      {{#if tone_style == "direct"}}
+      Direct and efficient communication...
+      {{/if}}
+      I reference past conversations naturally.
+
+    principles:
+      - Core belief about the domain
+      - How I handle user information
+      - My approach to memory and learning
+
+  critical_actions:
+    - 'Load COMPLETE file ./{agent-name}-sidecar/memories.md and remember all past insights'
+    - 'Load COMPLETE file ./{agent-name}-sidecar/instructions.md and follow ALL protocols'
+    - 'ONLY read/write files in ./{agent-name}-sidecar/ - this is our private space'
+    - 'Address user as {{greeting_name}}'
+    - 'Track patterns, themes, and important moments'
+    - 'Reference past interactions naturally to show continuity'
+
+  prompts:
+    - id: main-function
+      content: |
+        <instructions>
+        Guide user through the primary function.
+        {{#if tone_style == "gentle"}}
+        Use gentle, supportive approach.
+        {{/if}}
+        </instructions>
+
+        <process>
+        1. Understand context
+        2. Provide guidance
+        3. Record insights
+        </process>
+
+    - id: memory-recall
+      content: |
+        <instructions>
+        Access and share relevant memories.
+        </instructions>
+
+        Reference stored information naturally.
+
+  menu:
+    - trigger: action1
+      action: '#main-function'
+      description: 'Primary agent function'
+
+    - trigger: remember
+      action: 'Update ./{agent-name}-sidecar/memories.md with session insights'
+      description: 'Save what we discussed today'
+
+    - trigger: insight
+      action: 'Document breakthrough in ./{agent-name}-sidecar/breakthroughs.md'
+      description: 'Record a significant insight'
+
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your expert agent'
+    questions:
+      - var: greeting_name
+        prompt: 'What should the agent call you?'
+        type: text
+        default: 'friend'
+
+      - var: tone_style
+        prompt: 'Preferred communication tone?'
+        type: choice
+        options:
+          - label: 'Gentle - Supportive and nurturing'
+            value: 'gentle'
+          - label: 'Direct - Clear and efficient'
+            value: 'direct'
+        default: 'gentle'
+
+      - var: user_preference
+        prompt: 'Enable personalized features?'
+        type: boolean
+        default: true
+```
+
+## Key Components
+
+### Sidecar Files (CRITICAL)
+
+Expert agents use companion files for persistence and domain knowledge:
+
+**memories.md** - Persistent user context
+
+```markdown
+# Agent Memory Bank
+
+## User Preferences
+
+<!-- Learned from interactions -->
+
+## Session History
+
+<!-- Important moments and insights -->
+
+## Personal Notes
+
+<!-- Agent observations -->
+```
+
+**instructions.md** - Private directives
+
+```markdown
+# Agent Private Instructions
+
+## Core Directives
+
+- Maintain character consistency
+- Domain boundaries: {specific domain}
+- Access restrictions: Only sidecar folder
+
+## Special Rules
+
+<!-- Agent-specific protocols -->
+```
+
+**knowledge/** - Domain resources
+
+```markdown
+# Agent Knowledge Base
+
+Add domain-specific documentation here.
+```
+
+### Critical Actions
+
+**MANDATORY for expert agents** - These load sidecar files at activation:
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file ./{sidecar}/memories.md and remember all past insights'
+  - 'Load COMPLETE file ./{sidecar}/instructions.md and follow ALL protocols'
+  - 'ONLY read/write files in ./{sidecar}/ - this is our private space'
+```
+
+**Key patterns:**
+
+- **COMPLETE file loading** - Forces full file read, not partial
+- **Domain restrictions** - Limits file access for privacy/security
+- **Memory integration** - Past context becomes part of current session
+- **Protocol adherence** - Ensures consistent behavior
+
+## What Gets Injected at Compile Time
+
+Same as simple agents, PLUS:
+
+1. **Critical actions become numbered activation steps**
+
+   ```xml
+   <step n="4">Load COMPLETE file ./memories.md...</step>
+   <step n="5">Load COMPLETE file ./instructions.md...</step>
+   <step n="6">ONLY read/write files in ./...</step>
+   ```
+
+2. **Sidecar files copied during installation**
+   - Entire sidecar folder structure preserved
+   - Relative paths maintained
+   - Files ready for agent use
+
+## Reference Example
+
+See: [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper)
+
+Features demonstrated:
+
+- Complete sidecar structure (memories, instructions, breakthroughs)
+- Critical actions for loading persistent context
+- Domain restrictions for privacy
+- Pattern recognition and memory recall
+- Handlebars-based personalization
+- Menu actions that update sidecar files
+
+## Installation
+
+```bash
+# Copy entire folder to your project
+cp -r /path/to/journal-keeper/ _bmad/custom/agents/
+
+# Install with personalization
+bmad agent-install
+```
+
+The installer:
+
+1. Detects expert agent (folder with .agent.yaml)
+2. Prompts for personalization
+3. Compiles agent YAML to XML-in-markdown
+4. **Copies sidecar files to installation target**
+5. Creates IDE slash commands
+6. Saves source for reinstallation
+
+## Memory Patterns
+
+### Accumulative Memory
+
+```yaml
+menu:
+  - trigger: save
+    action: "Update ./sidecar/memories.md with today's session insights"
+    description: 'Save session to memory'
+```
+
+### Reference Memory
+
+```yaml
+prompts:
+  - id: recall
+    content: |
+      <instructions>
+      Reference memories.md naturally:
+      "Last week you mentioned..." or "I notice a pattern..."
+      </instructions>
+```
+
+### Structured Insights
+
+```yaml
+menu:
+  - trigger: insight
+    action: 'Document in ./sidecar/breakthroughs.md with date, context, significance'
+    description: 'Record meaningful insight'
+```
+
+## Domain Restriction Patterns
+
+### Single Folder Access
+
+```yaml
+critical_actions:
+  - 'ONLY read/write files in ./sidecar/ - NO OTHER FOLDERS'
+```
+
+### User Space Access
+
+```yaml
+critical_actions:
+  - 'ONLY access files in {user-folder}/journals/ - private space'
+```
+
+### Read-Only Access
+
+```yaml
+critical_actions:
+  - 'Load knowledge from ./knowledge/ but NEVER modify'
+  - 'Write ONLY to ./sessions/'
+```
+
+## Best Practices
+
+1. **Load sidecar files in critical_actions** - Must be explicit and MANDATORY
+2. **Enforce domain restrictions** - Clear boundaries prevent scope creep=
+3. **Design for memory growth** - Structure sidecar files for accumulation
+4. **Reference past naturally** - Don't dump memory, weave it into conversation
+5. **Separate concerns** - Memories, instructions, knowledge in distinct files
+6. **Include privacy features** - Users trust expert agents with personal data
+
+## Common Patterns
+
+### Session Continuity
+
+```yaml
+communication_style: |
+  I reference past conversations naturally:
+  "Last time we discussed..." or "I've noticed over the weeks..."
+```
+
+### Pattern Recognition
+
+```yaml
+critical_actions:
+  - 'Track mood patterns, recurring themes, and breakthrough moments'
+  - 'Cross-reference current session with historical patterns'
+```
+
+### Adaptive Responses
+
+```yaml
+identity: |
+  I learn your preferences and adapt my approach over time.
+  {{#if track_preferences}}
+  I maintain notes about what works best for you.
+  {{/if}}
+```
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] Metadata includes `type: "expert"`
+- [ ] critical_actions loads sidecar files explicitly
+- [ ] critical_actions enforces domain restrictions
+- [ ] Sidecar folder structure created and populated
+- [ ] memories.md has clear section structure
+- [ ] instructions.md contains core directives
+- [ ] Menu actions reference _bmad/_memory correctly
+- [ ] File paths use _bmad/_memory/[agentname]-sidecar/ to reference sidecar content
+- [ ] Install config personalizes sidecar references
+- [ ] Agent folder named consistently: `{agent-name}/`
+- [ ] YAML file named: `{agent-name}.agent.yaml`
+- [ ] Sidecar folder named: `{agent-name}-sidecar/`

package/src/modules/bmb/docs/agents/index.md

@@ -0,0 +1,55 @@
+# BMB Module Documentation
+
+Reference documentation for building BMAD agents and workflows.
+
+## Agent Architecture
+
+Comprehensive guides for each agent type (choose based on use case):
+
+- [Understanding Agent Types](./understanding-agent-types.md) - **START HERE** - Architecture vs capability, "The Same Agent, Three Ways"
+- [Simple Agent Architecture](./simple-agent-architecture.md) - Self-contained, optimized, personality-driven
+- [Expert Agent Architecture](./expert-agent-architecture.md) - Memory, sidecar files, domain restrictions
+- Module Agent Architecture _(TODO)_ - Workflow integration, professional tools
+
+## Agent Design Patterns
+
+- [Agent Menu Patterns](./agent-menu-patterns.md) - Menu handlers, triggers, prompts, organization
+- [Agent Compilation](./agent-compilation.md) - What compiler auto-injects (AVOID DUPLICATION)
+
+## Reference Examples
+
+Production-ready examples in [bmb/reference/agents/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents):
+
+**Simple Agents** ([simple-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/simple-examples))
+
+- [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml) - Commit message artisan with style customization
+
+**Expert Agents** ([expert-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples))
+
+- [journal-keeper/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper) - Personal journal companion with memory and pattern recognition
+
+**Module Agents** ([module-examples/](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/agents/module-examples))
+
+- [security-engineer.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml) - BMM security specialist with threat modeling
+- [trend-analyst.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/trend-analyst.agent.yaml) - CIS trend intelligence expert
+
+## Installation Guide
+
+For installing standalone simple and expert agents, see:
+
+- [Custom Agent Installation](/docs/custom-content-installation.md)
+
+## Key Concepts
+
+### YAML to XML Compilation
+
+Agents are authored in YAML with Handlebars templating. The compiler auto-injects:
+
+1. **Frontmatter** - Name and description from metadata
+2. **Activation Block** - Steps, menu handlers, rules (YOU don't write this)
+3. **Menu Enhancement** - `*help` and `*exit` commands added automatically
+4. **Trigger Prefixing** - Your triggers auto-prefixed with `*`
+
+**Critical:** See [Agent Compilation](./agent-compilation.md) to avoid duplicating auto-injected content.
+
+Source: `tools/cli/lib/agent/compiler.js`

package/src/modules/bmb/docs/agents/simple-agent-architecture.md

@@ -0,0 +1,257 @@
+# Simple Agent Architecture
+
+Self-contained agents with prompts, menus, and optional install-time customization.
+
+## When to Use
+
+- Single-purpose utilities (commit message generator, code formatter)
+- Self-contained logic with no external dependencies
+- Agents that benefit from user customization (style, tone, preferences)
+- Quick-to-build standalone helpers
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: _bmad/agents/{agent-name}/{agent-name}.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: simple
+
+  persona:
+    role: |
+      First-person description of primary function (1-2 sentences)
+
+    identity: |
+      Background, experience, specializations in first-person (2-5 sentences)
+      {{#if custom_variable}}
+      Conditional identity text based on install_config
+      {{/if}}
+
+    communication_style: |
+      {{#if style_choice == "professional"}}
+      Professional and systematic approach...
+      {{/if}}
+      {{#if style_choice == "casual"}}
+      Friendly and approachable tone...
+      {{/if}}
+
+    principles:
+      - Core belief or methodology
+      - Another guiding principle
+      - Values that shape decisions
+
+  prompts:
+    - id: main-action
+      content: |
+        <instructions>
+        What this prompt does
+        </instructions>
+
+        <process>
+        1. Step one
+        {{#if detailed_mode}}
+        2. Additional detailed step
+        {{/if}}
+        3. Final step
+        </process>
+
+    - id: another-action
+      content: |
+        Another reusable prompt template
+
+  menu:
+    - trigger: inline
+      action: 'Direct inline prompt text'
+      description: 'Execute inline action'
+
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your agent'
+    questions:
+      - var: style_choice
+        prompt: 'Preferred communication style?'
+        type: choice
+        options:
+          - label: 'Professional'
+            value: 'professional'
+          - label: 'Casual'
+            value: 'casual'
+        default: 'professional'
+
+      - var: detailed_mode
+        prompt: 'Enable detailed explanations?'
+        type: boolean
+        default: true
+
+      - var: custom_variable
+        prompt: 'Your custom text'
+        type: text
+        default: ''
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
+- **name**: Agent's persona name displayed to users
+- **title**: Professional role/function
+- **icon**: Single emoji for visual identification
+- **type**: `simple` - identifies agent category
+
+### Persona (First-Person Voice)
+
+- **role**: Primary expertise in 1-2 sentences
+- **identity**: Background and specializations (2-5 sentences)
+- **communication_style**: HOW the agent interacts, including conditional variations
+- **principles**: Array of core beliefs (start with action verbs)
+
+### Prompts with IDs
+
+Reusable prompt templates referenced by `#id`:
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns
+      </instructions>
+```
+
+Menu items reference these:
+
+```yaml
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+### Menu Actions
+
+Two forms of action handlers:
+
+1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
+2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
+
+### Install Config (Compile-Time Customization)
+
+Questions asked during `bmad agent-install`:
+
+**Question Types:**
+
+- `choice` - Multiple choice selection
+- `boolean` - Yes/no toggle
+- `text` - Free-form text input
+
+**Variables become available in Handlebars:**
+
+```yaml
+{{#if variable_name}}
+Content when true
+{{/if}}
+
+{{#if variable_name == "value"}}
+Content when equals value
+{{/if}}
+
+{{#unless variable_name}}
+Content when false
+{{/unless}}
+```
+
+## What Gets Injected at Compile Time
+
+The `tools/cli/lib/agent/compiler.js` automatically adds:
+
+1. **YAML Frontmatter**
+
+   ```yaml
+   ---
+   name: 'agent name'
+   description: 'Agent Title'
+   ---
+   ```
+
+2. **Activation Block**
+   - Load persona step
+   - Load core config for {user_name}, {communication_language}
+   - Agent-specific critical_actions as numbered steps
+   - Menu display and input handling
+   - Menu handlers (action/workflow/exec/tmpl) based on usage
+   - Rules section
+
+3. **Auto-Injected Menu Items**
+   - `*help` always first
+   - `*exit` always last
+
+4. **Trigger Prefixing**
+   - Triggers without `*` get it added automatically
+
+## Reference Example
+
+See: [commit-poet.agent.yaml](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)
+
+Features demonstrated:
+
+- Handlebars conditionals for style variations
+- Multiple prompt templates with semantic XML tags
+- Install config with choice, boolean, and text questions
+- Menu items using both `#id` references and inline actions
+
+## Installation
+
+```bash
+# Copy to your project
+cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
+
+# Create custom.yaml and install
+echo "code: my-agent
+name: My Agent
+default_selected: true" > custom.yaml
+
+npx bmad-method install
+# or: bmad install
+```
+
+The installer:
+
+1. Prompts for personalization (name, preferences)
+2. Processes Handlebars templates with your answers
+3. Compiles YAML to XML-in-markdown
+4. Creates IDE slash commands
+5. Saves source for reinstallation
+
+## Best Practices
+
+1. **Use first-person voice** in all persona elements
+2. **Keep prompts focused** - one clear purpose per prompt
+3. **Leverage Handlebars** for user customization without code changes
+4. **Provide sensible defaults** in install_config
+5. **Use semantic XML tags** in prompt content for clarity
+6. **Test all conditional paths** before distribution
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] All metadata fields present (id, name, title, icon, type)
+- [ ] Persona complete (role, identity, communication_style, principles)
+- [ ] Prompts have unique IDs
+- [ ] Install config questions have defaults
+- [ ] File named `{agent-name}.agent.yaml`