docs updated and agent standalone builder working now from the main install flow

2025-10-04 01:26:38 -05:00
parent 5ee4cf535c
commit a747017520
9 changed files with 908 additions and 96 deletions
--- a/src/modules/bmb/README.md
+++ b/src/modules/bmb/README.md
@@ -0,0 +1,132 @@
+# BMB - BMad Builder Module
+
+The BMB (BMad Builder Module) provides specialized tools and workflows for creating, customizing, and extending BMad Method components, including custom agents, workflows, and integrations.
+
+## Module Structure
+
+### 🤖 `/agents`
+
+Builder-specific agents that help create and customize BMad Method components:
+
+- Agent creation and configuration specialists
+- Workflow designers
+- Integration builders
+
+### 📋 `/workflows`
+
+Specialized workflows for building and extending BMad Method capabilities:
+
+#### Core Builder Workflows
+
+- `create-agent` - Design and implement custom agents
+- `create-workflow` - Build new workflow definitions
+- `create-team` - Configure agent teams
+- `bundle-agent` - Package agents for distribution
+- `create-method` - Design custom development methodologies
+
+#### Integration Workflows
+
+- `integrate-tool` - Connect external tools and services
+- `create-adapter` - Build API adapters
+- `setup-environment` - Configure development environments
+
+## Key Features
+
+### Agent Builder
+
+Create custom agents with:
+
+- Role-specific instructions
+- Tool configurations
+- Behavior patterns
+- Integration points
+
+### Workflow Designer
+
+Design workflows that:
+
+- Orchestrate multiple agents
+- Define process flows
+- Handle different project scales
+- Integrate with existing systems
+
+### Team Configuration
+
+Build teams that:
+
+- Combine complementary agent skills
+- Coordinate on complex tasks
+- Share context effectively
+- Deliver cohesive results
+
+## Quick Start
+
+```bash
+# Create a new custom agent
+bmad bmb create-agent
+
+# Design a new workflow
+bmad bmb create-workflow
+
+# Bundle an agent for sharing
+bmad bmb bundle-agent
+
+# Create a custom team configuration
+bmad bmb create-team
+```
+
+## Use Cases
+
+### Custom Agent Development
+
+Build specialized agents for:
+
+- Domain-specific expertise
+- Company-specific processes
+- Tool integrations
+- Automation tasks
+
+### Workflow Customization
+
+Create workflows for:
+
+- Unique development processes
+- Compliance requirements
+- Quality gates
+- Deployment pipelines
+
+### Team Orchestration
+
+Configure teams for:
+
+- Large-scale projects
+- Cross-functional collaboration
+- Specialized domains
+- Custom methodologies
+
+## Integration with BMM
+
+BMB works alongside BMM to:
+
+- Extend core BMM capabilities
+- Create custom implementations
+- Build domain-specific solutions
+- Integrate with existing tools
+
+## Best Practices
+
+1. **Start with existing patterns** - Study BMM agents and workflows before creating new ones
+2. **Keep it modular** - Build reusable components
+3. **Document thoroughly** - Clear documentation helps others use your creations
+4. **Test extensively** - Validate agents and workflows before production use
+5. **Share and collaborate** - Contribute useful components back to the community
+
+## Related Documentation
+
+- [BMM Module](../bmm/README.md) - Core method implementation
+- [Agent Creation Guide](./workflows/create-agent/README.md) - Detailed agent building instructions
+- [Workflow Design Patterns](./workflows/README.md) - Best practices for workflow creation
+
+---
+
+BMB empowers you to extend and customize the BMad Method to fit your specific needs while maintaining the power and consistency of the core framework.
--- a/src/modules/bmb/workflows/create-agent/README.md
+++ b/src/modules/bmb/workflows/create-agent/README.md
@@ -105,10 +105,17 @@ create-agent/

 ### Generated Files

