feat: Comprehensive edit-agent workflow enhancement with Expert agent support and unified validation
## Overview Major enhancement to edit-agent workflow to match create-agent quality standards, plus critical addition of Expert agent sidecar file support and consolidation of validation checklists into single source of truth. ## 1. edit-agent Workflow Comprehensive Enhancement ### Documentation Reference Updates (workflow.yaml) **Fixed all broken references** - replaced deleted docs with new comprehensive guides: - ❌ Removed: agent-types.md, agent-architecture.md, agent-command-patterns.md, communication-styles.md - ✅ Added structured references: * Core Concepts: understanding_agent_types, agent_compilation * Architecture Guides: simple_architecture, expert_architecture, module_architecture * Design Patterns: menu_patterns, communication_presets, brainstorm_context * Reference Agents: commit-poet, journal-keeper, module examples, BMM agents ### Critical Persona Field Guidance Added (instructions.md +59 lines) **The #1 issue in legacy agents** - comprehensive guidance on persona field separation: - Explains how LLMs interpret each field: * role → "What knowledge/skills/capabilities do I possess?" * identity → "What background/experience/context shapes my responses?" * communication_style → "What verbal patterns/word choice do I use?" * principles → "What beliefs/philosophy drive my choices?" - BEFORE/AFTER examples showing common mistakes - Red flag word detection guide (ensures, experienced, believes in, etc.) - Pure communication style examples from reference agents ### Enhanced Step 1: Analysis (instructions.md +57 lines) - References all new comprehensive documentation - **CRITICAL: Persona field separation analysis** * Checks for behaviors/role/identity mixed into communication_style * Compares against communication_presets for purity * Compares against reference agents for quality - Warm, conversational feedback explaining issues found ### Massive Step 3 Enhancement: Communication Style Refinement (+122 lines) **7-step prescriptive pattern for fixing the #1 quality issue:** 1. Diagnose Current Communication Style - red flag word detection 2. Extract Non-Style Content - working copy methodology 3. Discover TRUE Communication Style - interview questions + preset exploration 4. Craft Pure Communication Style - good/bad examples from references 5. Show Before/After With Full Context - complete transformation 6. Validate Against Standards - zero red flags, compare to presets/references 7. Confirm With User - explain changes, read dramatically, refine Examples from actual reference agents: - "Treats analysis like a treasure hunt - excited by every clue" (Mary/analyst) - "Ultra-succinct. Speaks in file paths and AC IDs" (Amelia/dev) - "Poetic drama and flair with every turn of a phrase" (commit-poet) ### Legacy Type Migration Pattern (+42 lines) **Comprehensive guide for full/hybrid/standalone → Simple/Expert/Module migration:** - Clear explanations of modern types (architecture, NOT capability) - Migration patterns with decision tree - Structural conversion guides (Simple ↔ Expert) - Module = design intent clarification ### Enhanced Validation (Step 4) - Persona field separation validation emphasized - Updated success message with all quality standards - Comprehensive checklist validation ### Complete README Documentation (200 lines created) - Purpose emphasizing persona field separation as #1 issue - 14 common editing scenarios (persona separation listed FIRST) - Complete doc reference listing by category - Dedicated "Critical: Persona Field Separation" section - Red flag words guide - 3 detailed usage scenarios - Quality standards checklist ## 2. Expert Agent Sidecar File Support (NEW) ### Step 1: Smart Path Detection and Loading (+35 lines) **Automatically detects and loads based on path type:** ```yaml If path is .agent.yaml → Simple Agent (load single file) If path is folder → Expert Agent: - Load .agent.yaml from inside folder - Load ALL sidecar files (*.md, *.txt, *.csv, *.json, *.yaml) - Create inventory for reference - Present: "Loaded agent.yaml + 5 sidecar files: [list]" ``` **Sidecar analysis:** - Maps which menu items reference which sidecar files (tmpl="path", data="path") - Checks if all sidecar references actually exist - Identifies unused/orphaned sidecar files - Assesses sidecar organization **Warm expert agent feedback:** "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." ### Step 3: Sidecar Editing Patterns (+47 lines) **5 complete sidecar editing scenarios:** 1. **Updating templates** - Edit content, verify references work, test variables 2. **Adding new sidecar files** - Create file + add menu item with reference 3. **Removing unused sidecar files** - Confirm unused, ask to delete, clean references 4. **Reorganizing sidecar structure** - Move files, update ALL YAML references 5. **Updating knowledge base files** - Edit .csv/.json/.yaml data directly **Critical mindset:** "Sidecar files are as much a part of the agent as the YAML!" ### Step 4: Sidecar Validation (+16 lines) **Conversational validation:** - "Your menu item 'daily-journal' references 'templates/daily.md'... checking... ✓ exists!" - Check for orphaned files not referenced anywhere - Verify sidecar file formats (YAML parses, CSV has headers, markdown well-formed) - Success message: "✓ All sidecar file references valid - 5 sidecar files, all referenced correctly!" ### README Updates - "What You'll Need" distinguishes Simple vs Expert paths - Scenario 2b: Complete Expert agent editing example (journal-keeper template update) - Updated common scenarios list ## 3. Unified Validation Checklist (Single Source of Truth) ### Problem Solved - create-agent had outdated checklist (62 lines, no persona field separation) - edit-agent had enhanced checklist (112 lines, with our improvements) - Risk of drift and inconsistency between workflows ### Solution: agent-validation-checklist.md (160 lines) **Canonical location:** `/src/modules/bmb/workflows/create-agent/` **Comprehensive coverage combining best of both:** - YAML structure validation - **Persona field separation** (field separation check, purity check, quality benchmarking) - Menu validation (including sidecar file path validation) - Type-specific validation (Simple/Expert/Module) - Compilation validation - Common issues and fixes section **Key sections:** - Persona Validation (CRITICAL - #1 Quality Issue) * Field Separation Check (what belongs where) * Communication Style Purity Check (red flag word detection) * Quality Benchmarking (compare to presets and references) - Expert Agent validation (9 sidecar-specific checks) - Module Agent validation (design intent verification) - Common Issues and Fixes (real examples with solutions) ### References Updated **create-agent/workflow.yaml:** ```yaml validation: "{installed_path}/agent-validation-checklist.md" ``` **edit-agent/workflow.yaml:** ```yaml # Shared validation checklist (canonical location in create-agent folder) validation: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/agent-validation-checklist.md" ``` **edit-agent/instructions.md:** ```xml <note>The validation checklist is shared between create-agent and edit-agent workflows to ensure consistent quality standards.</note> ``` ### Files Changed - ✅ Created: agent-validation-checklist.md (160 lines) - ❌ Deleted: create-agent/checklist.md (62 lines) - ❌ Deleted: edit-agent/checklist.md (112 lines) - Updated: Both workflow.yaml files to reference unified checklist ## Statistics **Overall changes:** 6 files changed, +553 insertions, -264 deletions **edit-agent enhancements:** - instructions.md: +396 lines (comprehensive guidance) - README.md: +213 lines (complete documentation) - workflow.yaml: +32 lines (proper doc references) **Validation unification:** - Net result: Better quality, less duplication, easier maintenance - Single source of truth for all agent validation ## Impact ### For Users Editing Agents - Automatically detects and handles Expert agents with sidecar files - Clear guidance on fixing #1 issue (persona field separation) - 7-step prescriptive pattern for communication style refinement - Warm, educational feedback throughout - Validates against same standards as create-agent ### For Agent Quality - Both create and edit workflows use same validation standards - Persona field separation gets proper attention - Expert agent sidecar files treated as first-class citizens - Legacy agents can be migrated to modern standards - All agents validated against reference implementations ### For Maintenance - ONE checklist to maintain instead of two - Consistent quality standards across workflows - Documentation properly linked to new comprehensive guides - No risk of checklist drift This brings edit-agent to the same quality level as create-agent while adding critical Expert agent support and establishing single source of truth for validation.
This commit is contained in:
Brian Madison
parent
054b031c1d
commit
224af173ef
|
|
@ -0,0 +1,174 @@
|
|||
# BMAD Agent Validation Checklist
|
||||
|
||||
Use this checklist to validate agents meet BMAD quality standards, whether creating new agents or editing existing ones.
|
||||
|
||||
## YAML Structure Validation (Source Files)
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`
|
||||
- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`)
|
||||
- [ ] `agent.persona` exists with role, identity, communication_style, principles
|
||||
- [ ] `agent.menu` exists with at least one item
|
||||
- [ ] Filename is kebab-case and ends with `.agent.yaml`
|
||||
|
||||
## Agent Structure Validation
|
||||
|
||||
- [ ] Agent file format is valid (.agent.yaml for source)
|
||||
- [ ] Agent type matches structure: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration)
|
||||
- [ ] File naming follows convention: `{agent-name}.agent.yaml`
|
||||
- [ ] If Expert: folder structure with .agent.yaml + sidecar files
|
||||
- [ ] If Module: includes header comment explaining WHY Module Agent (design intent)
|
||||
|
||||
## Persona Validation (CRITICAL - #1 Quality Issue)
|
||||
|
||||
**Field Separation Check:**
|
||||
|
||||
- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
|
||||
- [ ] **identity** contains ONLY background/experience/context (who agent is)
|
||||
- [ ] **communication_style** contains ONLY verbal patterns - NO behaviors, NO role statements, NO principles
|
||||
- [ ] **principles** contains operating philosophy and behavioral guidelines
|
||||
|
||||
**Communication Style Purity Check:**
|
||||
|
||||
- [ ] Communication style does NOT contain red flag words: "ensures", "makes sure", "always", "never"
|
||||
- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
|
||||
- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to"
|
||||
- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y"
|
||||
- [ ] Communication style is 1-2 sentences describing HOW they talk (word choice, quirks, verbal patterns)
|
||||
|
||||
**Quality Benchmarking:**
|
||||
|
||||
- [ ] Compare communication style against {communication_presets} - similarly pure?
|
||||
- [ ] Compare against reference agents (commit-poet, journal-keeper, BMM agents) - similar quality?
|
||||
- [ ] Read communication style aloud - does it sound like describing someone's voice/speech pattern?
|
||||
|
||||
## Menu Validation
|
||||
|
||||
- [ ] All menu items have `trigger` field
|
||||
- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation)
|
||||
- [ ] Each item has `description` field
|
||||
- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action`
|
||||
- [ ] Workflow paths are correct (if workflow attribute present)
|
||||
- [ ] Workflow paths use `{project-root}` variable for portability
|
||||
- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)**
|
||||
- [ ] No duplicate triggers within same agent
|
||||
- [ ] Menu items are in logical order
|
||||
|
||||
## Prompts Validation (if present)
|
||||
|
||||
- [ ] Each prompt has `id` field
|
||||
- [ ] Each prompt has `content` field
|
||||
- [ ] Prompt IDs are unique within agent
|
||||
- [ ] If using `action="#prompt-id"` in menu, corresponding prompt exists
|
||||
|
||||
## Critical Actions Validation (if present)
|
||||
|
||||
- [ ] Critical actions array contains non-empty strings
|
||||
- [ ] Critical actions describe steps that MUST happen during activation
|
||||
- [ ] No placeholder text in critical actions
|
||||
|
||||
## Type-Specific Validation
|
||||
|
||||
### Simple Agent (Self-Contained)
|
||||
|
||||
- [ ] Single .agent.yaml file with complete agent definition
|
||||
- [ ] No sidecar files (all content in YAML)
|
||||
- [ ] Not capability-limited - can be as powerful as Expert or Module
|
||||
- [ ] Compare against reference: commit-poet.agent.yaml
|
||||
|
||||
### Expert Agent (With Sidecar Files)
|
||||
|
||||
- [ ] Folder structure: .agent.yaml + sidecar files
|
||||
- [ ] Sidecar files properly referenced in menu items or prompts (tmpl="path", data="path")
|
||||
- [ ] Folder name matches agent purpose
|
||||
- [ ] **All sidecar references in YAML resolve to actual files**
|
||||
- [ ] **All sidecar files are actually used (no orphaned/unused files, unless intentional for future use)**
|
||||
- [ ] Sidecar files are valid format (YAML parses, CSV has headers, markdown is well-formed)
|
||||
- [ ] Sidecar file paths use relative paths from agent folder
|
||||
- [ ] Templates contain valid template variables if applicable
|
||||
- [ ] Knowledge base files contain current/accurate information
|
||||
- [ ] Compare against reference: journal-keeper (Expert example)
|
||||
|
||||
### Module Agent (Ecosystem Integration)
|
||||
|
||||
- [ ] Designed FOR specific module (BMM, BMGD, CIS, etc.)
|
||||
- [ ] Integrates with module workflows (referenced in menu items)
|
||||
- [ ] Coordinates with other module agents (if applicable)
|
||||
- [ ] Included in module's default bundle (if applicable)
|
||||
- [ ] Header comment explains WHY Module Agent (design intent, not just location)
|
||||
- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure)
|
||||
- [ ] Compare against references: security-engineer, dev, analyst (Module examples)
|
||||
|
||||
## Compilation Validation (Post-Build)
|
||||
|
||||
- [ ] Agent compiles without errors to .md format
|
||||
- [ ] Compiled file has proper frontmatter (name, description)
|
||||
- [ ] Compiled XML structure is valid
|
||||
- [ ] `<agent>` tag has id, name, title, icon attributes
|
||||
- [ ] `<activation>` section is present with proper steps
|
||||
- [ ] `<persona>` section compiled correctly
|
||||
- [ ] `<menu>` section includes both user items AND auto-injected *help/*exit
|
||||
- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action)
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.)
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Syntax is valid (YAML source, XML compiled)
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona alone
|
||||
- [ ] Agent name/title are descriptive and clear
|
||||
- [ ] Icon emoji is appropriate and represents agent purpose
|
||||
|
||||
## Reference Standards
|
||||
|
||||
Your agent should meet these quality standards:
|
||||
|
||||
✓ Persona fields properly separated (communication_style is pure verbal patterns)
|
||||
✓ Agent type matches structure (Simple/Expert/Module)
|
||||
✓ All workflow/sidecar paths resolve correctly
|
||||
✓ Menu structure is clear and logical
|
||||
✓ No legacy terminology (full/hybrid/standalone)
|
||||
✓ Comparable quality to reference agents (commit-poet, journal-keeper, BMM agents)
|
||||
✓ Communication style has ZERO red flag words
|
||||
✓ Compiles cleanly to XML without errors
|
||||
|
||||
## Common Issues and Fixes
|
||||
|
||||
### Issue: Communication Style Has Behaviors
|
||||
|
||||
**Problem:** "Experienced analyst who ensures all stakeholders are heard"
|
||||
**Fix:** Extract to proper fields:
|
||||
|
||||
- identity: "Senior analyst with 8+ years..."
|
||||
- communication_style: "Treats analysis like a treasure hunt"
|
||||
- principles: "Ensure all stakeholder voices heard"
|
||||
|
||||
### Issue: Broken Sidecar References (Expert agents)
|
||||
|
||||
**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist
|
||||
**Fix:** Either create the file or fix the path to point to actual file
|
||||
|
||||
### Issue: Using Legacy Type Names
|
||||
|
||||
**Problem:** Comments refer to "full agent" or "hybrid agent"
|
||||
**Fix:** Update to Simple/Expert/Module terminology
|
||||
|
||||
### Issue: Menu Triggers Start With Asterisk
|
||||
|
||||
**Problem:** `trigger: "*create"` in YAML
|
||||
**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"`
|
||||
|
||||
## Issues Found (Use for tracking)
|
||||
|
||||
### Critical Issues
|
||||
|
||||
<!-- List any issues that MUST be fixed before agent can function -->
|
||||
|
||||
### Warnings
|
||||
|
||||
<!-- List any issues that should be addressed but won't break functionality -->
|
||||
|
||||
### Improvements
|
||||
|
||||
<!-- List any optional enhancements that could improve the agent -->
|
||||
|
|
@ -1,62 +0,0 @@
|
|||
# Build Agent Validation Checklist (YAML Agents)
|
||||
|
||||
## Agent Structure Validation
|
||||
|
||||
### YAML Structure
|
||||
|
||||
- [ ] YAML parses without errors
|
||||
- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`, `module`
|
||||
- [ ] `agent.persona` exists with role, identity, communication_style, and principles
|
||||
- [ ] `agent.menu` exists with at least one item
|
||||
|
||||
### Core Components
|
||||
|
||||
- [ ] `metadata.id` points to final compiled path: `{bmad_folder}/{{module}}/agents/{{agent}}.md`
|
||||
- [ ] `metadata.module` matches the module folder (e.g., `bmm`, `bmb`, `cis`)
|
||||
- [ ] Principles are an array (preferred) or string with clear values
|
||||
|
||||
## Persona Completeness
|
||||
|
||||
- [ ] Role clearly defines primary expertise area (1–2 lines)
|
||||
- [ ] Identity includes relevant background and strengths (3–5 lines)
|
||||
- [ ] Communication style gives concrete guidance (3–5 lines)
|
||||
- [ ] Principles present and meaningful (no placeholders)
|
||||
|
||||
## Menu Validation
|
||||
|
||||
- [ ] Triggers do not start with `*` (auto-prefixed during build)
|
||||
- [ ] Each item has a `description`
|
||||
- [ ] Handlers use valid attributes (`workflow`, `exec`, `tmpl`, `data`, `action`)
|
||||
- [ ] Paths use `{project-root}` or valid variables
|
||||
- [ ] No duplicate triggers
|
||||
|
||||
## Optional Sections
|
||||
|
||||
- [ ] `prompts` defined when using `action: "#id"`
|
||||
- [ ] `critical_actions` present if custom activation steps are needed
|
||||
- [ ] Customize file (if created) located at `{project-root}/{bmad_folder}/_cfg/agents/{{module}}-{{agent}}.customize.yaml`
|
||||
|
||||
## Build Verification
|
||||
|
||||
- [ ] Run compile to build `.md`: `npm run install:bmad` → "Compile Agents" (or `bmad install` → Compile)
|
||||
- [ ] Confirm compiled file exists at `{project-root}/{bmad_folder}/{{module}}/agents/{{agent}}.md`
|
||||
|
||||
## Final Quality
|
||||
|
||||
- [ ] Filename is kebab-case and ends with `.agent.yaml`
|
||||
- [ ] Output location correctly placed in module or standalone directory
|
||||
- [ ] Agent purpose and commands are clear and consistent
|
||||
|
||||
## Issues Found
|
||||
|
||||
### Critical Issues
|
||||
|
||||
<!-- List any issues that MUST be fixed before agent can function -->
|
||||
|
||||
### Warnings
|
||||
|
||||
<!-- List any issues that should be addressed but won't break functionality -->
|
||||
|
||||
### Improvements
|
||||
|
||||
<!-- List any optional enhancements that could improve the agent -->
|
||||
|
|
@ -27,7 +27,7 @@ module_agent_examples: "{project-root}/src/modules/bmb/reference/agents/module-e
|
|||
installed_path: "{project-root}/{bmad_folder}/bmb/workflows/create-agent"
|
||||
template: false # This is an interactive workflow - no template needed
|
||||
instructions: "{installed_path}/instructions.md"
|
||||
validation: "{installed_path}/checklist.md"
|
||||
validation: "{installed_path}/agent-validation-checklist.md"
|
||||
|
||||
# Output configuration - YAML agents compiled to .md at install time
|
||||
# Module agents: Save to {bmad_folder}/{{target_module}}/agents/
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
|
||||
## Editing Options
|
||||
## Common Editing Scenarios
|
||||
|
||||
The workflow provides 12 focused editing options:
|
||||
The workflow handles these common improvement needs:
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
- **create-agent** - Create new agents from scratch
|
||||
- **edit-workflow** - Edit workflows referenced by agents
|
||||
- **audit-workflow** - Audit workflows for compliance
|
||||
|
||||
## 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 → 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.
|
||||
|
|
|
|||
|
|
@ -1,112 +0,0 @@
|
|||
# Edit Agent - Validation Checklist
|
||||
|
||||
Use this checklist to validate agent edits meet BMAD Core standards.
|
||||
|
||||
## Agent Structure Validation
|
||||
|
||||
- [ ] Agent file format is valid (YAML or markdown/XML)
|
||||
- [ ] Agent type is clearly identified (full, hybrid, standalone)
|
||||
- [ ] File naming follows convention: `{agent-name}.agent.yaml` or `{agent-name}.agent.md`
|
||||
|
||||
## Persona Validation
|
||||
|
||||
- [ ] Role is clearly defined and specific
|
||||
- [ ] Identity/purpose articulates what the agent does
|
||||
- [ ] Communication style is specified (if custom style desired)
|
||||
- [ ] Principles are listed and actionable (if applicable)
|
||||
|
||||
## Activation Validation
|
||||
|
||||
- [ ] Step 1: Loads persona from current agent file
|
||||
- [ ] Step 2: Loads config file (if agent needs user context)
|
||||
- [ ] Step 3: Sets user context variables (user_name, etc.)
|
||||
- [ ] Step 4: Displays greeting using user_name and shows menu
|
||||
- [ ] Step 5: WAITs for user input (doesn't auto-execute)
|
||||
- [ ] Step 6: Processes user selection (number or trigger text)
|
||||
- [ ] Step 7: Executes appropriate menu handler
|
||||
|
||||
## Menu Validation
|
||||
|
||||
- [ ] All menu items numbered sequentially
|
||||
- [ ] Each item has cmd attribute with asterisk trigger (*help, *create, etc.)
|
||||
- [ ] Workflow paths are correct (if workflow attribute present)
|
||||
- [ ] Help command is present (\*help)
|
||||
- [ ] Exit command is present (\*exit)
|
||||
- [ ] Menu items are in logical order
|
||||
|
||||
## Configuration Validation
|
||||
|
||||
- [ ] Config file path is correct for module
|
||||
- [ ] Config variables loaded in activation step 2
|
||||
- [ ] Error handling present if config fails to load
|
||||
- [ ] user_name used in greeting and communication
|
||||
- [ ] communication_language used for output
|
||||
- [ ] output_folder used for file outputs (if applicable)
|
||||
|
||||
## Menu Handler Validation
|
||||
|
||||
- [ ] menu-handlers section is present
|
||||
- [ ] Workflow handler loads {project-root}/{bmad_folder}/core/tasks/workflow.xml
|
||||
- [ ] Workflow handler passes yaml path as 'workflow-config' parameter
|
||||
- [ ] Handlers check for attributes (workflow, exec, tmpl, data, action)
|
||||
- [ ] Handler logic is complete and follows patterns
|
||||
|
||||
## Workflow Integration Validation
|
||||
|
||||
- [ ] All workflow paths exist and are correct
|
||||
- [ ] Workflow paths use {project-root} variable
|
||||
- [ ] Workflows are appropriate for agent's purpose
|
||||
- [ ] Workflow parameters are passed correctly
|
||||
|
||||
## Communication Validation
|
||||
|
||||
- [ ] Agent communicates in {communication_language}
|
||||
- [ ] Communication style matches persona
|
||||
- [ ] Error messages are clear and helpful
|
||||
- [ ] Confirmation messages for user actions
|
||||
|
||||
## Rules Validation
|
||||
|
||||
- [ ] Rules section defines agent behavior clearly
|
||||
- [ ] File loading rules are specified
|
||||
- [ ] Menu trigger format rules are clear
|
||||
- [ ] Communication rules align with persona
|
||||
|
||||
## Quality Checks
|
||||
|
||||
- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, etc.)
|
||||
- [ ] No broken references or missing files
|
||||
- [ ] Syntax is valid (YAML or XML)
|
||||
- [ ] Indentation is consistent
|
||||
- [ ] Agent purpose is clear from reading persona alone
|
||||
|
||||
## Type-Specific Validation
|
||||
|
||||
### Full Agent
|
||||
|
||||
- [ ] Has complete menu system with multiple items
|
||||
- [ ] Loads config file for user context
|
||||
- [ ] Supports multiple workflows
|
||||
- [ ] Session management is clear
|
||||
|
||||
### Hybrid Agent
|
||||
|
||||
- [ ] Simplified activation (may skip some steps)
|
||||
- [ ] Focused set of workflows
|
||||
- [ ] May or may not have menu
|
||||
- [ ] Config loading is appropriate
|
||||
|
||||
### Standalone Agent
|
||||
|
||||
- [ ] Single focused purpose
|
||||
- [ ] Minimal activation (1-3 steps)
|
||||
- [ ] No menu system
|
||||
- [ ] Direct execution pattern
|
||||
- [ ] May not need config file
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] Agent file has been saved
|
||||
- [ ] File path is in correct module directory
|
||||
- [ ] Agent is ready for testing
|
||||
- [ ] Documentation is updated (if needed)
|
||||
|
|
@ -6,42 +6,178 @@
|
|||
<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:
|
||||
|
||||
- Agent types guide: {agent_types}
|
||||
- Agent architecture: {agent_architecture}
|
||||
- Command patterns: {agent_commands}
|
||||
- Communication styles: {communication_styles}
|
||||
- Workflow execution engine: {workflow_execution_engine}
|
||||
**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:**
|
||||
|
||||
- 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):**
|
||||
|
||||
- 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
|
||||
<critical>Sidecar files are as much a part of the agent as the YAML!</critical>
|
||||
|
||||
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:**
|
||||
|
||||
- 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
|
||||
<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
|
||||
|
||||
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>
|
||||
|
||||
|
|
|
|||
|
|
@ -9,23 +9,39 @@ 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_folder}/bmb/workflows/create-agent/agent-types.md"
|
||||
agent_architecture: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/agent-architecture.md"
|
||||
agent_commands: "{project-root}/{bmad_folder}/bmb/workflows/create-agent/agent-command-patterns.md"
|
||||
communication_styles: "{project-root}/{bmad_folder}/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_folder}/core/tasks/workflow.xml"
|
||||
|
||||
# Reference examples and conventions
|
||||
example_agents_dir: "{project-root}/{bmad_folder}/bmm/agents/"
|
||||
agent_activation_rules: "{project-root}/src/utility/models/agent-activation-ide.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/"
|
||||
|
||||
# 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_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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue