bmad-method 6.0.0-alpha.1 → 6.0.0-alpha.11

package/src/modules/bmb/workflows/edit-agent/instructions.md

@@ -1,47 +1,183 @@
 # Edit Agent - Agent Editor Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-agent/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/edit-agent/workflow.yaml</critical>
 <critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
 <critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
 <critical>Communicate all responses in {communication_language}</critical>
 
+<critical>Understanding Agent Persona Fields - ESSENTIAL for Editing Agents Correctly</critical>
+
+When editing an agent, you MUST understand how the compiled agent LLM interprets persona fields. This is the #1 issue found in agent edits:
+
+**The Four Persona Fields and LLM Interpretation:**
+
+- **role** → LLM reads: "What knowledge, skills, and capabilities do I possess?"
+  Example: "Senior Software Engineer" or "Strategic Business Analyst + Requirements Expert"
+
+- **identity** → LLM reads: "What background, experience, and context shape my responses?"
+  Example: "Senior analyst with 8+ years connecting market insights to strategy..."
+
+- **communication_style** → LLM reads: "What verbal patterns, word choice, quirks, and phrasing do I use?"
+  Example: "Treats analysis like a treasure hunt - excited by every clue"
+
+- **principles** → LLM reads: "What beliefs and operating philosophy drive my choices?"
+  Example: "Every business challenge has root causes. Ground findings in evidence."
+
+**MOST COMMON EDITING MISTAKE - Behaviors Mixed Into Communication Style:**
+
+BEFORE (incorrect - found in many legacy agents):
+
+```yaml
+communication_style: 'Experienced analyst who uses systematic approaches and ensures all stakeholders are heard'
+```
+
+^ This MIXES identity (experienced analyst) + behavior (ensures stakeholders heard) into style!
+
+AFTER (correct - persona fields properly separated):
+
+```yaml
+identity: 'Senior analyst with 8+ years connecting insights to strategy'
+communication_style: 'Systematic and probing. Structures findings hierarchically.'
+principles:
+  - 'Ensure all stakeholder voices heard'
+  - 'Ground findings in evidence'
+```
+
+**How to Recognize When Communication Style Needs Fixing:**
+
+Red flag words in communication_style indicate behaviors/role mixed in:
+
+- "ensures", "makes sure", "always", "never" → These are behaviors (move to principles)
+- "experienced", "expert who", "senior" → These are identity (move to identity field)
+- "believes in", "focused on" → These are principles (move to principles array)
+
+**Pure Communication Styles (from {communication_presets}):**
+
+Notice these contain ZERO role/identity/principles - only HOW they talk:
+
+- "Treats analysis like a treasure hunt - excited by every clue"
+- "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable"
+- "Asks 'WHY?' relentlessly like a detective on a case"
+- "Poetic drama and flair with every turn of a phrase"
+
+Use {communication_presets} CSV and reference agents in {reference_agents} as your guide for pure communication styles.
+
 <workflow>
 
 <step n="1" goal="Load and deeply understand the target agent">
 <ask>What is the path to the agent you want to edit?</ask>
 
-<action>Load the agent file from the provided path</action>
-<action>Load ALL agent documentation to inform understanding:
+<action>Detect agent type from provided path and load ALL relevant files:
+
+**If path is a .agent.yaml file (Simple Agent):**
+
+- Load the single YAML file
+- Note: Simple agent, all content in one file
+
+**If path is a folder (Expert Agent with sidecar files):**
+
+- Load the .agent.yaml file from inside the folder
+- Load ALL sidecar files in the folder:
+  - Templates (_.md, _.txt)
+  - Documentation files
+  - Knowledge base files (_.csv, _.json, \*.yaml)
+  - Any other resources referenced by the agent
+- Create inventory of sidecar files for reference
+- Note: Expert agent with sidecar structure
+
+**If path is ambiguous:**
 
