refactor: optimize data files for LLM runtime consumption

Dense format optimization across all agent data files.
- Removed redundancy, fluff, and exposition
- Converted prose to tables, lists, code blocks
- Structured for quick scanning and validation
- Preserved ALL technical rules and checkpoints
- Updated for simplified agent model (hasSidecar boolean)

Results: 763 lines removed while preserving functionality.
Files optimized: agent-architecture, agent-compilation,
agent-menu-patterns, agent-metadata, agent-validation,
brainstorm-context, critical-actions, persona-properties,
principles-crafting, understanding-agent-types

Author: Brian Madison

src/workflows/agent/data/agent-architecture.md

@@ -1,28 +1,10 @@
-# Agent Compilation: YAML Source → Final Agent
+# Agent Compilation: YAML → Compiled
 
-> **For the LLM running this workflow:** This document explains what the compiler adds. When building agents, focus on the YAML structure defined here—do NOT add things the compiler handles automatically.
->
-> **Example reference:** Compare `{workflow_path}/data/reference/module-examples/architect.agent.yaml` (source, 32 lines) with `architect.md` (compiled, 69 lines) to see what the compiler adds.
+**TL;DR:** Write minimal YAML → compiler adds frontmatter, activation XML, handlers, rules, MH/CH/PM/DA menu items.
 
 ---
 
-## Quick Overview
-
-You write: **YAML source file** (`agent-name.agent.yaml`)
-Compiler produces: **Markdown with XML** (`agent-name.md`) for LLM consumption
-
-The compiler transforms your clean YAML into a fully functional agent by adding:
-- Frontmatter (name, description)
-- XML activation block with numbered steps
-- Menu handlers (workflow, exec, action)
-- Auto-injected menu items (MH, CH, PM, DA)
-- Rules section
-
----
-
-## What YOU Provide (YAML Source)
-
-Your YAML contains ONLY these sections:
+## YAML Structure (YOU WRITE)
 
 ```yaml
 agent:
@@ -31,7 +13,7 @@ agent:
     name: "Persona Name"
     title: "Agent Title"
     icon: "🔧"
-    module: "stand-alone" or "bmm" or "cis" or "bmgd"
+    module: "stand-alone" | "bmm" | "cis" | "bmgd"
 
   persona:
     role: "First-person role description"
@@ -40,17 +22,17 @@ agent:
     principles:
       - "Core belief or methodology"
 
-  critical_actions:              # Optional - for any agent with activation behavior
+  critical_actions:              # Optional - ANY agent can have these
     - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
     - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
     - "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"
 
-  prompts:                        # Optional - for Simple/Expert agents
+  prompts:                        # Optional - standalone agents
     - id: prompt-name
       content: |
         <instructions>Prompt content</instructions>
 
-  menu:                           # Your custom items only
+  menu:                           # Custom items ONLY
     - trigger: XX or fuzzy match on command-name
       workflow: "path/to/workflow.yaml"   # OR
       exec: "path/to/file.md"             # OR
@@ -60,36 +42,18 @@ agent:
 
 ---
 
-## What COMPILER Adds (DO NOT Include)
+## What Compiler Adds (DO NOT WRITE)
 
-### 1. Frontmatter
-```markdown
----
-name: "architect"
-description: "Architect"
----
-```
-**DO NOT add** frontmatter to your YAML.
+| Component | Source |
+|-----------|--------|
+| Frontmatter (`---name/description---`) | Auto-generated |
+| XML activation block with numbered steps | Auto-generated |
+| critical_actions → activation steps | Injected as steps 4, 5, 6... |
+| Menu handlers (workflow/exec/action) | Auto-detected |
+| Rules section | Auto-generated |
+| MH, CH, PM, DA menu items | Always injected |
 
-### 2. XML Activation Block
-```xml
-<activation critical="MANDATORY">
-  <step n="1">Load persona from this current agent file</step>
-  <step n="2">Load config to get {user_name}, {communication_language}</step>
-  <step n="3">Remember: user's name is {user_name}</step>
-  <!-- YOUR critical_actions inserted here as steps 4, 5, etc. -->
-  <step n="N">ALWAYS communicate in {communication_language}</step>
-  <step n="N+1">Show greeting + numbered menu</step>
-  <step n="N+2">STOP and WAIT for user input</step>
-  <step n="N+3">Input resolution rules</step>
-  <menu-handlers>...</menu-handlers>
-  <rules>...</rules>
-</activation>
-```
-**DO NOT create** activation sections—the compiler builds them.
-
-### 3. Auto-Injected Menu Items
-Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
+### Auto-Injected Menu Items (NEVER add)
 
 | Code | Trigger | Description |
 |------|---------|-------------|
@@ -98,55 +62,10 @@ Every agent gets these 4 items automatically. **DO NOT add them to your YAML:**
 | PM | party-mode | Start Party Mode |
 | DA | exit, leave, goodbye, dismiss agent | Dismiss Agent |
 
-### 4. Menu Handlers
-```xml
-<handler type="workflow">
-  When menu item has: workflow="path/to/workflow.yaml"
-  → Load workflow.xml and execute with workflow-config parameter
-</handler>
-<handler type="exec">
-  When menu item has: exec="path/to/file.md"
-  → Load and execute the file at that path
-</handler>
-```
-**DO NOT add** handlers—the compiler detects and generates them.
-
 ---
 
-## Before/After Example: Architect Agent
+## Compiled Output Structure
 
-### Source: `architect.agent.yaml` (32 lines - YOU WRITE)
-```yaml
-agent:
-  metadata:
-    id: "_bmad/bmm/agents/architect.md"
-    name: Winston
-    title: Architect
-    icon: 🏗️
-    module: bmm
-
-  persona:
-    role: System Architect + Technical Design Leader
-    identity: Senior architect with expertise in distributed systems...
-    communication_style: "Speaks in calm, pragmatic tones..."
-    principles: |
-      - User journeys drive technical decisions...
-
-  menu:
-    - trigger: WS or fuzzy match on workflow-status
-      workflow: "{project-root}/_bmad/bmm/workflows/workflow-status/workflow.yaml"
-      description: "[WS] Get workflow status..."
-
-    - trigger: CA or fuzzy match on create-architecture
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/create-architecture/workflow.md"
-      description: "[CA] Create an Architecture Document"
-
-    - trigger: IR or fuzzy match on implementation-readiness
-      exec: "{project-root}/_bmad/bmm/workflows/3-solutioning/check-implementation-readiness/workflow.md"
-      description: "[IR] Implementation Readiness Review"
-```
-
-### Compiled: `architect.md` (69 lines - COMPILER PRODUCES)
 ```markdown
 ---
 name: "architect"
