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

package/src/modules/bmb/workflows/create-module/instructions.md

@@ -1,21 +1,25 @@
 # Build Module - Interactive Module Builder Instructions
 
-<critical>The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md</critical>
-<critical>You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/build-module/workflow.yaml</critical>
-<critical>Study existing modules in: {project_root}/bmad/ for patterns</critical>
+<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/create-module/workflow.yaml</critical>
+<critical>Study existing modules in: {project-root}/bmad/ for patterns</critical>
+<critical>Communicate in {communication_language} throughout the module creation process</critical>
 
 <workflow>
 
 <step n="-1" goal="Optional brainstorming for module ideas" optional="true">
 <ask>Do you want to brainstorm module ideas first? [y/n]</ask>
 
-If yes:
-<action>Invoke brainstorming workflow: {project-root}/bmad/cis/workflows/brainstorming/workflow.yaml</action>
-<action>Pass context data: {installed_path}/brainstorm-context.md</action>
-<action>Wait for brainstorming session completion</action>
-<action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio</action>
+<check if="yes">
+  <action>Invoke brainstorming workflow: {brainstorming_workflow}</action>
+  <action>Pass context data: {brainstorming_context}</action>
+  <action>Wait for brainstorming session completion</action>
+  <action>Use brainstorming output to inform module concept, agent lineup, and workflow portfolio in following steps</action>
+</check>
 
-If no, proceed to check for module brief.
+<check if="no">
+  <action>Proceed directly to Step 0</action>
+</check>
 
 <template-output>brainstorming_results</template-output>
 </step>
@@ -23,16 +27,20 @@ If no, proceed to check for module brief.
 <step n="0" goal="Check for module brief" optional="true">
 <ask>Do you have a module brief or should we create one? [have/create/skip]</ask>
 
-If create:
-<action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
-<action>Wait for module brief completion</action>
-<action>Load the module brief to use as blueprint</action>
+<check if="create">
+  <action>Invoke module-brief workflow: {project-root}/bmad/bmb/workflows/module-brief/workflow.yaml</action>
+  <action>Wait for module brief completion</action>
+  <action>Load the module brief to use as blueprint</action>
+</check>
 
-If have:
-<ask>Provide path to module brief document</ask>
-<action>Load the module brief and use it to pre-populate all planning sections</action>
+<check if="have">
+  <ask>Provide path to module brief document</ask>
+  <action>Load the module brief and use it to pre-populate all planning sections</action>
+</check>
 
-If skip, proceed directly to module definition.
+<check if="skip">
+  <action>Proceed directly to Step 1</action>
+</check>
 
 <template-output>module_brief</template-output>
 </step>
@@ -44,278 +52,334 @@ If skip, proceed directly to module definition.
 <action>Review directory structures and component guidelines</action>
 <action>Study the installation infrastructure patterns</action>
 
-Ask the user about their module vision:
+<action>If brainstorming or module brief was completed, reference those results to guide the conversation</action>
 
-**Module Identity:**
+<action>Guide user to articulate their module's vision, exploring its purpose, what it will help with, and who will use it</action>
 
-1. **Module code** (kebab-case, e.g., "rpg-toolkit", "data-viz", "team-collab")
-2. **Module name** (friendly name, e.g., "RPG Toolkit", "Data Visualization Suite")
-3. **Module purpose** (1-2 sentences describing what it does)
-4. **Target audience** (who will use this module?)
+<action>Based on their description, intelligently propose module details:</action>
 
-**Module Theme Examples:**
+**Module Identity Development:**
 
-- **Domain-Specific:** Legal, Medical, Finance, Education
-- **Creative:** RPG/Gaming, Story Writing, Music Production
-- **Technical:** DevOps, Testing, Architecture, Security
-- **Business:** Project Management, Marketing, Sales
-- **Personal:** Journaling, Learning, Productivity
+1. **Module name** - Extract from their description with proper title case
+2. **Module code** - Generate kebab-case from name following patterns:
+   - Multi-word descriptive names → shortened kebab-case
+   - Domain-specific terms → recognizable abbreviations
+   - Present suggested code and confirm it works for paths like bmad/{{code}}/agents/
+3. **Module purpose** - Refine their description into 1-2 clear sentences
+4. **Target audience** - Infer from context or ask if unclear
 
