mirror of
https://github.com/bmadcode/BMAD-METHOD.git
synced 2025-12-29 16:14:59 +00:00
224af173ef
## 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.