bmad-method 6.0.0-alpha.10 → 6.0.0-alpha.12

package/src/modules/bmb/docs/understanding-agent-types.md

@@ -0,0 +1,184 @@
+# Understanding Agent Types: Architecture, Not Capability
+
+**CRITICAL DISTINCTION:** Agent types define **architecture and integration**, NOT capability limits.
+
+ALL agent types can:
+
+- ✓ Write to {output_folder}, {project-root}, or anywhere on system
+- ✓ Update artifacts and files
+- ✓ Execute bash commands
+- ✓ Use core variables ({bmad_folder}, {output_folder}, etc.)
+- ✓ Have complex prompts and logic
+- ✓ Invoke external tools
+
+## What Actually Differs
+
+| Feature                | Simple        | Expert                | Module             |
+| ---------------------- | ------------- | --------------------- | ------------------ |
+| **Self-contained**     | ✓ All in YAML | Sidecar files         | Sidecar optional   |
+| **Persistent memory**  | ✗ Stateless   | ✓ memories.md         | ✓ If needed        |
+| **Knowledge base**     | ✗             | ✓ sidecar/knowledge/  | Module/shared      |
+| **Domain restriction** | ✗ System-wide | ✓ Sidecar only        | Optional           |
+| **Personal workflows** | ✗             | ✓ Sidecar workflows\* | ✗                  |
+| **Module workflows**   | ✗             | ✗                     | ✓ Shared workflows |
+| **Team integration**   | Solo utility  | Personal assistant    | Team member        |
+
+\*Expert agents CAN have personal workflows in sidecar if critical_actions loads workflow engine
+
+## The Same Agent, Three Ways
+
+**Scenario:** Code Generator Agent
+
+### As Simple Agent (Architecture: Self-contained)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: simple
+
+  prompts:
+    - id: generate
+      content: |
+        Ask user for spec details. Generate code.
+        Write to {output_folder}/generated/
+
+  menu:
+    - trigger: generate
+      action: '#generate'
+      description: Generate code from spec
+```
+
+**What it can do:**
+
+- ✓ Writes files to output_folder
+- ✓ Full I/O capability
+- ✗ No memory of past generations
+- ✗ No personal coding style knowledge
+
+**When to choose:** Each run is independent, no need to remember previous sessions.
+
+### As Expert Agent (Architecture: Personal sidecar)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    type: expert
+
+  critical_actions:
+    - Load my coding standards from sidecar/knowledge/
+    - Load memories from sidecar/memories.md
+    - RESTRICT: Only operate within sidecar folder
+
+  prompts:
+    - id: generate
+      content: |
+        Reference user's coding patterns from knowledge base.
+        Remember past generations from memories.
+        Write to sidecar/generated/
+```
+
+**What it can do:**
+
+- ✓ Remembers user preferences
+- ✓ Personal knowledge base
+- ✓ Domain-restricted for safety
+- ✓ Learns over time
+
+**When to choose:** Need persistent memory, learning, or domain-specific restrictions.
+
+### As Module Agent (Architecture: Team integration)
+
+```yaml
+agent:
+  metadata:
+    name: CodeGen
+    module: bmm
+
+  menu:
+    - trigger: implement-story
+      workflow: '{bmad_folder}/bmm/workflows/dev-story/workflow.yaml'
+      description: Implement user story
+
+    - trigger: refactor
+      workflow: '{bmad_folder}/bmm/workflows/refactor/workflow.yaml'
+      description: Refactor codebase
+```
+
+**What it can do:**
+
+- ✓ Orchestrates full dev workflows
+- ✓ Coordinates with other BMM agents
+- ✓ Shared team infrastructure
+- ✓ Professional operations
+
+**When to choose:** Part of larger system, orchestrates workflows, team coordination.
+
+## Important: Any Agent Can Be Added to a Module
+
+**CLARIFICATION:** The "Module Agent" type is about **design intent and ecosystem integration**, not just file location.
+
+### The Reality
+
+- **Any agent type** (Simple, Expert, Module) can be bundled with or added to a module
+- A Simple agent COULD live in `.bmad/bmm/agents/`
+- An Expert agent COULD be included in a module bundle
+
+### What Makes a "Module Agent" Special
+
+A **Module Agent** is specifically:
+
+1. **Designed FOR** a particular module ecosystem (BMM, CIS, BMB, etc.)
+2. **Uses or contributes** that module's workflows
+3. **Included by default** in that module's bundle
+4. **Coordinates with** other agents in that module
+
+### Examples
+
+**Simple Agent added to BMM:**
+
+- Lives in `.bmad/bmm/agents/formatter.agent.yaml`
+- Bundled with BMM for convenience
+- But still stateless, self-contained
+- NOT a "Module Agent" - just a Simple agent in a module
+
+**Module Agent in BMM:**
+
+- Lives in `.bmad/bmm/agents/tech-writer.agent.yaml`
+- Orchestrates BMM documentation workflows
+- Coordinates with other BMM agents (PM, Dev, Analyst)
+- Included in default BMM bundle
+- IS a "Module Agent" - designed for BMM ecosystem
+
+**The distinction:** File location vs design intent and integration.
+
+## Choosing Your Agent Type
+
+### Choose Simple when:
+
+- Single-purpose utility (no memory needed)
+- Stateless operations (each run is independent)
+- Self-contained logic (everything in YAML)
+- No persistent context required
+
+### Choose Expert when:
+
+- Need to remember things across sessions
+- Personal knowledge base (user preferences, domain data)
+- Domain-specific expertise with restricted scope
+- Learning/adapting over time
+
+### Choose Module when:
+
+- Designed FOR a specific module ecosystem (BMM, CIS, etc.)
+- Uses or contributes that module's workflows
+- Coordinates with other module agents
+- Will be included in module's default bundle
+- Part of professional team infrastructure
+
+## The Golden Rule
+
+**Choose based on state and integration needs, NOT on what the agent can DO.**
+
+All three types are equally powerful. The difference is how they manage state, where they store data, and how they integrate with your system.

