pig-farm-controller/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 This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them Communicate all responses in {communication_language}

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

Load the target workflow completely:

• workflow.yaml configuration
• instructions.md (if exists)
• template.md (if exists)
• checklist.md (if exists)
• Any additional data files referenced

Load ALL workflow documentation to inform understanding:

• Workflow creation guide: {workflow_creation_guide}
• Workflow execution engine: {workflow_execution_engine}
• Study example workflows from: {project-root}/bmad/bmm/workflows/

Analyze the workflow deeply:

• Identify workflow type (document, action, interactive, autonomous, meta)
• Understand purpose and user journey
• Map out step flow and logic
• Check variable consistency across files
• Evaluate instruction style (intent-based vs prescriptive)
• Assess template structure (if applicable)
• Review validation criteria
• Identify config dependencies
• Check for web bundle configuration
• Evaluate against best practices from loaded guides

Reflect understanding back to {user_name}:

Present a warm, conversational summary adapted to the workflow's complexity:

• What this workflow accomplishes (its purpose and value)
• How it's structured (type, steps, interactive points)
• What you notice (strengths, potential improvements, issues)
• Your initial assessment based on best practices
• How it fits in the larger BMAD ecosystem

Be conversational and insightful. Help {user_name} see their workflow through your eyes.

Does this match your understanding of what this workflow should accomplish? workflow_understanding

Understand WHAT the user wants to improve and WHY before diving into edits

Engage in collaborative discovery:

Ask open-ended questions to understand their goals:

• What prompted you to want to edit this workflow?
• What feedback have you gotten from users running it?
• Are there specific steps that feel clunky or confusing?
• Is the workflow achieving its intended outcome?
• Are there new capabilities you want to add?
• Is the instruction style working well for your users?

Listen for clues about:

• User experience issues (confusing steps, unclear instructions)
• Functional issues (broken references, missing validation)
• Performance issues (too many steps, repetitive, tedious)
• Maintainability issues (hard to update, bloated, inconsistent variables)
• Instruction style mismatch (too prescriptive when should be adaptive, or vice versa)
• Integration issues (doesn't work well with other workflows)

Based on their responses and your analysis from step 1, identify improvement opportunities:

Organize by priority and user goals:

• CRITICAL issues blocking successful runs
• IMPORTANT improvements enhancing user experience
• NICE-TO-HAVE enhancements for polish

Present these conversationally, explaining WHY each matters and HOW it would help.

Assess instruction style fit:

Based on the workflow's purpose and your analysis:

• Is the current style (intent-based vs prescriptive) appropriate?
• Would users benefit from more/less structure?
• Are there steps that should be more adaptive?
• Are there steps that need more specificity?

Discuss style as part of improvement discovery, not as a separate concern.

Collaborate on priorities:

Don't just list options - discuss them:

• "I noticed {{issue}} - this could make users feel {{problem}}. Want to address this?"
• "The workflow could be more {{improvement}} which would help when {{use_case}}. Worth exploring?"
• "Based on what you said about {{user_goal}}, we might want to {{suggestion}}. Thoughts?"

Let the conversation flow naturally. Build a shared vision of what "better" looks like.

improvement_goals

Work iteratively - improve, review, refine. Never dump all changes at once.

For each improvement area, facilitate collaboratively:

1. Explain the current state and why it matters

   • Show relevant sections of the workflow
   • Explain how it works now and implications
   • Connect to user's goals from step 2

2. Propose improvements with rationale

   • Suggest specific changes that align with best practices
   • Explain WHY each change helps
   • Provide examples from the loaded guides when helpful
   • Show before/after comparisons for clarity
   • Reference the creation guide's patterns naturally

3. Collaborate on the approach

   • Ask if the proposed change addresses their need
   • Invite modifications or alternative approaches
   • Explain tradeoffs when relevant
   • Adapt based on their feedback

4. Apply changes iteratively

   • Make one focused improvement at a time
   • Show the updated section
   • Confirm it meets their expectation
   • Move to next improvement or refine current one

Common improvement patterns to facilitate:

If refining instruction style:

• Discuss where the workflow feels too rigid or too loose
• Identify steps that would benefit from intent-based approach
• Identify steps that need prescriptive structure
• Convert between styles thoughtfully, explaining tradeoffs
• Show how each style serves the user differently
• Test proposed changes by reading them aloud

If improving step flow:

• Walk through the user journey step by step
• Identify friction points or redundancy
• Propose streamlined flow
• Consider where steps could merge or split
• Ensure each step has clear goal and value
• Check that repeat conditions make sense

If fixing variable consistency:

• Identify variables used across files
• Find mismatches in naming or usage
• Propose consistent naming scheme
• Update all files to match
• Verify variables are defined in workflow.yaml

If enhancing validation:

• Review current checklist (if exists)
• Discuss what "done well" looks like
• Make criteria specific and measurable
• Add validation for new features
• Remove outdated or vague criteria

If updating configuration:

• Review standard config pattern
• Check if user context variables are needed
• Ensure output_folder, user_name, communication_language are used appropriately
• Add missing config dependencies
• Clean up unused config fields

If adding/updating templates:

• Understand the document structure needed
• Design template variables that match instruction outputs
• Ensure variable names are descriptive snake_case
• Include proper metadata headers
• Test that all variables can be filled

If configuring web bundle:

• Identify all files the workflow depends on
• Check for invoked workflows (must be included)
• Verify paths are bmad/-relative
• Remove config_source dependencies
• Build complete file list

If improving user interaction:

• Find places where could be more open-ended
• Add educational context where users might be lost
• Remove unnecessary confirmation steps
• Make questions clearer and more purposeful
• Balance guidance with user autonomy

Throughout improvements, educate when helpful:

Share insights from the guides naturally:

• "The creation guide recommends {{pattern}} for workflows like this"
• "Looking at examples in BMM, this type of step usually {{approach}}"
• "The execution engine expects {{structure}} for this to work properly"

Connect improvements to broader BMAD principles without being preachy.

After each significant change:

• "Does this flow feel better for what you're trying to achieve?"
• "Want to refine this further, or move to the next improvement?"
• "How does this change affect the user experience?"

improvement_implementation

Run comprehensive validation conversationally:

Don't just check boxes - explain what you're validating and why it matters:

• "Let me verify all file references resolve correctly..."
• "Checking that variables are consistent across all files..."
• "Making sure the step flow is logical and complete..."
• "Validating template variables match instruction outputs..."
• "Ensuring config dependencies are properly set up..."

Load validation checklist: {installed_path}/checklist.md Check all items from checklist systematically

Present issues conversationally:

Explain what's wrong and implications:

• "I found {{issue}} which could cause {{problem}} when users run this"
• "The {{component}} needs {{fix}} because {{reason}}"

Propose fixes immediately:

• "I can fix this by {{solution}}. Should I?"
• "We have a couple options here: {{option1}} or {{option2}}. Thoughts?"

Fix approved issues and re-validate

Confirm success warmly:

"Excellent! Everything validates cleanly:

• All file references resolve
• Variables are consistent throughout
• Step flow is logical and complete
• Template aligns with instructions (if applicable)
• Config dependencies are set up correctly
• Web bundle is complete (if applicable)

Your workflow is in great shape."

validation_results

Create a conversational summary of what improved:

Tell the story of the transformation:

• "We started with {{initial_state}}"
• "You wanted to {{user_goals}}"
• "We made these key improvements: {{changes_list}}"
• "Now your workflow {{improved_capabilities}}"

Highlight the impact:

• "This means users will experience {{benefit}}"
• "The workflow is now more {{quality}}"
• "It follows best practices for {{patterns}}"

Guide next steps based on changes made:

If instruction style changed:

• "Since we made the workflow more {{style}}, you might want to test it with a real user to see how it feels"

If template was updated:

• "The template now has {{new_variables}} - run the workflow to generate a sample document"

If this is part of larger module work:

• "This workflow is part of {{module}} - consider if other workflows need similar improvements"

If web bundle was configured:

• "The web bundle is now set up - you can test deploying this workflow standalone"

Be a helpful guide to what comes next, not just a task completer.

Would you like to:

• Test the edited workflow by running it
• Edit another workflow
• Make additional refinements to this one
• Return to your module work

completion_summary