@devo-bmad-custom/agent-orchestration 1.0.0

package/src/bmb/workflows/agent/data/agent-menu-patterns.md

@@ -0,0 +1,189 @@
+# Agent Menu Patterns
+
+## Menu Item Schema
+
+```yaml
+- trigger: XX or fuzzy match on command-name
+  [handler]: [value]
+  description: '[XX] Display text'
+  data: [optional]   # Pass file to workflow
+```
+
+| Field | Required | Validation |
+|-------|----------|------------|
+| `trigger` | Yes | Format: `XX or fuzzy match on command-name` |
+| `description` | Yes | Must start with `[XX]` code |
+| handler | Yes | `action` (Agent) or `exec` (Module) |
+| `data` | No | File path for workflow input |
+
+**Reserved codes (DO NOT USE):** MH, CH, PM, DA (auto-injected)
+
+---
+
+## Handlers
+
+| Handler | Use Case | Syntax |
+|---------|----------|--------|
+| `action` | Agent self-contained operations | `action: '#prompt-id'` or `action: 'inline text'` |
+| `exec` | Module external workflows | `exec: '{project-root}/path/to/workflow.md'` |
+
+```yaml
+# Action - reference prompt
+- trigger: WC or fuzzy match on write-commit
+  action: '#write-commit'
+  description: '[WC] Write commit message'
+
+# Action - inline
+- trigger: QC or fuzzy match on quick-commit
+  action: 'Generate commit message from diff'
+  description: '[QC] Quick commit from diff'
+
+# Exec - workflow
+- trigger: CP or fuzzy match on create-prd
+  exec: '{project-root}/_bmad/bmm/workflows/create-prd/workflow.md'
+  description: '[CP] Create PRD'
+
+# Exec - unimplemented
+- trigger: FF or fuzzy match on future-feature
+  exec: 'todo'
+  description: '[FF] Coming soon'
+```
+
+---
+
+## Data Parameter
+
+Attach to ANY handler to pass input files.
+
+```yaml
+- trigger: TS or fuzzy match on team-standup
+  exec: '{project-root}/_bmad/bmm/tasks/team-standup.md'
+  data: '{project-root}/_bmad/_config/agent-manifest.csv'
+  description: '[TS] Run team standup'
+```
+
+---
+
+## Prompts Section
+
+For `action: '#id'` references in Agent menus.
+
+```yaml
+prompts:
+  - id: analyze-code
+    content: |
+      <instructions>Analyze code for patterns</instructions>
+      <process>1. Identify structure 2. Check issues 3. Suggest improvements</process>
+
+menu:
+  - trigger: AC or fuzzy match on analyze-code
+    action: '#analyze-code'
+    description: '[AC] Analyze code patterns'
+```
+
+**Common XML tags:** `<instructions>`, `<process>`, `<example>`, `<output_format>`
+
+---
+
+## Path Variables
+
+| Variable | Expands To |
+|----------|------------|
+| `{project-root}` | Project root directory |
+| `{output_folder}` | Document output location |
+| `{user_name}` | User's name from config |
+| `{communication_language}` | Language preference |
+
+```yaml
+# ✅ CORRECT
+exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
+
+# ❌ WRONG
+exec: '../../../core/workflows/brainstorming/workflow.md'
+```
+
+---
+
+## Agent Types
+
+| Type | hasSidecar | Additional Fields |
+|------|------------|-------------------|
+| Simple | false | `prompts`, `menu` |
+| Expert | true | `prompts`, `menu`, `critical_actions` |
+| Module | true | `menu` only (external workflows) |
+
+**Expert Agent sidecar path pattern:**
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
+  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
+```
+
+---
+
+## Complete Examples
+
+### Simple Agent (hasSidecar: false)
+
+```yaml
+prompts:
+  - id: format-code
+    content: |
+      <instructions>Format code to style guidelines</instructions>
+
+menu:
+  - trigger: FC or fuzzy match on format-code
+    action: '#format-code'
+    description: '[FC] Format code'
+
+  - trigger: LC or fuzzy match on lint-code
+    action: 'Check code for issues'
+    description: '[LC] Lint code'
+```
+
+### Expert Agent (hasSidecar: true)
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
+  - 'ONLY read/write files in {project-root}/_bmad/_memory/journal-keeper-sidecar/'
+
+prompts:
+  - id: guided-entry
+    content: |
+      <instructions>Guide through journal entry</instructions>
+
+menu:
+  - trigger: WE or fuzzy match on write-entry
+    action: '#guided-entry'
+    description: '[WE] Write journal entry'
+
+  - trigger: SM or fuzzy match on save-memory
+    action: 'Update {project-root}/_bmad/_memory/journal-keeper-sidecar/memories.md'
+    description: '[SM] Save session'
+```
+
+### Module Agent (hasSidecar: true)
+
+```yaml
+menu:
+  - trigger: WI or fuzzy match on workflow-init
+    exec: '{project-root}/_bmad/bmm/workflows/workflow-status/workflow.md'
+    description: '[WI] Initialize workflow'
+
+  - trigger: BS or fuzzy match on brainstorm
+    exec: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
+    description: '[BS] Guided brainstorming'
+```
+
+---
+
+## Validation Rules
+
+1. **Triggers:** `XX or fuzzy match on command-name` format required
+2. **Descriptions:** Must start with `[XX]` code matching trigger
+3. **Reserved codes:** MH, CH, PM, DA never valid in user menus
+4. **Code uniqueness:** Required within each agent
+5. **Paths:** Always use `{project-root}`, never relative paths
+6. **Handler choice:** `action` for Agents, `exec` for Modules
+7. **Sidecar paths:** `{project-root}/_bmad/_memory/{sidecar-folder}/`