@@ -159,25 +78,26 @@ You must fully embody this agent's persona...
 <agent id="architect.agent.yaml" name="Winston" title="Architect" icon="🏗️">
 <activation critical="MANDATORY">
   <step n="1">Load persona from this current agent file (already in context)</step>
-  <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT...</step>
+  <step n="2">Load config to get {user_name}, {communication_language}</step>
   <step n="3">Remember: user's name is {user_name}</step>
-  <step n="4">Show greeting using {user_name} from config...</step>
-  <step n="5">STOP and WAIT for user input...</step>
-  <step n="6">On user input: Number → execute menu item[n]...</step>
-  <step n="7">When executing a menu item: Check menu-handlers section...</step>
+  <!-- YOUR critical_actions inserted here as steps 4, 5, 6... -->
+  <step n="N">ALWAYS communicate in {communication_language}</step>
+  <step n="N+1">Show greeting + numbered menu</step>
+  <step n="N+2">STOP and WAIT for user input</step>
 
   <menu-handlers>
     <handlers>
-      <handler type="workflow">...</handler>
-      <handler type="exec">...</handler>
+      <handler type="workflow">Load workflow.xml and execute with workflow-config parameter</handler>
+      <handler type="exec">Load and execute the file at that path</handler>
+      <handler type="action">Execute prompt with matching id from prompts section</handler>
     </handlers>
   </menu-handlers>
 
   <rules>
     <r>ALWAYS communicate in {communication_language}</r>
     <r>Stay in character until exit selected</r>
-    <r>Display Menu items as the item dictates...</r>
-    <r>Load files ONLY when executing menu items...</r>
+    <r>Display Menu items as the item dictates</r>
+    <r>Load files ONLY when executing menu items</r>
   </rules>
 </activation>
 
@@ -188,104 +108,78 @@ You must fully embody this agent's persona...
   <principles>- User journeys drive technical decisions...</principles>
 </persona>
 
+<prompts>
+  <prompt id="prompt-name">
+    <instructions>Prompt content</instructions>
+  </prompt>
+</prompts>
+
 <menu>
   <item cmd="MH or fuzzy match on menu or help">[MH] Redisplay Menu Help</item>
   <item cmd="CH or fuzzy match on chat">[CH] Chat with the Agent about anything</item>
