# Edit Agent Workflow

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 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 modern agent architecture (Simple/Expert/Module)
- Migrating from legacy patterns (full/hybrid/standalone)

## When to Use

Use this workflow when you need to:

- **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
- 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 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. **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 comprehensive agent documentation:

**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). 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 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

- **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

## Example Usage

**Scenario 1: Fix persona field separation (most common)**

```
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 → 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:

```
/bmad:bmb:agents:bmad-builder
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.