pig-farm-controller/bmad/bmb/workflows/edit-module/instructions.md

Edit Module - Module 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-module/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 module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)

Load the module directory structure completely:

• Scan all directories and files
• Load config.yaml
• Load README.md
• List all agents in agents/ directory
• List all workflows in workflows/ directory
• Check for installer files (if in src/modules/)
• Identify any custom structure or patterns

Load ALL module documentation to inform understanding:

• Module structure guide: {module_structure_guide}
• Study reference modules: BMM, BMB, CIS
• Understand BMAD module patterns and conventions

Analyze the module deeply:

• Identify module purpose and role in BMAD ecosystem
• Understand agent organization and relationships
• Map workflow organization and dependencies
• Evaluate config structure and completeness
• Check documentation quality and currency
• Assess installer configuration (if source module)
• Identify cross-module integrations
• Evaluate against best practices from loaded guides

Reflect understanding back to {user_name}:

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

• What this module provides (its purpose and value in BMAD)
• How it's organized (agents, workflows, structure)
• What you notice (strengths, potential improvements, issues)
• How it fits in the larger BMAD ecosystem
• Your initial assessment based on best practices

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

Does this match your understanding of what this module should provide? module_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 module?
• What feedback have you gotten from users of this module?
• Are there specific agents or workflows that need attention?
• Is the module fulfilling its intended purpose?
• Are there new capabilities you want to add?
• How well does it integrate with other modules?
• Is the documentation helping users understand and use the module?

Listen for clues about:

• Structural issues (poor organization, hard to navigate)
• Agent/workflow issues (outdated, broken, missing functionality)
• Configuration issues (missing fields, incorrect setup)
• Documentation issues (outdated, incomplete, unclear)
• Integration issues (doesn't work well with other modules)
• Installer issues (installation problems, missing files)
• User experience issues (confusing, hard to use)

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

Organize by priority and user goals:

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

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

Collaborate on priorities:

Don't just list options - discuss them:

• "I noticed {{issue}} - this could make it hard for users to {{problem}}. Want to address this?"
• "The module 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 agent and workflow edits, invoke specialized workflows rather than doing inline

For each improvement area, facilitate collaboratively:

1. Explain the current state and why it matters

   • Show relevant sections of the module
   • 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 reference modules when helpful
   • Reference the structure 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 appropriately

   • For agent edits: Invoke edit-agent workflow
   • For workflow edits: Invoke edit-workflow workflow
   • For module-level changes: Make directly and iteratively
   • Show updates and confirm satisfaction

Common improvement patterns to facilitate:

If improving module organization:

• Discuss how the current structure serves (or doesn't serve) users
• Propose reorganization that aligns with mental models
• Consider feature-based vs type-based organization
• Plan the reorganization steps
• Update all references after moving files

If updating module configuration:

• Review current config.yaml fields
• Check for missing standard fields (user_name, communication_language, output_folder)
• Add module-specific fields as needed
• Remove unused or outdated fields
• Ensure config is properly documented

If managing agents:

• Ask which agent needs attention and why
• For editing existing agent:
• For adding new agent: Guide creation and integration
• For removing agent: Confirm, remove, update references
• Ensure all agent references in workflows remain valid

If managing workflows:

• Ask which workflow needs attention and why
• For editing existing workflow:
• For adding new workflow: Guide creation and integration
• For removing workflow: Confirm, remove, update agent references
• Ensure all workflow files are properly organized

If improving documentation:

• Review current README and identify gaps
• Discuss what users need to know
• Update module overview and purpose
• List agents and workflows with clear descriptions
• Add usage examples if helpful
• Ensure installation/setup instructions are clear

If setting up cross-module integration:

• Identify which workflows from other modules are needed
• Show how to reference workflows properly: {project-root}/bmad/{{module}}/workflows/{{workflow}}/workflow.yaml
• Document the integration in README
• Ensure dependencies are clear
• Consider adding example usage

If updating installer (source modules only):

• Review installer script for correctness
• Check web bundle configurations
• Verify all files are included
• Test installation paths
• Update module metadata

When invoking specialized workflows:

Explain why you're handing off:

• "This agent needs detailed attention. Let me invoke the edit-agent workflow to give it proper focus."
• "The workflow editor can handle this more thoroughly. I'll pass control there."

After the specialized workflow completes, return and continue:

• "Great! That agent/workflow is updated. Want to work on anything else in the module?"

Throughout improvements, educate when helpful:

Share insights from the guides naturally:

• "The module structure guide recommends {{pattern}} for this scenario"
• "Looking at how BMM organized this, we could use {{approach}}"
• "The BMAD convention is to {{pattern}} which helps with {{benefit}}"

Connect improvements to broader BMAD principles without being preachy.

After each significant change:

• "Does this organization feel more intuitive?"
• "Want to refine this further, or move to the next improvement?"
• "How does this change affect users of the module?"

improvement_implementation

Run comprehensive validation conversationally:

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

• "Let me verify the module structure is solid..."
• "Checking that all agent workflow references are valid..."
• "Making sure config.yaml has all necessary fields..."
• "Validating documentation is complete and accurate..."
• "Ensuring cross-module references work correctly..."

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}} for users"
• "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:

• Module structure is well-organized
• All agent and workflow references are valid
• Configuration is complete
• Documentation is thorough and current
• Cross-module integrations work properly
• Installer is correct (if applicable)

Your module 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 module {{improved_capabilities}}"

Highlight the impact:

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

Guide next steps based on changes made:

If structure changed significantly:

• "Since we reorganized the structure, you should update any external references to this module"

If agents or workflows were updated:

• "The updated agents/workflows should be tested with real user interactions"

If cross-module integration was added:

• "Test the integration with {{other_module}} to ensure it works smoothly"

If installer was updated:

• "Test the installation process to verify all files are included correctly"

If this is part of larger BMAD work:

• "Consider if patterns from this module could benefit other modules"

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

Would you like to:

• Test the edited module by invoking one of its agents
• Edit a specific agent or workflow in more detail
• Make additional refinements to the module
• Work on a different module

completion_summary