-<critical>Check {src_impact} variable to determine output location:</critical>
+**Module Theme Reference Categories:**
 
-- If {src_impact} = true: Module will be created at {src_output_folder}
-- If {src_impact} = false: Module will be created at {default_output_folder}
+- Domain-Specific (Legal, Medical, Finance, Education)
+- Creative (RPG/Gaming, Story Writing, Music Production)
+- Technical (DevOps, Testing, Architecture, Security)
+- Business (Project Management, Marketing, Sales)
+- Personal (Journaling, Learning, Productivity)
 
-Store module identity for scaffolding.
+<critical>Determine output location:</critical>
+
+- Module will be created at {installer_output_folder}
+
+<action>Store module identity for scaffolding</action>
 
 <template-output>module_identity</template-output>
 </step>
 
 <step n="2" goal="Plan module components">
-Gather the module's component architecture:
+<action>Based on the module purpose, intelligently propose an initial component architecture</action>
 
 **Agents Planning:**
-Ask: How many agents will this module have? (typically 1-5)
 
-For each agent, gather:
+<action>Suggest agents based on module purpose, considering agent types (Simple/Expert/Module) appropriate to each role</action>
 
-- Agent name and purpose
-- Will it be Simple, Expert, or Module type?
-- Key commands it should have
-- Create now or placeholder for later?
+**Example Agent Patterns by Domain:**
 
-Example for RPG module:
+- Data/Analytics: Analyst, Designer, Builder roles
+- Gaming/Creative: Game Master, Generator, Storytelling roles
+- Team/Business: Manager, Facilitator, Documentation roles
 
-1. DM Agent - Dungeon Master assistant (Module type)
-2. NPC Agent - Character simulation (Expert type)
-3. Story Writer Agent - Adventure creation (Module type)
+<action>Present suggested agent list with types, explaining we can start with core ones and add others later</action>
+<action>Confirm which agents resonate with their vision</action>
 
 **Workflows Planning:**
-Ask: How many workflows? (typically 2-10)
 
-For each workflow, gather:
+<action>Intelligently suggest workflows that complement the proposed agents</action>
 
-- Workflow name and purpose
-- Document, Action, or Interactive type?
-- Complexity (simple/complex)
-- Create now or placeholder?
+**Example Workflow Patterns by Domain:**
 
-Example workflows:
+- Data/Analytics: analyze-dataset, create-dashboard, generate-report
+- Gaming/Creative: session-prep, generate-encounter, world-building
+- Team/Business: planning, facilitation, documentation workflows
 
-1. adventure-plan - Create full adventure (Document)
-2. random-encounter - Quick encounter generator (Action)
-3. npc-generator - Create NPCs on the fly (Interactive)
-4. treasure-generator - Loot tables (Action)
+<action>For each workflow, note whether it should be Document, Action, or Interactive type</action>
+<action>Confirm which workflows are most important to start with</action>
+<action>Determine which to create now vs placeholder</action>
 
 **Tasks Planning (optional):**
-Ask: Any special tasks that don't warrant full workflows?
+<ask>Any special tasks that don't warrant full workflows?</ask>
 
-For each task:
-
-- Task name and purpose
-- Standalone or supporting?
+<action if="tasks needed">For each task, capture name, purpose, and whether standalone or supporting</action>
 
 <template-output>module_components</template-output>
 </step>
 
+<step n="2b" goal="Determine module complexity">
+<action>Based on components, intelligently determine module type using criteria:</action>
+
+**Simple Module Criteria:**
+
+- 1-2 agents, all Simple type
+- 1-3 workflows
+- No complex integrations
+
+**Standard Module Criteria:**
+
+- 2-4 agents with mixed types
+- 3-8 workflows
+- Some shared resources
+
+**Complex Module Criteria:**
+
+- 4+ agents or multiple Module-type agents
+- 8+ workflows
+- Complex interdependencies
+- External integrations
+
+<action>Present determined module type with explanation of what structure will be set up</action>
+
+<template-output>module_type</template-output>
+</step>
+
 <step n="3" goal="Create module directory structure">
