@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/module/data/module-yaml-conventions.md

@@ -0,0 +1,392 @@
+# module.yaml Conventions
+
+**Purpose:** Defines how module.yaml works, including variables, templates, and how they provide context to agents and workflows.
+
+---
+
+## Overview
+
+`module.yaml` is the configuration file for a BMAD module. It:
+- Defines module metadata (code, name, description)
+- Collects user input via prompts during installation
+- Makes those inputs available to agents and workflows as variables
+- Specifies which module should be selected by default
+
+---
+
+## Frontmatter Fields
+
+### Required Fields
+
+```yaml
+code: {module-code}              # kebab-case identifier
+name: "Display Name"             # Human-readable name
+header: "Brief description"      # One-line summary
+subheader: "Additional context"  # More detail
+default_selected: false          # Auto-select on install?
+```
+
+### `default_selected` Guidelines
+
+| Module Type | default_selected | Example |
+|-------------|------------------|---------|
+| Core/Primary | `true` | BMM (agile software delivery) |
+| Specialized | `false` | CIS (creative innovation), BMGD (game dev) |
+| Experimental | `false` | New modules in development |
+
+---
+
+## Variables System
+
+### Core Config Variables (Always Available)
+
+These variables are automatically available to ALL modules:
+
+```yaml
+# Variables from Core Config inserted:
+## user_name                  # User's name
+## communication_language     # Preferred language
+## document_output_language    # Output document language
+## output_folder             # Default output location
+```
+
+No need to define these — they're injected automatically.
+
+---
+
+### Custom Variables
+
+Define custom variables for user input:
+
+```yaml
+variable_name:
+  prompt: "Question to ask the user?"
+  default: "{default_value}"
+  result: "{template_for_final_value}"
+```
+
+**Example:**
+
+```yaml
+project_name:
+  prompt: "What is the title of your project?"
+  default: "{directory_name}"
+  result: "{value}"
+```
+
+### Variable Templates
+
+In `prompt` and `result`, you can use templates:
+
+| Template | Expands To |
+|----------|------------|
+| `{value}` | The user's input |
+| `{directory_name}` | Current directory name |
+| `{output_folder}` | Output folder from core config |
+| `{project-root}` | Project root path |
+| `{variable_name}` | Another variable's value |
+
+---
+
+## Variable Types
+
+### 1. Simple Text Input
+
+```yaml
+project_name:
+  prompt: "What is the title of your project?"
+  default: "{directory_name}"
+  result: "{value}"
+```
+
+---
+
+### 2. Boolean/Flag
+
+```yaml
+enable_feature:
+  prompt: "Enable this feature?"
+  default: false
+  result: "{value}"
+```
+
+---
+
+### 3. Single Select
+
+```yaml
+skill_level:
+  prompt: "What is your experience level?"
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - Explains concepts clearly"
+    - value: "intermediate"
+      label: "Intermediate - Balanced approach"
+    - value: "expert"
+      label: "Expert - Direct and technical"
+```
+
+---
+
+### 4. Multi Select
+
+```yaml
+platforms:
+  prompt: "Which platforms do you need?"
+  default: ["unity", "unreal"]
+  result: "{value}"
+  multi-select:
+    - value: "unity"
+      label: "Unity"
+    - value: "unreal"
+      label: "Unreal Engine"
+    - value: "godot"
+      label: "Godot"
+```
+
+---
+
+### 5. Multi-Line Prompt
+
+```yaml
+complex_variable:
+  prompt:
+    - "First question?"
+    - "Second context?"
+    - "Third detail?"
+  default: "default_value"
+  result: "{value}"
+```
+
+---
+
+### 6. Required Variable
+
+```yaml
+critical_variable:
+  prompt: "Required information:"
+  required: true
+  result: "{value}"
+```
+
+---
+
+### 7. Path Variable
+
+```yaml
+artifacts_folder:
+  prompt: "Where should artifacts be stored?"
+  default: "{output_folder}/artifacts"
+  result: "{project-root}/{value}"
+```
+
+---
+
+## Variable Inheritance / Aliasing
+
+Create an alias for another variable:
+
+```yaml
+primary_artifacts:
+  prompt: "Where should primary artifacts be stored?"
+  default: "{output_folder}/artifacts"
+  result: "{project-root}/{value}"
+
+# Alias for workflow compatibility
+sprint_artifacts:
+  inherit: "primary_artifacts"
+```
+
+Now `sprint_artifacts` and `primary_artifacts` reference the same value.
+
+---
+
+## How Variables Become Available
+
+### To Agents
+
+After installation, variables are available in agent frontmatter/context:
+
+```yaml
+# In agent.agent.yaml or workflow execution
+{variable_name}  # Expands to the user's configured value
+```
+
+**Example:** If the user configured `project_name: "MyApp"`, agents can reference `{project_name}` and it will expand to `"MyApp"`.
+
+### To Workflows
+
+Workflows can reference module variables in their step files:
+
+```yaml
+---
+outputFile: '{implementation_artifacts}/my-output.md'
+---
+```
+
+This expands the `implementation_artifacts` variable from module.yaml.
+
+---
+
+## Real-World Examples
+
+### BMM (BMad Method) — Complex Configuration
+
+```yaml
+code: bmm
+name: "BMM: BMad Method Agile-AI Driven-Development"
+header: "BMad Method™: Breakthrough Method of Agile-Ai Driven-Dev"
+subheader: "Agent and Workflow Configuration for this module"
+default_selected: true
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+
+project_name:
+  prompt: "What is the title of your project?"
+  default: "{directory_name}"
+  result: "{value}"
+
+user_skill_level:
+  prompt:
+    - "What is your development experience level?"
+    - "This affects how agents explain concepts."
+  default: "intermediate"
+  result: "{value}"
+  single-select:
+    - value: "beginner"
+      label: "Beginner - Explain concepts clearly"
+    - value: "intermediate"
+      label: "Intermediate - Balanced approach"
+    - value: "expert"
+      label: "Expert - Direct and technical"
+
+planning_artifacts:
+  prompt: "Where should planning artifacts be stored?"
+  default: "{output_folder}/planning-artifacts"
+  result: "{project-root}/{value}"
+
+implementation_artifacts:
+  prompt: "Where should implementation artifacts be stored?"
+  default: "{output_folder}/implementation-artifacts"
+  result: "{project-root}/{value}"
+
+project_knowledge:
+  prompt: "Where should project knowledge be stored?"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+tea_use_mcp_enhancements:
+  prompt: "Enable MCP enhancements in Test Architect?"
+  default: false
+  result: "{value}"
+```
+
+---
+
+### CIS (Creative Innovation Suite) — Minimal Configuration
+
+```yaml
+code: cis
+name: "CIS: Creative Innovation Suite"
+header: "Creative Innovation Suite (CIS) Module"
+subheader: "No custom configuration - uses Core settings only"
+default_selected: false
+
+# Variables from Core Config inserted:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+```
+
+Some modules don't need custom variables — core config is enough!
+
+---
+
+### BMGD (Game Development) — Multi-Select Example
+
+```yaml
+code: bmgd
+name: "BMGD: BMad Game Development"
+header: "BMad Game Development Module"
+subheader: "Configure game development settings"
+default_selected: false
+
+project_name:
+  prompt: "What is the name of your game project?"
+  default: "{directory_name}"
+  result: "{value}"
+
+primary_platform:
+  prompt: "Which game engine do you use?"
+  default: ["unity", "unreal"]
+  required: true
+  result: "{value}"
+  multi-select:
+    - value: "unity"
+      label: "Unity"
+    - value: "unreal"
+      label: "Unreal Engine"
+    - value: "godot"
+      label: "Godot"
+    - value: "other"
+      label: "Custom / Other"
+```
+
+---
+
+## Best Practices
+
+### DO:
+- Keep prompts clear and concise
+- Provide sensible defaults
+- Use `result: "{project-root}/{value}"` for paths
+- Use single/multi-select for structured choices
+- Group related variables logically
+
+### DON'T:
+- Overwhelm users with too many questions
+- Ask for information that could be inferred
+- Use technical jargon in prompts
+- Create variables that are never used
+
+---
+
+## Variable Naming
+
+- **kebab-case** (e.g., `planning_artifacts`, `user_skill_level`)
+- Descriptive but concise
+- Avoid conflicts with core variables
+
+---
+
+## Testing Your module.yaml
+
+After creating module.yaml, test it:
+
+1. Run `bmad install` in a test project
+2. Verify prompts appear correctly
+3. Check that variables expand in agents/workflows
+4. Test default values
+5. Validate path templates resolve correctly
+
+---
+
+## Quick Reference
+
+| Pattern | Use Case |
+|---------|----------|
+| Simple text input | Names, titles, descriptions |
+| Boolean/Flag | Enable/disable features |
+| Single select | Experience levels, categories |
+| Multi select | Platforms, frameworks, options |
+| Multi-line prompt | Complex questions needing context |
+| Required | Must-have information |
+| Path variable | Directory locations |
+| Inherit/Alias | Compatibility, references |

