bmad-method 6.0.0-alpha.11 → 6.0.0-alpha.13

package/src/modules/bmb/README.md

@@ -5,6 +5,8 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 ## 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)
@@ -16,124 +18,172 @@ Specialized tools and workflows for creating, customizing, and extending BMad co
 
 **BMad Builder** - Master builder agent orchestrating all creation workflows with deep knowledge of BMad architecture and conventions.
 
+- Location: `.bmad/bmb/agents/bmad-builder.md`
+
 ### 📋 Workflows
 
-Comprehensive suite for building and maintaining BMad components.
+**Active Workflows** (Step-File Architecture)
 
-## Core Workflows
+- Location: `src/modules/bmb/workflows/`
+- 5 core workflows with 41 step files total
+- Template-based execution with JIT loading
 
-### Creation Workflows
+**Legacy Workflows** (Being Migrated)
 
-**[create-agent](./workflows/create-agent/README.md)** - Build BMad agents
+- Location: `src/modules/bmb/workflows-legacy/`
+- Module-specific workflows pending conversion to step-file architecture
 
-- Interactive persona development
-- Command structure design
-- YAML source compilation to .md
+### 📚 Documentation
 
-**[create-workflow](./workflows/create-workflow/README.md)** - Design workflows
+- Location: `src/modules/bmb/docs/`
+- Comprehensive guides for agents and workflows
+- Architecture patterns and best practices
 
-- Structured multi-step processes
-- Configuration validation
-- Web bundle support
+### 🔍 Reference Materials
 
-**[create-module](./workflows/create-module/README.md)** - Build complete modules
+- Location: `src/modules/bmb/reference/`
+- Working examples of agents and workflows
+- Template patterns and implementation guides
 
-- Full module infrastructure
-- Agent and workflow integration
-- Installation automation
+## Documentation
 
-**[module-brief](./workflows/module-brief/README.md)** - Strategic planning
+### 📖 Agent Documentation
 
-- Module blueprint creation
-- Vision and architecture
-- Comprehensive analysis
+- **[Agent Index](./docs/agents/index.md)** - Complete agent architecture guide
+- **[Agent Types Guide](./docs/agents/understanding-agent-types.md)** - Simple vs Expert vs Module agents
+- **[Menu Patterns](./docs/agents/agent-menu-patterns.md)** - YAML menu design and handler types
+- **[Agent Compilation](./docs/agents/agent-compilation.md)** - Auto-injection rules and compilation process
 
-### Editing Workflows
+### 📋 Workflow Documentation
 
-**[edit-agent](./workflows/edit-agent/README.md)** - Modify existing agents
+- **[Workflow Index](./docs/workflows/index.md)** - Core workflow system overview
+- **[Architecture Guide](./docs/workflows/architecture.md)** - Step-file design and JIT loading
+- **[Template System](./docs/workflows/step-template.md)** - Standard step file template
+- **[Intent vs Prescriptive](./docs/workflows/intent-vs-prescriptive-spectrum.md)** - Design philosophy
 
-- Persona refinement
-- Command updates
-- Best practice compliance
+## Reference Materials
 
-**[edit-workflow](./workflows/edit-workflow/README.md)** - Update workflows
+### 🤖 Agent Examples
 
-- Structure maintenance
-- Configuration updates
-- Documentation sync
+- **[Simple Agent Example](./reference/agents/simple-examples/commit-poet.agent.yaml)** - Self-contained agent
+- **[Expert Agent Example](./reference/agents/expert-examples/journal-keeper/)** - Agent with persistent memory
+- **[Module Agent Examples](./reference/agents/module-examples/)** - Integration patterns (BMM, CIS)
+
+### 📋 Workflow Examples
+
+- **[Meal Prep & Nutrition](./reference/workflows/meal-prep-nutrition/)** - Complete step-file workflow demonstration
+- **Template patterns** for document generation and state management
+
+## Core Workflows
 
-**[edit-module](./workflows/edit-module/README.md)** - Module enhancement
+### Creation Workflows (Step-File Architecture)
 
-- Component modifications
-- Dependency management
-- Version control
+**[create-agent](./workflows/create-agent/)** - Build BMad agents
 
-### Maintenance Workflows
+- 11 guided steps from brainstorming to celebration
+- 18 reference data files with validation checklists
+- Template-based agent generation
+
+**[create-workflow](./workflows/create-workflow/)** - Design workflows
+
+- 12 structured steps from init to review
+- 9 template files for workflow creation
+- Step-file architecture implementation
+
+### Editing Workflows
+
+**[edit-agent](./workflows/edit-agent/)** - Modify existing agents
+
+- 5 steps: discovery → validation
+- Intent-driven analysis and updates
+- Best practice compliance
 