- YAML agent saved at:
-  `{output_folder}/agents/{{agent_filename}}.agent.yaml` (or `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml` if `src_impact=true`)
- Compiled `.md` generated by installer at:
-  `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
+#### For Standalone Agents (not part of a module)
+
+- **YAML Source**: `{output_folder}/agents/{{agent_filename}}.agent.yaml`
+- **Installation Location**: `{project-root}/bmad/agents/{{agent_filename}}.md`
+- **Compilation**: Run `npm run build:agents` or use the installer menu
+
+#### For Module Agents
+
+- **YAML Source**: `src/modules/{{target_module}}/agents/{{agent_filename}}.agent.yaml`
+- **Installation Location**: `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md`
+- **Compilation**: Automatic during module installation

 ### YAML Agent Structure (simplified)

@@ -136,6 +143,51 @@ agent:
 If created, generates at:
 `{project-root}/bmad/_cfg/agents/{{module}}-{{agent_filename}}.customize.yaml`

+## Installation and Compilation
+
+### Agent Installation Locations
+
+Agents are installed to different locations based on their type:
+
+1. **Standalone Agents** (not part of a module)
+   - Source: Created in your project's output folder
+   - Installed to: `{project-root}/bmad/agents/`
+   - Compilation: Manual via `npm run build:agents`
+
+2. **Module Agents** (part of BMM, BMB, or custom modules)
+   - Source: Created in `src/modules/{module}/agents/`
+   - Installed to: `{project-root}/bmad/{module}/agents/`
+   - Compilation: Automatic during module installation
+
+### Compilation Process
+
+The installer compiles YAML agent definitions to Markdown:
+
+```bash
+# For standalone agents
+npm run build:agents
+
+# For all BMad components (includes agents)
+npm run install:bmad
+
+# Using the installer menu
+npm run installer
+# Then select: Compile Agents
+```
+
+### Build Commands
+
+Additional build commands for agent management:
+
+```bash
+# Build specific agent types
+npx bmad-method build:agents        # Build standalone agents
+npx bmad-method build:modules        # Build module agents (with modules)
+
+# Full rebuild
+npx bmad-method build:all           # Rebuild everything
+```
+
 ## Requirements

 - BMAD Core v6 project structure
@@ -192,11 +244,13 @@ Users can go from **vague idea → brainstormed concept → built agent** in one

 ### After Completion

-1. Compile agents: `npm run install:bmad` → "Compile Agents"
-2. Test the compiled `.md` agent in your IDE
-3. Implement any "todo" workflows
-4. Refine persona based on usage or via customize file
-5. Add more commands as agent evolves
+1. **Compile the agent**:
+   - For standalone agents: Run `npm run build:agents` or use the installer menu
+   - For module agents: Automatic during module installation
+2. **Test the agent**: Use the compiled `.md` agent in your IDE
+3. **Implement placeholders**: Complete any "todo" workflows referenced
+4. **Refine as needed**: Use customize file for persona adjustments
+5. **Evolve over time**: Add new commands as requirements emerge

 ## Agent Types

--- a/src/modules/bmb/workflows/create-agent/agent-types.md
+++ b/src/modules/bmb/workflows/create-agent/agent-types.md
@@ -2,7 +2,41 @@

 ## Overview

-BMAD agents come in three distinct types, each designed for different use cases and complexity levels.
+BMAD agents come in three distinct types, each designed for different use cases and complexity levels. The type determines where the agent is stored and what capabilities it has.
+
+## Directory Structure by Type
+
+### Standalone Agents (Simple & Expert)
+
+Live in their own dedicated directories under `bmad/agents/`:
+
+```
+bmad/agents/
+├── my-helper/                   # Simple agent
+│   ├── my-helper.agent.yaml     # Agent definition
+│   └── my-helper.md             # Built XML (generated)
+│
+└── domain-expert/               # Expert agent
+    ├── domain-expert.agent.yaml
+    ├── domain-expert.md         # Built XML
+    └── domain-expert-sidecar/   # Expert resources
+        ├── memories.md          # Persistent memory
+        ├── instructions.md      # Private directives
+        └── knowledge/           # Domain knowledge
+
+```
+
+### Module Agents
+
+Part of a module system under `bmad/{module}/agents/`:
+
+```
+bmad/bmm/agents/
+├── product-manager.agent.yaml
+├── product-manager.md           # Built XML
+├── business-analyst.agent.yaml
+└── business-analyst.md          # Built XML
+```

 ## Agent Types

@@ -10,12 +44,15 @@ BMAD agents come in three distinct types, each designed for different use cases

 **Purpose:** Self-contained, standalone agents with embedded capabilities

+**Location:** `bmad/agents/{agent-name}/`
+
 **Characteristics:**

 - All logic embedded within the agent file
 - No external dependencies
 - Quick to create and deploy
 - Perfect for single-purpose tools
+- Lives in its own directory

 **Use Cases:**

@@ -24,7 +61,26 @@ BMAD agents come in three distinct types, each designed for different use cases
 - Simple analyzers
 - Static advisors

-**Structure:**
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'Helper'
+    title: 'Simple Helper'
+    icon: '🤖'
+    type: 'simple'
+  persona:
+    role: 'Simple Helper Role'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  menu:
+    - trigger: calculate
+      description: 'Perform calculation'
+```
+
+**XML Structure (built):**

 ```xml
 <agent id="simple-agent" name="Helper" title="Simple Helper" icon="🤖">
@@ -49,12 +105,15 @@ BMAD agents come in three distinct types, each designed for different use cases

 **Purpose:** Specialized agents with domain expertise and sidecar resources

+**Location:** `bmad/agents/{agent-name}/` with sidecar directory
+
 **Characteristics:**

 - Has access to specific folders/files
 - Domain-restricted operations
 - Maintains specialized knowledge
 - Can have memory/context files
+- Includes sidecar directory for resources

 **Use Cases:**

@@ -63,7 +122,30 @@ BMAD agents come in three distinct types, each designed for different use cases
 - Domain expert (medical, legal, technical)
 - Personal coach with history

-**Structure:**
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'Domain Expert'
+    title: 'Specialist'
+    icon: '🎯'
+    type: 'expert'
+  persona:
+    role: 'Domain Specialist Role'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  critical_actions:
+    - 'Load COMPLETE file {agent-folder}/instructions.md and follow ALL directives'
+    - 'Load COMPLETE file {agent-folder}/memories.md into permanent context'
+    - 'ONLY access {user-folder}/diary/ - NO OTHER FOLDERS'
+  menu:
+    - trigger: analyze
+      description: 'Analyze domain-specific data'
+```
+
+**XML Structure (built):**

 ```xml
 <agent id="expert-agent" name="Domain Expert" title="Specialist" icon="🎯">
@@ -83,26 +165,33 @@ BMAD agents come in three distinct types, each designed for different use cases
 </agent>
 ```

-**Sidecar Structure:**
+**Complete Directory Structure:**

 ```
-expert-agent/
-├── agent.md          # Main agent file
-├── memories.md       # Personal context/memories
-├── knowledge/        # Domain knowledge base
-└── data/            # Agent-specific data
+bmad/agents/expert-agent/
+├── expert-agent.agent.yaml      # Agent YAML source
+├── expert-agent.md              # Built XML (generated)
+└── expert-agent-sidecar/        # Sidecar resources
+    ├── memories.md              # Persistent memory
+    ├── instructions.md          # Private directives
+    ├── knowledge/               # Domain knowledge base
+    │   └── README.md
+    └── sessions/                # Session notes
 ```

 ### 3. Module Agent

 **Purpose:** Full-featured agents belonging to a module with access to workflows and resources

+**Location:** `bmad/{module}/agents/`
+
 **Characteristics:**

 - Part of a BMAD module (bmm, bmb, cis)
 - Access to multiple workflows
 - Can invoke other tasks and agents
 - Professional/enterprise grade
+- Integrated with module workflows

 **Use Cases:**

@@ -111,7 +200,33 @@ expert-agent/
 - Test Architect (test strategies, automation)
 - Business Analyst (market research, requirements)

-**Structure:**
+**YAML Structure (source):**
+
+```yaml
+agent:
+  metadata:
+    name: 'John'
+    title: 'Product Manager'
+    icon: '📋'
+    module: 'bmm'
+    type: 'module'
+  persona:
+    role: 'Product Management Expert'
+    identity: '...'
+    communication_style: '...'
+    principles: ['...']
+  critical_actions:
+    - 'Load config from {project-root}/bmad/{module}/config.yaml'
+  menu:
+    - trigger: create-prd
+      workflow: '{project-root}/bmad/bmm/workflows/prd/workflow.yaml'
+      description: 'Create PRD'
+    - trigger: validate
+      exec: '{project-root}/bmad/core/tasks/validate-workflow.xml'
+      description: 'Validate document'
+```
+
+**XML Structure (built):**

 ```xml
 <agent id="bmad/bmm/agents/pm.md" name="John" title="Product Manager" icon="📋">
--- a/src/modules/bmb/workflows/create-agent/instructions.md
+++ b/src/modules/bmb/workflows/create-agent/instructions.md
@@ -55,18 +55,20 @@ Present the recommendation naturally: _"Given that your agent will [summarize pu

 For Module agents, discover:

- "Which system would this fit best with?" (bmm, bmb, cis, or custom)
+- "Which module system would this fit best with?" (bmm, bmb, cis, or custom)
 - Store as {{target_module}} for path determination
+- Agent will be saved to: bmad/{{target_module}}/agents/

-For Expert agents, explore:
+For Simple/Expert agents (standalone):

- "What kind of information will it need to access?"
- "Are there specific folders or data it should work with?"
+- "This will be your personal agent, not tied to a module"
+- Agent will be saved to: bmad/agents/{{agent-name}}/
+- All sidecar files will be in the same folder

-<critical>Check {src_impact} variable to determine output location:</critical>
+<critical>Determine agent location:</critical>

- If {src_impact} = true: Agent will be saved to {src_output_file}
- If {src_impact} = false: Agent will be saved to {default_output_file}
+- Module Agent → bmad/{{module}}/agents/{{agent-name}}.agent.yaml
+- Standalone Agent → bmad/agents/{{agent-name}}/{{agent-name}}.agent.yaml

 <note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
 </step>
@@ -298,15 +300,124 @@ Make it feel like preparing an office:
 - "What kind of information will it need quick access to?"
 - "Should it have its own data folders?"

-Create the resources as a natural extension:
+<action>Determine sidecar location:</action>

-1. "Creating [agent name]'s knowledge base..."
-2. "Setting up its personal workspace..."
-3. "Giving it access to the resources it needs..."
+- If build tools available: Create next to agent YAML
+- If no build tools: Create in output folder with clear structure
+
+<action>Actually CREATE the sidecar files:</action>
+
+1. Create folder structure:
+
+```
+{{agent_filename}}-sidecar/
+├── memories.md         # Persistent memory
+├── instructions.md     # Private directives
+├── knowledge/         # Knowledge base
+│   └── README.md
+└── sessions/          # Session notes
+```
+
+2. Create **memories.md**:
+
+```markdown
+# {{agent_name}}'s Memory Bank
+
+## User Preferences
+
+<!-- Populated as I learn about you -->
+
+## Session History
+
+<!-- Important moments from our interactions -->
+
+## Personal Notes
+
+<!-- My observations and insights -->
+```
+
+3. Create **instructions.md**:
+
+```markdown
+# {{agent_name}} Private Instructions
+
+## Core Directives
+
+- Maintain character: {{brief_personality_summary}}
+- Domain: {{agent_domain}}
+- Access: Only this sidecar folder
+
+## Special Instructions
+
+{{any_special_rules_from_creation}}
+```
+
+4. Create **knowledge/README.md**:
+
+```markdown
+# {{agent_name}}'s Knowledge Base
+
+Add domain-specific resources here.
+```
+
+<action>Update agent YAML to reference sidecar:</action>
+Add `sidecar:` section with paths to created files
+
+<action>Show user the created structure:</action>
+"I've created {{agent_name}}'s complete workspace at: {{sidecar_path}}"

 <template-output>sidecar_resources</template-output>
 </step>

+<step n="8b" goal="Handle build tools availability">
+<action>Check if BMAD build tools are available:</action>
+
+<check>If in BMAD-METHOD project with build tools:</check>
+<action>Proceed normally - agent will be built later</action>
+
+<check>If NO build tools available (external project):</check>
+<ask>Build tools not detected in this project. Would you like me to:
+
+1. Generate the compiled agent (.md with XML) ready to use
+2. Keep the YAML and build it elsewhere
+3. Provide both formats</ask>
+
+<check>If option 1 or 3 selected:</check>
+<action>Generate compiled agent XML:</action>
+
+```xml
+<!-- Powered by BMAD-CORE™ -->
+
+# {{agent_title}}
+
+<agent id="{{agent_id}}" name="{{agent_name}}" title="{{agent_title}}" icon="{{agent_icon}}">
+  <activation critical="MANDATORY">
+    <!-- Inject standard activation -->
+    {{activation_rules}}
+    {{activation_greeting}}
+  </activation>
+
+  <persona>
+    <role>{{role}}</role>
+    <identity>{{identity}}</identity>
+    <communication_style>{{style}}</communication_style>
+    <principles>{{principles}}</principles>
+  </persona>
+
+  <menu>
+    <item cmd="*help">Show numbered menu</item>
+    {{converted_menu_items}}
+    <item cmd="*exit">Exit with confirmation</item>
+  </menu>
+</agent>
+```
+
+<action>Save compiled version as {{agent_filename}}.md</action>
+<action>Provide path for .claude/commands/ or similar</action>
+
+<template-output>build_handling</template-output>
+</step>
+
 <step n="9" goal="Quality check with personality">

 "Let me make sure [agent name] is ready to go!"
--- a/src/modules/bmm/README.md
+++ b/src/modules/bmm/README.md
@@ -0,0 +1,126 @@
+# BMM - BMad Method Module
+
+The BMM (BMad Method Module) is the core orchestration system for the BMad Method v6a, providing comprehensive software development lifecycle management through specialized agents, workflows, teams, and tasks.
+
+## 📚 Essential Reading
+
+**Before using BMM, you MUST read the [BMM v6 Workflows Guide](./workflows/README.md).** This document explains the revolutionary v6a workflow system and how all components work together.
+
+## Module Structure
+
+### 🤖 `/agents`
+
+Specialized AI agents for different development roles:
+
+- **PM** (Product Manager) - Product planning and requirements
+- **Analyst** - Business analysis and research
+- **Architect** - Technical architecture and design
+- **SM** (Scrum Master) - Sprint and story management
+- **DEV** (Developer) - Code implementation
+- **SR** (Senior Reviewer) - Code review and quality
+- **UX** - User experience design
+- And more specialized roles
+
+### 📋 `/workflows`
+
+The heart of BMM - structured workflows for the four development phases:
+
+1. **Analysis Phase** (Optional)
+   - `brainstorm-project` - Project ideation
+   - `research` - Market/technical research
+   - `product-brief` - Product strategy
+
+2. **Planning Phase** (Required)
+   - `plan-project` - Scale-adaptive project planning
+   - Routes to appropriate documentation based on project complexity
+
+3. **Solutioning Phase** (Level 3-4 projects)
+   - `3-solutioning` - Architecture design
+   - `tech-spec` - Epic-specific technical specifications
+
+4. **Implementation Phase** (Iterative)
+   - `create-story` - Story generation
+   - `story-context` - Expertise injection
+   - `dev-story` - Implementation
+   - `review-story` - Quality validation
+   - `correct-course` - Issue resolution
+   - `retrospective` - Continuous improvement
+
+### 👥 `/teams`
+
+Pre-configured agent teams for different project types and phases. Teams coordinate multiple agents working together on complex tasks.
+
+### 📝 `/tasks`
+
+Reusable task definitions that agents execute within workflows. These are the atomic units of work that compose into larger workflows.
+
+### 🔧 `/sub-modules`
+
+Extension modules that add specialized capabilities to BMM.
+
+### 🏗️ `/testarch`
+
+Test architecture and quality assurance components.
+
+## Quick Start
+
+```bash
+# Run a planning workflow
+bmad pm plan-project
+
+# Create a new story
+bmad sm create-story
+
+# Run development workflow
+bmad dev develop
+
+# Review implementation
+bmad sr review-story
+```
+
+## Key Concepts
+
+### Scale Levels
+
+BMM automatically adapts to project complexity:
+
+- **Level 0**: Single atomic change
+- **Level 1**: 1-10 stories, minimal documentation
+- **Level 2**: 5-15 stories, focused PRD
+- **Level 3**: 12-40 stories, full architecture
+- **Level 4**: 40+ stories, enterprise scale
+
+### Just-In-Time Design
+
+Technical specifications are created one epic at a time during implementation, not all upfront, allowing for learning and adaptation.
+
+### Context Injection
+
+Story-specific technical guidance is generated dynamically, providing developers with exactly the expertise needed for each task.
+
+## Integration with BMad Core
+
+BMM integrates seamlessly with the BMad Core framework, leveraging:
+
+- The agent execution engine
+- Workflow orchestration
+- Task management
+- Team coordination
+
+## Related Documentation
+
+- [BMM Workflows Guide](./workflows/README.md) - **Start here!**
+- [Agent Documentation](./agents/README.md) - Individual agent capabilities
+- [Team Configurations](./teams/README.md) - Pre-built team setups
+- [Task Library](./tasks/README.md) - Reusable task components
+
+## Best Practices
+
+1. **Always start with the workflows** - Let workflows guide your process
+2. **Respect the scale** - Don't over-document small projects
+3. **Embrace iteration** - Use retrospectives to continuously improve
+4. **Trust the process** - The v6a methodology has been carefully designed
+
+---
+
+For detailed information about the complete BMad Method v6a workflow system, see the [BMM Workflows README](./workflows/README.md).
--- a/src/modules/bmm/workflows/README.md
+++ b/src/modules/bmm/workflows/README.md
@@ -346,4 +346,4 @@ bmad sm retrospective     # After epic

 ---

-This document supersedes v6-IMPORTANT-BMM-FLOW.md and serves as the authoritative guide to BMM workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.
+This document serves as the authoritative guide to BMM v6a workflow execution. For detailed information about individual workflows, see their respective README files in the workflow folders.