bmad-method 5.1.3 → 6.0.0-alpha.0

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

@@ -0,0 +1,509 @@
+# 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>
+
+<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>
+
+If no, proceed to check for module brief.
+
+<template-output>brainstorming_results</template-output>
+</step>
+
+<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>
+
+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>
+
+If skip, proceed directly to module definition.
+
+<template-output>module_brief</template-output>
+</step>
+
+<step n="1" goal="Define module concept and scope">
+<critical>Load and study the complete module structure guide</critical>
+<action>Load module structure guide: {module_structure_guide}</action>
+<action>Understand module types (Simple/Standard/Complex)</action>
+<action>Review directory structures and component guidelines</action>
+<action>Study the installation infrastructure patterns</action>
+
+Ask the user about their module vision:
+
+**Module Identity:**
+
+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?)
+
+**Module Theme Examples:**
+
+- **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
+
+<critical>Check {src_impact} variable to determine output location:</critical>
+
+- If {src_impact} = true: Module will be created at {src_output_folder}
+- If {src_impact} = false: Module will be created at {default_output_folder}
+
+Store module identity for scaffolding.
+
+<template-output>module_identity</template-output>
+</step>
+
+<step n="2" goal="Plan module components">
+Gather the module's component architecture:
+
+**Agents Planning:**
+Ask: How many agents will this module have? (typically 1-5)
+
+For each agent, gather:
+
+- Agent name and purpose
+- Will it be Simple, Expert, or Module type?
+- Key commands it should have
+- Create now or placeholder for later?
+
+Example for RPG module:
+
+1. DM Agent - Dungeon Master assistant (Module type)
+2. NPC Agent - Character simulation (Expert type)
+3. Story Writer Agent - Adventure creation (Module type)
+
+**Workflows Planning:**
+Ask: How many workflows? (typically 2-10)
+
+For each workflow, gather:
+
+- Workflow name and purpose
+- Document, Action, or Interactive type?
+- Complexity (simple/complex)
+- Create now or placeholder?
+
+Example 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)
+
+**Tasks Planning (optional):**
+Ask: Any special tasks that don't warrant full workflows?
+
+For each task:
+
+- Task name and purpose
+- Standalone or supporting?
+
+<template-output>module_components</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}
+
+<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
+```
+
+<action>Create installer directory:</action>
+
+```
+{{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
+```
+
+<template-output>directory_structure</template-output>
+</step>
+
+<step n="4" goal="Generate module configuration">
+Create the main module config.yaml:
+
+```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"
+```
+
+<critical>Determine save location based on {src_impact}:</critical>
+
+- If {src_impact} = true: Save to {src_output_folder}/config.yaml
+- If {src_impact} = false: Save to {default_output_folder}/config.yaml
+
+<template-output>module_config</template-output>
+</step>
+
+<step n="5" goal="Create first agent" optional="true">
+Ask: **Create your first agent now? [Yes/no]**
+
+If yes:
+<invoke-workflow input="{{module_components}}">
+{agent_builder}
+</invoke-workflow>
+
+Guide them to create the primary agent for the module.
+<critical>Ensure it's saved to the correct location based on {src_impact}:</critical>
+
+- If {src_impact} = true: {src_output_folder}/agents/
+- If {src_impact} = false: {default_output_folder}/agents/
+
+If no, create placeholder:
+
+```md
+# {{primary_agent_name}} Agent
+
+<!-- TODO: Create using build-agent workflow -->
+<!-- Purpose: {{agent_purpose}} -->
+<!-- Type: {{agent_type}} -->
+```
+
+<template-output>first_agent</template-output>
+</step>
+
+<step n="6" goal="Create first workflow" optional="true">
+Ask: **Create your first workflow now? [Yes/no]**
+
+If yes:
+<invoke-workflow input="{{module_components}}">
+{workflow_builder}
+</invoke-workflow>
+
+Guide them to create the primary workflow.
+<critical>Ensure it's saved to the correct location based on {src_impact}:</critical>
+
+- If {src_impact} = true: {src_output_folder}/workflows/
+- If {src_impact} = false: {default_output_folder}/workflows/
+
+If no, create placeholder structure:
+
+```
+workflows/{{workflow_name}}/
+├── workflow.yaml    # TODO: Configure
+├── instructions.md  # TODO: Add steps
+└── template.md     # TODO: If document workflow
+```
+
+<template-output>first_workflow</template-output>
+</step>
+
+<step n="7" goal="Setup module installer">
+<action>Load installer templates from: {installer_templates}</action>
+
+Create install-module-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
+```
+
+Create installer.js stub (optional):
+
+```javascript
+// {{module_name}} Module Installer
+// This is a placeholder for complex installation logic
+
+function installModule(config) {
+  console.log('Installing {{module_name}} module...');
+
+  // TODO: Add any complex installation logic here
+  // Examples:
+  // - Database setup
+  // - API key configuration
+  // - External service registration
+  // - File system preparation
+
+  console.log('{{module_name}} module installed successfully!');
+  return true;
+}
+
+module.exports = { installModule };
+```
+
+<template-output>installer_config</template-output>
+</step>
+
+<step n="8" goal="Create module documentation">
+Generate comprehensive README.md:
+
+````markdown
+# {{module_name}}
+
+{{module_purpose}}
+
+## Overview
+
+This module provides:
+{{component_summary}}
+
+## Installation
+
+```bash
+bmad install {{module_code}}
+```
+````
+
+## Components
+
+### Agents ({{agent_count}})
+
+{{agent_documentation}}
+
+### Workflows ({{workflow_count}})
+
+{{workflow_documentation}}
+
+### Tasks ({{task_count}})
+
+{{task_documentation}}
+
+## Quick Start
+
+1. **Load the main agent:**
+
+   ```
+   agent {{primary_agent}}
+   ```
+
+2. **View available commands:**
+
+   ```
+   *help
+   ```
+
+3. **Run the main workflow:**
+   ```
+   workflow {{primary_workflow}}
+   ```
+
+## Module Structure
+
+```
+{{directory_tree}}
+```
+
+## Configuration
+
+The module can be configured in `bmad/{{module_code}}/config.yaml`
+
+Key settings:
+{{configuration_options}}
+
+## Examples
+
+### Example 1: {{example_use_case}}
+
+{{example_walkthrough}}
+
+## Development Roadmap
+
+- [ ] {{roadmap_item_1}}
+- [ ] {{roadmap_item_2}}
+- [ ] {{roadmap_item_3}}
+
+## Contributing
+
+To extend this module:
+
+1. Add new agents using `build-agent` workflow
+2. Add new workflows using `build-workflow` workflow
+3. Submit improvements via pull request
+
+## Author
+
+Created by {{user_name}} on {{date}}
+
+````
+
+<template-output>module_readme</template-output>
+</step>
+
+<step n="9" goal="Generate component roadmap">
+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
+{{phase3_tasks}}
+
+## Quick Commands
+
+Create new agent:
+````
+
+workflow build-agent
+
+```
+
+Create new workflow:
+```
+
+workflow build-workflow
+
+```
+
+## Notes
+{{development_notes}}
+```
+
+Ask if user wants to:
+
+1. Continue building more components now
+2. Save roadmap for later development
+3. Test what's been built so far
+
+<template-output>development_roadmap</template-output>
+</step>
+
+<step n="10" goal="Validate and finalize module">
+Run validation checks:
+
+1. **Structure validation:**
+   - All required directories created
+   - Config files properly formatted
+   - Installer configuration valid
+
+2. **Component validation:**
+   - At least one agent or workflow exists (or planned)
+   - All references use correct paths
+   - Module code consistent throughout
+
+3. **Documentation validation:**
+   - README.md complete
+   - Installation instructions clear
+   - Examples provided
+
+Show summary:
+
+```
+✅ 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
+```
+
+Next steps:
+
+1. Complete remaining components using roadmap
+2. Test module with: `bmad install {{module_code}}`
+3. Share module or integrate with existing system
+
+Ask: Would you like to:
+
+- Create another component now?
+- Test the module installation?
+- Exit and continue later?
+
+<template-output>module_summary</template-output>
+</step>
+
+</workflow>