-<critical>Determine base module path based on {src_impact}:</critical>
-- If {src_impact} = true: Use {src_output_folder}
-- If {src_impact} = false: Use {default_output_folder}
+<critical>Use module path determined in Step 1:</critical>
+- The module base path is {{module_path}}
 
 <action>Create base module directories at the determined path:</action>
 
 ```
 {{module_code}}/
-├── agents/           # Agent definitions
-├── workflows/        # Workflow folders
-├── tasks/           # Task files (if any)
-├── templates/       # Shared templates
-├── data/           # Module data files
-├── config.yaml     # Module configuration
-└── README.md       # Module documentation
+├── agents/                    # Agent definitions
+├── workflows/                 # Workflow folders
+├── tasks/                     # Task files (if any)
+├── templates/                 # Shared templates
+├── data/                      # Module data files
+├── _module-installer/         # Installation configuration
+│   └── install-config.yaml   # Configuration questions (config.yaml generated at install time)
+└── README.md                  # Module documentation
 ```
 
 <action>Create installer directory:</action>
 
+**INSTALLED MODULE STRUCTURE** (generated in target project after installation):
+
+```
+{{module_code}}/
+├── agents/                    # Compiled agents
+├── workflows/                 # Workflow instances
+├── config.yaml               # Generated from install-config.yaml during installation
+└── data/                     # User data directory
+```
+
+**SOURCE MODULE** (\_module-installer is for installation only, not copied to target):
+
 ```
 {{module_code}}/
 ├── _module-installer/
-│   ├── install-module-config.yaml
-│   ├── installer.js (optional)
-│   └── assets/     # Files to copy during install
-├── config.yaml     # Runtime configuration
-├── agents/         # Agent configs (optional)
-├── workflows/      # Workflow instances
-└── data/          # User data directory
+│   ├── install-config.yaml   # Configuration questions
+│   ├── installer.js          # Optional custom installation logic
+│   └── assets/               # Files to copy during install
 ```
 
 <template-output>directory_structure</template-output>
 </step>
 
-<step n="4" goal="Generate module configuration">
-Create the main module config.yaml:
+<step n="4" goal="Plan module configuration fields">
+<action>Based on the module purpose and components, determine what configuration settings the module needs</action>
 
-```yaml
-# {{module_name}} Module Configuration
-module_name: {{module_name}}
-module_code: {{module_code}}
-author: {{user_name}}
-description: {{module_purpose}}
-
-# Module paths
-module_root: "{project-root}/bmad/{{module_code}}"
-installer_path: "{project-root}/bmad/{{module_code}}"
-
-# Component counts
-agents:
-  count: {{agent_count}}
-  list: {{agent_list}}
-
-workflows:
-  count: {{workflow_count}}
-  list: {{workflow_list}}
-
-tasks:
-  count: {{task_count}}
-  list: {{task_list}}
-
-# Module-specific settings
-{{custom_settings}}
-
-# Output configuration
-output_folder: "{project-root}/docs/{{module_code}}"
-data_folder: "{{determined_module_path}}/data"
-```
+**Configuration Field Planning:**
 
-<critical>Determine save location based on {src_impact}:</critical>
+<ask>Does your module need any user-configurable settings during installation?</ask>
 
-- If {src_impact} = true: Save to {src_output_folder}/config.yaml
-- If {src_impact} = false: Save to {default_output_folder}/config.yaml
+**Common configuration patterns:**
 
-<template-output>module_config</template-output>
-</step>
+- Output/data paths (where module saves files)
+- Feature toggles (enable/disable functionality)
+- Integration settings (API keys, external services)
+- Behavior preferences (automation level, detail level)
+- User skill level or experience settings
 
