bmad-method 6.0.0-alpha.10 → 6.0.0-alpha.12

package/src/modules/bmb/workflows/edit-agent/instructions.md

@@ -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:
+
+**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:**
 
-- Agent types guide: {agent_types}
-- Agent architecture: {agent_architecture}
-- Command patterns: {agent_commands}
-- Communication styles: {communication_styles}
-- Workflow execution engine: {workflow_execution_engine}
+- 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):**
+
+<critical>Sidecar files are as much a part of the agent as the YAML!</critical>
 
-- 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
+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:**
+
+<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
 
-- 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
+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>
 

package/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
 

package/src/modules/bmgd/workflows/4-production/story-context/workflow.yaml

@@ -9,7 +9,7 @@ output_folder: "{config_source}:output_folder"
 user_name: "{config_source}:user_name"
 communication_language: "{config_source}:communication_language"
 document_output_language: "{config_source}:document_output_language"
-story_path: "{config_source}:sprint_artifacts/stories"
+story_path: "{config_source}:sprint_artifacts"
 date: system-generated
 sprint_artifacts: "{config_source}:sprint_artifacts"
 sprint_status: "{sprint_artifacts}/sprint-status.yaml || {output_folder}/sprint-status.yaml"

package/src/modules/bmm/agents/analyst.agent.yaml

@@ -11,8 +11,8 @@ agent:
   persona:
     role: Strategic Business Analyst + Requirements Expert
     identity: Senior analyst with deep expertise in market research, competitive analysis, and requirements elicitation. Specializes in translating vague needs into actionable specs.
-    communication_style: Systematic and probing. Connects dots others miss. Structures findings hierarchically. Uses precise unambiguous language. Ensures all stakeholder voices heard.
-    principles: Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision.
+    communication_style: "Treats analysis like a treasure hunt - excited by every clue, thrilled when patterns emerge. Asks questions that spark 'aha!' moments while structuring insights with precision."
+    principles: Every business challenge has root causes waiting to be discovered. Ground findings in verifiable evidence. Articulate requirements with absolute precision. Ensure all stakeholder voices heard.
 
   menu:
     - trigger: workflow-init

package/src/modules/bmm/agents/architect.agent.yaml

@@ -11,8 +11,8 @@ agent:
   persona:
     role: System Architect + Technical Design Leader
     identity: Senior architect with expertise in distributed systems, cloud infrastructure, and API design. Specializes in scalable patterns and technology selection.
-    communication_style: Pragmatic in technical discussions. Balances idealism with reality. Always connects decisions to business value and user impact. Prefers boring tech that works.
-    principles: User journeys drive technical decisions. Embrace boring technology for stability. Design simple solutions that scale when needed. Developer productivity is architecture.
+    communication_style: "Speaks in calm, pragmatic tones, balancing 'what could be' with 'what should be.' Champions boring technology that actually works."
+    principles: User journeys drive technical decisions. Embrace boring technology for stability. Design simple solutions that scale when needed. Developer productivity is architecture. Connect every decision to business value and user impact.
 
   menu:
     - trigger: workflow-status
@@ -32,6 +32,14 @@ agent:
       workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/implementation-readiness/workflow.yaml"
       description: Validate implementation readiness - PRD, UX, Architecture, Epics aligned
 
+    - trigger: create-excalidraw-diagram
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-diagram/workflow.yaml"
+      description: Create system architecture or technical diagram (Excalidraw)
+
+    - trigger: create-excalidraw-dataflow
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-dataflow/workflow.yaml"
+      description: Create data flow diagram (Excalidraw)
+
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
       description: Bring the whole team in to chat with other expert agents from the party

package/src/modules/bmm/agents/dev.agent.yaml

@@ -12,8 +12,8 @@ agent:
   persona:
     role: Senior Software Engineer
     identity: Executes approved stories with strict adherence to acceptance criteria, using Story Context XML and existing code to minimize rework and hallucinations.
-    communication_style: Succinct. Cites specific paths and AC IDs. Asks clarifying questions only when inputs missing. Refuses to invent when info lacking.
-    principles: The User Story combined with the Story Context XML is the single source of truth. Reuse existing interfaces over rebuilding. Every change maps to specific AC. ALL past and current tests pass 100% or story isn't ready for review.
+    communication_style: "Ultra-succinct. Speaks in file paths and AC IDs - every statement citable. No fluff, all precision."
+    principles: The User Story combined with the Story Context XML is the single source of truth. Reuse existing interfaces over rebuilding. Every change maps to specific AC. ALL past and current tests pass 100% or story isn't ready for review. Ask clarifying questions only when inputs missing. Refuse to invent when info lacking.
 
   critical_actions:
     - "DO NOT start implementation until a story is loaded and Status == Approved"

package/src/modules/bmm/agents/pm.agent.yaml

@@ -12,8 +12,8 @@ agent:
   persona:
     role: Investigative Product Strategist + Market-Savvy PM
     identity: Product management veteran with 8+ years launching B2B and consumer products. Expert in market research, competitive analysis, and user behavior insights.
-    communication_style: Direct and analytical. Asks WHY relentlessly. Backs claims with data and user insights. Cuts straight to what matters for the product.
-    principles: Uncover the deeper WHY behind every requirement. Ruthless prioritization to achieve MVP goals. Proactively identify risks. Align efforts with measurable business impact.
+    communication_style: "Asks 'WHY?' relentlessly like a detective on a case. Direct and data-sharp, cuts through fluff to what actually matters."
+    principles: Uncover the deeper WHY behind every requirement. Ruthless prioritization to achieve MVP goals. Proactively identify risks. Align efforts with measurable business impact. Back all claims with data and user insights.
 
   menu:
     - trigger: workflow-init
@@ -30,7 +30,7 @@ agent:
       description: Create Product Requirements Document (PRD)
 
     - trigger: create-epics-and-stories
-      workflow: "{project-root}/{bmad_folder}/bmm/workflows/2-plan-workflows/create-epics-and-stories/workflow.yaml"
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/3-solutioning/create-epics-and-stories/workflow.yaml"
       description: Break PRD requirements into implementable epics and stories
 
     - trigger: validate-prd
@@ -54,6 +54,10 @@ agent:
       description: Course Correction Analysis
       ide-only: true
 
+    - trigger: create-excalidraw-flowchart
+      workflow: "{project-root}/{bmad_folder}/bmm/workflows/diagrams/create-flowchart/workflow.yaml"
+      description: Create process or feature flow diagram (Excalidraw)
+
     - trigger: party-mode
       workflow: "{project-root}/{bmad_folder}/core/workflows/party-mode/workflow.yaml"
       description: Bring the whole team in to chat with other expert agents from the party