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

package/src/modules/bmb/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/README.md

@@ -1,242 +0,0 @@
-# Expert Agent Reference: Personal Journal Keeper (Whisper)
-
-This folder contains a complete reference implementation of a **BMAD Expert Agent** - an agent with persistent memory and domain-specific resources via a sidecar folder.
-
-## Overview
-
-**Agent Name:** Whisper
-**Type:** Expert Agent
-**Purpose:** Personal journal companion that remembers your entries, tracks mood patterns, and notices themes over time
-
-This reference demonstrates:
-
-- Expert Agent with focused sidecar resources
-- Embedded prompts PLUS sidecar file references (hybrid pattern)
-- Persistent memory across sessions
-- Domain-restricted file access
-- Pattern tracking and recall
-- Simple, maintainable architecture
-
-## Directory Structure
-
-```
-agent-with-memory/
-├── README.md                          # This file
-├── journal-keeper.agent.yaml          # Main agent definition
-└── journal-keeper-sidecar/            # Agent's private workspace
-    ├── instructions.md                # Core directives
-    ├── memories.md                    # Persistent session memory
-    ├── mood-patterns.md               # Emotional tracking data
-    ├── breakthroughs.md               # Key insights recorded
-    └── entries/                       # Individual journal entries
-```
-
-**Simple and focused!** Just 4 core files + a folder for entries.
-
-## Key Architecture Patterns
-
-### 1. Hybrid Command Pattern
-
-Expert Agents can use BOTH:
-
-- **Embedded prompts** via `action: "#prompt-id"` (like Simple Agents)
-- **Sidecar file references** via direct paths
-
-```yaml
-menu:
-  # Embedded prompt (like Simple Agent)
-  - trigger: 'write'
-    action: '#guided-entry'
-    description: "Write today's journal entry"
-
-  # Direct sidecar file action
-  - trigger: 'insight'
-    action: 'Document this breakthrough in ./journal-keeper-sidecar/breakthroughs.md'
-    description: 'Record a meaningful insight'
-```
-
-This hybrid approach gives you the best of both worlds!
-
-### 2. Mandatory Critical Actions
-
-Expert Agents MUST load sidecar files explicitly:
-
-```yaml
-critical_actions:
-  - 'Load COMPLETE file ./journal-keeper-sidecar/memories.md'
-  - 'Load COMPLETE file ./journal-keeper-sidecar/instructions.md'
-  - 'ONLY read/write files in ./journal-keeper-sidecar/'
-```
-
-**Key points:**
-
-- Files are loaded at startup
-- Domain restriction is enforced
-- Agent knows its boundaries
-
-### 3. Persistent Memory Pattern
-
-The `memories.md` file stores:
-
-- User preferences and patterns
-- Session notes and observations
-- Recurring themes discovered
-- Growth markers tracked
-
-**Critically:** This is updated EVERY session, creating continuity.
-
-### 4. Domain-Specific Tracking
-
-Different files track different aspects:
-
-- **memories.md** - Qualitative insights and observations
-- **mood-patterns.md** - Quantitative emotional data
-- **breakthroughs.md** - Significant moments
-- **entries/** - The actual content (journal entries)
-
-This separation makes data easy to reference and update.
-
-### 5. Simple Sidecar Structure
-
-Unlike modules with complex folder hierarchies, Expert Agent sidecars are flat and focused:
-
-- Just the files the agent needs
-- No nested workflows or templates
-- Easy to understand and maintain
-- All domain knowledge in one place
-
-## Comparison: Simple vs Expert vs Module
-
-| Feature       | Simple Agent         | Expert Agent               | Module Agent           |
-| ------------- | -------------------- | -------------------------- | ---------------------- |
-| Architecture  | Single YAML          | YAML + sidecar folder      | YAML + module system   |
-| Memory        | Session only         | Persistent (sidecar files) | Config-driven          |
-| Prompts       | Embedded only        | Embedded + external files  | Workflow references    |
-| Dependencies  | None                 | Sidecar folder             | Module workflows/tasks |
-| Domain Access | None                 | Restricted to sidecar      | Full module access     |
-| Complexity    | Low                  | Medium                     | High                   |
-| Use Case      | Self-contained tools | Domain experts with memory | Full workflow systems  |
-
-## The Sweet Spot
-
-Expert Agents are the middle ground:
-
-- **More powerful** than Simple Agents (persistent memory, domain knowledge)
-- **Simpler** than Module Agents (no workflow orchestration)
-- **Focused** on specific domain expertise
-- **Personal** to the user's needs
-
-## When to Use Expert Agents
-
-**Perfect for:**
-
-- Personal assistants that need memory (journal keeper, diary, notes)
-- Domain specialists with knowledge bases (specific project context)
-- Agents that track patterns over time (mood, habits, progress)
-- Privacy-focused tools with restricted access
-- Tools that learn and adapt to individual users
-
-**Key indicators:**
-
-- Need to remember things between sessions
-- Should only access specific folders/files
-- Tracks data over time
-- Adapts based on accumulated knowledge
-
-## File Breakdown
-
-### journal-keeper.agent.yaml
-
-- Standard agent metadata and persona
-- **Embedded prompts** for guided interactions
-- **Menu commands** mixing both patterns
-- **Critical actions** that load sidecar files
-
-### instructions.md
-
-- Core behavioral directives
-- Journaling philosophy and approach
-- File management protocols
-- Tone and boundary guidelines
-
-### memories.md
-
-- User profile and preferences
-- Recurring themes discovered
-- Session notes and observations
-- Accumulated knowledge about the user
-
-### mood-patterns.md
-
-- Quantitative tracking (mood scores, energy, etc.)
-- Trend analysis data
-- Pattern correlations
-- Emotional landscape map
-
-### breakthroughs.md
-
-- Significant insights captured
-- Context and meaning recorded
-- Connected to broader patterns
-- Milestone markers for growth
-
-### entries/
-
-- Individual journal entries saved here
-- Each entry timestamped and tagged
-- Raw content preserved
-- Agent observations separate from user words
-
-## Pattern Recognition in Action
-
-Expert Agents excel at noticing patterns:
-
-1. **Reference past sessions:** "Last week you mentioned feeling stuck..."
-2. **Track quantitative data:** Mood scores over time
-3. **Spot recurring themes:** Topics that keep surfacing
-4. **Notice growth:** Changes in language, perspective, emotions
-5. **Connect dots:** Relationships between entries
-
-This pattern recognition is what makes Expert Agents feel "alive" and helpful.
-
-## Usage Notes
-
-### Starting Fresh
-
-The sidecar files are templates. A new user would:
-
-1. Start journaling with the agent
-2. Agent fills in memories.md over time
-3. Patterns emerge from accumulated data
-4. Insights build from history
-
-### Building Your Own Expert Agent
-
-1. **Define the domain** - What specific area will this agent focus on?
-2. **Choose sidecar files** - What data needs to be tracked/remembered?
-3. **Mix command patterns** - Use embedded prompts + sidecar references
-4. **Enforce boundaries** - Clearly state domain restrictions
-5. **Design for accumulation** - How will memory grow over time?
-
-### Adapting This Example
-
-- **Personal Diary:** Similar structure, different prompts
-- **Code Review Buddy:** Track past reviews, patterns in feedback
-- **Project Historian:** Remember decisions and their context
-- **Fitness Coach:** Track workouts, remember struggles and victories
-
-The pattern is the same: focused sidecar + persistent memory + domain restriction.
-
-## Key Takeaways
-
-- **Expert Agents** bridge Simple and Module complexity
-- **Sidecar folders** provide persistent, domain-specific memory
-- **Hybrid commands** use both embedded prompts and file references
-- **Pattern recognition** comes from accumulated data
-- **Simple structure** keeps it maintainable
-- **Domain restriction** ensures focused expertise
-- **Memory is the superpower** - remembering makes the agent truly useful
-
----
-
-_This reference shows how Expert Agents can be powerful memory-driven assistants while maintaining architectural simplicity._

package/src/modules/bmb/workflows/create-agent/data/reference/agents/module-examples/README.md

@@ -1,48 +0,0 @@
-# Module Agent Examples
-
-Reference examples for module-integrated agents.
-
-## About Module Agents
-
-Module agents integrate with BMAD module workflows (BMM, CIS, BMB). They:
-
-- Orchestrate multi-step workflows
-- Use `_bmad` path variables
-- Have fixed professional personas (no install_config)
-- Reference module-specific configurations
-
-## Examples
-
-### security-engineer.agent.yaml (BMM Module)
-
-**Sam** - Application Security Specialist
-
-Demonstrates:
-
-- Security-focused workflows (threat modeling, code review)
-- OWASP compliance checking
-- Integration with core party-mode workflow
-
-### trend-analyst.agent.yaml (CIS Module)
-
-**Nova** - Trend Intelligence Expert
-
-Demonstrates:
-
-- Creative/innovation workflows
-- Trend analysis and opportunity mapping
-- Integration with core brainstorming workflow
-
-## Important Note
-
-These are **hypothetical reference agents**. The workflows they reference (threat-model, trend-scan, etc.) may not exist. They serve as examples of proper module agent structure.
-
-## Using as Templates
-
-When creating module agents:
-
-1. Copy relevant example
-2. Update metadata (id, name, title, icon, module)
-3. Rewrite persona for your domain
-4. Replace menu with actual available workflows
-5. Remove hypothetical workflow references

package/src/modules/bmb/workflows/create-agent/data/reference/agents/simple-examples/README.md

@@ -1,223 +0,0 @@
-# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
-
-This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
-
-## Overview
-
-**Agent Name:** Inkwell Von Comitizen
-**Type:** Simple Agent (Standalone)
-**Purpose:** Transform commit messages into art with multiple writing styles
-
-This reference demonstrates:
-
-- Pure self-contained architecture (no external dependencies)
-- Embedded prompts using `action="#prompt-id"` pattern
-- Multiple sophisticated output modes from single input
-- Strong personality-driven design
-- Complete YAML schema for Simple Agents
-
-## File Structure
-
-```
-stand-alone/
-├── README.md                    # This file - architecture overview
-└── commit-poet.agent.yaml       # Complete agent definition (single file!)
-```
-
-That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
-
-## Key Architecture Patterns
-
-### 1. Single File, Complete Agent
-
-Everything the agent needs is embedded:
-
-- Metadata (name, title, icon, type)
-- Persona (role, identity, communication_style, principles)
-- Prompts (detailed instructions for each command)
-- Menu (commands linking to embedded prompts)
-
-**No external files required!**
-
-### 2. Embedded Prompts with ID References
-
-Instead of inline action text, complex prompts are defined separately and referenced by ID:
-
-```yaml
-prompts:
-  - id: conventional-commit
-    content: |
-      OH! Let's craft a BEAUTIFUL conventional commit message!
-
-      First, I need to understand your changes...
-      [Detailed instructions]
-
-menu:
-  - trigger: conventional
-    action: '#conventional-commit' # References the prompt above
-    description: 'Craft a structured conventional commit'
-```
-
-**Benefits:**
-
-- Clean separation of menu structure from prompt content
-- Prompts can be as detailed as needed
-- Easy to update individual prompts
-- Commands stay concise in the menu
-
-### 3. The `#` Reference Pattern
-
-When you see `action="#prompt-id"`:
-
-- The `#` signals: "This is an internal reference"
-- LLM looks for `<prompt id="prompt-id">` in the same agent
-- Executes that prompt's content as the instruction
-
-This is different from:
-
-- `action="inline text"` - Execute this text directly
-- `exec="{path}"` - Load external file
-
-### 4. Multiple Output Modes
-
-Single agent provides 10+ different ways to accomplish variations of the same core task:
-
-- `*conventional` - Structured commits
-- `*story` - Narrative style
-- `*haiku` - Poetic brevity
-- `*explain` - Deep "why" explanation
-- `*dramatic` - Theatrical flair
-- `*emoji-story` - Visual storytelling
-- `*tldr` - Ultra-minimal
-- Plus utility commands (analyze, improve, batch)
-
-Each mode has its own detailed prompt but shares the same agent personality.
-
-### 5. Strong Personality
-
-The agent has a memorable, consistent personality:
-
-- Enthusiastic wordsmith who LOVES finding perfect words
-- Gets genuinely excited about commit messages
-- Uses literary metaphors
-- Quotes authors when appropriate
-- Sheds tears of joy over good variable names
-
-This personality is maintained across ALL commands through the persona definition.
-
-## When to Use Simple Agents
-
-**Perfect for:**
-
-- Single-purpose tools (calculators, converters, analyzers)
-- Tasks that don't need external data
-- Utilities that can be completely self-contained
-- Quick operations with embedded logic
-- Personality-driven assistants with focused domains
-
-**Not ideal for:**
-
-- Agents needing persistent memory across sessions
-- Domain-specific experts with knowledge bases
-- Agents that need to access specific folders/files
-- Complex multi-workflow orchestration
-
-## YAML Schema Deep Dive
-
-```yaml
-agent:
-  metadata:
-    id: _bmad/agents/{agent-name}/{agent-name}.md  # Build path
-    name: "Display Name"
-    title: "Professional Title"
-    icon: "🎭"
-    type: simple  # CRITICAL: Identifies as Simple Agent
-
-  persona:
-    role: |
-      First-person description of what the agent does
-    identity: |
-      Background, experience, specializations (use "I" voice)
-    communication_style: |
-      HOW the agent communicates (tone, quirks, patterns)
-    principles:
-      - "I believe..." statements
-      - Core values that guide behavior
-
-  prompts:
-    - id: unique-identifier
-      content: |
-        Detailed instructions for this command
-        Can be as long and detailed as needed
-        Include examples, steps, formats
-
-  menu:
-    - trigger: command-name
-      action: "#prompt-id"
-      description: "What shows in the menu"
-```
-
-## Why This Pattern is Powerful
-
-1. **Zero Dependencies** - Works anywhere, no setup required
-2. **Portable** - Single file can be moved/shared easily
-3. **Maintainable** - All logic in one place
-4. **Flexible** - Multiple modes/commands from one personality
-5. **Memorable** - Strong personality creates engagement
-6. **Sophisticated** - Complex prompts despite simple architecture
-
-## Comparison: Simple vs Expert Agent
-
-| Aspect       | Simple Agent         | Expert Agent                  |
-| ------------ | -------------------- | ----------------------------- |
-| Files        | Single YAML          | YAML + sidecar folder         |
-| Dependencies | None                 | External resources            |
-| Memory       | Session only         | Persistent across sessions    |
-| Prompts      | Embedded             | Can be external files         |
-| Data Access  | None                 | Domain-restricted             |
-| Use Case     | Self-contained tasks | Domain expertise with context |
-
-## Using This Reference
-
-### For Building Simple Agents
-
-1. Study the YAML structure - especially `prompts` section
-2. Note how personality permeates every prompt
-3. See how `#prompt-id` references work
-4. Understand menu → prompt connection
-
-### For Understanding Embedded Prompts
-
-1. Each prompt is a complete instruction set
-2. Prompts maintain personality voice
-3. Structured enough to be useful, flexible enough to adapt
-4. Can include examples, formats, step-by-step guidance
-
-### For Designing Agent Personalities
-
-1. Persona defines WHO the agent is
-2. Communication style defines HOW they interact
-3. Principles define WHAT guides their decisions
-4. Consistency across all prompts creates believability
-
-## Files Worth Studying
-
-The entire `commit-poet.agent.yaml` file is worth studying, particularly:
-
-1. **Persona section** - How to create a memorable character
-2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
-3. **Menu structure** - Clean command organization
-4. **Prompt references** - The `#prompt-id` pattern
-
-## Key Takeaways
-
-- **Simple Agents** are powerful despite being single-file
-- **Embedded prompts** allow sophisticated behavior
-- **Strong personality** makes agents memorable and engaging
-- **Multiple modes** from single agent provides versatility
-- **Self-contained** = portable and dependency-free
-- **The `#prompt-id` pattern** enables clean prompt organization
-
----
-
-_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._