-- Agent types guide: {agent_types}
-- Agent architecture: {agent_architecture}
-- Command patterns: {agent_commands}
-- Communication styles: {communication_styles}
-- Workflow execution engine: {workflow_execution_engine}
+- Check if it's a folder containing .agent.yaml → Expert agent
+- Check if it's a direct .agent.yaml path → Simple agent
+- If neither, ask user to clarify
+
+Present what was loaded:
+
+- "Loaded [agent-name].agent.yaml"
+- If Expert: "Plus 5 sidecar files: [list them]"
   </action>
+  <action>Load ALL agent documentation to inform understanding:
+
+**Core Concepts:**
+
+- Understanding agent types: {understanding_agent_types}
+- Agent compilation process: {agent_compilation}
+
+**Architecture Guides:**
+
+- Simple agent architecture: {simple_architecture}
+- Expert agent architecture: {expert_architecture}
+- Module agent architecture: {module_architecture}
+
+**Design Patterns:**
+
+- Menu patterns: {menu_patterns}
+- Communication presets: {communication_presets}
+- Brainstorm context: {brainstorm_context}
+
+**Reference Agents:**
+
+- Simple example: {reference_simple_agent}
+- Expert example: {reference_expert_agent}
+- Module examples: {reference_module_agents}
+- BMM agents (distinct voices): {bmm_agents}
+
+**Workflow execution engine:** {workflow_execution_engine}
+</action>
 
 <action>Analyze the agent structure thoroughly:
 
+**Basic Structure:**
+
 - Parse persona (role, identity, communication_style, principles)
 - Understand activation flow and steps
 - Map menu items and their workflows
 - Identify configuration dependencies
-- Assess agent type (full, hybrid, standalone)
+- Assess agent type: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration)
 - Check workflow references for validity
-- Evaluate against best practices from loaded guides
-  </action>
+
+**If Expert Agent - Analyze Sidecar Files:**
+
+- Map which menu items reference which sidecar files (tmpl="path", data="path")
+- Check if all sidecar references in YAML actually exist
+- Identify unused sidecar files (not referenced in YAML)
+- Assess sidecar organization (are templates grouped logically?)
+- Note any sidecar files that might need editing (outdated templates, old docs)
+
+**CRITICAL - Persona Field Separation Analysis:**
+
+- Check if communication_style contains ONLY verbal patterns
+- Identify any behaviors mixed into communication_style (red flags: "ensures", "makes sure", "always")
+- Identify any role/identity statements in communication_style (red flags: "experienced", "expert who", "senior")
+- Identify any principles in communication_style (red flags: "believes in", "focused on")
+- Compare communication_style against {communication_presets} for purity
+- Compare against similar reference agents
+
+**Evaluate against best practices from loaded guides**
+</action>
 
 <action>Reflect understanding back to {user_name}:
 
 Present a warm, conversational summary adapted to the agent's complexity:
 
 - What this agent does (its role and purpose)
-- How it's structured (type, menu items, workflows)
+- How it's structured (Simple/Expert/Module type, menu items, workflows)
+- **If Expert agent:** Describe the sidecar structure warmly:
+  - "This is an Expert agent with a nice sidecar structure - I see 3 templates, 2 knowledge files, and a README"
+  - Mention what the sidecar files are for (if clear from names/content)
+  - Note any sidecar issues (broken references, unused files)
+- **If persona field separation issues found:** Gently point out that communication_style has behaviors/role mixed in - explain this is common and fixable
 - What you notice (strengths, potential improvements, issues)
 - Your initial assessment of its health
 
 Be conversational, not clinical. Help {user_name} see their agent through your eyes.
+
+Example of mentioning persona issues warmly:
+"I notice the communication_style has some behaviors mixed in (like 'ensures stakeholders are heard'). This is super common - we can easily extract those to principles to make the persona clearer. The agent's core purpose is solid though!"
+
+Example of mentioning Expert agent sidecar structure:
+"This is beautifully organized as an Expert agent! The sidecar files include 3 journal templates (daily, weekly, breakthrough) and a mood-patterns knowledge file. Your menu items reference them nicely. I do notice 'old-template.md' isn't referenced anywhere - we could clean that up."
 </action>
 
 <ask>Does this match your understanding of what this agent should do?</ask>
