workflow cleanup

2025-10-15 23:50:34 -05:00
parent f4b16bfacf
commit 72b6640f4b
43 changed files with 99290 additions and 25 deletions
--- a/src/modules/bmb/workflows/convert-legacy/instructions.md
+++ b/src/modules/bmb/workflows/convert-legacy/instructions.md
@@ -205,6 +205,17 @@ For Modules:
   - Agent permissions → note in instructions
   - Processing flow → integrate into workflow steps

+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
 <invoke-workflow>
  workflow: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml
  inputs:
@@ -214,6 +225,9 @@ For Modules:
    - instructions: {{converted_sections}}
 </invoke-workflow>

+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
 <goto step="6">Continue to Validation</goto>
 </step>

@@ -263,6 +277,17 @@ For Modules:
   - YOLO mode → autonomous flag or optional steps
   - Critical notices → workflow.yaml comments

+<critical>When invoking create-workflow, the standard config block will be automatically added:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
 <invoke-workflow>
  workflow: {project-root}/bmad/bmb/workflows/create-workflow/workflow.yaml
  inputs:
@@ -272,6 +297,9 @@ For Modules:
    - template: {{generated_template_if_document}}
 </invoke-workflow>

+<action>Verify the created workflow.yaml includes standard config block</action>
+<action>Update converted instructions to use config variables where appropriate</action>
+
 <goto step="6">Continue to Validation</goto>
 </step>

@@ -292,6 +320,17 @@ For Workflows:
 - [ ] Template variables match
 - [ ] File structure correct

+**Standard Config Validation (Workflows):**
+
+- [ ] workflow.yaml contains standard config block:
+  - config_source defined
+  - output_folder, user_name, communication_language pulled from config
+  - date set to system-generated
+- [ ] Converted instructions use config variables where appropriate
+- [ ] Template includes config variables in metadata (if document workflow)
+- [ ] No hardcoded paths that should use {output_folder}
+- [ ] No generic greetings that should use {user_name}
+
 For Modules:

 - [ ] All components converted
--- a/src/modules/bmb/workflows/create-workflow/instructions.md
+++ b/src/modules/bmb/workflows/create-workflow/instructions.md
@@ -116,6 +116,19 @@ Include:
 - Required tools if any
 - Recommended inputs if any

+<critical>ALWAYS include the standard config block:</critical>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{{target_module}}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
+<critical>This standard config ensures workflows can run autonomously and communicate properly with users</critical>
+
 Follow path conventions from guide:

 - Use {project-root} for absolute paths
@@ -158,6 +171,23 @@ Generate the instructions.md file following the workflow creation guide:
   - Set limits ("3-5 items maximum")
   - Save checkpoints with <template-output>

+<critical>Standard config variable usage:</critical>
+
+Instructions MUST use the standard config variables where appropriate:
+
+- Communicate in {communication_language} throughout the workflow
+- Address user as {user_name} in greetings and summaries
+- Write all output files to {output_folder} or subdirectories
+- Include {date} in generated document headers
+
+Example usage in instructions:
+
+```xml
+<action>Write document to {output_folder}/output-file.md</action>
+<critical>Communicate all responses in {communication_language}</critical>
+<output>Hello {user_name}, the workflow is complete!</output>
+```
+
 <critical>Save location:</critical>

 - Write to {{output_folder}}/instructions.md
@@ -171,9 +201,16 @@ Generate the template.md file following guide conventions:
 1. Document structure with clear sections
 2. Variable syntax: {{variable_name}} using snake_case
 3. Variable names MUST match <template-output> tags exactly from instructions
-4. Include standard metadata:
-   - **Date:** {{date}}
-   - **Author:** {{user_name}} (if applicable)
+4. Include standard metadata header using config variables:
+
+   ```markdown
+   # Document Title
+
+   **Date:** {{date}}
+   **Author:** {{user_name}}
+   **Language:** {{communication_language}}
+   ```
+
 5. Follow naming conventions from guide:
   - Use descriptive names: {{primary_user_journey}} not {{puj}}
   - Snake_case for all variables
@@ -181,11 +218,21 @@ Generate the template.md file following guide conventions:

 Variable sources as per guide:

- workflow.yaml config values
+- workflow.yaml config values (user_name, communication_language, date, output_folder)
 - User input runtime values
 - Step outputs via <template-output>
 - System variables (date, paths)