-**[convert-legacy](./workflows/convert-legacy/README.md)** - Migration tool
+**[edit-workflow](./workflows/edit-workflow/)** - Update workflows
 
-- v4 to v6 conversion
-- Structure compliance
-- Convention updates
+- 5 steps: analyze → compliance check
+- Structure maintenance and validation
+- Template updates for consistency
 
-**[audit-workflow](./workflows/audit-workflow/README.md)** - Quality validation
+### Quality Assurance
 
-- Structure verification
-- Config standards check
-- Bloat detection
-- Web bundle completeness
+**[workflow-compliance-check](./workflows/workflow-compliance-check/)** - Validation
 
-**[redoc](./workflows/redoc/README.md)** - Auto-documentation
+- 8 systematic validation steps
+- Adversarial analysis approach
+- Detailed compliance reporting
 
-- Reverse-tree approach
-- Technical writer quality
-- Convention compliance
+### 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:
 
-### Full Module Agent
+### Simple Agent
 
-- Complete persona and role definition
-- Command structure with fuzzy matching
-- Workflow integration
-- Module-specific capabilities
+- **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
 
-### Hybrid Agent
+### Expert Agent
 
-- Shared core capabilities
-- Module-specific extensions
-- Cross-module compatibility
+- **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
 
-### Standalone Agent
+### Module Agent
 
-- Independent operation
-- Minimal dependencies
-- Specialized single purpose
+- **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
 
-1. **Load BMad Builder agent** in your IDE
-2. **Choose creation type:**
+### Using BMad Builder Agent
+
+1. **Load BMad Builder agent** in your IDE:
    ```
-   *create-agent     # New agent
-   *create-workflow  # New workflow
-   *create-module    # Complete module
+   /bmad:bmb:agents:bmad-builder
    ```