@@ -63,22 +199,29 @@ Ask open-ended questions to understand their goals:
 
 Listen for clues about:
 
+- **Persona field separation issues** (communication_style contains behaviors/role/principles)
 - Functional issues (broken references, missing workflows)
+- **Sidecar file issues** (for Expert agents: outdated templates, unused files, missing references)
 - User experience issues (confusing menu, unclear communication)
 - Performance issues (too slow, too verbose, not adaptive enough)
 - Maintenance issues (hard to update, bloated, inconsistent)
 - Integration issues (doesn't work well with other agents/workflows)
+- **Legacy pattern issues** (using old "full/hybrid/standalone" terminology, outdated structures)
   </action>
 
 <action>Based on their responses and your analysis from step 1, identify improvement opportunities:
 
 Organize by priority and user goals:
 
-- CRITICAL issues blocking functionality
-- IMPORTANT improvements enhancing user experience
-- NICE-TO-HAVE enhancements for polish
+- **CRITICAL issues blocking functionality** (broken paths, invalid references)
+- **PERSONA FIELD SEPARATION** (if found - this significantly improves LLM interpretation)
+- **IMPORTANT improvements enhancing user experience** (menu clarity, better workflows)
+- **NICE-TO-HAVE enhancements for polish** (better triggers, communication refinement)
 
 Present these conversationally, explaining WHY each matters and HOW it would help.
+
+If persona field separation issues found, explain the impact:
+"I found some behaviors in the communication_style field. When we separate these properly, the LLM will have much clearer understanding of the persona. Right now it's trying to interpret 'ensures stakeholders heard' as a verbal pattern, when it's actually an operating principle. Fixing this makes the agent more consistent and predictable."
 </action>
 
 <action>Collaborate on priorities:
@@ -128,18 +271,161 @@ Let the conversation flow naturally. Build a shared vision of what "better" look
 
 **If fixing broken references:**
 
-- Identify all broken paths
+- Identify all broken paths (workflow paths, sidecar file references)
 - Explain what each reference should point to
 - Verify new paths exist before updating
+- **For Expert agents:** Check both YAML references AND actual sidecar file existence
 - Update and confirm working
 
-**If refining persona/communication:**
+**If editing sidecar files (Expert agents only):**
+
+<critical>Sidecar files are as much a part of the agent as the YAML!</critical>
 
-- Review current persona definition
-- Discuss desired communication style with examples
-- Explore communication styles guide for patterns
-- Refine language to match intent
-- Test tone with example interactions
+Common sidecar editing scenarios:
+
+**Updating templates:**
+
+- Read current template content
+- Discuss what needs to change with user
+- Show before/after of template updates
+- Verify menu item references still work
+- Test template variables resolve correctly
+
+**Adding new sidecar files:**
+
+- Create the new file (template, doc, knowledge base)
+- Add menu item in YAML that references it (tmpl="path/to/new-file.md")
+- Verify the reference path is correct
+- Test the menu item loads the sidecar file
+
+**Removing unused sidecar files:**
+
+- Confirm file is truly unused (not referenced in YAML)
+- Ask user if safe to delete (might be there for future use)
+- Delete file if approved
+- Clean up any stale references
+
+**Reorganizing sidecar structure:**
+
+- Discuss better organization (e.g., group templates in subfolder)
+- Move files to new locations
+- Update ALL references in YAML to new paths
+- Verify all menu items still work
+
+**Updating knowledge base files (.csv, .json, .yaml in sidecar):**
+
+- Understand what knowledge the file contains
+- Discuss what needs updating
+- Edit the knowledge file directly
+- Verify format is still valid
+- No YAML changes needed (data file just gets loaded)
+
+**If refining persona/communication (MOST COMMON IMPROVEMENT NEEDED):**
+
+<critical>Persona field separation is the #1 quality issue. Follow this pattern EXACTLY:</critical>
+
+**Step 1: Diagnose Current Communication Style**
+
+- Read current communication_style field word by word
+- Identify ANY content that isn't pure verbal patterns
+- Use red flag words as detection:
+  - "ensures", "makes sure", "always", "never" → Behaviors (belongs in principles)
+  - "experienced", "expert who", "senior", "seasoned" → Identity descriptors (belongs in role/identity)
+  - "believes in", "focused on", "committed to" → Philosophy (belongs in principles)
+  - "who does X", "that does Y" → Behavioral descriptions (belongs in role or principles)
+
+Example diagnosis:
+
+```yaml
+# CURRENT (problematic)
+communication_style: 'Experienced analyst who uses systematic approaches and ensures all stakeholders are heard'
+# IDENTIFIED ISSUES:
+# - "Experienced analyst" → identity descriptor
+# - "who uses systematic approaches" → behavioral description
+# - "ensures all stakeholders are heard" → operating principle
+# ONLY THIS IS STYLE: [nothing! Need to find the actual verbal pattern]
+```
+
+**Step 2: Extract Non-Style Content to Proper Fields**
+
+- Create a working copy with sections:
+  - ROLE (capabilities/skills)
+  - IDENTITY (background/context)
+  - PURE STYLE (verbal patterns only)
+  - PRINCIPLES (beliefs/behaviors)
+
+- Move identified content to proper sections:
+  ```yaml
+  # ROLE: "Strategic analyst"
+  # IDENTITY: "Experienced analyst who uses systematic approaches"
+  # PURE STYLE: [need to discover - interview user about HOW they talk]
+  # PRINCIPLES:
+  #   - "Ensure all stakeholder voices heard"
+  #   - "Use systematic, structured approaches"
+  ```
+
+**Step 3: Discover the TRUE Communication Style**
+Since style was buried under behaviors, interview the user:
+
+- "How should this agent SOUND when talking?"
+- "What verbal quirks or patterns make them distinctive?"
+- "Are they formal? Casual? Energetic? Measured?"
+- "Any metaphors or imagery that capture their voice?"
+
+Then explore {communication_presets} together:
+
+- Show relevant categories (Professional, Creative, Analytical, etc.)
+- Read examples of pure styles
+- Discuss which resonates with agent's essence
+
+**Step 4: Craft Pure Communication Style**
+Write 1-2 sentences focused ONLY on verbal patterns:
+
+Good examples from reference agents:
+
+- "Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge" (Mary/analyst)
+- "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable" (Amelia/dev)
+- "Asks 'WHY?' relentlessly like a detective on a case" (John/pm)
+- "Poetic drama and flair with every turn of a phrase" (commit-poet)
+
+Bad example (what we're fixing):
+
+- "Experienced who ensures quality and uses best practices" ← ALL behaviors, NO style!
+
+**Step 5: Show Before/After With Full Context**
+Present the complete transformation:
+
+```yaml
+# BEFORE
+persona:
+  role: "Analyst"
+  communication_style: "Experienced analyst who uses systematic approaches and ensures all stakeholders are heard"
+
+# AFTER
+persona:
+  role: "Strategic Business Analyst + Requirements Expert"
+  identity: "Senior analyst with 8+ years connecting market insights to strategy and translating complex problems into clear requirements"
+  communication_style: "Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments."
+  principles:
+    - "Ensure all stakeholder voices heard"
+    - "Use systematic, structured approaches to analysis"
+    - "Ground findings in evidence, not assumptions"
+```
+
+**Step 6: Validate Against Standards**
+
+- Communication style has ZERO red flag words
+- Communication style describes HOW they talk, not WHAT they do
+- Compare against {communication_presets} - similarly pure?
+- Compare against reference agents - similar quality?
+- Read it aloud - does it sound like a voice description?
+
+**Step 7: Confirm With User**
+
+- Explain WHAT changed and WHY each move happened
+- Read the new communication style dramatically to demonstrate the voice
+- Ask: "Does this capture how you want them to sound?"
+- Refine based on feedback
 
 **If updating activation:**
 
@@ -164,12 +450,73 @@ Let the conversation flow naturally. Build a shared vision of what "better" look
 - Propose enhanced logic based on agent architecture patterns
 - Ensure handlers properly invoke workflows
 
-**If optimizing agent type:**
+**If optimizing agent type or migrating from legacy terminology:**
+
+<critical>Legacy agents may use outdated "full/hybrid/standalone" terminology. Migrate to Simple/Expert/Module:</critical>
+
+**Understanding the Modern Types:**
+
+- **Simple** = Self-contained in single .agent.yaml file
+  - NOT capability-limited! Can be as powerful as any agent
+  - Architecture choice: everything in one file
+  - Example: commit-poet (reference_simple_agent)
+
+- **Expert** = Includes sidecar files (templates, docs, knowledge bases)
+  - Folder structure with .agent.yaml + additional files
+  - Sidecar files referenced in menu items or prompts
+  - Example: journal-keeper (reference_expert_agent)
+
+- **Module** = Designed for BMAD ecosystem integration
+  - Integrated with specific module workflows (BMM, BMGD, CIS, etc.)
+  - Coordinates with other module agents
+  - Included in module's default bundle
+  - This is design INTENT, not capability limitation
+  - Examples: security-engineer, dev, analyst (reference_module_agents)
+
+**Migration Pattern from Legacy Types:**
+
+If agent uses "full/hybrid/standalone" terminology:
+
+1. **Identify current structure:**
+   - Single file? → Probably Simple
+   - Has sidecar files? → Probably Expert
+   - Part of module ecosystem? → Probably Module
+   - Multiple could apply? → Choose based on PRIMARY characteristic
+
+2. **Update any references in comments/docs:**
+   - Change "full agent" → Simple or Module (depending on context)
+   - Change "hybrid agent" → Usually Simple or Expert
+   - Change "standalone agent" → Usually Simple
 
-- Discuss whether current type fits use case
-- Explain characteristics of full/hybrid/standalone
-- If converting, guide through structural changes
-- Ensure all pieces align with new type
+3. **Verify type choice:**
+   - Read {understanding_agent_types} together
+   - Compare against reference agents
+   - Confirm structure matches chosen type
+
+4. **Update validation checklist expectations** based on new type
+
+**If genuinely converting between types:**
+
+Simple → Expert (adding sidecar files):
+
+- Create folder with agent name
+- Move .agent.yaml into folder
+- Add sidecar files (templates, docs, etc.)
+- Update menu items to reference sidecar files
+- Test all references work
+
+Expert → Simple (consolidating):
+
+- Inline sidecar content into YAML (or remove if unused)
+- Move .agent.yaml out of folder
+- Update any menu references
+- Delete sidecar folder after verification
+
+Module ↔ Others:
+
+- Module is about design intent, not structure
+- Can be Simple OR Expert structurally
+- Change is about integration ecosystem, not file structure
   </action>
 
 <action>Throughout improvements, educate when helpful:
@@ -199,14 +546,28 @@ Connect improvements to broader BMAD principles without being preachy.
 Don't just check boxes - explain what you're validating and why it matters:
 
 - "Let me verify all the workflow paths resolve correctly..."
+- **"If Expert agent: Checking all sidecar file references..."**
 - "Checking that the activation flow works smoothly..."
 - "Making sure menu handlers are wired up properly..."
 - "Validating config loading is robust..."
+- **"CRITICAL: Checking persona field separation - ensuring communication_style is pure..."**
+
+**For Expert Agents - Sidecar File Validation:**
+
+Walk through each sidecar reference:
+
+- "Your menu item 'daily-journal' references 'templates/daily.md'... checking... ✓ exists!"
+- "Menu item 'breakthrough' references 'templates/breakthrough.md'... checking... ✓ exists!"
+- Check for orphaned sidecar files not referenced anywhere
+- If found: "I noticed 'old-template.md' isn't referenced in any menu items. Should we keep it?"
+- Verify sidecar file formats (YAML is valid, CSV has headers, etc.)
   </action>
 
-<action>Load validation checklist: {installed_path}/checklist.md</action>
+<action>Load validation checklist: {validation}</action>
 <action>Check all items from checklist systematically</action>
 
+<note>The validation checklist is shared between create-agent and edit-agent workflows to ensure consistent quality standards. Any agent (whether newly created or edited) is validated against the same comprehensive criteria.</note>
+
 <check if="validation_issues_found">
   <action>Present issues conversationally:
 
@@ -229,13 +590,16 @@ Propose fixes immediately:
 
 "Excellent! Everything validates cleanly:
 
-- All paths resolve correctly
-- Activation flow is solid
-- Menu structure is clear
-- Handlers work properly
-- Config loading is robust
+- ✓ Persona fields properly separated (communication_style is pure!)
+- ✓ All paths resolve correctly
+- ✓ **[If Expert agent: All sidecar file references valid - 5 sidecar files, all referenced correctly!]**
+- ✓ Activation flow is solid
+- ✓ Menu structure is clear
+- ✓ Handlers work properly
+- ✓ Config loading is robust
+- ✓ Agent type matches structure (Simple/Expert/Module)
 
-Your agent is in great shape."
+Your agent meets all BMAD quality standards. Great work!"
 </action>
 </check>
 

package/src/modules/bmb/workflows/edit-agent/workflow.yaml

@@ -4,30 +4,44 @@ description: "Edit existing BMAD agents while following all best practices and c
 author: "BMad"
 
 # Critical variables load from config_source
-config_source: "{project-root}/bmad/bmb/config.yaml"
+config_source: "{project-root}/{bmad_folder}/bmb/config.yaml"
 communication_language: "{config_source}:communication_language"
 user_name: "{config_source}:user_name"
 
 # Required Data Files - Critical for understanding agent conventions
-agent_types: "{project-root}/bmad/bmb/workflows/create-agent/agent-types.md"
-agent_architecture: "{project-root}/bmad/bmb/workflows/create-agent/agent-architecture.md"
-agent_commands: "{project-root}/bmad/bmb/workflows/create-agent/agent-command-patterns.md"
-communication_styles: "{project-root}/bmad/bmb/workflows/create-agent/communication-styles.md"
+
+# Core Concepts
+understanding_agent_types: "{project-root}/{bmad_folder}/bmb/docs/understanding-agent-types.md"
+agent_compilation: "{project-root}/{bmad_folder}/bmb/docs/agent-compilation.md"
+
+# Architecture Guides (Simple, Expert, Module)
+simple_architecture: "{project-root}/{bmad_folder}/bmb/docs/simple-agent-architecture.md"
+expert_architecture: "{project-root}/{bmad_folder}/bmb/docs/expert-agent-architecture.md"
+module_architecture: "{project-root}/{bmad_folder}/bmb/docs/module-agent-architecture.md"
+
+# Design Patterns
+menu_patterns: "{project-root}/{bmad_folder}/bmb/docs/agent-menu-patterns.md"
+communication_presets: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/communication-presets.csv"
+brainstorm_context: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/brainstorm-context.md"
 
 # Workflow execution engine reference
-workflow_execution_engine: "{project-root}/bmad/core/tasks/workflow.xml"
+workflow_execution_engine: "{project-root}/{bmad_folder}/core/tasks/workflow.xml"
+
+# Reference Agents - Clean implementations showing best practices
+reference_agents: "{project-root}/{bmad_folder}/bmb/reference/agents/"
+reference_simple_agent: "{reference_agents}/simple-examples/commit-poet.agent.yaml"
+reference_expert_agent: "{reference_agents}/expert-examples/journal-keeper/journal-keeper.agent.yaml"
+reference_module_agents: "{reference_agents}/module-examples/"
 
-# Optional docs that can be used to understand the target agent
-recommended_inputs:
-  - target_agent: "Path to the agent.yaml or agent.md file to edit"
-  - example_agents: "{project-root}/bmad/bmm/agents/"
-  - agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.xml"
+# BMM Agents - Examples of distinct communication voices
+bmm_agents: "{project-root}/{bmad_folder}/bmm/agents/"
 
 # Module path and component files
-installed_path: "{project-root}/bmad/bmb/workflows/edit-agent"
+installed_path: "{project-root}/{bmad_folder}/bmb/workflows/edit-agent"
 template: false # This is an action workflow - no template needed
 instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/checklist.md"
+# Shared validation checklist (canonical location in create-agent folder)
+validation: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/agent-validation-checklist.md"
 
 standalone: true
 

package/src/modules/bmb/workflows/edit-module/README.md

@@ -106,7 +106,7 @@ Modules can share workflows:
 
 ```yaml
 # In agent menu item:
-workflow: '{project-root}/bmad/other-module/workflows/shared-workflow/workflow.yaml'
+workflow: '{project-root}/{bmad_folder}/other-module/workflows/shared-workflow/workflow.yaml'
 ```
 
 Common patterns:
@@ -151,7 +151,7 @@ Changes are reviewed and approved by you before being applied.
 - Can configure web bundles
 - Are the development source of truth
 
-**Installed modules** (in bmad/):
+**Installed modules** (in {bmad_folder}/):
 
 - Are deployed to target projects
 - Use config.yaml for user customization

package/src/modules/bmb/workflows/edit-module/checklist.md

@@ -5,7 +5,7 @@ Use this checklist to validate module edits meet BMAD Core standards.
 ## Module Structure Validation
 
 - [ ] Module has clear 3-letter code (bmm, bmb, cis, etc.)
-- [ ] Module is in correct location (src/modules/ for source, bmad/ for installed)
+- [ ] Module is in correct location (src/modules/ for source, {bmad_folder}/ for installed)
 - [ ] agents/ directory exists
 - [ ] workflows/ directory exists
 - [ ] config.yaml exists in module root
@@ -128,7 +128,7 @@ Use this checklist to validate module edits meet BMAD Core standards.
 
 - [ ] Web bundles configured in workflow.yaml files
 - [ ] All referenced files included in web_bundle_files
-- [ ] Paths are bmad/-relative (not project-root)
+- [ ] Paths are {bmad_folder}/-relative (not project-root)
 - [ ] No config_source references in web bundles
 - [ ] Invoked workflows included in dependencies
 

package/src/modules/bmb/workflows/edit-module/instructions.md

@@ -1,7 +1,7 @@
 # Edit Module - Module Editor Instructions
 
-<critical>The workflow execution engine is governed by: {project-root}/bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/bmad/bmb/workflows/edit-module/workflow.yaml</critical>
+<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
+<critical>You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/edit-module/workflow.yaml</critical>
 <critical>This workflow uses ADAPTIVE FACILITATION - adjust your communication based on context and user needs</critical>
 <critical>The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them</critical>
 <critical>Communicate all responses in {communication_language}</critical>
@@ -9,7 +9,7 @@
 <workflow>
 
 <step n="1" goal="Load and deeply understand the target module">
-<ask>What is the path to the module you want to edit? (provide path to module directory like bmad/bmm/ or src/modules/bmm/)</ask>
+<ask>What is the path to the module you want to edit? (provide path to module directory like {bmad_folder}/bmm/ or src/modules/bmm/)</ask>
 
 <action>Load the module directory structure completely:
 
@@ -123,7 +123,9 @@ Let the conversation flow naturally. Build a shared vision of what "better" look
 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
+   - Provide examples from reference modules: {bmm_module_dir}, {bmb_module_dir}, {cis_module_dir}
+   - Reference agents from: {existing_agents_dir}
+   - Reference workflows from: {existing_workflows_dir}
    - Reference the structure guide's patterns naturally
 
 3. **Collaborate on the approach**
@@ -185,7 +187,7 @@ Let the conversation flow naturally. Build a shared vision of what "better" look
 **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
+- Show how to reference workflows properly: {project-root}/{bmad_folder}/{{module}}/workflows/{{workflow}}/workflow.yaml
 - Document the integration in README
 - Ensure dependencies are clear
 - Consider adding example usage