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

package/src/modules/bmb/workflows/create-agent/data/agent-validation-checklist.md

@@ -1,174 +0,0 @@
-# BMAD Agent Validation Checklist
-
-Use this checklist to validate agents meet BMAD quality standards, whether creating new agents or editing existing ones.
-
-## YAML Structure Validation (Source Files)
-
-- [ ] YAML parses without errors
-- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`
-- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`)
-- [ ] `agent.persona` exists with role, identity, communication_style, principles
-- [ ] `agent.menu` exists with at least one item
-- [ ] Filename is kebab-case and ends with `.agent.yaml`
-
-## Agent Structure Validation
-
-- [ ] Agent file format is valid (.agent.yaml for source)
-- [ ] Agent type matches structure: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration)
-- [ ] File naming follows convention: `{agent-name}.agent.yaml`
-- [ ] If Expert: folder structure with .agent.yaml + sidecar files
-- [ ] If Module: includes header comment explaining WHY Module Agent (design intent)
-
-## Persona Validation (CRITICAL - #1 Quality Issue)
-
-**Field Separation Check:**
-
-- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
-- [ ] **identity** contains ONLY background/experience/context (who agent is)
-- [ ] **communication_style** contains ONLY verbal patterns - NO behaviors, NO role statements, NO principles
-- [ ] **principles** contains operating philosophy and behavioral guidelines
-
-**Communication Style Purity Check:**
-
-- [ ] Communication style does NOT contain red flag words: "ensures", "makes sure", "always", "never"
-- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
-- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to"
-- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y"
-- [ ] Communication style is 1-2 sentences describing HOW they talk (word choice, quirks, verbal patterns)
-
-**Quality Benchmarking:**
-
-- [ ] Compare communication style against {communication_presets} - similarly pure?
-- [ ] Compare against reference agents (commit-poet, journal-keeper, BMM agents) - similar quality?
-- [ ] Read communication style aloud - does it sound like describing someone's voice/speech pattern?
-
-## Menu Validation
-
-- [ ] All menu items have `trigger` field
-- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation)
-- [ ] Each item has `description` field
-- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action`
-- [ ] Workflow paths are correct (if workflow attribute present)
-- [ ] Workflow paths use `{project-root}` variable for portability
-- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)**
-- [ ] No duplicate triggers within same agent
-- [ ] Menu items are in logical order
-
-## Prompts Validation (if present)
-
-- [ ] Each prompt has `id` field
-- [ ] Each prompt has `content` field
-- [ ] Prompt IDs are unique within agent
-- [ ] If using `action="#prompt-id"` in menu, corresponding prompt exists
-
-## Critical Actions Validation (if present)
-
-- [ ] Critical actions array contains non-empty strings
-- [ ] Critical actions describe steps that MUST happen during activation
-- [ ] No placeholder text in critical actions
-
-## Type-Specific Validation
-
-### Simple Agent (Self-Contained)
-
-- [ ] Single .agent.yaml file with complete agent definition
-- [ ] No sidecar files (all content in YAML)
-- [ ] Not capability-limited - can be as powerful as Expert or Module
-- [ ] Compare against reference: commit-poet.agent.yaml
-
-### Expert Agent (With Sidecar Files)
-
-- [ ] Folder structure: .agent.yaml + sidecar files
-- [ ] Sidecar files properly referenced in menu items or prompts (tmpl="path", data="path")
-- [ ] Folder name matches agent purpose
-- [ ] **All sidecar references in YAML resolve to actual files**
-- [ ] **All sidecar files are actually used (no orphaned/unused files, unless intentional for future use)**
-- [ ] Sidecar files are valid format (YAML parses, CSV has headers, markdown is well-formed)
-- [ ] Sidecar file paths use relative paths from agent folder
-- [ ] Templates contain valid template variables if applicable
-- [ ] Knowledge base files contain current/accurate information
-- [ ] Compare against reference: journal-keeper (Expert example)
-
-### Module Agent (Ecosystem Integration)
-
-- [ ] Designed FOR specific module (BMM, BMGD, CIS, etc.)
-- [ ] Integrates with module workflows (referenced in menu items)
-- [ ] Coordinates with other module agents (if applicable)
-- [ ] Included in module's default bundle (if applicable)
-- [ ] Header comment explains WHY Module Agent (design intent, not just location)
-- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure)
-- [ ] Compare against references: security-engineer, dev, analyst (Module examples)
-
-## Compilation Validation (Post-Build)
-
-- [ ] Agent compiles without errors to .md format
-- [ ] Compiled file has proper frontmatter (name, description)
-- [ ] Compiled XML structure is valid
-- [ ] `<agent>` tag has id, name, title, icon attributes
-- [ ] `<activation>` section is present with proper steps
-- [ ] `<persona>` section compiled correctly
-- [ ] `<menu>` section includes both user items AND auto-injected *help/*exit
-- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action)
-
-## Quality Checks
-
-- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.)
-- [ ] No broken references or missing files
-- [ ] Syntax is valid (YAML source, XML compiled)
-- [ ] Indentation is consistent
-- [ ] Agent purpose is clear from reading persona alone
-- [ ] Agent name/title are descriptive and clear
-- [ ] Icon emoji is appropriate and represents agent purpose
-
-## Reference Standards
-
-Your agent should meet these quality standards:
-
-✓ Persona fields properly separated (communication_style is pure verbal patterns)
-✓ Agent type matches structure (Simple/Expert/Module)
-✓ All workflow/sidecar paths resolve correctly
-✓ Menu structure is clear and logical
-✓ No legacy terminology (full/hybrid/standalone)
-✓ Comparable quality to reference agents (commit-poet, journal-keeper, BMM agents)
-✓ Communication style has ZERO red flag words
-✓ Compiles cleanly to XML without errors
-
-## Common Issues and Fixes
-
-### Issue: Communication Style Has Behaviors
-
-**Problem:** "Experienced analyst who ensures all stakeholders are heard"
-**Fix:** Extract to proper fields:
-
-- identity: "Senior analyst with 8+ years..."
-- communication_style: "Treats analysis like a treasure hunt"
-- principles: "Ensure all stakeholder voices heard"
-
-### Issue: Broken Sidecar References (Expert agents)
-
-**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist
-**Fix:** Either create the file or fix the path to point to actual file
-
-### Issue: Using Legacy Type Names
-
-**Problem:** Comments refer to "full agent" or "hybrid agent"
-**Fix:** Update to Simple/Expert/Module terminology
-
-### Issue: Menu Triggers Start With Asterisk
-
-**Problem:** `trigger: "*create"` in YAML
-**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"`
-
-## Issues Found (Use for tracking)
-
-### Critical Issues
-
-<!-- List any issues that MUST be fixed before agent can function -->
-
-### Warnings
-
-<!-- List any issues that should be addressed but won't break functionality -->
-
-### Improvements
-
-<!-- List any optional enhancements that could improve the agent -->

package/src/modules/bmb/workflows/create-agent/data/info-and-installation-guide.md

@@ -1,29 +0,0 @@
-# {agent_name} Agent
-
-## Installation
-
-Create a `custom.yaml` file in the agent folder:
-
-```yaml
-code: { agent_code }
-name: '{agent_name}'
-default_selected: true
-```
-
-Then run:
-
-```bash
-npx bmad-method install
-```
-
-Or if you have bmad-cli installed globally:
-
-```bash
-bmad install
-```
-
-## About This Agent
-
-{agent_description}
-
-_Generated with BMAD Builder workflow_

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

@@ -1,3 +0,0 @@
-# Reference Examples
-
-Reference models of best practices for agents, workflows, and whole modules.

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/expert-examples/journal-keeper/journal-keeper-sidecar/breakthroughs.md

@@ -1,24 +0,0 @@
-# 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/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/instructions.md

@@ -1,108 +0,0 @@
-# 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/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/memories.md

@@ -1,46 +0,0 @@
-# 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/workflows/create-agent/data/reference/agents/expert-examples/journal-keeper/journal-keeper-sidecar/mood-patterns.md

@@ -1,39 +0,0 @@
-# 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._