diff --git a/src/modules/bmb/workflows/create-agent/agent-validation-checklist.md b/src/modules/bmb/workflows/create-agent/agent-validation-checklist.md new file mode 100644 index 00000000..56ba23c1 --- /dev/null +++ b/src/modules/bmb/workflows/create-agent/agent-validation-checklist.md @@ -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 +- [ ] `` tag has id, name, title, icon attributes +- [ ] `` section is present with proper steps +- [ ] `` section compiled correctly +- [ ] `` 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 + + + +### Warnings + + + +### Improvements + + diff --git a/src/modules/bmb/workflows/create-agent/checklist.md b/src/modules/bmb/workflows/create-agent/checklist.md deleted file mode 100644 index 544ba1a5..00000000 --- a/src/modules/bmb/workflows/create-agent/checklist.md +++ /dev/null @@ -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 - - - -### Warnings - - - -### Improvements - - diff --git a/src/modules/bmb/workflows/create-agent/workflow.yaml b/src/modules/bmb/workflows/create-agent/workflow.yaml index 834c44ed..5710ac05 100644 --- a/src/modules/bmb/workflows/create-agent/workflow.yaml +++ b/src/modules/bmb/workflows/create-agent/workflow.yaml @@ -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/ diff --git a/src/modules/bmb/workflows/edit-agent/README.md b/src/modules/bmb/workflows/edit-agent/README.md index d1fd89b1..7b1b131f 100644 --- a/src/modules/bmb/workflows/edit-agent/README.md +++ b/src/modules/bmb/workflows/edit-agent/README.md @@ -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. diff --git a/src/modules/bmb/workflows/edit-agent/checklist.md b/src/modules/bmb/workflows/edit-agent/checklist.md deleted file mode 100644 index aeb5625b..00000000 --- a/src/modules/bmb/workflows/edit-agent/checklist.md +++ /dev/null @@ -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) diff --git a/src/modules/bmb/workflows/edit-agent/instructions.md b/src/modules/bmb/workflows/edit-agent/instructions.md index 2ea4a9a9..de5cdb6d 100644 --- a/src/modules/bmb/workflows/edit-agent/instructions.md +++ b/src/modules/bmb/workflows/edit-agent/instructions.md @@ -6,42 +6,178 @@ The goal is COLLABORATIVE IMPROVEMENT - work WITH the user, not FOR them Communicate all responses in {communication_language} +Understanding Agent Persona Fields - ESSENTIAL for Editing Agents Correctly + +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. + What is the path to the agent you want to edit? -Load the agent file from the provided path -Load ALL agent documentation to inform understanding: +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]" + 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} + 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 - + +**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** + 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." Does this match your understanding of what this agent should do? @@ -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) 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." 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 +Sidecar files are as much a part of the agent as the YAML! + +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):** + +Persona field separation is the #1 quality issue. Follow this pattern EXACTLY: + +**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 +Legacy agents may use outdated "full/hybrid/standalone" terminology. Migrate to Simple/Expert/Module: + +**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 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.) -Load validation checklist: {installed_path}/checklist.md +Load validation checklist: {validation} Check all items from checklist systematically +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. + 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!" diff --git a/src/modules/bmb/workflows/edit-agent/workflow.yaml b/src/modules/bmb/workflows/edit-agent/workflow.yaml index 11d68a09..499da63c 100644 --- a/src/modules/bmb/workflows/edit-agent/workflow.yaml +++ b/src/modules/bmb/workflows/edit-agent/workflow.yaml @@ -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