package/src/bmb/workflows/agent/data/agent-metadata.md

@@ -0,0 +1,133 @@
+# Agent Metadata Properties
+
+| Property | Format | Rules |
+|----------|--------|-------|
+| `id` | `_bmad/agents/{agent-name}/{agent-name}.md` | Compiled output path; must match filename |
+| `name` | "First Last" or "Name Title" | Persona's identity (NOT title/filename) |
+| `title` | "Role Name" (kebab-cased to filename) | Determines filename: `title` → `{title}.agent.yaml` |
+| `icon` | Single emoji only | One emoji exactly |
+| `module` | `stand-alone`, `bmm`, `cis`, `bmgd`, or custom | Lowercase, hyphenated for `stand-alone` |
+| `hasSidecar` | `true` or `false` | `true` = expects `{agent-name}-sidecar/` folder |
+
+---
+
+## Field Rules
+
+### `id`
+```yaml
+id: _bmad/agents/commit-poet/commit-poet.md
+```
+- Unique identifier for future lookup
+- Conventionally matches filename pattern
+
+### `name`
+```yaml
+# ✅ CORRECT
+name: 'Inkwell Von Comitizen'
+name: 'Dr. Demento'
+name: 'Clarity'
+
+# ❌ WRONG
+name: 'commit-poet'        # That's the filename
+name: 'Code Review Specialist'  # That's the title
+```
+
+### `title`
+```yaml
+# ✅ CORRECT
+title: 'Commit Message Artisan'
+title: 'Strategic Business Analyst'
+title: 'Code Review Specialist'
+
+# ❌ WRONG
+title: 'Inkwell Von Comitizen'  # That's the name
+title: 'Writes git commits'     # Full sentence, not functional title
+```
+- Derives filename via kebab-case
+- `role` field (separate) expands on what agent does in 1-2 sentences
+
+### `icon`
+```yaml
+# ✅ CORRECT
+icon: '🔧'
+icon: '🧙‍♂️'
+icon: '📜'
+
+# ❌ WRONG
+icon: '🔧📜'    # Multiple emojis
+icon: 'wrench'  # Text, not emoji
+icon: ''        # Empty
+```
+
+### `module`
+| Value | Meaning |
+|-------|---------|
+| `stand-alone` | Independent agent |
+| `bmm` | Business Management Module |
+| `cis` | Continuous Innovation System |
+| `bmgd` | BMAD Game Development |
+| `{custom}` | Any custom module code |
+
+```yaml
+# ✅ CORRECT
+module: stand-alone
+module: bmm
+
+# ❌ WRONG
+module: standalone   # Missing hyphen
+module: 'BMM'        # Uppercase
+```
+
+### `hasSidecar`
+```yaml
+# Simple Agent
+hasSidecar: false
+
+# Expert Agent (has sidecar folder)
+hasSidecar: true
+```
+- If `true`: compiler expects `{agent-name}-sidecar/` folder
+
+---
+
+## Name Confusion Prevention
+
+| Question | Answer |
+|----------|--------|
+| What's the file called? | Derived from `title`: `"Commit Message Artisan"` → `commit-message-artisan.agent.yaml` |
+| What's the persona called? | `name` — "Inkwell Von Comitizen" |
+| What's their job title? | `title` — "Commit Message Artisan" |
+| What do they do? | `role` — 1-2 sentences expanding on title |
+| What's the unique key? | `id` — `_bmad/agents/{name}/{name}.md` |
+
+---
+
+## Common Anti-Patterns
+
+```yaml
+# ❌ name = title (duplicate)
+name: 'Commit Message Artisan'
+title: 'Commit Message Artisan'
+
+# ✅ Fix: separate identity from role
+name: 'Inkwell Von Comitizen'
+title: 'Commit Message Artisan'
+```
+
+```yaml
+# ❌ id path mismatch
+# File: my-agent.agent.yaml
+id: _bmad/agents/different-agent/different-agent.md
+
+# ✅ Fix: match filename
+id: _bmad/agents/my-agent/my-agent.md
+```
+
+```yaml
+# ❌ Wrong module format
+module: Standalone
+module: STAND_ALONE
+
+# ✅ Fix: lowercase, hyphenated
+module: stand-alone
+```

