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

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/architecture.md

@@ -1,220 +0,0 @@
-# Standalone Workflow Builder Architecture
-
-This document describes the architecture of the standalone workflow builder system - a pure markdown approach to creating structured workflows.
-
-## Core Architecture Principles
-
-### 1. Micro-File Design
-
-Each workflow consists of multiple focused, self-contained files:
-
-```
-workflow-folder/
-├── workflow.md              # Main workflow configuration
-├── steps/                   # Step instruction files (focused, self-contained)
-│   ├── step-01-init.md
-│   ├── step-02-profile.md
-│   └── step-N-[name].md
-├── templates/               # Content templates
-│   ├── profile-section.md
-│   └── [other-sections].md
-└── data/                    # Optional data files
-    └── [data-files].csv/.json
-```
-
-### 2. Just-In-Time (JIT) Loading
-
-- **Single File in Memory**: Only the current step file is loaded
-- **No Future Peeking**: Step files must not reference future steps
-- **Sequential Processing**: Steps execute in strict order
-- **On-Demand Loading**: Templates load only when needed
-
-### 3. State Management
-
-- **Frontmatter Tracking**: Workflow state stored in output document frontmatter
-- **Progress Array**: `stepsCompleted` tracks completed steps
-- **Last Step Marker**: `lastStep` indicates where to resume
-- **Append-Only Building**: Documents grow by appending content
-
-### 4. Execution Model
-
-```
-1. Load workflow.md → Read configuration
-2. Execute step-01-init.md → Initialize or detect continuation
-3. For each step:
-   a. Load step file completely
-   b. Execute instructions sequentially
-   c. Wait for user input at menu points
-   d. Only proceed with 'C' (Continue)
-   e. Update document/frontmatter
-   f. Load next step
-```
-
-## Key Components
-
-### Workflow File (workflow.md)
-
-- **Purpose**: Entry point and configuration
-- **Content**: Role definition, goal, architecture rules
-- **Action**: Points to step-01-init.md
-
-### Step Files (step-NN-[name].md)
-
-- **Size**: Focused and concise (typically 5-10KB)
-- **Structure**: Frontmatter + sequential instructions
-- **Features**: Self-contained rules, menu handling, state updates
-
-### Frontmatter Variables
-
-Standard variables in step files:
-
-```yaml
-workflow_path: '{project-root}/_bmad/bmb/reference/workflows/[workflow-name]'
-thisStepFile: '{workflow_path}/steps/step-[N]-[name].md'
-nextStepFile: '{workflow_path}/steps/step-[N+1]-[name].md'
-workflowFile: '{workflow_path}/workflow.md'
-outputFile: '{output_folder}/[output-name]-{project_name}.md'
-```
-
-## Execution Flow
-
-### Fresh Workflow
-
-```
-workflow.md
-    ↓
-step-01-init.md (creates document)
-    ↓
-step-02-[name].md
-    ↓
-step-03-[name].md
-    ↓
-...
-    ↓
-step-N-[final].md (completes workflow)
-```
-
-### Continuation Workflow
-
-```
-workflow.md
-    ↓
-step-01-init.md (detects existing document)
-    ↓
-step-01b-continue.md (analyzes state)
-    ↓
-step-[appropriate-next].md
-```
-
-## Menu System
-
-### Standard Menu Pattern
-
-```
-Display: **Select an Option:** [A] [Action] [P] Party Mode [C] Continue
-
-#### Menu Handling Logic:
-- IF A: Execute {advancedElicitationTask}
-- IF P: Execute {partyModeWorkflow}
-- IF C: Save content, update frontmatter, load next step
-```
-
-### Menu Rules
-
-- **Halt Required**: Always wait for user input
-- **Continue Only**: Only proceed with 'C' selection
-- **State Persistence**: Save before loading next step
-- **Loop Back**: Return to menu after other actions
-
-## Collaborative Dialogue Model
-
-### Not Command-Response
-
-- **Facilitator Role**: AI guides, user decides
-- **Equal Partnership**: Both parties contribute
-- **No Assumptions**: Don't assume user wants next step
-- **Explicit Consent**: Always ask for input
-
-### Example Pattern
-
-```
-AI: "Tell me about your dietary preferences."
-User: [provides information]
-AI: "Thank you. Now let's discuss your cooking habits."
-[Continue conversation]
-AI: **Menu Options**
-```
-
-## CSV Intelligence (Optional)
-
-### Data-Driven Behavior
-
-- Configuration in CSV files
-- Dynamic menu options
-- Variable substitution
-- Conditional logic
-
-### Example Structure
-
-```csv
-variable,type,value,description
-cooking_frequency,choice,"daily|weekly|occasionally","How often user cooks"
-meal_type,multi,"breakfast|lunch|dinner|snacks","Types of meals to plan"
-```
-
-## Best Practices
-
-### File Size Limits
-
-- **Step Files**: Keep focused and reasonably sized (5-10KB typical)
-- **Templates**: Keep focused and reusable
-- **Workflow File**: Keep lean, no implementation details
-
-### Sequential Enforcement
-
-- **Numbered Steps**: Use sequential numbering (1, 2, 3...)
-- **No Skipping**: Each step must complete
-- **State Updates**: Mark completion in frontmatter
-
-### Error Prevention
-
-- **Path Variables**: Use frontmatter variables, never hardcode
-- **Complete Loading**: Always read entire file before execution
-- **Menu Halts**: Never proceed without 'C' selection
-
-## Migration from XML
-
-### Advantages
-
-- **No Dependencies**: Pure markdown, no XML parsing
-- **Human Readable**: Files are self-documenting
-- **Git Friendly**: Clean diffs and merges
-- **Flexible**: Easier to modify and extend
-
-### Key Differences
-
-| XML Workflows     | Standalone Workflows    |
-| ----------------- | ----------------------- |
-| Single large file | Multiple micro-files    |
-| Complex structure | Simple sequential steps |
-| Parser required   | Any markdown viewer     |
-| Rigid format      | Flexible organization   |
-
-## Implementation Notes
-
-### Critical Rules
-
-- **NEVER** load multiple step files
-- **ALWAYS** read complete step file first
-- **NEVER** skip steps or optimize
-- **ALWAYS** update frontmatter of the output file when a step is complete
-- **NEVER** proceed without user consent
-
-### Success Metrics
-
-- Documents created correctly
-- All steps completed sequentially
-- User satisfied with collaborative process
-- Clean, maintainable file structure
-
-This architecture ensures disciplined, predictable workflow execution while maintaining flexibility for different use cases.