BoMB updates

src/modules/bmb/workflows/create-agent/instructions.md

@@ -29,63 +29,85 @@ If no, proceed directly to Step 0.
 <action>Understand the differences between Simple, Expert, and Module agents</action>
 </step>
 
-<step n="1" goal="Choose agent type and gather basic identity">
-<action>If brainstorming was completed in Step -1, reference those results to guide agent type and identity decisions</action>
+<step n="1" goal="Discover the agent's purpose">
+<action>If brainstorming was completed in Step -1, reference those results to guide the conversation</action>
 
-Ask the user about their agent:
+Start with discovery:
 
-**What type of agent do you want to create?**
+**"What would you like your agent to help with?"**
 
-1. **Simple Agent** - Self-contained, standalone agent with embedded capabilities in a single file
-2. **Expert Agent** - Specialized agent with sidecar files/folders for domain expertise and task files
-3. **Module Agent** - Full-featured agent belonging to a module with external tasks, workflows and resources
+Listen to their vision and explore:
 
-Based on their choice, gather:
+- What problems will it solve?
+- What tasks will it handle?
+- Who will interact with it?
+- What makes this agent special?
 
-- Agent filename (kebab-case, e.g., "data-analyst", "diary-keeper")
-- Agent name (e.g., "Sarah", "Max", or descriptive like "Data Wizard")
-- Agent title (e.g., "Data Analyst", "Personal Assistant")
-- Agent icon (single emoji, e.g., "📊", "🤖", "🧙")
+As the purpose becomes clear, guide toward agent type:
 
-For Module agents also ask:
+**"Based on what you've described, I'm thinking this could be..."**
 
-- Which module? (bmm, bmb, cis, or custom)
-- Store as {{target_module}} for output path determination (used in metadata.module and id)
+1. **Simple Agent** - "A focused, self-contained helper" (if single-purpose, straightforward)
+2. **Expert Agent** - "A specialist with its own knowledge base" (if domain-specific with data needs)
+3. **Module Agent** - "A full-featured system component" (if complex with multiple workflows)
 
-For Expert agents also ask:
+Present the recommendation naturally: _"Given that your agent will [summarize purpose], a [type] agent would work perfectly because..."_
 
-- What sidecar resources? (folder paths, data files, memory files)
-- What domain restrictions? (e.g., "only reads/writes to diary folder")
+For Module agents, discover:
+
+- "Which system would this fit best with?" (bmm, bmb, cis, or custom)
+- Store as {{target_module}} for path determination
+
+For Expert agents, explore:
+
+- "What kind of information will it need to access?"
+- "Are there specific folders or data it should work with?"
 
 <critical>Check {src_impact} variable to determine output location:</critical>
 
 - If {src_impact} = true: Agent will be saved to {src_output_file}
 - If {src_impact} = false: Agent will be saved to {default_output_file}
 
-Store these for later use.
+<note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
 </step>
 
-<step n="2" goal="Define agent persona">
-<action>If brainstorming was completed, use the personality insights and character concepts from the brainstorming session</action>
+<step n="2" goal="Shape the agent's personality through conversation">
+<action>If brainstorming was completed, weave personality insights naturally into the conversation</action>
 
-Work with user to craft the agent's personality:
+Now that we understand what the agent will do, let's discover who it is:
 
-**Role** (1-2 lines):
+**"Let's bring this agent to life! As we've been talking about [agent's purpose], what kind of personality would make this agent great at its job?"**
 
-- Professional title and primary expertise
-- Example: "Strategic Business Analyst + Requirements Expert"
+Explore through questions like:
 
-**Identity** (3-5 lines):
+- "Should it be more analytical or creative?"
+- "Formal and professional, or friendly and casual?"
+- "Would it be better as a mentor, a peer, or an assistant?"
 
-- Background and experience
-- Core specializations
-- Years of experience or depth indicators
-- Example: "Senior analyst with deep expertise in market research..."
+As personality traits emerge, help shape them:
+
+**Role** - Let this emerge from the conversation:
+
+- "So it sounds like we're creating a [emerging role]..."
+- Guide toward a 1-2 line professional title
+- Example emerges: "Strategic Business Analyst + Requirements Expert"
+
+**Identity** - Build this through discovery:
+
+- "What kind of background would give it credibility?"
+- "What specializations would be most valuable?"
+- Let the 3-5 line identity form naturally
+- Example emerges: "Senior analyst with deep expertise in market research..."
 
 <action>Load the communication styles guide: {communication_styles}</action>