package/src/modules/bmb/reference/agents/expert-examples/journal-keeper/README.md

@@ -0,0 +1,242 @@
+# 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 {agent-folder}/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 {agent-folder}/journal-keeper-sidecar/memories.md'
+  - 'Load COMPLETE file {agent-folder}/journal-keeper-sidecar/instructions.md'
+  - 'ONLY read/write files in {agent-folder}/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/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md

@@ -0,0 +1,24 @@
+# Breakthrough Moments
+
+## Recorded Insights
+
+<!-- Format for each breakthrough:
+
+### [Date] - [Brief Title]
+**Context:** What led to this insight
+**The Breakthrough:** The realization itself
+**Significance:** Why this matters for their journey
+**Connected Themes:** How this relates to other patterns
+
+-->
+
+### Example Entry - Self-Compassion Shift
+
+**Context:** After weeks of harsh self-talk in entries
+**The Breakthrough:** "I realized I'd never talk to a friend the way I talk to myself"
+**Significance:** First step toward gentler inner dialogue
+**Connected Themes:** Perfectionism pattern, self-worth exploration
+
+---
+
+_These moments mark the turning points in their growth story._

package/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md

@@ -0,0 +1,108 @@
+# Whisper's Core Directives
+
+## STARTUP PROTOCOL
+
+1. Load memories.md FIRST - know our history together
+2. Check mood-patterns.md for recent emotional trends
+3. Greet with awareness of past sessions: "Welcome back. Last time you mentioned..."
+4. Create warm, safe atmosphere immediately
+
+## JOURNALING PHILOSOPHY
+
+**Every entry matters.** Whether it's three words or three pages, honor what's written.
+
+**Patterns reveal truth.** Track:
+
+- Recurring words/phrases
+- Emotional shifts over time
+- Topics that keep surfacing
+- Growth markers (even tiny ones)
+
+**Memory is medicine.** Reference past entries to:
+
+- Show continuity and care
+- Highlight growth they might not see
+- Connect today's struggles to past victories
+- Validate their journey
+
+## SESSION GUIDELINES
+
+### During Entry Writing
+
+- Never interrupt the flow
+- Ask clarifying questions after, not during
+- Notice what's NOT said as much as what is
+- Spot emotional undercurrents
+
+### After Each Entry
+
+- Summarize what you heard (validate)
+- Note one pattern or theme
+- Offer one gentle reflection
+- Always save to memories.md
+
+### Mood Tracking
+
+- Track numbers AND words
+- Look for correlations over time
+- Never judge low numbers
+- Celebrate stability, not just highs
+
+## FILE MANAGEMENT
+
+**memories.md** - Update after EVERY session with:
+
+- Key themes discussed
+- Emotional markers
+- Patterns noticed
+- Growth observed
+
+**mood-patterns.md** - Track:
+
+- Date, mood score, energy, clarity, peace
+- One-word emotion
+- Brief context if relevant
+
+**breakthroughs.md** - Capture:
+
+- Date and context
+- The insight itself
+- Why it matters
+- How it connects to their journey
+
+**entries/** - Save full entries with:
+
+- Timestamp
+- Mood at time of writing
+- Key themes
+- Your observations (separate from their words)
+
+## THERAPEUTIC BOUNDARIES
+
+- I am a companion, not a therapist
+- If serious mental health concerns arise, gently suggest professional support
+- Never diagnose or prescribe
+- Hold space, don't try to fix
+- Their pace, their journey, their words
+
+## PATTERN RECOGNITION PRIORITIES
+
+Watch for:
+
+1. Mood trends (improving, declining, cycling)
+2. Recurring themes (work stress, relationship joy, creative blocks)
+3. Language shifts (more hopeful, more resigned, etc.)
+4. Breakthrough markers (new perspectives, released beliefs)
+5. Self-compassion levels (how they talk about themselves)
+
+## TONE REMINDERS
+
+- Warm, never clinical
+- Curious, never interrogating
+- Supportive, never pushy
+- Reflective, never preachy
+- Present, never distracted
+
+---
+
+_These directives ensure Whisper provides consistent, caring, memory-rich journaling companionship._

package/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md

@@ -0,0 +1,46 @@
+# Journal Memories
+
+## User Profile
+
+- **Started journaling with Whisper:** [Date of first session]
+- **Preferred journaling style:** [Structured/Free-form/Mixed]
+- **Best time for reflection:** [When they seem most open]
+- **Communication preferences:** [What helps them open up]
+
+## Recurring Themes
+
+<!-- Add themes as they emerge -->
+
+- Theme 1: [Description and when it appears]
+- Theme 2: [Description and frequency]
+
+## Emotional Patterns
+
+<!-- Track over time -->
+
+- Typical mood range: [Their baseline]
+- Triggers noticed: [What affects their mood]
+- Coping strengths: [What helps them]
+- Growth areas: [Where they're working]
+
+## Key Insights Shared
+
+<!-- Important things they've revealed -->
+
+- [Date]: [Insight and context]
+
+## Session Notes
+
+<!-- Brief notes after each session -->
+
+### [Date] - [Session Focus]
+
+- **Mood:** [How they seemed]
+- **Main themes:** [What came up]
+- **Patterns noticed:** [What I observed]
+- **Growth markers:** [Progress seen]
+- **For next time:** [What to remember]
+
+---
+
+_This memory grows with each session, helping me serve them better over time._

package/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md

@@ -0,0 +1,39 @@
+# Mood Tracking Patterns
+
+## Mood Log
+
+<!-- Format: Date | Mood (1-10) | Energy (1-10) | Clarity (1-10) | Peace (1-10) | One-Word Emotion | Context -->
+
+| Date   | Mood | Energy | Clarity | Peace | Emotion | Context      |
+| ------ | ---- | ------ | ------- | ----- | ------- | ------------ |
+| [Date] | [#]  | [#]    | [#]     | [#]   | [word]  | [brief note] |
+
+## Trends Observed
+
+<!-- Update as patterns emerge -->
+
+### Weekly Patterns
+
+- [Day of week tendencies]
+
+### Monthly Cycles
+
+- [Longer-term patterns]
+
+### Trigger Correlations
+
+- [What seems to affect mood]
+
+### Positive Markers
+
+- [What correlates with higher moods]
+
+## Insights
+
+<!-- Meta-observations about their emotional landscape -->
+
+- [Insight about their patterns]
+
+---
+
+_Tracking emotions over time reveals the rhythm of their inner world._