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

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

@@ -1,184 +0,0 @@
-# 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, {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/bmm/workflows/dev-story/workflow.yaml'
-      description: Implement user story
-
-    - trigger: refactor
-      workflow: '_bmad/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/docs/index.md

@@ -1,247 +0,0 @@
-# BMB - BMad Builder Module
-
-Specialized tools and workflows for creating, customizing, and extending BMad components including agents, workflows, and complete modules.
-
-## Table of Contents
-
-- [Module Structure](#module-structure)
-- [Documentation](#documentation)
-- [Reference Materials](#reference-materials)
-- [Core Workflows](#core-workflows)
-- [Agent Types](#agent-types)
-- [Quick Start](#quick-start)
-- [Best Practices](#best-practices)
-
-## Module Structure
-
-### 🤖 Agents
-
-**BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
-
-- Install Location: `_bmad/bmb/agents/bmad-builder.md`
-
-### 📚 Documentation
-
-- Comprehensive guides for agents, workflows, and modules
-- Architecture patterns and best practices
-
-### 🔍 Reference Materials
-
-- Location: `../reference/`
-- Working examples of custom stand alone agents and workflows
-- Template patterns and implementation guides
-
-## Documentation
-
-### 📖 Agent Documentation
-
-- **[Agent Index](./agents/index.md)** - Complete agent architecture guide
-- **[Agent Types Guide](./agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
-- **[Menu Patterns](./agents/agent-menu-patterns.md)** - YAML menu design and handler types
-- **[Agent Compilation](./agents/agent-compilation.md)** - Auto-injection rules and compilation process
-
-### 📋 Workflow Documentation
-
-- **[Workflow Index](./workflows/index.md)** - Core workflow system overview
-- **[Architecture Guide](./workflows/architecture.md)** - Step-file design and JIT loading
-- **Template System** _(TODO)_ - Standard step file template
-- **[Intent vs Prescriptive](./workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
-
-## Reference Materials
-
-### 🤖 Agent Examples
-
-- **[Simple Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
-- **[Expert Agent Example](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/expert-examples/journal-keeper/journal-keeper.agent.yaml)** - Agent with persistent memory
-- **[Module Add On Agent Examples](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/src/modules/bmb/reference/agents/module-examples/security-engineer.agent.yaml)** - Integration patterns (BMM, CIS)
-
-### 📋 Workflow Examples
-
-- **[Meal Prep & Nutrition](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/modules/bmb/reference/workflows/meal-prep-nutrition)** - Complete step-file workflow demonstration
-- **Template patterns** for document generation and state management
-
-## Core Workflows
-
-### Creation Workflows (Step-File Architecture)
-
-**create-agent** _(TODO)_ - Build BMad agents
-
-- 11 guided steps from brainstorming to celebration
-- 18 reference data files with validation checklists
-- Template-based agent generation
-
-**create-workflow** _(TODO)_ - Design workflows
-
-- 12 structured steps from init to review
-- 9 template files for workflow creation
-- Step-file architecture implementation
-
-### Editing Workflows
-
-**edit-agent** _(TODO)_ - Modify existing agents
-
-- 5 steps: discovery → validation
-- Intent-driven analysis and updates
-- Best practice compliance
-
-**edit-workflow** _(TODO)_ - Update workflows
-
-- 5 steps: analyze → compliance check
-- Structure maintenance and validation
-- Template updates for consistency
-
-### Quality Assurance
-
-**workflow-compliance-check** _(TODO)_ - Validation
-
-- 8 systematic validation steps
-- Adversarial analysis approach
-- Detailed compliance reporting
-
-### Legacy Migration (Pending)
-
-Workflows in `workflows-legacy/` are being migrated to step-file architecture:
-
-- Module-specific workflows
-- Historical implementations
-- Conversion planning in progress
-
-## Agent Types
-
-BMB creates three agent architectures:
-
-### Simple Agent
-
-- **Self-contained**: All logic in single YAML file
-- **Stateless**: No persistent memory across sessions
-- **Purpose**: Single utilities and specialized tools
-- **Example**: Commit poet, code formatter
-
-### Expert Agent
-
-- **Persistent Memory**: Maintains knowledge across sessions
-- **Sidecar Resources**: External files and data storage
-- **Domain-specific**: Focuses on particular knowledge areas
-- **Example**: Journal keeper, domain consultant
-
-### Module Agent
-
-- **Team Integration**: Orchestrates within specific modules
-- **Workflow Coordination**: Manages complex processes
-- **Professional Infrastructure**: Enterprise-grade capabilities
-- **Examples**: BMM project manager, CIS innovation strategist
-
-## Quick Start
-
-### Using BMad Builder Agent
-
-1. **Load BMad Builder agent** in your IDE:
-   ```
-   /bmad:bmb:agents:bmad-builder
-   ```
-2. **Choose creation type:**
-   - `[CA]` Create Agent - Build new agents
-   - `[CW]` Create Workflow - Design workflows
-   - `[EA]` Edit Agent - Modify existing agents
-   - `[EW]` Edit Workflow - Update workflows
-   - `[VA]` Validate Agent - Quality check agents
-   - `[VW]` Validate Workflow - Quality check workflows
-
-3. **Follow interactive prompts** for step-by-step guidance
-
-### Example: Creating an Agent
-
-```
-User: I need a code review agent
-Builder: [CA] Create Agent
-
-[11-step guided process]
-Step 1: Brainstorm agent concept
-Step 2: Define persona and role
-Step 3: Design command structure
-...
-Step 11: Celebrate and deploy
-```
-
-### Direct Workflow Execution
-
-Workflows can also be run directly without the agent interface:
-
-```yaml
-# Execute specific workflow steps
-workflow: ./workflows/create-agent/workflow.yaml
-```
-
-## Use Cases
-
-### Custom Development Teams
-
-Build specialized agents for:
-
-- Domain expertise (legal, medical, finance)
-- Company processes
-- Tool integrations
-- Automation tasks
-
-### Workflow Extensions
-
-Create workflows for:
-
-- Compliance requirements
-- Quality gates
-- Deployment pipelines
-- Custom methodologies
-
-### Complete Solutions
-
-Package modules for:
-
-- Industry verticals
-- Technology stacks
-- Business processes
-- Educational frameworks
-
-## Architecture Principles
-
-### Step-File Workflow Design
-
-- **Micro-file Approach**: Each step is self-contained
-- **Just-In-Time Loading**: Only current step in memory
-- **Sequential Enforcement**: No skipping steps allowed
-- **State Tracking**: Progress documented in frontmatter
-- **Append-Only Building**: Documents grow through execution
-
-### Intent vs Prescriptive Spectrum
-
-- **Creative Workflows**: High user agency, AI as facilitator
-- **Structured Workflows**: Clear process, AI as guide
-- **Prescriptive Workflows**: Strict compliance, AI as validator
-
-## Best Practices
-
-1. **Study Reference Materials** - Review docs/ and reference/ examples
-2. **Choose Right Agent Type** - Simple vs Expert vs Module based on needs
-3. **Follow Step-File Patterns** - Use established templates and structures
-4. **Document Thoroughly** - Clear instructions and frontmatter metadata
-5. **Validate Continuously** - Use compliance workflows for quality
-6. **Maintain Consistency** - Follow YAML patterns and naming conventions
-
-## Integration
-
-BMB components integrate with:
-
-- **BMad Core** - Framework foundation and agent compilation
-- **BMM** - Development workflows and project management
-- **CIS** - Creative innovation and strategic workflows
-- **Custom Modules** - Domain-specific solutions
-
-## Getting Help
-
-- **Documentation**: Check `docs/` for comprehensive guides
-- **Reference Materials**: See `reference/` for working examples
-- **Validation**: Use `workflow-compliance-check` for quality assurance
-- **Templates**: Leverage workflow templates for consistent patterns
-
----
-
-BMB provides a complete toolkit for extending BMad Method with disciplined, systematic approaches to agent and workflow development while maintaining framework consistency and power.

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

@@ -1,45 +0,0 @@
-# BMAD Workflows Documentation
-
-Welcome to the BMAD Workflows documentation - a modern system for creating structured, collaborative workflows optimized for AI execution.
-
-## 📚 Core Documentation
-
-### [Terms](./terms.md)
-
-Essential terminology and concepts for understanding BMAD workflows.
-
-### [Architecture & Execution Model](./architecture.md)
-
-The micro-file architecture, JIT step loading, state management, and collaboration patterns that make BMAD workflows optimal for AI execution.
-
-### Writing Workflows _(TODO)_
-
-Complete guide to creating workflows: workflow.md control files, step files, CSV data integration, and frontmatter design.
-
-### Step Files & Dialog Patterns _(TODO)_
-
-Crafting effective step files: structure, execution rules, prescriptive vs intent-based dialog, and validation patterns.
-
-### Templates & Content Generation _(TODO)_
-
-Creating append-only templates, frontmatter design, conditional content, and dynamic content generation strategies.
-
-### Workflow Patterns _(TODO)_
-
-Common workflow types: linear, conditional, protocol integration, multi-agent workflows, and real-world examples.
-
-### Migration Guide _(TODO)_
-
-Converting from XML-heavy workflows to the new pure markdown format, with before/after examples and checklist.
-
-### Best Practices & Reference _(TODO)_
-
-Critical rules, anti-patterns, performance optimization, debugging, quick reference templates, and troubleshooting.
-
-## 🚀 Quick Start
-
-BMAD workflows are pure markdown, self-contained systems that guide collaborative processes through structured step files where the AI acts as a facilitator working with humans.
-
----
-
-_This documentation covers the next generation of BMAD workflows - designed from the ground up for optimal AI-human collaboration._

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.