bmad-method 6.0.0-alpha.20 → 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._