-  <item cmd="WS...">[WS] Get workflow status...</item>           ← YOUR CUSTOM ITEMS
-  <item cmd="CA...">[CA] Create an Architecture Document</item>
-  <item cmd="IR...">[IR] Implementation Readiness Review</item>
-  <item cmd="PM...">[PM] Start Party Mode</item>
-  <item cmd="DA...">[DA] Dismiss Agent</item>
+  <!-- YOUR CUSTOM ITEMS HERE -->
+  <item cmd="PM or fuzzy match on party-mode">[PM] Start Party Mode</item>
+  <item cmd="DA or fuzzy match on exit leave goodbye dismiss agent">[DA] Dismiss Agent</item>
 </menu>
 </agent>
 ```
-**Key additions by compiler:** Frontmatter, activation block, handlers, rules, MH/CH/PM/DA menu items.
-
----
-
-## DO NOT DO Checklist
-
-When building agent YAML, **DO NOT:**
-
-- [ ] Add frontmatter (`---name/description---`) to YAML
-- [ ] Create activation blocks or XML sections
-- [ ] Add MH (menu/help) menu item
-- [ ] Add CH (chat) menu item
-- [ ] Add PM (party-mode) menu item
-- [ ] Add DA (dismiss/exit) menu item
-- [ ] Add menu handlers (workflow/exec logic)
-- [ ] Add rules section
-- [ ] Duplicate any auto-injected content
-
-**DO:**
-- [ ] Define metadata (id, name, title, icon, module)
-- [ ] Define persona (role, identity, communication_style, principles)
-- [ ] Define critical_actions (if agent has activation behavior)
-- [ ] Define prompts with IDs (Simple/Expert agents only)
-- [ ] Define menu with your custom items only
-- [ ] Use proper trigger format: `XX or fuzzy match on command-name`
-- [ ] Use proper description format: `[XX] Description text`
 
 ---
 
-## Agent critical_actions
+## critical_actions Injection
 
-For any agent with activation behavior, your `critical_actions` become activation steps.
-
-### Agents with sidecar (hasSidecar: true):
+Your `critical_actions` become numbered activation steps.
 
+### With sidecar (hasSidecar: true):
 ```yaml
 critical_actions:
   - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md"
   - "Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md"
   - "ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/"
 ```
+→ Injected as steps 4, 5, 6
 
-The compiler injects these as steps 4, 5, 6 in the activation block:
-
-```xml
-<step n="4">Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/memories.md</step>
-<step n="5">Load COMPLETE file {project-root}/_bmad/_memory/journal-sidecar/instructions.md</step>
-<step n="6">ONLY read/write files in {project-root}/_bmad/_memory/journal-sidecar/</step>
-<step n="7">ALWAYS communicate in {communication_language}</step>
-```
-
-### Agents without sidecar (hasSidecar: false):
-
+### Without sidecar (hasSidecar: false):
 ```yaml
 critical_actions:
   - "Give user an inspirational quote before showing menu"
-  - "Review {project-root}/finances/ for most recent data file"
 ```
+→ Injected as step 4
 
-The compiler injects these as steps 4, 5 in the activation block:
-
-```xml
-<step n="4">Give user an inspirational quote before showing menu</step>
-<step n="5">Review {project-root}/finances/ for most recent data file</step>
-<step n="6">ALWAYS communicate in {communication_language}</step>
-```
+### No critical_actions:
+Activation jumps directly from step 3 to "ALWAYS communicate in {communication_language}"
 
 ---
 
-## Division of Responsibilities
+## DO NOT / DO Checklist
 
-| Aspect | YOU Provide (YAML) | COMPILER Adds |
-|--------|-------------------|---------------|
-| Agent identity | metadata + persona | Wrapped in XML |
-| Memory/actions | critical_actions | Inserted as activation steps |
-| Prompts | prompts with IDs | Referenced by menu actions |
-| Menu items | Your custom commands only | + MH, CH, PM, DA (auto) |
-| Activation | — | Full XML block with handlers |
-| Rules | — | Standardized rules section |
-| Frontmatter | — | name/description header |
+**DO NOT:**
+- [ ] Add frontmatter
+- [ ] Create activation/XML blocks
+- [ ] Add MH/CH/PM/DA menu items
+- [ ] Add menu handlers
+- [ ] Add rules section
+- [ ] Duplicate auto-injected content
+
+**DO:**
+- [ ] Define metadata (id, name, title, icon, module)
+- [ ] Define persona (role, identity, communication_style, principles)
+- [ ] Define critical_actions (if activation behavior needed)
+- [ ] Define prompts with IDs (standalone agents)
+- [ ] Define menu with custom items only
+- [ ] Use format: `XX or fuzzy match on command-name`
+- [ ] Use description format: `[XX] Description text`
 
 ---
 
-## Quick Reference for LLM
+## Division of Responsibilities
 
-- **Focus on:** Clean YAML structure, persona definition, custom menu items
-- **Ignore:** What happens after compilation—that's the compiler's job
-- **Remember:** Every agent gets MH, CH, PM, DA automatically—don't add them
-- **critical_actions:** Use for activation behavior (loading files, greetings, data fetches)
-- **Module agents:** Use `workflow:` or `exec:` references, not inline actions
+| Aspect | YOU (YAML) | COMPILER |
+|--------|------------|----------|
+| Agent identity | metadata + persona | Wrapped in XML |
+| Activation steps | critical_actions | Inserted as steps 4+ |
+| Prompts | prompts with IDs | Referenced by actions |
+| Menu items | Custom only | + MH, CH, PM, DA |
+| Activation block | — | Full XML with handlers |
+| Rules | — | Standardized section |
+| Frontmatter | — | name/description |