+<critical>Standard config variables in templates:</critical>
+
+Templates MUST use standard config variables in headers:
+
+- {{user_name}} - Document author
+- {{date}} - Generation date
+- {{communication_language}} - Content language (if multilingual)
+
+These variables are automatically available from workflow.yaml config block.
+
 <critical>Save location:</critical>

 - Write to {{output_folder}}/template.md
@@ -230,12 +277,32 @@ If yes, create placeholder files or copy from templates.

 <step n="9" goal="Test and validate workflow">
 Review the created workflow:
+
+**Basic Validation:**
+
 1. Verify all file paths are correct
 2. Check variable names match between files
 3. Ensure step numbering is sequential
 4. Validate YAML syntax
 5. Confirm all placeholders are replaced

+**Standard Config Validation:** 6. Verify workflow.yaml contains standard config block:
+
+- config_source defined
+- output_folder, user_name, communication_language pulled from config
+- date set to system-generated
+
+7. Check instructions use config variables where appropriate
+8. Verify template includes config variables in metadata (if document workflow)
+
+**YAML/Instruction/Template Alignment:** 9. Cross-check all workflow.yaml variables against instruction usage:
+
+- Are all yaml variables referenced in instructions.md OR template.md?
+- Are there hardcoded values that should be variables?
+- Do template variables match <template-output> tags in instructions?
+
+10. Identify any unused yaml fields (bloat detection)
+
 Show user a summary of created files and their locations.
 Ask if they want to:

@@ -262,12 +329,24 @@ If yes:
   - Remove {config_source} references (use hardcoded values)
   - Example: "{project-root}/bmad/bmm/workflows/x" → "bmad/bmm/workflows/x"

-3. List ALL referenced files:
-   - Scan instructions.md for any file paths
-   - Scan template.md for any includes or references
-   - Include all data files (CSV, JSON, etc.)
-   - Include any sub-workflow YAML files
-   - Include any shared templates
+3. List ALL referenced files by scanning:
+
+   **Scan instructions.md for:**
+   - File paths in <action> tags
+   - Data files (CSV, JSON, YAML, etc.)
+   - Validation/checklist files
+   - Any <invoke-workflow> calls → must include that workflow's yaml file
+   - Any <goto> tags that reference other workflows
+   - Shared templates or includes
+
+   **Scan template.md for:**
+   - Any includes or references to other files
+   - Shared template fragments
+
+   **Critical: Workflow Dependencies**
+   - If instructions call another workflow, that workflow's yaml MUST be in web_bundle_files
+   - Example: `<invoke-workflow>{project-root}/bmad/core/workflows/x/workflow.yaml</invoke-workflow>`
+     → Add "bmad/core/workflows/x/workflow.yaml" to web_bundle_files

 4. Create web_bundle_files array with complete list

--- a/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml
+++ b/src/modules/bmb/workflows/create-workflow/workflow-template/workflow.yaml
@@ -8,6 +8,7 @@ author: "BMad"
 config_source: "{project-root}/{module-code}/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Required Data Files - HALT if missing!
--- a/src/modules/bmb/workflows/edit-workflow/instructions.md
+++ b/src/modules/bmb/workflows/edit-workflow/instructions.md
@@ -37,6 +37,26 @@ Analyze for:
 - **Template variables**: Use snake_case and descriptive names?
 - **Validation criteria**: Are checklist items measurable and specific?

+**Standard Config Audit:**
+
+- **workflow.yaml config block**: Check for standard config variables
+  - Is config_source defined?
+  - Are output_folder, user_name, communication_language pulled from config?
+  - Is date set to system-generated?
+- **Instructions usage**: Do instructions use config variables?
+  - Does it communicate in {communication_language}?
+  - Does it address {user_name}?
+  - Does it write to {output_folder}?
+- **Template usage**: Does template.md include config variables in metadata?
+
+**YAML/File Alignment:**
+
+- **Unused yaml fields**: Are there variables in workflow.yaml not used in instructions OR template?
+- **Missing variables**: Are there hardcoded values that should be variables?
+- **Web bundle completeness**: If web_bundle exists, does it include all dependencies?
+  - All referenced files listed?
+  - Called workflows included?
+
 <action>Create a list of identified issues or improvement opportunities</action>
 <action>Prioritize issues by importance (critical, important, nice-to-have)</action>
 </step>
