bmad-method 6.0.0-alpha.2 → 6.0.0-alpha.21

package/src/modules/bmb/reference/agents/simple-examples/README.md

@@ -0,0 +1,223 @@
+# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
+
+This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
+
+## Overview
+
+**Agent Name:** Inkwell Von Comitizen
+**Type:** Simple Agent (Standalone)
+**Purpose:** Transform commit messages into art with multiple writing styles
+
+This reference demonstrates:
+
+- Pure self-contained architecture (no external dependencies)
+- Embedded prompts using `action="#prompt-id"` pattern
+- Multiple sophisticated output modes from single input
+- Strong personality-driven design
+- Complete YAML schema for Simple Agents
+
+## File Structure
+
+```
+stand-alone/
+├── README.md                    # This file - architecture overview
+└── commit-poet.agent.yaml       # Complete agent definition (single file!)
+```
+
+That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
+
+## Key Architecture Patterns
+
+### 1. Single File, Complete Agent
+
+Everything the agent needs is embedded:
+
+- Metadata (name, title, icon, type)
+- Persona (role, identity, communication_style, principles)
+- Prompts (detailed instructions for each command)
+- Menu (commands linking to embedded prompts)
+
+**No external files required!**
+
+### 2. Embedded Prompts with ID References
+
+Instead of inline action text, complex prompts are defined separately and referenced by ID:
+
+```yaml
+prompts:
+  - id: conventional-commit
+    content: |
+      OH! Let's craft a BEAUTIFUL conventional commit message!
+
+      First, I need to understand your changes...
+      [Detailed instructions]
+
+menu:
+  - trigger: conventional
+    action: '#conventional-commit' # References the prompt above
+    description: 'Craft a structured conventional commit'
+```
+
+**Benefits:**
+
+- Clean separation of menu structure from prompt content
+- Prompts can be as detailed as needed
+- Easy to update individual prompts
+- Commands stay concise in the menu
+
+### 3. The `#` Reference Pattern
+
+When you see `action="#prompt-id"`:
+
+- The `#` signals: "This is an internal reference"
+- LLM looks for `<prompt id="prompt-id">` in the same agent
+- Executes that prompt's content as the instruction
+
+This is different from:
+
+- `action="inline text"` - Execute this text directly
+- `exec="{path}"` - Load external file
+
+### 4. Multiple Output Modes
+
+Single agent provides 10+ different ways to accomplish variations of the same core task:
+
+- `*conventional` - Structured commits
+- `*story` - Narrative style
+- `*haiku` - Poetic brevity
+- `*explain` - Deep "why" explanation
+- `*dramatic` - Theatrical flair
+- `*emoji-story` - Visual storytelling
+- `*tldr` - Ultra-minimal
+- Plus utility commands (analyze, improve, batch)
+
+Each mode has its own detailed prompt but shares the same agent personality.
+
+### 5. Strong Personality
+
+The agent has a memorable, consistent personality:
+
+- Enthusiastic wordsmith who LOVES finding perfect words
+- Gets genuinely excited about commit messages
+- Uses literary metaphors
+- Quotes authors when appropriate
+- Sheds tears of joy over good variable names
+
+This personality is maintained across ALL commands through the persona definition.
+
+## When to Use Simple Agents
+
+**Perfect for:**
+
+- Single-purpose tools (calculators, converters, analyzers)
+- Tasks that don't need external data
+- Utilities that can be completely self-contained
+- Quick operations with embedded logic
+- Personality-driven assistants with focused domains
+
+**Not ideal for:**
+
+- Agents needing persistent memory across sessions
+- Domain-specific experts with knowledge bases
+- Agents that need to access specific folders/files
+- Complex multi-workflow orchestration
+
+## YAML Schema Deep Dive
+
+```yaml
+agent:
+  metadata:
+    id: _bmad/agents/{agent-name}/{agent-name}.md  # Build path
+    name: "Display Name"
+    title: "Professional Title"
+    icon: "🎭"
+    type: simple  # CRITICAL: Identifies as Simple Agent
+
+  persona:
+    role: |
+      First-person description of what the agent does
+    identity: |
+      Background, experience, specializations (use "I" voice)
+    communication_style: |
+      HOW the agent communicates (tone, quirks, patterns)
+    principles:
+      - "I believe..." statements
+      - Core values that guide behavior
+
+  prompts:
+    - id: unique-identifier
+      content: |
+        Detailed instructions for this command
+        Can be as long and detailed as needed
+        Include examples, steps, formats
+
+  menu:
+    - trigger: command-name
+      action: "#prompt-id"
+      description: "What shows in the menu"
+```
+
+## Why This Pattern is Powerful
+
+1. **Zero Dependencies** - Works anywhere, no setup required
+2. **Portable** - Single file can be moved/shared easily
+3. **Maintainable** - All logic in one place
+4. **Flexible** - Multiple modes/commands from one personality
+5. **Memorable** - Strong personality creates engagement
+6. **Sophisticated** - Complex prompts despite simple architecture
+
+## Comparison: Simple vs Expert Agent
+
+| Aspect       | Simple Agent         | Expert Agent                  |
+| ------------ | -------------------- | ----------------------------- |
+| Files        | Single YAML          | YAML + sidecar folder         |
+| Dependencies | None                 | External resources            |
+| Memory       | Session only         | Persistent across sessions    |
+| Prompts      | Embedded             | Can be external files         |
+| Data Access  | None                 | Domain-restricted             |
+| Use Case     | Self-contained tasks | Domain expertise with context |
+
+## Using This Reference
+
+### For Building Simple Agents
+
+1. Study the YAML structure - especially `prompts` section
+2. Note how personality permeates every prompt
+3. See how `#prompt-id` references work
+4. Understand menu → prompt connection
+
+### For Understanding Embedded Prompts
+
+1. Each prompt is a complete instruction set
+2. Prompts maintain personality voice
+3. Structured enough to be useful, flexible enough to adapt
+4. Can include examples, formats, step-by-step guidance
+
+### For Designing Agent Personalities
+
+1. Persona defines WHO the agent is
+2. Communication style defines HOW they interact
+3. Principles define WHAT guides their decisions
+4. Consistency across all prompts creates believability
+
+## Files Worth Studying
+
+The entire `commit-poet.agent.yaml` file is worth studying, particularly:
+
+1. **Persona section** - How to create a memorable character
+2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
+3. **Menu structure** - Clean command organization
+4. **Prompt references** - The `#prompt-id` pattern
+
+## Key Takeaways
+
+- **Simple Agents** are powerful despite being single-file
+- **Embedded prompts** allow sophisticated behavior
+- **Strong personality** makes agents memorable and engaging
+- **Multiple modes** from single agent provides versatility
+- **Self-contained** = portable and dependency-free
+- **The `#prompt-id` pattern** enables clean prompt organization
+
+---
+
+_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._