-<step n="5" goal="Create first agent" optional="true">
-Ask: **Create your first agent now? [Yes/no]**
+<action>For each configuration field needed, determine:</action>
 
-If yes:
-<invoke-workflow input="{{module_components}}">
-{agent_builder}
-</invoke-workflow>
+1. Field name (snake_case)
+2. Whether it's INTERACTIVE (asks user) or STATIC (hardcoded)
+3. Prompt text (if interactive)
+4. Default value
+5. Type: text input, single-select, or multi-select
+6. Result template (how the value gets stored)
 
-Guide them to create the primary agent for the module.
-<critical>Ensure it's saved to the correct location based on {src_impact}:</critical>
+<action>Store planned configuration fields for installer generation in step 7</action>
 
-- If {src_impact} = true: {src_output_folder}/agents/
-- If {src_impact} = false: {default_output_folder}/agents/
+<template-output>module_config_fields</template-output>
+</step>
 
-If no, create placeholder:
+<step n="5" goal="Create first agent" optional="true">
+<ask>Create your first agent now? [yes/no]</ask>
 
-```md
-# {{primary_agent_name}} Agent
+<check if="yes">
+  <action>Invoke agent builder workflow: {agent_builder}</action>
+  <action>Pass module_components as context input</action>
+  <action>Guide them to create the primary agent for the module</action>
 
-<!-- TODO: Create using build-agent workflow -->
-<!-- Purpose: {{agent_purpose}} -->
-<!-- Type: {{agent_type}} -->
-```
+<critical>Save to module's agents folder:</critical>
+
+- Save to {{module_path}}/agents/
+  </check>
+
+<check if="no">
+  <action>Create placeholder file in agents folder with TODO notes including agent name, purpose, and type</action>
+</check>
 
 <template-output>first_agent</template-output>
 </step>
 
 <step n="6" goal="Create first workflow" optional="true">
-Ask: **Create your first workflow now? [Yes/no]**
+<ask>Create your first workflow now? [yes/no]</ask>
 
-If yes:
-<invoke-workflow input="{{module_components}}">
-{workflow_builder}
-</invoke-workflow>
+<check if="yes">
+  <action>Invoke workflow builder: {workflow_builder}</action>
+  <action>Pass module_components as context input</action>
+  <action>Guide them to create the primary workflow</action>
 
-Guide them to create the primary workflow.
-<critical>Ensure it's saved to the correct location based on {src_impact}:</critical>
+<critical>Save to module's workflows folder:</critical>
 
-- If {src_impact} = true: {src_output_folder}/workflows/
-- If {src_impact} = false: {default_output_folder}/workflows/
+- Save to {{module_path}}/workflows/
+  </check>
 
-If no, create placeholder structure:
-
-```
-workflows/{{workflow_name}}/
-├── workflow.yaml    # TODO: Configure
-├── instructions.md  # TODO: Add steps
-└── template.md     # TODO: If document workflow
-```
+<check if="no">
+  <action>Create placeholder workflow folder structure with TODO notes for workflow.yaml, instructions.md, and template.md if document workflow</action>
+</check>
 
 <template-output>first_workflow</template-output>
 </step>
 
 <step n="7" goal="Setup module installer">
-<action>Load installer templates from: {installer_templates}</action>
+<action>Load installer template from: {installer_templates}/install-config.yaml</action>
+
+<critical>IMPORTANT: Create install-config.yaml NOT install-config.yaml</critical>
+<critical>This is the STANDARD format that BMAD installer uses</critical>
 
