mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
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
@@ -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/
|
||||
|
||||
Reference in New Issue
Block a user