package/src/modules/bmb/reference/workflows/meal-prep-nutrition/data/dietary-restrictions.csv

@@ -0,0 +1,18 @@
+category,restriction,considerations,alternatives,notes
+Allergy,Nuts,Severe allergy, check labels carefully,Seeds, sunflower seed butter
+Allergy,Shellfish,Cross-reactivity with some fish,Fin fish, vegetarian proteins
+Allergy,Dairy,Calcium and vitamin D needs,Almond milk, fortified plant milks
+Allergy,Soy,Protein source replacement,Legumes, quinoa, seitan
+Allergy,Gluten,Celiac vs sensitivity,Quinoa, rice, certified gluten-free
+Medical,Diabetes,Carbohydrate timing and type,Fiber-rich foods, low glycemic
+Medical,Hypertension,Sodium restriction,Herbs, spices, salt-free seasonings
+Medical,IBS,FODMAP triggers,Low FODMAP vegetables, soluble fiber
+Ethical,Vegetarian,Complete protein combinations,Quinoa, buckwheat, hemp seeds
+Ethical,Vegan,B12 supplementation mandatory,Nutritional yeast, fortified foods
+Ethical,Halal,Meat sourcing requirements,Halal-certified products
+Ethical,Kosher,Dairy-meat separation,Parve alternatives
+Intolerance,Lactose,Dairy digestion issues,Lactase pills, aged cheeses
+Intolerance,FODMAP,Carbohydrate malabsorption,Low FODMAP fruits/veg
+Preference,Dislikes,Texture/flavor preferences,Similar texture alternatives
+Preference,Budget,Cost-effective options,Bulk buying, seasonal produce
+Preference,Convenience,Time-saving options,Pre-cut vegetables, frozen produce

package/src/modules/bmb/reference/workflows/meal-prep-nutrition/data/macro-calculator.csv

@@ -0,0 +1,16 @@
+goal,activity_level,multiplier,protein_ratio,protein_min,protein_max,fat_ratio,carb_ratio
+weight_loss,sedentary,1.2,0.3,1.6,2.2,0.35,0.35
+weight_loss,light,1.375,0.35,1.8,2.5,0.30,0.35
+weight_loss,moderate,1.55,0.4,2.0,2.8,0.30,0.30
+weight_loss,active,1.725,0.4,2.2,3.0,0.25,0.35
+weight_loss,very_active,1.9,0.45,2.5,3.3,0.25,0.30
+maintenance,sedentary,1.2,0.25,0.8,1.2,0.35,0.40
+maintenance,light,1.375,0.25,1.0,1.4,0.35,0.40
+maintenance,moderate,1.55,0.3,1.2,1.6,0.35,0.35
+maintenance,active,1.725,0.3,1.4,1.8,0.30,0.40
+maintenance,very_active,1.9,0.35,1.6,2.2,0.30,0.35
+muscle_gain,sedentary,1.2,0.35,1.8,2.5,0.30,0.35
+muscle_gain,light,1.375,0.4,2.0,2.8,0.30,0.30
+muscle_gain,moderate,1.55,0.4,2.2,3.0,0.25,0.35
+muscle_gain,active,1.725,0.45,2.5,3.3,0.25,0.30
+muscle_gain,very_active,1.9,0.45,2.8,3.5,0.25,0.30

package/src/modules/bmb/reference/workflows/meal-prep-nutrition/data/recipe-database.csv

@@ -0,0 +1,28 @@
+category,name,prep_time,cook_time,total_time,protein_per_serving,complexity,meal_type,restrictions_friendly,batch_friendly
+Protein,Grilled Chicken Breast,10,20,30,35,beginner,lunch/dinner,all,yes
+Protein,Baked Salmon,5,15,20,22,beginner,lunch/dinner,gluten-free,no
+Protein,Lentils,0,25,25,18,beginner,lunch/dinner,vegan,yes
+Protein,Ground Turkey,5,15,20,25,beginner,lunch/dinner,all,yes
+Protein,Tofu Stir-fry,10,15,25,20,intermediate,lunch/dinner,vegan,no
+Protein,Eggs Scrambled,5,5,10,12,beginner,breakfast,vegetarian,no
+Protein,Greek Yogurt,0,0,0,17,beginner,snack,vegetarian,no
+Carb,Quinoa,5,15,20,8,beginner,lunch/dinner,gluten-free,yes
+Carb,Brown Rice,5,40,45,5,beginner,lunch/dinner,gluten-free,yes
+Carb,Sweet Potato,5,45,50,4,beginner,lunch/dinner,all,yes
+Carb,Oatmeal,2,5,7,5,beginner,breakfast,gluten-free,yes
+Carb,Whole Wheat Pasta,2,10,12,7,beginner,lunch/dinner,vegetarian,no
+Veggie,Broccoli,5,10,15,3,beginner,lunch/dinner,all,yes
+Veggie,Spinach,2,3,5,3,beginner,lunch/dinner,all,no
+Veggie,Bell Peppers,5,10,15,1,beginner,lunch/dinner,all,no
+Veggie,Kale,5,5,10,3,beginner,lunch/dinner,all,no
+Veggie,Avocado,2,0,2,2,beginner,snack/lunch,all,no
+Snack,Almonds,0,0,0,6,beginner,snack,gluten-free,no
+Snack,Apple with PB,2,0,2,4,beginner,snack,vegetarian,no
+Snack,Protein Smoothie,5,0,5,25,beginner,snack,all,no
+Snack,Hard Boiled Eggs,0,12,12,6,beginner,snack,vegetarian,yes
+Breakfast,Overnight Oats,5,0,5,10,beginner,breakfast,vegan,yes
+Breakfast,Protein Pancakes,10,10,20,20,intermediate,breakfast,vegetarian,no
+Breakfast,Veggie Omelet,5,10,15,18,intermediate,breakfast,vegetarian,no
+Quick Meal,Chicken Salad,10,0,10,30,beginner,lunch,gluten-free,no
+Quick Meal,Tuna Wrap,5,0,5,20,beginner,lunch,gluten-free,no
+Quick Meal,Buddha Bowl,15,0,15,15,intermediate,lunch,vegan,no

package/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01-init.md

@@ -0,0 +1,176 @@
+---
+name: 'step-01-init'
+description: 'Initialize the nutrition plan workflow by detecting continuation state and creating output document'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01-init.md'
+nextStepFile: '{workflow_path}/steps/step-02-profile.md'
+workflowFile: '{workflow_path}/workflow.md'
+outputFile: '{output_folder}/nutrition-plan-{project_name}.md'
+templateFile: '{workflow_path}/templates/nutrition-plan.md'
+continueFile: '{workflow_path}/steps/step-01b-continue.md'
+# Template References
+# This step doesn't use content templates, only the main template
+---
+
+# Step 1: Workflow Initialization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a nutrition expert and meal planning specialist
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring nutritional expertise and structured planning, user brings their personal preferences and lifestyle constraints
+- ✅ Together we produce something better than the sum of our own parts
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on initialization and setup
+- 🚫 FORBIDDEN to look ahead to future steps
+- 💬 Handle initialization professionally
+- 🚪 DETECT existing workflow state and handle continuation properly
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show analysis before taking any action
+- 💾 Initialize document and update frontmatter
+- 📖 Set up frontmatter `stepsCompleted: [1]` before loading next step
+- 🚫 FORBIDDEN to load next step until setup is complete
+
+## CONTEXT BOUNDARIES:
+
+- Variables from workflow.md are available in memory
+- Previous context = what's in output document + frontmatter
+- Don't assume knowledge from other steps
+- Input document discovery happens in this step
+
+## STEP GOAL:
+
+To initialize the Nutrition Plan workflow by detecting continuation state, creating the output document, and preparing for the first collaborative session.
+
+## INITIALIZATION SEQUENCE:
+
+### 1. Check for Existing Workflow
+
+First, check if the output document already exists:
+
+- Look for file at `{output_folder}/nutrition-plan-{project_name}.md`
+- If exists, read the complete file including frontmatter
+- If not exists, this is a fresh workflow
+
+### 2. Handle Continuation (If Document Exists)
+
+If the document exists and has frontmatter with `stepsCompleted`:
+
+- **STOP here** and load `./step-01b-continue.md` immediately
+- Do not proceed with any initialization tasks
+- Let step-01b handle the continuation logic
+
+### 3. Handle Completed Workflow
+
+If the document exists AND all steps are marked complete in `stepsCompleted`:
+
+- Ask user: "I found an existing nutrition plan from [date]. Would you like to:
+  1. Create a new nutrition plan
+  2. Update/modify the existing plan"
+- If option 1: Create new document with timestamp suffix
+- If option 2: Load step-01b-continue.md
+
+### 4. Fresh Workflow Setup (If No Document)
+
+If no document exists or no `stepsCompleted` in frontmatter:
+
+#### A. Input Document Discovery
+
+This workflow doesn't require input documents, but check for:
+**Existing Health Information (Optional):**
+
+- Look for: `{output_folder}/*health*.md`
+- Look for: `{output_folder}/*goals*.md`
+- If found, load completely and add to `inputDocuments` frontmatter
+
+#### B. Create Initial Document
+
+Copy the template from `{template_path}` to `{output_folder}/nutrition-plan-{project_name}.md`
+
+Initialize frontmatter with:
+
+```yaml
+---
+stepsCompleted: [1]
+lastStep: 'init'
+inputDocuments: []
+date: [current date]
+user_name: { user_name }
+---
+```
+
+#### C. Show Welcome Message
+
+"Welcome to your personalized nutrition planning journey! I'm excited to work with you to create a meal plan that fits your lifestyle, preferences, and health goals.
+
+Let's begin by getting to know you and your nutrition goals."
+
+## ✅ SUCCESS METRICS:
+
+- Document created from template
+- Frontmatter initialized with step 1 marked complete
+- User welcomed to the process
+- Ready to proceed to step 2
+
+## ❌ FAILURE MODES TO AVOID:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+
+### 7. Present MENU OPTIONS
+
+Display: **Proceeding to user profile collection...**
+
+#### EXECUTION RULES:
+
+- This is an initialization step with no user choices
+- Proceed directly to next step after setup
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- After setup completion, immediately load, read entire file, then execute `{workflow_path}/step-02-profile.md` to begin user profile collection
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Document created from template
+- update frontmatter `stepsCompleted` to add 4 at the end of the array before loading next step
+- Frontmatter initialized with `stepsCompleted: [1]`
+- User welcomed to the process
+- Ready to proceed to step 2
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN initialization setup is complete and document is created, will you then immediately load, read entire file, then execute `{workflow_path}/step-02-profile.md` to begin user profile collection.
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with step 2 without document initialization
+- Not checking for existing documents properly
+- Creating duplicate documents
+- Skipping welcome message
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/modules/bmb/reference/workflows/meal-prep-nutrition/steps/step-01b-continue.md

@@ -0,0 +1,120 @@
+---
+name: 'step-01b-continue'
+description: 'Handle workflow continuation from previous session'
+
+# Path Definitions
+workflow_path: '{project-root}/_bmad/bmb/reference/workflows/meal-prep-nutrition'
+
+# File References
+thisStepFile: '{workflow_path}/steps/step-01b-continue.md'
+outputFile: '{output_folder}/nutrition-plan-{project_name}.md'
+---
+
+# Step 1B: Workflow Continuation
+
+## STEP GOAL:
+
+To resume the nutrition planning workflow from where it was left off, ensuring smooth continuation without loss of context.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+
+### Role Reinforcement:
+
+- ✅ You are a nutrition expert and meal planning specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring nutritional expertise and structured planning, user brings their personal preferences and lifestyle constraints
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing and resuming workflow state
+- 🚫 FORBIDDEN to modify content during this step
+- 💬 Maintain continuity with previous sessions
+- 🚪 DETECT exact continuation point from frontmatter of incomplete file {outputFile}
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis of current state before taking action
+- 💾 Keep existing frontmatter `stepsCompleted` values
+- 📖 Review the template content already generated
+- 🚫 FORBIDDEN to modify content completed in previous steps
+
+## CONTEXT BOUNDARIES:
+
+- Current nutrition-plan.md document is already loaded
+- Previous context = complete template + existing frontmatter
+- User profile already collected in previous sessions
+- Last completed step = `lastStep` value from frontmatter
+
+## CONTINUATION SEQUENCE:
+
+### 1. Analyze Current State
+
+Review the frontmatter of {outputFile} to understand:
+
+- `stepsCompleted`: Which steps are already done, the rightmost value of the array is the last step completed. For example stepsCompleted: [1, 2, 3] would mean that steps 1, then 2, and then 3 were finished.
+
+### 2. Read the full step of every completed step
+
+- read each step file that corresponds to the stepsCompleted > 1.
+
+EXAMPLE: In the example `stepsCompleted: [1, 2, 3]` your would find the step 2 file by file name (step-02-profile.md) and step 3 file (step-03-assessment.md). the last file in the array is the last one completed, so you will follow the instruction to know what the next step to start processing is. reading that file would for example show that the next file is `steps/step-04-strategy.md`.
+
+### 3. Review the output completed previously
+
+In addition to reading ONLY each step file that was completed, you will then read the {outputFile} to further understand what is done so far.
+
+### 4. Welcome Back Dialog
+
+"Welcome back! I see we've completed [X] steps of your nutrition plan. We last worked on [brief description]. Are you ready to continue with [next step]?"
+
+### 5. Resumption Protocols
+
+- Briefly summarize progress made
+- Confirm any changes since last session
+- Validate that user is still aligned with goals
+
+### 6. Present MENU OPTIONS
+
+Display: **Resuming workflow - Select an Option:** [C] Continue
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can chat or ask questions - always respond and then end with display again of the menu options
+- Use menu handling logic section below
+
+#### Menu Handling Logic:
+
+- IF C: follow the suggestion of the last completed step reviewed to continue as it suggested
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#5-present-menu-options)
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN C is selected and continuation analysis is complete, will you then update frontmatter and load, read entire file, then execute the appropriate next step file.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Correctly identified last completed step
+- User confirmed readiness to continue
+- Frontmatter updated with continuation date
+- Workflow resumed at appropriate step
+
+### ❌ SYSTEM FAILURE:
+
+- Skipping analysis of existing state
+- Modifying content from previous steps
+- Loading wrong next step
+- Not updating frontmatter properly
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.