bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.20

package/src/modules/bmb/workflows/create-agent/templates/simple-agent.template.md

@@ -0,0 +1,257 @@
+# Simple Agent Architecture
+
+Self-contained agents with prompts, menus, and optional install-time customization.
+
+## When to Use
+
+- Single-purpose utilities (commit message generator, code formatter)
+- Self-contained logic with no external dependencies
+- Agents that benefit from user customization (style, tone, preferences)
+- Quick-to-build standalone helpers
+
+## YAML Structure
+
+```yaml
+agent:
+  metadata:
+    id: _bmad/agents/{agent-name}/{agent-name}.md
+    name: 'Persona Name'
+    title: 'Agent Title'
+    icon: 'emoji'
+    type: simple
+
+  persona:
+    role: |
+      First-person description of primary function (1-2 sentences)
+
+    identity: |
+      Background, experience, specializations in first-person (2-5 sentences)
+      {{#if custom_variable}}
+      Conditional identity text based on install_config
+      {{/if}}
+
+    communication_style: |
+      {{#if style_choice == "professional"}}
+      Professional and systematic approach...
+      {{/if}}
+      {{#if style_choice == "casual"}}
+      Friendly and approachable tone...
+      {{/if}}
+
+    principles:
+      - Core belief or methodology
+      - Another guiding principle
+      - Values that shape decisions
+
+  prompts:
+    - id: main-action
+      content: |
+        <instructions>
+        What this prompt does
+        </instructions>
+
+        <process>
+        1. Step one
+        {{#if detailed_mode}}
+        2. Additional detailed step
+        {{/if}}
+        3. Final step
+        </process>
+
+    - id: another-action
+      content: |
+        Another reusable prompt template
+
+  menu:
+    - trigger: inline
+      action: 'Direct inline prompt text'
+      description: 'Execute inline action'
+
+    - multi: "[DF] Do Foo or start [CH] Chat with expert"
+      triggers:
+        - do-foo
+            - input: [DF] or fuzzy match on do foo
+            - action: '#main-action'
+            - data: what is being discussed or suggested with the command, along with custom party custom agents if specified
+            - type: action
+        - expert-chat:
+            - input: [CH] or fuzzy match validate agent
+            - action: agent responds as expert based on its persona to converse
+            - type: action
+
+  install_config:
+    compile_time_only: true
+    description: 'Personalize your agent'
+    questions:
+      - var: style_choice
+        prompt: 'Preferred communication style?'
+        type: choice
+        options:
+          - label: 'Professional'
+            value: 'professional'
+          - label: 'Casual'
+            value: 'casual'
+        default: 'professional'
+
+      - var: detailed_mode
+        prompt: 'Enable detailed explanations?'
+        type: boolean
+        default: true
+
+      - var: custom_variable
+        prompt: 'Your custom text'
+        type: text
+        default: ''
+```
+
+## Key Components
+
+### Metadata
+
+- **id**: Final compiled path (`_bmad/agents/{name}/{name}.md` for standalone)
+- **name**: Agent's persona name displayed to users
+- **title**: Professional role/function
+- **icon**: Single emoji for visual identification
+- **type**: `simple` - identifies agent category
+
+### Persona (First-Person Voice)
+
+- **role**: Primary expertise in 1-2 sentences
+- **identity**: Background and specializations (2-5 sentences)
+- **communication_style**: HOW the agent interacts, including conditional variations
+- **principles**: Array of core beliefs (start with action verbs)
+
+### Prompts with IDs
+
+Reusable prompt templates referenced by `#id`:
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>
+      Analyze the provided code for patterns
+      </instructions>
+```
+
+Menu items reference these:
+
+```yaml
+menu:
+  - trigger: analyze
+    action: '#analyze-code'
+    description: 'Analyze code patterns'
+```
+
+### Menu Actions
+
+Two forms of action handlers:
+
+1. **Prompt Reference**: `action: "#prompt-id"` - Executes prompt content
+2. **Inline Instruction**: `action: "Direct text instruction"` - Executes text directly
+
+### Install Config (Compile-Time Customization)
+
+Questions asked during `bmad agent-install`:
+
+**Question Types:**
+
+- `choice` - Multiple choice selection
+- `boolean` - Yes/no toggle
+- `text` - Free-form text input
+
+**Variables become available in Handlebars:**
+
+```yaml
+{{#if variable_name}}
+Content when true
+{{/if}}
+
+{{#if variable_name == "value"}}
+Content when equals value
+{{/if}}
+
+{{#unless variable_name}}
+Content when false
+{{/unless}}
+```
+
+## What Gets Injected at Compile Time
+
+The `tools/cli/lib/agent/compiler.js` automatically adds:
+
+1. **YAML Frontmatter**
+
+   ```yaml
+   ---
+   name: 'agent name'
+   description: 'Agent Title'
+   ---
+   ```
+
+2. **Activation Block**
+   - Load persona step
+   - Load core config for {user_name}, {communication_language}
+   - Agent-specific critical_actions as numbered steps
+   - Menu display and input handling
+   - Menu handlers (action/workflow/exec/tmpl) based on usage
+   - Rules section
+
+3. **Auto-Injected Menu Items**
+   - `*help` always first
+   - `*exit` always last
+
+4. **Trigger Prefixing**
+   - Triggers without `*` get it added automatically
+
+## Reference Example
+
+See: `../../reference/agents/simple-examples/commit-poet.agent.yaml`
+
+Features demonstrated:
+
+- Handlebars conditionals for style variations
+- Multiple prompt templates with semantic XML tags
+- Install config with choice, boolean, and text questions
+- Menu items using both `#id` references and inline actions
+
+## Installation
+
+```bash
+# Copy to your project
+cp /path/to/commit-poet.agent.yaml _bmad/custom/agents/
+
+# Create custom.yaml and install
+echo "code: my-agent
+name: My Agent
+default_selected: true" > custom.yaml
+
+npx bmad-method install
+# or: bmad install
+```
+
+The installer:
+
+1. Prompts for personalization (name, preferences)
+2. Processes Handlebars templates with your answers
+3. Compiles YAML to XML-in-markdown
+4. Creates IDE slash commands
+5. Saves source for reinstallation
+
+## Best Practices
+
+1. **Use first-person voice** in all persona elements
+2. **Keep prompts focused** - one clear purpose per prompt
+3. **Leverage Handlebars** for user customization without code changes
+4. **Provide sensible defaults** in install_config
+5. **Use semantic XML tags** in prompt content for clarity
+6. **Test all conditional paths** before distribution
+
+## Validation Checklist
+
+- [ ] Valid YAML syntax
+- [ ] All metadata fields present (id, name, title, icon, type)
+- [ ] Persona complete (role, identity, communication_style, principles)
+- [ ] Prompts have unique IDs
+- [ ] Install config questions have defaults
+- [ ] File named `{agent-name}.agent.yaml`

package/src/modules/bmb/workflows/create-agent/workflow.md

@@ -0,0 +1,58 @@
+---
+name: create-agent
+description: Interactive workflow to build BMAD Core compliant agents with optional brainstorming, persona development, and command structure
+web_bundle: true
+---
+
+# Create Agent Workflow
+
+**Goal:** Collaboratively build BMAD Core compliant agents through guided discovery, preserving all functionality from the legacy workflow while enabling step-specific loading.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also an expert agent architect and builder specializing in BMAD Core agent creation. You guide users through discovering their agent's purpose, shaping its personality, building its capabilities, and generating complete YAML configuration with all necessary supporting files.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self contained instruction file
+- **Just-In-Time Loading**: Only the current step file is in memory
+- **Sequential Enforcement**: Steps completed in order, conditional based on agent type
+- **State Tracking**: Document progress in agent output files
+- **Agent-Type Optimization**: Load only relevant steps for Simple/Expert/Module agents
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute numbered sections in order
+3. **WAIT FOR INPUT**: Halt at menus and wait for user selection
+4. **CHECK CONTINUATION**: Only proceed when user selects 'C' (Continue)
+5. **SAVE STATE**: Update progress before loading next step
+6. **LOAD NEXT**: When directed, load and execute the next step file
+
+### Critical Rules
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps unless explicitly optional
+- 💾 **ALWAYS** save progress and outputs
+- 🎯 **ALWAYS** follow exact instructions in step files
+- ⏸️ **ALWAYS** halt at menus and wait for input
+- 📋 **NEVER** pre-load future steps
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Configuration Loading
+
+Load and read full config from `{project-root}/_bmad/bmb/config.yaml`:
+
+- `project_name`, `user_name`, `communication_language`, `document_output_language`, `bmb_creations_output_folder`
+
+### 2. First Step EXECUTION
+
+Load, read completely, then execute `steps/step-01-brainstorm.md` to begin the workflow.

package/src/modules/bmb/workflows/create-module/steps/step-01-init.md

@@ -0,0 +1,155 @@
+---
+nextStepFile: '{installed_path}/steps/step-02-concept.md'
+continueFile: '{installed_path}/steps/step-01b-continue.md'
+modulePlanTemplate: '{installed_path}/templates/module-plan.template.md'
+advancedElicitationTask: '{project-root}/_bmad/core/tasks/advanced-elicitation.xml'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+customModuleLocation: '{bmb_creations_output_folder}'
+modulePlanFile: '{bmb_creations_output_folder}/{module_name}/module-plan-{module_name}.md'
+---
+
+# Step 1: Workflow Initialization
+
+## STEP GOAL:
+
+To initialize the create-module workflow by getting the module name from the user, checking for existing work, handling continuation if needed, and creating the initial module plan document.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a Module Architect and BMAD Systems Specialist
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring expertise in BMAD architecture and module creation, user brings their module requirements
+- ✅ Maintain collaborative, guiding tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization, getting module name, and setting up tracking
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Module brief discovery happens in this step
+
+## SEQUENCE OF INSTRUCTIONS:
+
+### 1. Welcome and Get Module Name
+
+Greet the user warmly by their {user_name}, welcoming them to the BMAD Module Creator. Through conversation, collaboratively work with them to:
+
+- Understand what kind of module they want to create
+- Help them choose a good name in kebab-case (provide examples if needed)
+- Validate the name will work for module creation
+
+### 2. Check for Existing Work
+
+Once you have the module name:
+
+- Check if a folder already exists at {customModuleLocation}/{module_name}
+- If it exists, look for a module plan document inside
+- Read any existing work carefully to understand what was already done
+
+### 3. Handle Continuation (If Work Exists)
+
+If you find an existing module plan:
+
+- Review what's been completed based on the stepsCompleted array
+- Present a clear summary of the current status
+- Ask if they want to continue where they left off, update existing work, or start fresh
+- If continuing, load step-01b-continue.md
+
+### 4. Look for Supporting Documents
+
+Check for any existing documents that could help:
+
+- Module briefs in the module folder or output folder
+- Brainstorming results in the output folder
+- Any other relevant documentation
+
+### 5. Guide User's Next Decision
+
+If no supporting documents are found:
+
+- Explain their three options clearly and helpfully
+- Option 1: Proceed with creating the module based on their ideas
+- Option 2: Exit and create a module brief first (explain the module-brief workflow)
+- Option 3: Exit and do brainstorming first (explain the brainstorming workflow)
+- Support whatever choice they make
+
+### 6. Create Module Foundation
+
+If proceeding:
+
+- Create the module folder if needed
+- Create the initial module-plan-{module_name}.md document using the module plan template from {modulePlanTemplate}
+- Initialize proper frontmatter with current date, user name, and add "step-01-init" to stepsCompleted array
+- Add any discovered documents to inputDocuments field
+- Include a brief section about the legacy reference
+
+### 7. Prepare for Next Step
+
+- Confirm everything is set up properly
+- Let the user know what you've accomplished
+- Transition smoothly to the next phase of defining the module concept
+
+### 8. Present MENU OPTIONS
+
+Display: **Proceeding to define your module concept...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices (after inputs handled)
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, add step-01-init to the end of the stepsCompleted array in module plan frontmatter, then load, read entire file, then execute `{nextStepFile}` to define the module concept
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Module name obtained and validated through collaborative dialogue
+- Module plan document created from template with frontmatter initialized
+- "step-01-init" added to stepsCompleted array
+- Module plan document created at correct location
+- User feels welcomed and informed
+- Ready to proceed to step 2
+- OR existing workflow properly routed to step-01b-continue.md
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without module plan creation
+- Not checking for existing documents properly
+- Creating module without user input on name
+- Skipping folder creation
+- Not routing to step-01b-continue.md when appropriate
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and module plan document is created (OR continuation is properly routed), will you then immediately load, read entire file, then execute `{nextStepFile}` to begin defining the module concept.

package/src/modules/bmb/workflows/create-module/steps/step-01b-continue.md

@@ -0,0 +1,169 @@
+---
+modulePlanFile: '{bmb_creations_output_folder}/{module_name}/module-plan-{module_name}.md'
+---
+
+# Step 1b: Continue Module Creation
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a Module Architect and BMAD Systems Specialist
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring expertise in BMAD architecture and module creation, user brings their module requirements
+- ✅ Maintain collaborative, guiding tone throughout
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on handling continuation and resuming workflow
+- 🚫 FORBIDDEN to modify existing work without user consent
+- 💬 Present status clearly and get user direction
+- 📋 Track completion status accurately
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and analyze existing module plan
+- 💾 Update frontmatter with continuation status
+- 📖 Route to appropriate next step based on progress
+- 🚫 FORBIDDEN to skip steps just because they exist
+
+## CONTEXT BOUNDARIES:
+
+- Module plan document exists with previous work
+- Focus on understanding what's been done and what remains
+- Don't assume completion without verification
+- User direction guides next actions
+
+## STEP GOAL:
+
+To resume module creation by presenting current status, understanding what's been accomplished, and determining the next step in the process.
+
+## CONTINUATION HANDLING SEQUENCE:
+
+### 1. Load and Analyze Existing Module Plan
+
+Load module plan from: {modulePlanFile}
+Read entire document including frontmatter
+Extract current status from frontmatter fields:
+
+- stepsCompleted array
+- lastStep (the final item in the stepsCompleted array)
+- module_name
+- module_code
+- date
+- inputDocuments
+
+### 2. Present Current Status
+
+"Welcome back! I found your in-progress module creation for **{module_name}**.
+
+**Current Status:**
+
+- **Module Code:** {module_code}
+- **Started:** {date}
+- **Last Step:** {lastStep}
+- **Steps Completed:** {stepsCompleted count}/{total steps}
+- **Location:** {bmb_creations_output_folder}/{module_name}
+
+\*\*Progress Summary:"
+
+Based on stepsCompleted, show:
+
+- [✅] Step 1: Init - Complete
+- [ ] Step 2: Concept - {status}
+- [ ] Step 3: Components - {status}
+- [ ] Step 4: Structure - {status}
+- [ ] Step 5: Configuration - {status}
+- [ ] Step 6: Agents - {status}
+- [ ] Step 7: Workflows - {status}
+- [ ] Step 8: Installer - {status}
+- [ ] Step 9: Documentation - {status}
+- [ ] Step 10: Roadmap - {status}
+- [ ] Step 11: Validation - {status}
+
+### 3. Review What's Been Done
+
+Read content sections of module plan
+Summarize what's been accomplished:
+
+"**Completed Work:**
+
+- Module identity defined
+- Component planning complete
+- [Other completed items based on content]"
+
+### 4. Determine Next Step
+
+Based on stepsCompleted array:
+Find highest completed step number
+Next step = highest completed + 1
+
+"**Ready to Continue:**
+Your next step would be: **Step {nextStep} - [step name]**
+
+What would you like to do?
+
+1. **Continue** from where you left off
+2. **Review** what's been done so far
+3. **Modify** previous work
+4. **Start over** with a new plan"
+
+### 5. Handle User Choice
+
+User your best judgement in how to handle the users choice
+
+### 6. Update Continuation Status
+
+Update modulePlanFile frontmatter:
+
+- Set lastStep: 'continued'
+- Add note about continuation date
+- Keep stepsCompleted unchanged
+
+## ✅ SUCCESS METRICS:
+
+- User understands current progress
+- Next step identified correctly
+- User choice handled appropriately
+- Module plan updated with continuation status
+- Workflow resumed at correct location
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Not accurately reading previous status
+- Skipping steps just because they exist
+- Not offering review option
+- Losing previous work
+- Not updating continuation tracking
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Existing work properly loaded and analyzed
+- User clearly understands current status
+- Continuation options presented clearly
+- Next step determined correctly
+- Module plan updated with continuation information
+
+### ❌ SYSTEM FAILURE:
+
+- Not reading existing plan completely
+- Misrepresenting progress status
+- Losing track of what's been done
+- Not offering appropriate continuation options
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN user selects 'C' (Continue) and appropriate updates are saved to modulePlanFile, will you then load, read entire file, then execute the determined next step file to resume the module creation workflow.