-Create install-module-config.yaml:
+Create \_module-installer/install-config.yaml:
 
 ```yaml
-# {{module_name}} Installation Configuration
-module_name: { { module_name } }
-module_code: { { module_code } }
-installation_date: { { date } }
-
-# Installation steps
-install_steps:
-  - name: 'Create directories'
-    action: 'mkdir'
-    paths:
-      - '{project-root}/bmad/{{module_code}}'
-      - '{project-root}/bmad/{{module_code}}/data'
-      - '{project-root}/bmad/{{module_code}}/agents'
-
-  - name: 'Copy configuration'
-    action: 'copy'
-    source: '{installer_path}/config.yaml'
-    dest: '{project-root}/bmad/{{module_code}}/config.yaml'
-
-  - name: 'Register module'
-    action: 'register'
-    manifest: '{project-root}/bmad/_cfg/manifest.yaml'
-
-# External assets (if any)
-external_assets:
-  - description: '{{asset_description}}'
-    source: 'assets/{{filename}}'
-    dest: '{{destination_path}}'
-
-# Post-install message
-post_install_message: |
-  {{module_name}} has been installed successfully!
-
-  To get started:
-  1. Load any {{module_code}} agent
-  2. Use *help to see available commands
-  3. Check README.md for full documentation
+# {{module_name}} Module Configuration
+# This file defines installation questions and module configuration values
+
+code: {{module_code}}
+name: "{{module_name}}"
+default_selected: false # Set to true if this should be selected by default
+
+# Welcome message shown during installation
+prompt:
+  - "Thank you for choosing {{module_name}}!"
+  - "{{brief_module_description}}"
+
+# Core config values are automatically inherited:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+# ============================================================================
+# CONFIGURATION FIELDS (from step 4 planning)
+# ============================================================================
+# Each field can be:
+# 1. INTERACTIVE (has 'prompt' - asks user during installation)
+# 2. STATIC (no 'prompt' - just uses 'result' value)
+# ============================================================================
+
+# EXAMPLE Interactive text input:
+# output_path:
+#   prompt: "Where should {{module_code}} save outputs?"
+#   default: "output/{{module_code}}"
+#   result: "{project-root}/{value}"
+
+# EXAMPLE Interactive single-select:
+# detail_level:
+#   prompt: "How detailed should outputs be?"
+#   default: "standard"
+#   result: "{value}"
+#   single-select:
+#     - value: "minimal"
+#       label: "Minimal - Brief summaries only"
+#     - value: "standard"
+#       label: "Standard - Balanced detail"
+#     - value: "detailed"
+#       label: "Detailed - Comprehensive information"
+
+# EXAMPLE Static value:
+# module_version:
+#   result: "1.0.0"
+
+# EXAMPLE Static path:
+# data_path:
+#   result: "{project-root}/bmad/{{module_code}}/data"
+
+{{generated_config_fields_from_step_4}}
 ```
 
-Create installer.js stub (optional):
+<critical>Save location:</critical>
+
+- Save to {{module_path}}/\_module-installer/install-config.yaml
+
+<ask>Does your module need custom installation logic (database setup, API registration, etc.)?</ask>
 
-```javascript
-// {{module_name}} Module Installer
-// This is a placeholder for complex installation logic
+<check if="yes, create installer.js">
+  ```javascript
+  // {{module_name}} Module Installer
+  // Custom installation logic
 
