bmad-method 6.0.0-alpha.10 → 6.0.0-alpha.12

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

@@ -1,105 +1,216 @@
 # Edit Agent Workflow
 
-Interactive workflow for editing existing BMAD Core agents while maintaining best practices and conventions.
+Interactive workflow for editing existing BMAD agents while maintaining best practices and modern standards.
 
 ## Purpose
 
 This workflow helps you refine and improve existing agents by:
 
-- Analyzing agents against BMAD Core best practices
+- Analyzing agents against BMAD best practices
+- **Fixing persona field separation issues** (the #1 quality problem)
 - Identifying issues and improvement opportunities
 - Providing guided editing for specific aspects
 - Validating changes against agent standards
-- Ensuring consistency with agent architecture
+- Ensuring consistency with modern agent architecture (Simple/Expert/Module)
+- Migrating from legacy patterns (full/hybrid/standalone)
 
 ## When to Use
 
 Use this workflow when you need to:
 
-- Fix issues in existing agents
+- **Fix persona field separation** (communication_style has behaviors mixed in)
+- Fix issues in existing agents (broken paths, invalid references)
 - Add new menu items or workflows
 - Improve agent persona or communication style
 - Update configuration handling
-- Convert between agent types (full/hybrid/standalone)
+- Migrate from legacy terminology (full/hybrid/standalone → Simple/Expert/Module)
+- Convert between agent types
 - Optimize agent structure and clarity
+- Update legacy agents to modern BMAD standards
 
 ## What You'll Need
 
-- Path to the agent file you want to edit (.yaml or .md)
-- Understanding of what changes you want to make
+- Path to the agent file or folder you want to edit:
+  - Simple agent: path to .agent.yaml file
+  - Expert agent: path to folder containing .agent.yaml and sidecar files
+- Understanding of what changes you want to make (or let the workflow analyze and suggest)
 - Access to the agent documentation (loaded automatically)
 
 ## Workflow Steps
 
 1. **Load and analyze target agent** - Provide path to agent file
-2. **Analyze against best practices** - Automatic audit of agent structure
-3. **Select editing focus** - Choose what aspect to edit
-4. **Load relevant documentation** - Auto-loads guides based on your choice
-5. **Perform edits** - Review and approve changes iteratively
-6. **Validate all changes** - Comprehensive validation checklist
-7. **Generate change summary** - Summary of improvements made
-
-## Editing Options
-
-The workflow provides 12 focused editing options:
-
-1. **Fix critical issues** - Address broken references, syntax errors
-2. **Add/fix standard config** - Ensure config loading and variable usage
-3. **Refine persona** - Improve role, communication style, principles
-4. **Update activation** - Modify activation steps and greeting
-5. **Manage menu items** - Add, remove, or reorganize commands
-6. **Update workflow references** - Fix paths, add new workflows
-7. **Enhance menu handlers** - Improve handler logic
-8. **Improve command triggers** - Refine asterisk commands
-9. **Optimize agent type** - Convert between full/hybrid/standalone
-10. **Add new capabilities** - Add menu items, workflows, features
-11. **Remove bloat** - Delete unused commands, redundant instructions
-12. **Full review and update** - Comprehensive improvements
+2. **Discover improvement goals collaboratively** - Discuss what needs improvement and why
+3. **Facilitate improvements iteratively** - Make changes collaboratively with approval
+4. **Validate all changes holistically** - Comprehensive validation checklist
+5. **Review improvements and guide next steps** - Summary and guidance
+
+## Common Editing Scenarios
+
+The workflow handles these common improvement needs:
+
+1. **Fix persona field separation** - Extract behaviors from communication_style to principles (MOST COMMON)
+2. **Fix critical issues** - Address broken references, syntax errors
+3. **Edit sidecar files** - Update templates, knowledge bases, docs (Expert agents)
+4. **Add/fix standard config** - Ensure config loading and variable usage
+5. **Refine persona** - Improve role, identity, communication style, principles
+6. **Update activation** - Modify activation steps and greeting
+7. **Manage menu items** - Add, remove, or reorganize commands
+8. **Update workflow references** - Fix paths, add new workflows
+9. **Enhance menu handlers** - Improve handler logic
+10. **Improve command triggers** - Refine asterisk commands
+11. **Migrate agent type** - Convert from legacy full/hybrid/standalone to Simple/Expert/Module
+12. **Add new capabilities** - Add menu items, workflows, features
+13. **Remove bloat** - Delete unused commands, redundant instructions, orphaned sidecar files
+14. **Full review and update** - Comprehensive improvements
+
+**Most agents need persona field separation fixes** - this is the #1 quality issue found in legacy agents.
 
 ## Agent Documentation Loaded
 
-This workflow automatically loads:
+This workflow automatically loads comprehensive agent documentation:
 
-- **Agent Types Guide** - Understanding full, hybrid, and standalone agents
-- **Agent Architecture** - Structure, activation, and menu patterns
-- **Command Patterns** - Menu handlers and command triggers
-- **Communication Styles** - Persona and communication guidance
-- **Workflow Execution Engine** - How agents execute workflows
+**Core Concepts:**
+
+- **Understanding Agent Types** - Simple, Expert, Module distinctions (architecture, not capability)
+- **Agent Compilation** - How YAML compiles to XML and what auto-injects
+
+**Architecture Guides:**
+
+- **Simple Agent Architecture** - Self-contained agents (NOT capability-limited!)
+- **Expert Agent Architecture** - Agents with sidecar files (templates, docs, knowledge)
+- **Module Agent Architecture** - Ecosystem-integrated agents (design intent)
+
+**Design Patterns:**
+
+- **Agent Menu Patterns** - Menu handlers, command structure, workflow integration
+- **Communication Presets** - 60 pure communication styles across 13 categories
+- **Brainstorm Context** - Creative ideation for persona development
+
+**Reference Implementations:**
+
+- **commit-poet** (Simple) - Shows Simple agents can be powerful and sophisticated
+- **journal-keeper** (Expert) - Shows sidecar structure with memories and patterns
+- **security-engineer** (Module) - Shows design intent and ecosystem integration
+- **All BMM agents** - Examples of distinct, memorable communication voices
+
+**Workflow Execution Engine** - How agents execute workflows
+
+## Critical: Persona Field Separation
+
+**THE #1 ISSUE** in legacy agents is persona field separation. The workflow checks for this automatically.
+
+### What Is Persona Field Separation?
+
+Each persona field serves a specific purpose that the LLM uses when activating:
+
+- **role** → "What knowledge, skills, and capabilities do I possess?"
+- **identity** → "What background, experience, and context shape my responses?"
+- **communication_style** → "What verbal patterns, word choice, quirks do I use?"
+- **principles** → "What beliefs and philosophy drive my choices?"
+
+### The Problem
+
+Many agents have behaviors/role/identity mixed into communication_style:
+
+**WRONG:**
+
+```yaml
+communication_style: 'Experienced analyst who ensures all stakeholders are heard and uses systematic approaches'
+```
+
+**RIGHT:**
+
+```yaml
+identity: 'Senior analyst with 8+ years connecting market insights to strategy'
+communication_style: 'Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge'
+principles:
+  - 'Ensure all stakeholder voices heard'
+  - 'Use systematic, structured approaches'
+```
+
+### Red Flag Words
+
+If communication_style contains these words, it needs fixing:
+
+- "ensures", "makes sure", "always", "never" → Behaviors (move to principles)
+- "experienced", "expert who", "senior" → Identity (move to identity/role)
+- "believes in", "focused on" → Philosophy (move to principles)
 
 ## Output
 
-The workflow modifies your agent file in place, maintaining the original format (YAML or markdown). Changes are reviewed and approved by you before being applied.
+The workflow modifies your agent file in place, maintaining the original format (YAML). Changes are reviewed and approved by you before being applied.
 
 ## Best Practices
 
 - **Start with analysis** - Let the workflow audit your agent first
+- **Check persona field separation FIRST** - This is the #1 issue in legacy agents
+- **Use reference agents as guides** - Compare against commit-poet, journal-keeper, BMM agents
 - **Focus your edits** - Choose specific aspects to improve
 - **Review each change** - Approve or modify proposed changes
-- **Validate thoroughly** - Use the validation step to catch issues
+- **Validate persona purity** - Communication_style should have ZERO red flag words
+- **Validate thoroughly** - Use the validation step to catch all issues
 - **Test after editing** - Invoke the edited agent to verify it works
 
 ## Tips
 
-- If you're unsure what needs improvement, choose option 12 (Full review)
-- For quick fixes, choose the specific option (like option 6 for workflow paths)
+- **Most common fix needed:** Persona field separation - communication_style has behaviors/role mixed in
+- If you're unsure what needs improvement, let the workflow analyze the agent first
+- For quick fixes, tell the workflow specifically what needs fixing
 - The workflow loads documentation automatically - you don't need to read it first
 - You can make multiple rounds of edits in one session
+- **Red flag words in communication_style:** "ensures", "makes sure", "experienced", "expert who", "believes in"
+- Compare your agent's communication_style against the presets CSV - should be similarly pure
 - Use the validation step to ensure you didn't miss anything
 
-## Related Workflows
+## Example Usage
 
-- **create-agent** - Create new agents from scratch
-- **edit-workflow** - Edit workflows referenced by agents
-- **audit-workflow** - Audit workflows for compliance
+**Scenario 1: Fix persona field separation (most common)**
 
-## Example Usage
+```
+User: Edit the analyst agent
+Workflow: Loads agent → Analyzes → Finds communication_style has "ensures stakeholders heard"
+          → Explains this is behavior, should be in principles
+          → Extracts behaviors to principles
+          → Crafts pure communication style: "Treats analysis like a treasure hunt"
+          → Validates → Done
+```
+
+**Scenario 2: Add new workflow**
 
 ```
 User: I want to add a new workflow to the PM agent
-Workflow: Analyzes agent → Loads it → You choose option 5 (manage menu items)
-          → Adds new menu item with workflow reference → Validates → Done
+Workflow: Analyzes agent → User describes what workflow to add
+          → Adds new menu item with workflow reference
+          → Validates all paths resolve → Done
+```
+
+**Scenario 2b: Edit Expert agent sidecar files**
+
+```
+User: Edit the journal-keeper agent - I want to update the daily journal template
+Workflow: Loads folder → Finds .agent.yaml + 3 sidecar templates + 1 knowledge file
+          → Analyzes → Loads daily.md template
+          → User describes changes to template
+          → Updates daily.md, shows before/after
+          → Validates menu item 'daily-journal' still references it correctly → Done
+```
+
+**Scenario 3: Migrate from legacy type**
+
+```
+User: This agent says it's a "full agent" - what does that mean now?
+Workflow: Explains Simple/Expert/Module types
+          → Identifies agent is actually Simple (single file)
+          → Updates any legacy terminology in comments
+          → Validates structure matches type → Done
 ```
 
+## Related Workflows
+
+- **create-agent** - Create new agents from scratch with proper field separation
+- **edit-workflow** - Edit workflows referenced by agents
+- **audit-workflow** - Audit workflows for compliance
+
 ## Activation
 
 Invoke via BMad Builder agent:
@@ -110,3 +221,19 @@ Then select: *edit-agent
 ```
 
 Or directly via workflow.xml with this workflow config.
+
+## Quality Standards
+
+After editing with this workflow, your agent will meet these quality standards:
+
+✓ Persona fields properly separated (communication_style is pure verbal patterns)
+✓ Agent type matches structure (Simple/Expert/Module)
+✓ All workflow paths resolve correctly
+✓ Activation flow is robust
+✓ Menu structure is clear and logical
+✓ Handlers properly invoke workflows
+✓ Config loading works correctly
+✓ No legacy terminology (full/hybrid/standalone)
+✓ Comparable quality to reference agents
+
+This workflow ensures your agents meet the same high standards as the reference implementations and recently enhanced BMM agents.