@@ -47,21 +67,40 @@ Present the editing menu to the user:
 **What aspect would you like to edit?**

 1. **Fix critical issues** - Address missing headers, broken references
-2. **Update workflow.yaml** - Modify configuration, paths, metadata
-3. **Refine instructions** - Improve steps, add detail, fix flow
-4. **Update template** - Fix variables, improve structure (if applicable)
-5. **Enhance validation** - Make checklist more specific and measurable
-6. **Add new features** - Add steps, optional sections, or capabilities
-7. **Configure web bundle** - Add/update web bundle for deployment
-8. **Optimize for clarity** - Improve descriptions, add examples
-9. **Full review and update** - Comprehensive improvements across all files
+2. **Add/fix standard config** - Ensure standard config block and variable usage
+3. **Update workflow.yaml** - Modify configuration, paths, metadata
+4. **Refine instructions** - Improve steps, add detail, fix flow
+5. **Update template** - Fix variables, improve structure (if applicable)
+6. **Enhance validation** - Make checklist more specific and measurable
+7. **Add new features** - Add steps, optional sections, or capabilities
+8. **Configure web bundle** - Add/update web bundle for deployment
+9. **Remove bloat** - Delete unused yaml fields, duplicate values
+10. **Optimize for clarity** - Improve descriptions, add examples
+11. **Full review and update** - Comprehensive improvements across all files

-<ask>Select an option (1-9) or describe a custom edit:</ask>
+<ask>Select an option (1-11) or describe a custom edit:</ask>
 </step>

 <step n="4" goal="Load relevant documentation">
 Based on the selected edit type, load appropriate reference materials:

+<check>If option 2 (Add/fix standard config):</check>
+<action>Prepare standard config block template:</action>
+
+```yaml
+# Critical variables from config
+config_source: '{project-root}/bmad/{module}/config.yaml'
+output_folder: '{config_source}:output_folder'
+user_name: '{config_source}:user_name'
+communication_language: '{config_source}:communication_language'
+date: system-generated
+```
+
+<action>Check if workflow.yaml has existing config section (don't duplicate)</action>
+<action>Identify missing config variables to add</action>
+<action>Check instructions.md for config variable usage</action>
+<action>Check template.md for config variable usage</action>
+
 <check>If editing instructions or adding features:</check>
 <action>Review the "Writing Instructions" section of the creation guide</action>
 <action>Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns</action>
@@ -73,10 +112,16 @@ Based on the selected edit type, load appropriate reference materials:
 <check>If editing validation:</check>
 <action>Review the "Validation" section and measurable criteria examples</action>

+<check>If option 9 (Remove bloat):</check>
+<action>Cross-reference all workflow.yaml fields against instructions.md and template.md</action>
+<action>Identify yaml fields not used in any file</action>
+<action>Check for duplicate fields in web_bundle section</action>
+
 <check>If configuring web bundle:</check>
 <action>Review the "Web Bundles" section of the creation guide</action>
 <action>Scan all workflow files for referenced resources</action>
 <action>Create inventory of all files that must be included</action>
+<action>Scan instructions for <invoke-workflow> calls - those yamls must be included</action>

 <check>If fixing critical issues:</check>
 <action>Load the workflow execution engine documentation</action>
@@ -138,7 +183,7 @@ If updating existing web bundle:
 <step n="6" goal="Validate all changes" optional="true">
 <action>Run a comprehensive validation check:</action>

-Validation checks:
+**Basic Validation:**

 - [ ] All file paths resolve correctly
 - [ ] Variable names are consistent across files
@@ -151,13 +196,31 @@ Validation checks:
 - [ ] Critical headers are present in instructions
 - [ ] YAML syntax is valid

-Web bundle validation (if applicable):
+**Standard Config Validation:**
+
+- [ ] workflow.yaml contains config_source
+- [ ] output_folder, user_name, communication_language pulled from config
+- [ ] date set to system-generated
+- [ ] Instructions communicate in {communication_language} where appropriate
+- [ ] Instructions address {user_name} where appropriate
+- [ ] Instructions write to {output_folder} for file outputs
+- [ ] Template includes {{user_name}}, {{date}} in metadata (if document workflow)
+
+**YAML/File Alignment:**
+
+- [ ] All workflow.yaml variables used in instructions OR template
+- [ ] No unused yaml fields (bloat-free)
+- [ ] No duplicate fields between top-level and web_bundle
+- [ ] Template variables match <template-output> tags in instructions
+
+**Web bundle validation (if applicable):**

 - [ ] web_bundle section present if needed
 - [ ] All paths are bmad/-relative (no {project-root})
 - [ ] No {config_source} variables in web bundle
 - [ ] All referenced files listed in web_bundle_files
 - [ ] Instructions, validation, template paths correct
+- [ ] Called workflows (<invoke-workflow>) included in web_bundle_files
 - [ ] Complete file inventory verified

 <check>If any validation fails:</check>
--- a/src/modules/bmb/workflows/redoc/workflow.yaml
+++ b/src/modules/bmb/workflows/redoc/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmb/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Required knowledge base - BMAD conventions and patterns
--- a/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/brainstorm-game/workflow.yaml
@@ -3,10 +3,11 @@ name: "brainstorm-game"
 description: "Facilitate game brainstorming sessions by orchestrating the CIS brainstorming workflow with game-specific context, guidance, and additional game design techniques."
 author: "BMad"

-# Critical variables load from config_source
+# Critical variables from config
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Module path and component files
--- a/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/brainstorm-project/workflow.yaml
@@ -3,10 +3,11 @@ name: "brainstorm-project"
 description: "Facilitate project brainstorming sessions by orchestrating the CIS brainstorming workflow with project-specific context and guidance."
 author: "BMad"

-# Critical variables load from config_source
+# Critical variables from config
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Module path and component files
--- a/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/game-brief/workflow.yaml
@@ -3,10 +3,11 @@ name: game-brief
 description: "Interactive game brief creation workflow that guides users through defining their game vision with multiple input sources and conversational collaboration"
 author: "BMad"

-# Critical variables
+# Critical variables from config
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional input documents
--- a/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/product-brief/workflow.yaml
@@ -3,10 +3,11 @@ name: product-brief
 description: "Interactive product brief creation workflow that guides users through defining their product vision with multiple input sources and conversational collaboration"
 author: "BMad"

-# Critical variables
+# Critical variables from config
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional input documents
--- a/src/modules/bmm/workflows/1-analysis/research/workflow.yaml
+++ b/src/modules/bmm/workflows/1-analysis/research/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components - ROUTER PATTERN
--- a/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/gdd/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components
--- a/src/modules/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/narrative/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components
--- a/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/prd/workflow.yaml
@@ -8,6 +8,7 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 project_name: "{config_source}:project_name"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components
--- a/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/tech-spec/workflow.yaml
@@ -8,6 +8,7 @@ config_source: "{project-root}/bmad/bmm/config.yaml"
 project_name: "{config_source}:project_name"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components
--- a/src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml
+++ b/src/modules/bmm/workflows/2-plan-workflows/ux/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Workflow components
--- a/src/modules/bmm/workflows/3-solutioning/workflow.yaml
+++ b/src/modules/bmm/workflows/3-solutioning/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad Builder"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Input requirements
--- a/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/correct-course/workflow.yaml
@@ -6,6 +6,7 @@ author: "BMad Method"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/correct-course"
--- a/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml
+++ b/src/modules/bmm/workflows/4-implementation/retrospective/workflow.yaml
@@ -6,6 +6,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/bmm/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 installed_path: "{project-root}/bmad/bmm/workflows/4-implementation/retrospective"
--- a/src/modules/cis/workflows/design-thinking/workflow.yaml
+++ b/src/modules/cis/workflows/design-thinking/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional inputs for context
--- a/src/modules/cis/workflows/innovation-strategy/workflow.yaml
+++ b/src/modules/cis/workflows/innovation-strategy/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional inputs for context
--- a/src/modules/cis/workflows/problem-solving/workflow.yaml
+++ b/src/modules/cis/workflows/problem-solving/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional inputs for context
--- a/src/modules/cis/workflows/storytelling/workflow.yaml
+++ b/src/modules/cis/workflows/storytelling/workflow.yaml
@@ -7,6 +7,7 @@ author: "BMad"
 config_source: "{project-root}/bmad/cis/config.yaml"
 output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
 date: system-generated

 # Optional inputs for context