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. Adjust instruction style - Convert between intent-based and prescriptive styles
12. Full review and update - Comprehensive improvements across all files

Select an option (1-12) 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

If adjusting instruction style (option 11): Analyze current instruction style in instructions.md:

• Count tags vs tags
• Identify goal-oriented language ("guide", "explore", "help") vs prescriptive ("choose", "select", "specify")
• Assess whether steps are open-ended or structured with specific options Determine current dominant style: intent-based, prescriptive, or mixed Load the instruction style guide section from create-workflow

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

If adjusting instruction style (option 11): Present current style analysis to user:

Current Instruction Style Analysis:

• Current dominant style: {{detected_style}}
• Intent-based elements: {{intent_count}}
• Prescriptive elements: {{prescriptive_count}}

Understanding Intent-Based vs Prescriptive:

1. Intent-Based (Recommended) - Guide the LLM with goals and principles, let it adapt conversations naturally

• More flexible and conversational
• LLM chooses appropriate questions based on context
• Better for complex discovery and iterative refinement
• Example: <action>Guide user to define their target audience with specific demographics and needs</action>

2. Prescriptive - Provide exact wording for questions and options

• More controlled and predictable
• Ensures consistency across runs
• Better for simple data collection or specific compliance needs
• Example: <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask>

When to use Intent-Based:

• Complex discovery processes (user research, requirements gathering)
• Creative brainstorming and ideation
• Iterative refinement workflows
• When user input quality matters more than consistency
• Workflows requiring adaptation to context

When to use Prescriptive:

• Simple data collection (platform, format, yes/no choices)
• Compliance verification and standards adherence
• Configuration with finite options
• When consistency is critical across all executions
• Quick setup wizards

Best Practice: Mix Both Styles

Even workflows with a primary style should use the other when appropriate. For example:

<!-- Intent-based workflow with prescriptive moments -->
<step n="1" goal="Understand user vision">
  <action>Explore the user's vision, uncovering their creative intent and target experience</action>
</step>

<step n="2" goal="Capture basic metadata">
  <ask>What is your target platform? Choose: PC, Console, Mobile, Web</ask> <!-- Prescriptive for simple choice -->
</step>

<step n="3" goal="Deep dive into details">
  <action>Guide user to articulate their approach, exploring mechanics and unique aspects</action> <!-- Back to intent-based -->
</step>

What would you like to do?

1. Make more intent-based - Convert prescriptive tags to goal-oriented tags where appropriate
2. Make more prescriptive - Convert open-ended tags to specific tags with options
3. Optimize mix - Use intent-based for complex steps, prescriptive for simple data collection
4. Review specific steps - Show me each step and let me decide individually
5. Cancel - Keep current style

Select option (1-5):

Store user's style adjustment preference as {{style_adjustment_choice}}

If choice is 1 (make more intent-based): Identify prescriptive tags that could be converted to intent-based tags For each candidate conversion:

• Show original prescriptive version
• Suggest intent-based alternative focused on goals
• Explain the benefit of the conversion
• Ask for approval Apply approved conversions

If choice is 2 (make more prescriptive): Identify open-ended tags that could be converted to prescriptive tags For each candidate conversion:

• Show original intent-based version
• Suggest prescriptive alternative with specific options
• Explain when prescriptive is better here
• Ask for approval Apply approved conversions

If choice is 3 (optimize mix): Analyze each step for complexity and purpose Recommend style for each step:

• Simple data collection → Prescriptive
• Complex discovery → Intent-based
• Binary decisions → Prescriptive
• Creative exploration → Intent-based
• Standards/compliance → Prescriptive
• Iterative refinement → Intent-based Show recommendations with reasoning Apply approved optimizations

If choice is 4 (review specific steps): Present each step one at a time For each step:

• Show current instruction text
• Identify current style (intent-based, prescriptive, or mixed)
• Offer to keep, convert to intent-based, or convert to prescriptive
• Apply user's choice before moving to next step

If choice is 5 (cancel): Return to editing menu

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