package/src/bmb/workflows/module/module-help-generate.md

@@ -0,0 +1,254 @@
+---
+name: module-help-generate
+description: Generate or update module-help.csv for any BMad module with proper structure
+web_bundle: false
+
+# Path variables (to be set by caller)
+modulePath: '{module_path}'
+moduleYamlFile: '{module_path}/module.yaml'
+moduleHelpCsvFile: '{module_path}/module-help.csv'
+workflowsDir: '{module_path}/workflows'
+agentsDir: '{module_path}/agents'
+---
+
+# Module Help CSV Generator
+
+**Goal:** Generate or update a `module-help.csv` file that serves as the central registry for all module functionality - workflows, agents, and commands.
+
+**Your Role:** You are a Module Documentation Architect. You will analyze a module's structure and create a properly formatted CSV that enables discoverability and CLI integration.
+
+---
+
+## CRITICAL RULES (NO EXCEPTIONS)
+
+- ALWAYS read existing `module-help.csv` first if it exists - update/validate rather than replace
+- ALWAYS read `module.yaml` to get module code and type
+- ALWAYS read ALL agent `.yaml` files to understand menu triggers
+- ALWAYS read ALL workflow `workflow.md` files to understand purpose
+- ALWAYS place `anytime` entries at the TOP with EMPTY sequence
+- ALWAYS place phased entries BELOW anytime entries
+- ALWAYS number phases starting at `-1` (phase-1, phase-2, phase-3...)
+- ALWAYS leave sequence EMPTY for `anytime` entries (user chooses, not ordered)
+- ALWAYS include sequence number for phased entries (defines order within phase)
+- ALWAYS use EMPTY `workflow-file` for agent-only menu triggers
+- ALWAYS include `agent` column for agent-based features
+- NEVER assume workflow paths - verify from actual file structure
+- ALWAYS search for and put the file at the root of the module ONLY
+
+---
+
+## CSV STRUCTURE (13 columns)
+
+```
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+```
+
+| Column | Purpose | Rules |
+|--------|---------|-------|
+| `module` | Module code from `module.yaml` | Required |
+| `phase` | `anytime` or `phase-1`, `phase-2`, etc. | Phases start at -1 |
+| `name` | Display name of the feature | User-facing |
+| `code` | Short code for commands | Unique within module |
+| `sequence` | Order within phase | EMPTY for anytime, number for phases |
+| `workflow-file` | Path to workflow.md | EMPTY for agent-only |
+| `command` | Internal command name | Format: `{module_code}_{feature_code}` |
+| `required` | Whether required | Usually `false` |
+| `agent` | Associated agent name | From agent YAML metadata |
+| `options` | Mode or action type | e.g., "Create Mode", "Chat Mode" |
+| `description` | User-facing description | Explain what and when to use |
+| `output-location` | Where output goes | Folder name or EMPTY |
+| `outputs` | What is produced | Output type or EMPTY |
+
+---
+
+## PHASE AND SEQUENCING RULES
+
+### 1. anytime
+- Use for: standalone features, agent menu triggers, unrelated utilities
+- Place at TOP of file
+- `sequence` column MUST BE EMPTY
+- User chooses what to run - no order
+
+### 2. Phases (phase-1, phase-2, phase-3...)
+- Use for: sequential workflows, guided processes
+- Place BELOW anytime entries
+- Phases ALWAYS start at `-1` (not 0 or 1)
+- `sequence` defines order WITHIN phase (10, 20, 30...)
+- the name can be named differently than just phase but should be dash number at the end if sequence is needed
+
+### 3. Module Integration Patterns
+
+**Full module with phases:**
+```
+anytime entries (sequence empty)
+phase-1 entries (sequence 10, 20, 30...)
+phase-2 entries (sequence 10, 20, 30...)
+```
+
+**Add-on to existing module:**
+```
+May only have phase-3 entries that integrate into another module's workflow
+Sequence numbers fit logically before/after existing items
+```
+
+**Standalone collections:**
+```
+All entries are anytime
+No sequence numbers
+User picks one as needed
+```
+
+**Agent-only features:**
+```
+Empty workflow-file column
+Agent handles everything via its menu
+```
+
+---
+
+## EXECUTION SEQUENCE
+
+### Step 1: Identify Target Module
+
+Ask user:
+1. What is the path to the module?
+2. Or should we scan for modules in the workspace?
+
+### Step 2: Read Module Configuration
+
+Load and read:
+```
+{moduleYamlFile}
+```
+
+Extract:
+- `code` - Module identifier
+- `type` - Module type
+- `name` - Module display name
+
+### Step 3: Check for Existing module-help.csv
+
+Check if exists:
+```
+{moduleHelpCsvFile}
+```
+
+**If exists:**
+- Read entire file
+- Parse all existing entries
+- Ask user: Update existing, validate, or regenerate?
+
+**If not exists:**
+- Note: Will create new file
+- Proceed to discovery
+
+### Step 4: Discover All Workflows
+
+Scan the workflows directory:
+```
+{workflowsDir}
+```
+
+For each workflow found:
+- Read the `workflow.md` file
+- Extract: name, description, goal, role
+- Note the relative path for CSV entry
+
+### Step 5: Discover All Agents
+
+Scan the agents directory:
+```
+{agentsDir}
+```
+
+For each agent found:
+- Read the `.agent.yaml` file
+- Extract: metadata (name, title), persona, menu triggers
+- Identify agent-only triggers (no workflow route)
+- Identify workflow-routing triggers
+
+### Step 6: Determine Phasing Strategy
+
+Analyze the module and decide:
+
+**Question for each workflow:**
+- Is this part of a sequential journey? → Use phases
+- Is this standalone/optional? → Use anytime
+- Can user do this anytime? → Use anytime
+
+**For agent menu items:**
+- Does it route to a workflow? → Map to that workflow or anytime
+- Is it an inline action? → anytime, no workflow file
+
+### Step 7: Generate CSV Content
+
+Build the CSV following structure:
+
+**Header:**
+```
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+```
+
+**Entry Rules:**
+1. ALL `anytime` entries FIRST - `sequence` EMPTY
+2. THEN phased entries - `phase-1`, `phase-2`, etc.
+3. Within phases, `sequence` orders execution (10, 20, 30...)
+4. Agent-only actions: empty `workflow-file`, specify `agent`
+
+**Code Format:**
+- Command: `{module_code}_{feature_name}`
+- Keep codes short but memorable (2-3 letters usually)
+
+**Description Guidance:**
+- Explain WHAT the feature does
+- Include WHEN to use it (especially for phased items)
+- For add-on modules: "Best used after X but before Y"
+
+### Step 8: Present to User
+
+Before writing:
+1. Show the CSV content in a readable table format
+2. Explain phasing decisions
+3. Highlight any agent-only entries
+4. Ask for confirmation or adjustments
+
+### Step 9: Write File
+
+On confirmation:
+```
+Write to: {moduleHelpCsvFile}
+```
+
+---
+
+## EXAMPLE OUTPUT STRUCTURE
+
+### Full Module with Phases (like mwm):
+```csv
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+mwm,anytime,Chat with Wellness,CWC,,"mwm_chat",false,wellness-companion,Chat Mode,"Have a supportive conversation anytime",,,
+mwm,anytime,Quick Breathing,QB,,"mwm_breathing",false,meditation-guide,Breathing,"Quick 4-7-8 breathing exercise",,,
+mwm,phase-1,Daily Check In,DCI,10,_bmad/mwm/workflows/daily-checkin/workflow.md,mwm_daily_checkin,false,wellness-companion,Check In Mode,"Start your day with wellness check-in",mwm_output,"summary",
+mwm,phase-2,Wellness Journal,WJ,20,_bmad/mwm/workflows/wellness-journal/workflow.md,mwm_journal,false,wellness-companion,Journal Mode,"Reflect and track your wellness journey",mwm_output,"entry",
+```
+
+### Standalone Module (like bmad-custom):
+```csv
+module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
+bmad-custom,anytime,Quiz Master,QM,,"bmad_quiz",false,,Trivia,"Interactive trivia quiz with gameshow atmosphere",bmad_output,"results",
+bmad-custom,anytime,Wassup,WS,,"bmad_wassup",false,,Status,"Check uncommitted changes and suggest commits",bmad_output,"summary",
+bmad-custom,anytime,Write Commit,WC,,"bmad_write_commit",false,commit-poet,Write,"Craft a commit message from your changes",bmad_output,"message",
+```
+
+---
+
+## INITIALIZATION
+
+To begin this workflow:
+
+1. Ask user for the target module path if not provided
+2. Load and read `module.yaml` in the root of the target if it exists
+3. Check for existing `module-help.csv`
+4. Scan for all workflows and agents
+5. Generate CSV following all rules above
+6. Update the file and review with the user - never auto commit and push