-function installModule(config) {
-  console.log('Installing {{module_name}} module...');
+/\*\*
 
-  // TODO: Add any complex installation logic here
+- Module installation hook
+- Called after files are copied but before IDE configuration
+-
+- @param {Object} options - Installation options
+- @param {string} options.projectRoot - Project root directory
+- @param {Object} options.config - Module configuration from install-config.yaml
+- @param {Array} options.installedIDEs - List of IDE codes being configured
+- @param {Object} options.logger - Logger instance (log, warn, error methods)
+- @returns {boolean} - true if successful, false to abort installation
+  \*/
+  async function install(options) {
+  const { projectRoot, config, installedIDEs, logger } = options;
+
+  logger.log('Running {{module_name}} custom installer...');
+
+  // TODO: Add custom installation logic here
   // Examples:
-  // - Database setup
-  // - API key configuration
-  // - External service registration
-  // - File system preparation
+  // - Create database tables
+  // - Download external assets
+  // - Configure API connections
+  // - Initialize data files
+  // - Set up webhooks or integrations
 
-  console.log('{{module_name}} module installed successfully!');
+  logger.log('{{module_name}} custom installation complete!');
   return true;
+
 }
 
-module.exports = { installModule };
-```
+module.exports = { install };
+
+`````
+
+<critical>Save location:</critical>
+
+- Save to {{module_path}}/\_module-installer/installer.js
+</check>
+
+<check if="no">
+<action>Skip installer.js creation - the standard installer will handle everything</action>
+</check>
 
 <template-output>installer_config</template-output>
 </step>
@@ -337,7 +401,8 @@ This module provides:
 
 ```bash
 bmad install {{module_code}}
-```
+`````
+
 ````
 
 ## Components
@@ -402,8 +467,8 @@ Key settings:
 
 To extend this module:
 
-1. Add new agents using `build-agent` workflow
-2. Add new workflows using `build-workflow` workflow
+1. Add new agents using `create-agent` workflow
+2. Add new workflows using `create-workflow` workflow
 3. Submit improvements via pull request
 
 ## Author
@@ -419,31 +484,35 @@ Created by {{user_name}} on {{date}}
 Create a development roadmap for remaining components:
 
 **TODO.md file:**
+
 ```markdown
 # {{module_name}} Development Roadmap
 
 ## Phase 1: Core Components
+
 {{phase1_tasks}}
 
 ## Phase 2: Enhanced Features
+
 {{phase2_tasks}}
 
-## Phase 3: Polish & Integration
+## Phase 3: Polish and Integration
+
 {{phase3_tasks}}
 
 ## Quick Commands
 
 Create new agent:
-````
+```
 
-workflow build-agent
+workflow create-agent
 
 ```
 
 Create new workflow:
 ```
 
-workflow build-workflow
+workflow create-workflow
 
 ```
 
@@ -461,47 +530,50 @@ Ask if user wants to:
 </step>
 
 <step n="10" goal="Validate and finalize module">
-Run validation checks:
+<action>Run validation checks:</action>
 
-1. **Structure validation:**
-   - All required directories created
-   - Config files properly formatted
-   - Installer configuration valid
+**Structure validation:**
 
-2. **Component validation:**
-   - At least one agent or workflow exists (or planned)
-   - All references use correct paths
-   - Module code consistent throughout
+- All required directories created
+- Config files properly formatted
+- Installer configuration valid
 
-3. **Documentation validation:**
-   - README.md complete
-   - Installation instructions clear
-   - Examples provided
+**Component validation:**
 
-Show summary:
+- At least one agent or workflow exists (or planned)
+- All references use correct paths
+- Module code consistent throughout
 
-```
-✅ Module: {{module_name}} ({{module_code}})
-📁 Location:
-   - If {src_impact} = true: {src_output_folder}
-   - If {src_impact} = false: {default_output_folder}
-👥 Agents: {{agent_count}} ({{agents_created}} created, {{agents_planned}} planned)
-📋 Workflows: {{workflow_count}} ({{workflows_created}} created, {{workflows_planned}} planned)
-📝 Tasks: {{task_count}}
-📦 Installer: Ready at same location
-```
+**Documentation validation:**
+
+- README.md complete
+- Installation instructions clear
+- Examples provided
+
+<action>Present summary to {user_name}:</action>
+
+- Module name and code
+- Location path
+- Agent count (created vs planned)
+- Workflow count (created vs planned)
+- Task count
+- Installer status
 
-Next steps:
+<action>Provide next steps guidance:</action>
 
 1. Complete remaining components using roadmap
-2. Test module with: `bmad install {{module_code}}`
-3. Share module or integrate with existing system
+2. Run the BMAD Method installer to this project location
+3. Select 'Compile Agents' option after confirming folder
+4. Module will be compiled and available for use
+5. Test with bmad install command
+6. Share or integrate with existing system
 
-Ask: Would you like to:
+<ask>Would you like to:
 
 - Create another component now?
 - Test the module installation?
 - Exit and continue later?
+  </ask>
 
 <template-output>module_summary</template-output>
 </step>