BMAD-METHOD/bmad/bmb/workflows/edit-workflow/instructions.md

Edit Workflow - Workflow Editor Instructions

The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-workflow/workflow.yaml Study the workflow creation guide thoroughly at: {workflow_creation_guide} Communicate in {communication_language} throughout the workflow editing process

What is the path to the workflow you want to edit? (provide path to workflow.yaml or workflow folder)

Load the workflow.yaml file from the provided path Identify the workflow type (document, action, interactive, autonomous, meta) List all associated files (template.md, instructions.md, checklist.md, data files) Load any existing instructions.md and template.md files if present

Display a summary:

• Workflow name and description
• Type of workflow
• Files present
• Current structure overview

Load the complete workflow creation guide from: {workflow_creation_guide} Check the workflow against the guide's best practices:

Analyze for:

• Critical headers: Are workflow engine references present?
• File structure: Are all expected files present for this workflow type?
• Variable consistency: Do variable names match between files?
• Step structure: Are steps properly numbered and focused?
• XML tags: Are tags used correctly and consistently?
• Instructions clarity: Are instructions specific with examples and limits?
• 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?

Create a list of identified issues or improvement opportunities Prioritize issues by importance (critical, important, nice-to-have)

Present the editing menu to the user:

What aspect would you like to edit?

1. Fix critical issues - Address missing headers, broken references
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

Select an option (1-11) or describe a custom edit:

Based on the selected edit type, load appropriate reference materials:

If option 2 (Add/fix standard config): Prepare standard config block template:

# 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

Check if workflow.yaml has existing config section (don't duplicate) Identify missing config variables to add Check instructions.md for config variable usage Check template.md for config variable usage

If editing instructions or adding features: Review the "Writing Instructions" section of the creation guide Load example workflows from {project-root}/bmad/bmm/workflows/ for patterns

If editing templates: Review the "Templates and Variables" section of the creation guide Ensure variable naming conventions are followed

If editing validation: Review the "Validation" section and measurable criteria examples

If option 9 (Remove bloat): Cross-reference all workflow.yaml fields against instructions.md and template.md Identify yaml fields not used in any file Check for duplicate fields in web_bundle section

If configuring web bundle: Review the "Web Bundles" section of the creation guide Scan all workflow files for referenced resources Create inventory of all files that must be included Scan instructions for calls - those yamls must be included

If fixing critical issues: Load the workflow execution engine documentation Verify all required elements are present

Based on the selected focus area:

If configuring web bundle (option 7): Check if web_bundle section exists in workflow.yaml

If creating new web bundle:

1. Extract workflow metadata (name, description, author)
2. Convert all file paths to bmad/-relative format
3. Remove any {config_source} references
4. Scan instructions.md for all file references:
   • Data files (CSV, JSON)
   • Sub-workflows
   • Shared templates
   • Any included files
5. Scan template.md for any includes
6. Create complete web_bundle_files array
7. CRITICAL: Check for calls in instructions:
   • If workflow invokes other workflows, add existing_workflows field
   • Maps workflow variable name to bmad/-relative path
   • Signals bundler to recursively include invoked workflow's web_bundle
   • Example: existing_workflows: - core_brainstorming: "bmad/core/workflows/brainstorming/workflow.yaml"
8. Generate web_bundle section

If updating existing web bundle:

1. Verify all paths are bmad/-relative
2. Check for missing files in web_bundle_files
3. Remove any config dependencies
4. Update file list with newly referenced files

Show the current content that will be edited Explain the proposed changes and why they improve the workflow Generate the updated content following all conventions from the guide

Review the proposed changes. Options:

• [a] Accept and apply
• [e] Edit/modify the changes
• [s] Skip this change
• [n] Move to next file/section
• [d] Done with edits

If user selects 'a': Apply the changes to the file Log the change for the summary

If user selects 'e': What modifications would you like to make? Regenerate with modifications

If user selects 'd': Proceed to validation

Run a comprehensive validation check:

Basic Validation:

• All file paths resolve correctly
• Variable names are consistent across files
• Step numbering is sequential and logical
• Required XML tags are properly formatted
• No placeholders remain (like {TITLE} or {WORKFLOW_CODE})
• Instructions match the workflow type
• Template variables match instruction outputs (if applicable)
• Checklist criteria are measurable (if present)
• Critical headers are present in instructions
• YAML syntax is valid

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 optionally includes {{user_name}}, {{date}} in metadata (if document workflow)
• Template does NOT use {{communication_language}} in headers (agent-only variable)

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 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 () included in web_bundle_files
• Complete file inventory verified

If any validation fails: Issues found. Would you like to fix them? (y/n) If yes: Return to editing

Create a summary of all changes made for {user_name} in {communication_language}:

Summary Structure:

• Workflow name
• Changes made (file-by-file descriptions)
• Improvements (how workflow is now better aligned with best practices)
• Files modified (complete list with paths)
• Next steps (suggestions for additional improvements or testing)

Would you like to:

• Test the edited workflow
• Make additional edits
• Exit

If test workflow: Invoke the edited workflow for testing