9.6 KiB

Raw Blame History

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

Load and analyze target agent - Provide path to agent file
Discover improvement goals collaboratively - Discuss what needs improvement and why
Facilitate improvements iteratively - Make changes collaboratively with approval
Validate all changes holistically - Comprehensive validation checklist
Review improvements and guide next steps - Summary and guidance

Common Editing Scenarios

The workflow handles these common improvement needs:

Fix persona field separation - Extract behaviors from communication_style to principles (MOST COMMON)
Fix critical issues - Address broken references, syntax errors
Edit sidecar files - Update templates, knowledge bases, docs (Expert agents)
Add/fix standard config - Ensure config loading and variable usage
Refine persona - Improve role, identity, communication style, principles
Update activation - Modify activation steps and greeting
Manage menu items - Add, remove, or reorganize commands
Update workflow references - Fix paths, add new workflows
Enhance menu handlers - Improve handler logic
Improve command triggers - Refine asterisk commands
Migrate agent type - Convert from legacy full/hybrid/standalone to Simple/Expert/Module
Add new capabilities - Add menu items, workflows, features
Remove bloat - Delete unused commands, redundant instructions, orphaned sidecar files
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:

communication_style: 'Experienced analyst who ensures all stakeholders are heard and uses systematic approaches'

RIGHT:

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

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.

9.6 KiB Raw Blame History