bmad-method 6.0.0-alpha.21 → 6.0.0-alpha.23

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

@@ -1,363 +0,0 @@
-# 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

@@ -1,55 +0,0 @@
-# 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

@@ -1,257 +0,0 @@
-# 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`