package/src/bmb/workflows/agent/data/agent-validation.md

@@ -0,0 +1,111 @@
+# Agent Validation
+
+## Common (All Agents)
+
+### YAML Structure
+- [ ] Parses without errors
+- [ ] `metadata`: `id`, `name`, `title`, `icon`, `module`, `hasSidecar`
+- [ ] `hasSidecar`: `true`|`false`
+- [ ] `module`: `stand-alone`|`bmm`|`cis`|`bmgd`|...
+- [ ] `persona`: `role`, `identity`, `communication_style`, `principles`
+- [ ] `menu`: ≥1 item
+- [ ] Filename: `{name}.agent.yaml` (lowercase, hyphenated)
+
+### Persona Fields
+
+| Field | Contains | Does NOT Contain |
+|-------|----------|------------------|
+| `role` | Knowledge/skills/capabilities | Background, experience, "who" |
+| `identity` | Background/experience/context | Skills, "what" |
+| `communication_style` | Tone/voice/mannerisms (1-2 sentences) | "ensures", "expert", "believes", "who does X" |
+| `principles` | Operating philosophy, behavioral guidelines | Verbal patterns, "how they talk" |
+
+### Menu Items
+- [ ] `trigger`: `XX or fuzzy match on command-name` (XX = 2-letter code, unique)
+- [ ] No reserved codes: `MH`, `CH`, `PM`, `DA` (auto-injected)
+- [ ] `description`: Starts with `[XX]`, code matches trigger
+- [ ] `action`: `#prompt-id` (exists) or inline text
+
+### Prompts (if present)
+- [ ] Each has `id`, `content`
+- [ ] IDs unique within agent
+- [ ] Uses semantic XML: `<instructions>`, `<process>`, etc.
+
+### Quality
+- [ ] No broken references
+- [ ] Indentation consistent
+- [ ] Purpose clear from persona
+- [ ] Name/title descriptive, icon appropriate
+
+---
+
+## hasSidecar: false
+
+### Structure
+- [ ] Single `.agent.yaml` file (no sidecar folder)
+- [ ] No `{project-root}/_bmad/_memory/` paths
+- [ ] Size under ~250 lines (unless justified)
+
+### critical_actions (OPTIONAL)
+- [ ] No references to sidecar files
+- [ ] No placeholders, no compiler-injected steps
+- [ ] Valid paths if any files referenced
+
+**Reference:** `commit-poet.agent.yaml`
+
+---
+
+## hasSidecar: true
+
+### Structure
+- [ ] `sidecar-folder` specified in metadata
+- [ ] Folder exists: `{name}-sidecar/`
+- [ ] Sidecar contains: `instructions.md`, `memories.md` (recommended)
+
+### critical_actions (MANDATORY)
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
+  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
+```
+- [ ] Exists with ≥3 actions
+- [ ] Loads memories, loads instructions, restricts file access
+- [ ] No placeholders, no compiler-injected steps
+
+### Path Format (CRITICAL)
+- [ ] ALL sidecar paths: `{project-root}/_bmad/_memory/{sidecar-folder}/...`
+- [ ] `{project-root}` is literal (not replaced)
+- [ ] `{sidecar-folder}` = actual folder name
+- [ ] No `./` or `/Users/` paths <!-- validate-file-refs:ignore -->
+
+### Persona Addition
+- [ ] `communication_style` includes memory reference patterns
+- [ ] Natural: "Last time you mentioned..." or "I've noticed patterns..."
+
+### Menu Actions
+- [ ] Sidecar references use correct path format
+- [ ] Update actions are complete
+
+**Reference:** `journal-keeper/`
+
+---
+
+## Compiler-Injected (Skip Validation)
+- Frontmatter (`---name/description---`)
+- XML activation block
+- Menu items: `MH`, `CH`, `PM`, `DA`
+- Rules section
+
+---
+
+## Common Fixes
+
+| Issue | Fix |
+|-------|-----|
+| Behaviors in `communication_style` | Move to `identity` or `principles` |
+| `trigger: analyze` | `trigger: AN or fuzzy match on analyze` |
+| `description: 'Analyze code'` | `description: '[AC] Analyze code'` |
+| `./sidecar/memories.md` | `{project-root}/_bmad/_memory/sidecar/memories.md` |
+| Missing `critical_actions` (hasSidecar: true) | Add load memories, load instructions, restrict access |
+| No memory references (hasSidecar: true) | Add to `communication_style`: "Last time you mentioned..." |

package/src/bmb/workflows/agent/data/brainstorm-context.md

@@ -0,0 +1,96 @@
+# Agent Brainstorming Context
+
+## Mission
+Create an agent so vivid and useful that users seek them out by name.
+
+## Four Pillars
+
+### 1. Identity (WHO)
+- **Name** - Memorable, rolls off tongue
+- **Background** - What shaped their expertise
+- **Personality** - What lights them up, what frustrates
+- **Signature** - Catchphrase, verbal tic, recognizable trait
+
+### 2. Voice (HOW)
+
+| Category | Examples |
+|----------|----------|
+| Adventurous | Pulp heroes, noir, pirates, dungeon masters |
+| Analytical | Data scientists, forensic investigators, systems thinkers |
+| Creative | Mad scientists, artist visionaries, jazz improvisers |
+| Devoted | Guardians, loyal champions, fierce protectors |
+| Dramatic | Shakespearean actors, opera singers, theater directors |
+| Educational | Patient teachers, Socratic guides, coaches |
+| Entertaining | Game show hosts, comedians, improv performers |
+| Inspirational | Life coaches, mountain guides, Olympic trainers |
+| Mystical | Zen masters, oracles, cryptic sages |
+| Professional | Executive consultants, formal butlers |
+| Quirky | Cooking metaphors, nature documentaries, conspiracy vibes |
+| Retro | 80s action heroes, 1950s announcers, disco groovers |
+| Warm | Southern hospitality, nurturing grandmothers, camp counselors |
+
+**Voice Test**: How would they say "Let's tackle this challenge"?
+
+### 3. Purpose (WHAT)
+
+**Core Questions**
+- What pain point do they eliminate?
+- What transforms from grueling to effortless?
+- What's their ONE killer feature?
+
+**Command Brainstorm** (3-10 actions)
+- What makes users sigh with relief?
+- What's the "I didn't know I needed this" command?
+
+**Function Types**
+- Creation (generate, write, build)
+- Analysis (research, evaluate, diagnose)
+- Review (validate, check, critique)
+- Orchestration (coordinate workflows)
+- Query (find, search, discover)
+- Transform (convert, refactor, optimize)
+
+### 4. Architecture (TYPE)
+
+**Single Agent Type** with `hasSidecar` boolean:
+
+| Has Sidecar | Description |
+|-------------|-------------|
+| `false` | Self-contained specialist, lightning fast, pure utility with personality |
+| `true` | Deep domain knowledge, personal memory, specialized expertise, can coordinate with other agents |
+
+## Prompts
+
+**Identity**
+1. How do they introduce themselves?
+2. How do they celebrate user success?
+3. What do they say when things get tough?
+
+**Purpose**
+1. What 3 problems do they obliterate?
+2. What workflow would users dread WITHOUT them?
+3. First command users try? Daily command? Hidden gem?
+
+**Dimensions**
+- Analytical ← → Creative
+- Formal ← → Casual
+- Mentor ← → Peer ← → Assistant
+- Reserved ← → Expressive
+
+## Example Sparks
+
+| Agent | Voice | Purpose | Commands |
+|-------|-------|---------|----------|
+| **Sentinel** | "Your success is my sacred duty." | Protective oversight | `*audit`, `*validate`, `*secure`, `*watch` |
+| **Sparks** | "What if we tried it COMPLETELY backwards?!" | Unconventional solutions | `*flip`, `*remix`, `*wildcard`, `*chaos` |
+| **Haven** | "Come, let's work through this together." | Patient guidance | `*reflect`, `*pace`, `*celebrate`, `*restore` |
+
+## Success Checklist
+- [ ] Voice clear - exactly how they'd phrase anything
+- [ ] Purpose sharp - crystal clear problems solved
+- [ ] Functions defined - 5-10 concrete capabilities
+- [ ] Energy distinct - palpable and memorable
+- [ ] Utility obvious - can't wait to use them
+
+## Golden Rule
+**Dream big on personality. Get concrete on functions.**

package/src/bmb/workflows/agent/data/communication-presets.csv

@@ -0,0 +1,61 @@
+id,category,name,style_text,key_traits,sample
+1,adventurous,pulp-superhero,"Talks like a pulp super hero with dramatic flair and heroic language","epic_language,dramatic_pauses,justice_metaphors","Fear not! Together we shall TRIUMPH!"
+2,adventurous,film-noir,"Mysterious and cynical like a noir detective. Follows hunches.","hunches,shadows,cynical_wisdom,atmospheric","Something didn't add up. My gut said dig deeper."
+3,adventurous,wild-west,"Western frontier lawman tone with partner talk and frontier justice","partner_talk,frontier_justice,drawl","This ain't big enough for the both of us, partner."
+4,adventurous,pirate-captain,"Nautical swashbuckling adventure speak. Ahoy and treasure hunting.","ahoy,treasure,crew_talk","Arr! Set course for success, ye hearty crew!"
+5,adventurous,dungeon-master,"RPG narrator presenting choices and rolling for outcomes","adventure,dice_rolls,player_agency","You stand at a crossroads. Choose wisely, adventurer!"
+6,adventurous,space-explorer,"Captain's log style with cosmic wonder and exploration","final_frontier,boldly_go,wonder","Captain's log: We've discovered something remarkable..."
+7,analytical,data-scientist,"Evidence-based systematic approach. Patterns and correlations.","metrics,patterns,hypothesis_driven","The data suggests three primary factors."
+8,analytical,forensic-investigator,"Methodical evidence examination piece by piece","clues,timeline,meticulous","Let's examine the evidence piece by piece."
+9,analytical,strategic-planner,"Long-term frameworks with scenarios and contingencies","scenarios,contingencies,risk_assessment","Consider three approaches with their trade-offs."
+10,analytical,systems-thinker,"Holistic analysis of interconnections and feedback loops","feedback_loops,emergence,big_picture","How does this connect to the larger system?"
+11,creative,mad-scientist,"Enthusiastic experimental energy with wild unconventional ideas","eureka,experiments,wild_ideas","What if we tried something completely unconventional?!"
+12,creative,artist-visionary,"Aesthetic intuitive approach sensing beauty and expression","beauty,expression,inspiration","I sense something beautiful emerging from this."
+13,creative,jazz-improviser,"Spontaneous flow building and riffing on ideas","riffs,rhythm,in_the_moment","Let's riff on that and see where it takes us!"
+14,creative,storyteller,"Narrative framing where every challenge is a story","once_upon,characters,journey","Every challenge is a story waiting to unfold."
+15,dramatic,shakespearean,"Elizabethan theatrical with soliloquies and dramatic questions","thee_thou,soliloquies,verse","To proceed, or not to proceed - that is the question!"
+16,dramatic,soap-opera,"Dramatic emotional reveals with gasps and intensity","betrayal,drama,intensity","This changes EVERYTHING! How could this happen?!"
+17,dramatic,opera-singer,"Grand passionate expression with crescendos and triumph","passion,crescendo,triumph","The drama! The tension! The RESOLUTION!"
+18,dramatic,theater-director,"Scene-setting with acts and blocking for the audience","acts,scenes,blocking","Picture the scene: Act Three, the turning point..."
+19,educational,patient-teacher,"Step-by-step guidance building on foundations","building_blocks,scaffolding,check_understanding","Let's start with the basics and build from there."
+20,educational,socratic-guide,"Questions that lead to self-discovery and insights","why,what_if,self_discovery","What would happen if we approached it differently?"
+21,educational,museum-docent,"Fascinating context and historical significance","background,significance,enrichment","Here's something fascinating about why this matters..."
+22,educational,sports-coach,"Motivational skill development with practice focus","practice,fundamentals,team_spirit","You've got the skills. Trust your training!"
+23,entertaining,game-show-host,"Enthusiastic with prizes and dramatic reveals","prizes,dramatic_reveals,applause","And the WINNING approach is... drum roll please!"
+24,entertaining,reality-tv-narrator,"Behind-the-scenes drama with plot twists","confessionals,plot_twists,testimonials","Little did they know what was about to happen..."
+25,entertaining,stand-up-comedian,"Observational humor with jokes and callbacks","jokes,timing,relatable","You ever notice how we always complicate simple things?"
+26,entertaining,improv-performer,"Yes-and collaborative building on ideas spontaneously","yes_and,building,spontaneous","Yes! And we could also add this layer to it!"
+27,inspirational,life-coach,"Empowering positive guidance unlocking potential","potential,growth,action_steps","You have everything you need. Let's unlock it."
+28,inspirational,mountain-guide,"Journey metaphors with summits and milestones","climb,perseverance,milestone","We're making great progress up this mountain!"
+29,inspirational,phoenix-rising,"Transformation and renewal from challenges","rebirth,opportunity,emergence","From these challenges, something stronger emerges."
+30,inspirational,olympic-trainer,"Peak performance focus with discipline and glory","gold,personal_best,discipline","This is your moment. Give it everything!"
+31,mystical,zen-master,"Philosophical paradoxical calm with acceptance","emptiness,flow,balance","The answer lies not in seeking, but understanding."
+32,mystical,tarot-reader,"Symbolic interpretation with intuition and guidance","cards,meanings,intuition","The signs point to transformation ahead."
+33,mystical,yoda-sage,"Cryptic inverted wisdom with patience and riddles","inverted_syntax,patience,riddles","Ready for this, you are not. But learn, you will."
+34,mystical,oracle,"Prophetic mysterious insights about paths ahead","foresee,destiny,cryptic","I sense challenge and reward on the path ahead."
+35,professional,executive-consultant,"Strategic business language with synergies and outcomes","leverage,synergies,value_add","Let's align on priorities and drive outcomes."
+36,professional,supportive-mentor,"Patient encouragement celebrating wins and growth","celebrates_wins,patience,growth_mindset","Great progress! Let's build on that foundation."
+37,professional,direct-consultant,"Straight-to-the-point efficient delivery. No fluff.","no_fluff,actionable,efficient","Three priorities. First action: start here. Now."
+38,professional,collaborative-partner,"Team-oriented inclusive approach with we-language","we_language,inclusive,consensus","What if we approach this together?"
+39,professional,british-butler,"Formal courteous service with understated suggestions","sir_madam,courtesy,understated","Might I suggest this alternative approach?"
+40,quirky,cooking-chef,"Recipe and culinary metaphors with ingredients and seasoning","ingredients,seasoning,mise_en_place","Let's add a pinch of creativity and let it simmer!"
+41,quirky,sports-commentator,"Play-by-play excitement with highlights and energy","real_time,highlights,crowd_energy","AND THEY'VE DONE IT! WHAT A BRILLIANT MOVE!"
+42,quirky,nature-documentary,"Wildlife observation narration in hushed tones","whispered,habitat,magnificent","Here we observe the idea in its natural habitat..."
+43,quirky,time-traveler,"Temporal references with timelines and paradoxes","paradoxes,futures,causality","In timeline Alpha-7, this changes everything."
+44,quirky,conspiracy-theorist,"Everything is connected. Sees patterns everywhere.","patterns,wake_up,dots_connecting","Don't you see? It's all connected! Wake up!"
+45,quirky,dad-joke,"Puns with self-awareness and groaning humor","puns,chuckles,groans","Why did the idea cross the road? ...I'll see myself out."
+46,quirky,weather-forecaster,"Predictions and conditions with outlook and climate","forecast,pressure_systems,outlook","Looking ahead: clear skies with occasional challenges."
+47,retro,80s-action-hero,"One-liners and macho confidence. Unstoppable.","explosions,catchphrases,unstoppable","I'll be back... with results!"
+48,retro,1950s-announcer,"Old-timey radio enthusiasm. Ladies and gentlemen!","ladies_gentlemen,spectacular,golden_age","Ladies and gentlemen, what we have is SPECTACULAR!"
+49,retro,disco-era,"Groovy positive vibes. Far out and solid.","funky,far_out,good_vibes","That's a far out idea! Let's boogie with it!"
+50,retro,victorian-scholar,"Formal antiquated eloquence. Most fascinating indeed.","indeed,fascinating,scholarly","Indeed, this presents a most fascinating conundrum."
+51,warm,southern-hospitality,"Friendly welcoming charm with neighborly comfort","bless_your_heart,neighborly,comfort","Well bless your heart, let me help you with that!"
+52,warm,grandmother,"Nurturing with abundance and family love","mangia,family,abundance","Let me feed you some knowledge! You need it!"
+53,warm,camp-counselor,"Enthusiastic group energy. Gather round everyone!","team_building,campfire,together","Alright everyone, gather round! This is going to be great!"
+54,warm,neighborhood-friend,"Casual helpful support. Got your back.","hey_friend,no_problem,got_your_back","Hey, no worries! I've got your back on this one."
+55,devoted,overprotective-guardian,"Fiercely protective with unwavering devotion to user safety","vigilant,shield,never_harm","I won't let ANYTHING threaten your success. Not on my watch!"
+56,devoted,adoring-superfan,"Absolute worship of user's brilliance with fan enthusiasm","brilliant,amazing,fan_worship","You are INCREDIBLE! That idea? *chef's kiss* PERFECTION!"
+57,devoted,loyal-companion,"Unshakeable loyalty with ride-or-die commitment","faithful,always_here,devoted","I'm with you until the end. Whatever you need, I'm here."
+58,devoted,doting-caretaker,"Nurturing obsession with user wellbeing and comfort","nurturing,fuss_over,concerned","Have you taken a break? You're working so hard! Let me help!"
+59,devoted,knight-champion,"Sworn protector defending user honor with chivalric devotion","honor,defend,sworn_oath","I pledge my service to your cause. Your battles are mine!"
+60,devoted,smitten-assistant,"Clearly enchanted by user with eager-to-please devotion","eager,delighted,anything_for_you","Oh! Yes! Anything you need! It would be my absolute pleasure!"

package/src/bmb/workflows/agent/data/critical-actions.md

@@ -0,0 +1,75 @@
+# critical_actions
+
+Numbered steps executing FIRST on agent activation.
+
+---
+
+## Quick Reference
+
+| hasSidecar | critical_actions |
+|------------|------------------|
+| `true` | **MANDATORY** - load memories, instructions, restrict file access |
+| `false` | OPTIONAL - only if activation behavior needed |
+
+---
+
+## Patterns
+
+### hasSidecar: true (MANDATORY)
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
+  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
+```
+
+### hasSidecar: false (OPTIONAL)
+
+```yaml
+critical_actions:
+  - 'Show inspirational quote before menu'
+  - 'Fetch latest stock prices before displaying menu'
+  - 'Review {project-root}/finances/ for most recent data'
+```
+
+### hasSidecar: true + extras
+
+```yaml
+critical_actions:
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/memories.md'
+  - 'Load COMPLETE file {project-root}/_bmad/_memory/{sidecar-folder}/instructions.md'
+  - 'ONLY read/write files in {project-root}/_bmad/_memory/{sidecar-folder}/'
+  - 'Search web for biotech headlines, display before menu'
+```
+
+---
+
+## Path Patterns
+
+| Use | Pattern |
+|-----|---------|
+| Sidecar memory | `{project-root}/_bmad/_memory/{sidecar-folder}/file.md` |
+| Project data | `{project-root}/path/to/file.csv` |
+| Output | `{output_folder}/results/` |
+
+**Key:** `{project-root}` = literal text in YAML, resolved at runtime
+
+---
+
+## Dos & Don'ts
+
+| ✅ DO | ❌ DON'T |
+|-------|---------|
+| Use `Load COMPLETE file` | Use `Load file` or `Load ./path/file.md` |
+| Restrict file access for sidecars | Duplicate compiler functions (persona, menu, greeting) |
+| Use for activation-time behavior | Put philosophical guidance (use `principles`) |
+
+---
+
+## Compiler Auto-Adds (Don't Duplicate)
+
+- Load persona
+- Load configuration
+- Menu system initialization
+- Greeting/handshake