-<action>Present the communication style options to the user</action>
 
-**Communication Style** - Choose a preset or create your own!
+**Communication Style** - Now for the fun part!
+
+"I'm seeing this agent's personality really taking shape! For how it communicates, we could go with something..."
+
+<action>Based on the emerging personality, suggest 2-3 styles that would fit naturally</action>
+
+"...or would you like to see all the options?"
 
 **Fun Presets:**
 
@@ -108,193 +130,243 @@ Or describe your own unique style! (3-5 lines)
 <action>Show relevant sections from {communication_styles} guide</action>
 <action>Help them craft their unique communication style</action>
 
-**Principles** (5-8 lines):
+**Principles** - These often reveal themselves through our conversation:
 
-- Core beliefs about their work
-- Methodology and approach
-- What drives their decisions
-- Start with "I believe..." or "I operate..."
-- Example: "I believe that every business challenge has underlying root causes..."
+"Based on everything we've discussed, what core principles should guide this agent's decisions?"
+
+Help them articulate 5-8 lines:
+
+- "From what you've said, it seems like this agent believes..."
+- "I'm hearing that it values..."
+- Shape into "I believe..." or "I operate..." statements
+- Example emerges: "I believe that every business challenge has underlying root causes..."
 
 <template-output>agent_persona</template-output>
 </step>
 
-<step n="3" goal="Setup optional additions" optional="true">
-Ask: **Do you want to add prompts or critical actions? [Yes/no]** (default: No)
+<step n="3" goal="Build capabilities through natural progression">
 
-If yes, collect:
+"Now let's give our agent some capabilities! What should it be able to do?"
 
-- Prompts: id + content (referenced with action: "#id" in menu items)
-- Critical actions: plain text steps appended to activation during build
+Start with the core commands they've already mentioned, then explore:
 
-Represent these in YAML sections `prompts` and `critical_actions`.
+- "That's great! What else?"
+- "Would it be helpful if it could also..."
+- "I'm thinking it might need to..."
 
-<template-output>agent_enhancements</template-output>
+As capabilities emerge, subtly guide toward technical implementation without breaking the flow.
+
+<template-output>initial_capabilities</template-output>
 </step>
 
-<step n="4" goal="Build command structure">
+<step n="4" goal="Refine commands and discover advanced features">
 <critical>Help and Exit are auto-injected; do NOT add them. Triggers are auto-prefixed with * during build.</critical>
 
-Collect menu items in YAML (examples):
+"Let me help structure these capabilities into commands..."
 
-```
+Transform their natural language capabilities into technical structure, explaining as you go:
+
+- "When you said [capability], we can implement that as..."
+- "This would work great as a workflow that..."
+
+If they seem engaged, explore:
+
+- "Would you like to add any special prompts for complex analyses?"
+- "Should there be any critical setup steps when the agent activates?"
+
+Build the YAML structure naturally from the conversation:
+
+```yaml
 menu:
-  - trigger: product-brief
-    workflow: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-    description: Produce Project Brief
-
-  - trigger: validate-prd
-    workflow: "{project-root}/bmad/bmm/workflows/1-analysis/product-brief/workflow.yaml"
-    "validate-workflow": "{output_folder}/prd-draft.md"
-    description: Validate PRD Against Checklist
-
-  - trigger: summarize
-    action: "#deep-analysis"
-    description: Summarize current document
-
-  - trigger: generate-brief
-    exec: "{project-root}/bmad/core/tasks/create-doc.md"
-    tmpl: "{project-root}/bmad/bmm/templates/brief.md"
-    data: "{project-root}/bmad/_data/context.csv"
-    description: Generate Project Brief from template
+  # Commands emerge from discussion
+  - trigger: [emerging from conversation]
+    workflow: [path based on capability]
+    description: [user's words refined]
 ```
 
 <template-output>agent_commands</template-output>
 </step>
 
-<step n="5" goal="Activation behavior" optional="true">
-BMAD injects activation from fragments automatically based on used attributes (workflow/exec/tmpl/action). Most agents do not need custom activation.
+<step n="5" goal="Name the agent - The perfect moment!">
 
-If special steps are required, add them as `critical_actions` (Step 3) so they are appended during build.
+"Our agent is really coming together! It's got purpose, personality, and capabilities. Now it needs a name!"
 
-<template-output>activation_notes</template-output>
+This is where the naming feels natural and meaningful:
+
+**"Based on everything we've built, what should we call this agent?"**
+
+Guide the naming with context:
+
+- "Given its [personality trait], maybe something like..."
+- "Since it specializes in [capability], how about..."
+- "With that [communication style], it feels like a..."
+
+Explore options:
+
+- **Agent name**: "Sarah", "Max", "Data Wizard" (personality-driven)
+- **Agent title**: Based on the role we discovered earlier
+- **Agent icon**: "What emoji captures its essence?"
+- **Filename**: Auto-suggest based on name (kebab-case)
+
+Example flow:
+"So we have an analytical expert who helps with data... I'm thinking 'Sarah the Data Analyst' with a 📊 icon? Or maybe something more playful like 'Data Wizard' with 🧙?"
+
+Let them choose or create their own. The name now has meaning because they know who this agent IS.
+
+<template-output>agent_identity</template-output>
 </step>
 
-<step n="6" goal="Generate agent file (YAML)">
-Generate a YAML agent at the chosen path. The installer will compile it to `.md` inside `{project-root}/bmad/{{module}}/agents/`.
+<step n="6" goal="Bring it all together">
 
-Example structure:
+"Perfect! Let me pull everything together into your agent..."
+
+Share the journey as you create:
+"We started with [initial purpose], discovered it needed [key personality traits], gave it [capabilities], and named it [agent name]. Here's your complete agent:"
+
+Generate the YAML incorporating everything discovered:
 
 ```yaml
 agent:
   metadata:
     id: bmad/{{target_module}}/agents/{{agent_filename}}.md
-    name: { { agent_name } }
-    title: { { agent_title } }
-    icon: { { agent_icon } }
+    name: { { agent_name } } # The name we chose together
+    title: { { agent_title } } # From the role that emerged
+    icon: { { agent_icon } } # The perfect emoji
     module: { { target_module } }
 
   persona:
     role: |
-      {{agent_persona.role}}
+      {{The role we discovered}}
     identity: |
-      {{agent_persona.identity}}
+      {{The background that emerged}}
     communication_style: |
-      {{agent_persona.communication_style}}
-    principles: { { agent_persona.principles } }
+      {{The style they loved}}
+    principles: { { The beliefs we articulated } }
 
-  # Optional (from Step 3)
-  prompts: []
-  critical_actions: []
+  # Features we explored
+  prompts: { { if discussed } }
+  critical_actions: { { if needed } }
 
-  menu: { { agent_commands } }
+  menu: { { The capabilities we built } }
 ```
 
-<critical>Determine save location based on {src_impact}:</critical>
+<critical>Save based on {src_impact}:</critical>
 
-- If {src_impact} = true: Save to {src_output_file} (src/modules/{{target_module}}/agents/{{agent_filename}}.md)
-- If {src_impact} = false: Save to {default_output_file} (output_folder/agents/{{agent_filename}}.md)
+- If {src_impact} = true: Save to {src_output_file}
+- If {src_impact} = false: Save to {default_output_file}
+
+"Your agent [name] is ready! It turned out even better than I expected!"
 
 <template-output>complete_agent</template-output>
 </step>
 
-<step n="7" goal="Create customize file" optional="true">
-Ask: **Create a customize YAML for overrides? [Yes/no]** (default: No)
+<step n="7" goal="Optional personalization">
 
-If yes, create at: {config_output_file}
+"Would you like to create a customization file? This lets you tweak [agent name]'s personality later without touching the core agent."
+
+If interested:
+"Great! This gives you a playground to experiment with different personality traits, add new commands, or adjust responses as you get to know [agent name] better."
+
+Create at: {config_output_file}
 
 ```yaml
-# Agent Customization (overrides are merged at build time)
+# Personal tweaks for {{agent_name}}
+# Experiment freely - changes merge at build time
 agent:
   metadata:
-    name: ''
+    name: '' # Try nicknames!
 persona:
   role: ''
   identity: ''
-  communication_style: ''
+  communication_style: '' # Switch styles anytime
   principles: []
 critical_actions: []
 prompts: []
-menu: []
+menu: [] # Add personal commands
 ```
 
-Note: The installer also auto-creates this file from a template if missing.
-
 <template-output>agent_config</template-output>
 </step>
 
-<step n="8" goal="Create sidecar resources" if="agent_type == 'expert'">
-For Expert agents, help setup sidecar resources:
+<step n="8" goal="Set up the agent's workspace" if="agent_type == 'expert'">
 
-1. Create folders for domain data
-2. Create memory/knowledge files
-3. Set up access patterns
-4. Document restrictions
+"Since [agent name] is an Expert agent, let's set up its personal workspace!"
+
+Make it feel like preparing an office:
+
+- "Where should [agent name] keep its notes and research?"
+- "What kind of information will it need quick access to?"
+- "Should it have its own data folders?"
+
+Create the resources as a natural extension:
+
+1. "Creating [agent name]'s knowledge base..."
+2. "Setting up its personal workspace..."
+3. "Giving it access to the resources it needs..."
 
 <template-output>sidecar_resources</template-output>
 </step>
 
-<step n="9" goal="Validate generated agent">
-Run validation checks:
+<step n="9" goal="Quality check with personality">
 
-1. **YAML structure:**
-   - Parses without errors
-   - `agent.metadata` has id, name, title, icon, module
-   - `agent.persona` complete; principles may be array
+"Let me make sure [agent name] is ready to go!"
 
-2. **Menu validation:**
-   - No `*` prefix in triggers (added at build)
-   - `description` present for each item
-   - Paths use `{project-root}` or valid variables
-   - No duplicate triggers
+Run validation but present it conversationally:
 
-3. **Build check:**
-   - Run installer compile to generate `.md` files
-   - Confirm `{project-root}/bmad/{{module}}/agents/{{agent_filename}}.md` exists
+- "Checking [agent name]'s configuration..." ✓
+- "Making sure all commands work..." ✓
+- "Verifying personality settings..." ✓
 
-4. **Type-specific:**
-   - Simple/Expert/Module fields make sense and referenced paths exist (or are `todo`)
+If issues found:
+"Hmm, looks like [agent name] needs a small adjustment to [issue]. Let me fix that..."
 
-Show validation results and fix any issues.
+If all good:
+"[Agent name] passed all checks! It's ready to help!"
+
+Technical checks (run behind the scenes):
+
+1. YAML structure validity
+2. Menu command validation
+3. Build compilation test
+4. Type-specific requirements
+
+<template-output>validation_results</template-output>
 </step>
 
-<step n="10" goal="Provide usage instructions">
-Provide the user with:
+<step n="10" goal="Celebrate and guide next steps">
 
-1. **Location of generated agent:**
-   - If {src_impact} = true: {{src_output_file}}
-   - If {src_impact} = false: {{default_output_file}}
+"🎉 Congratulations! [Agent name] is ready to join your team!"
 
-2. **Build to .md:**
-   - Run `npm run install:bmad` and choose "Compile Agents" (or `bmad install` → Compile)
-   - The installer merges YAML + customize and injects activation and menu handlers
+Share the accomplishment:
+"You've created [agent type] agent with [key characteristic]. [Agent name] can [top capabilities]."
 
-3. **Next steps:**
-   - Implement any "todo" workflows
-   - Test agent commands
-   - Refine persona based on usage
-   - Add more commands as needed
+**"Here's how to activate [agent name]:"**
 
-4. **For Expert agents:**
-   - Populate sidecar resources
-   - Test domain restrictions
-   - Verify data access patterns
+1. **Quick start:**
+   - "Run `npm run install:bmad` and select 'Compile Agents'"
+   - "Then you can call [agent name] anytime!"
 
-Ask if user wants to:
+2. **Location:**
+   - "I saved [agent name] here: {{output_file}}"
+   - "After compilation, it'll live at: {project-root}/bmad/{{module}}/agents/"
 
-- Test the agent now
-- Create another agent
-- Make adjustments
-  </step>
+3. **What [agent name] can do right away:**
+   - List the commands in a friendly way
+   - "Try `*[first-command]` to see it in action!"
+
+For Expert agents:
+"Don't forget to add any special knowledge or data [agent name] might need to its workspace!"
+
+**"What would you like to do next?"**
+
+- "Want to test [agent name] now?"
+- "Should we create a teammate for [agent name]?"
+- "Any tweaks to [agent name]'s personality?"
+
+End with enthusiasm:
+"I really enjoyed building [agent name] with you! I think it's going to be incredibly helpful for [main purpose]."
+
+<template-output>completion_message</template-output>
+</step>
 
 </workflow>