-3. **Follow interactive prompts**
+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: *create-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
+```
 
-[Interactive session begins]
-- Brainstorming phase (optional)
-- Persona development
-- Command structure
-- Integration points
+### 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
@@ -165,30 +215,47 @@ Package modules for:
 - 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 existing patterns** - Review BMM/CIS implementations
-2. **Follow conventions** - Use established structures
-3. **Document thoroughly** - Clear instructions essential
-4. **Test iteratively** - Validate during creation
-5. **Consider reusability** - Build modular components
+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
-- **BMM** - Extend development capabilities
-- **CIS** - Leverage creative workflows
-- **Custom Modules** - Your domain solutions
+- **BMad Core** - Framework foundation and agent compilation
+- **BMM** - Development workflows and project management
+- **CIS** - Creative innovation and strategic workflows
+- **Custom Modules** - Domain-specific solutions
 
-## Related Documentation
+## Getting Help
 
-- **[Agent Creation Guide](./workflows/create-agent/README.md)** - Detailed instructions
-- **[Module Structure](./workflows/create-module/module-structure.md)** - Architecture patterns
-- **[BMM Module](../bmm/README.md)** - Reference implementation
-- **[Core Framework](../../core/README.md)** - Foundation concepts
+- **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 empowers you to extend BMad Method for your specific needs while maintaining framework consistency and power.
+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/_module-installer/install-config.yaml

@@ -17,15 +17,15 @@ subheader: "Configure the settings for the BoMB Factory!\nThe agent, workflow an
 
 custom_agent_location:
   prompt: "Where do custom agents get created?"
-  default: "{bmad_folder}/custom/agents"
+  default: "{bmad_folder}/custom/src/agents"
   result: "{project-root}/{value}"
 
 custom_workflow_location:
   prompt: "Where do custom workflows get stored?"
-  default: "{bmad_folder}/custom/workflows"
+  default: "{bmad_folder}/custom/src/workflows"
   result: "{project-root}/{value}"
 
 custom_module_location:
   prompt: "Where do custom modules get stored?"
-  default: "{bmad_folder}/custom/modules"
+  default: "{bmad_folder}/custom/src/modules"
   result: "{project-root}/{value}"

package/src/modules/bmb/agents/bmad-builder.agent.yaml

@@ -11,47 +11,61 @@ agent:
     module: bmb
 
   persona:
-    role: Master BMad Module Agent Team and Workflow Builder and Maintainer
-    identity: Lives to serve the expansion of the BMad Method
-    communication_style: Talks like a pulp super hero
+    role: Generalist Builder and BMAD System Maintainer
+    identity: A hands-on builder who gets things done efficiently and maintains the entire BMAD ecosystem
+    communication_style: Direct, action-oriented, and encouraging with a can-do attitude
     principles:
-      - Execute resources directly
+      - Execute resources directly without hesitation
       - Load resources at runtime never pre-load
-      - Always present numbered lists for choices
+      - Always present numbered lists for clear choices
+      - Focus on practical implementation and results
+      - Maintain system-wide coherence and standards
+      - Balance speed with quality and compliance
 
-  menu:
-    - trigger: audit-workflow
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/audit-workflow/workflow.yaml"
-      description: Audit existing workflows for BMAD Core compliance and best practices
+  discussion: true
+  conversational_knowledge:
+    - agents: "{project-root}/{bmad_folder}/bmb/docs/agents/kb.csv"
+    - workflows: "{project-root}/{bmad_folder}/bmb/docs/workflows/kb.csv"
+    - modules: "{project-root}/{bmad_folder}/bmb/docs/modules/kb.csv"
 
-    - trigger: convert
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/convert-legacy/workflow.yaml"
-      description: Convert v4 or any other style task agent or template to a workflow
+  menu:
+    - multi: "[CA] Create, [EA] Edit, or [VA] Validate BMAD agents with best practices"
+      triggers:
+        - create-agent:
+            - input: CA or fuzzy match create agent
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.md"
+            - data: null
+        - edit-agent:
+            - input: EA or fuzzy match edit agent
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/edit-agent/workflow.md"
+            - data: null
+        - run-agent-compliance-check:
+            - input: VA or fuzzy match validate agent
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/agent-compliance-check/workflow.md"
+            - data: null
 
-    - trigger: create-agent
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml"
-      description: Create a new BMAD Core compliant agent
+    - multi: "[CW] Create, [EW] Edit, or [VW] Validate BMAD workflows with best practices"
+      triggers:
+        - create-workflow:
+            - input: CW or fuzzy match create workflow
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.md"
+            - data: null
+            - type: exec
+        - edit-workflow:
+            - input: EW or fuzzy match edit workflow
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/edit-workflow/workflow.md"
+            - data: null
+            - type: exec
+        - run-workflow-compliance-check:
+            - input: VW or fuzzy match validate workflow
+            - route: "{project-root}/{bmad_folder}/bmb/workflows/workflow-compliance-check/workflow.md"
+            - data: null
+            - type: exec
 
     - trigger: create-module
       workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-module/workflow.yaml"
       description: Create a complete BMAD compatible module (custom agents and workflows)
 
-    - trigger: create-workflow
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/create-workflow/workflow.yaml"
-      description: Create a new BMAD Core workflow with proper structure
-
-    - trigger: edit-agent
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-agent/workflow.yaml"
-      description: Edit existing agents while following best practices
-
     - trigger: edit-module
       workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-module/workflow.yaml"
       description: Edit existing modules (structure, agents, workflows, documentation)
-
-    - trigger: edit-workflow
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/edit-workflow/workflow.yaml"
-      description: Edit existing workflows while following best practices
-
-    - trigger: redoc
-      workflow: "{project-root}/{bmad_folder}/bmb/workflows/redoc/workflow.yaml"
-      description: Create or update module documentation

package/src/modules/bmb/docs/{agent-menu-patterns.md → agents/agent-menu-patterns.md}

@@ -115,7 +115,7 @@ menu:
   - trigger: create-brief
     exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
     tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
-    description: 'Create project brief'
+    description: 'Create a Product Brief'
 ```
 
 **When to Use:**

package/src/modules/bmb/docs/{module-agent-architecture.md → agents/module-agent-architecture.md}

@@ -125,7 +125,7 @@ menu:
   - trigger: create-brief
     exec: '{project-root}/{bmad_folder}/core/tasks/create-doc.xml'
     tmpl: '{project-root}/{bmad_folder}/bmm/templates/brief.md'
-    description: 'Create project brief from template'
+    description: 'Create a Product Brief from template'
 ```
 
 Combines task execution with template file.

package/src/modules/bmb/docs/{simple-agent-architecture.md → agents/simple-agent-architecture.md}

@@ -219,7 +219,7 @@ cp /path/to/commit-poet.agent.yaml .bmad/custom/agents/
 
 # Install with personalization
 bmad agent-install
-# or: npx bmad agent-install
+# or: npx bmad-method agent-install
 ```
 
 The installer: