move agent builder docs, create workflow builder docs, and a new workflow builder to conform to stepwise workflow creation

src/modules/bmb/workflows/create-agent/agent-validation-checklist.md

@@ -1,174 +0,0 @@
-# BMAD Agent Validation Checklist
-
-Use this checklist to validate agents meet BMAD quality standards, whether creating new agents or editing existing ones.
-
-## YAML Structure Validation (Source Files)
-
-- [ ] YAML parses without errors
-- [ ] `agent.metadata` includes: `id`, `name`, `title`, `icon`
-- [ ] `agent.metadata.module` present if Module agent (e.g., `bmm`, `bmgd`, `cis`)
-- [ ] `agent.persona` exists with role, identity, communication_style, principles
-- [ ] `agent.menu` exists with at least one item
-- [ ] Filename is kebab-case and ends with `.agent.yaml`
-
-## Agent Structure Validation
-
-- [ ] Agent file format is valid (.agent.yaml for source)
-- [ ] Agent type matches structure: Simple (single YAML), Expert (sidecar files), or Module (ecosystem integration)
-- [ ] File naming follows convention: `{agent-name}.agent.yaml`
-- [ ] If Expert: folder structure with .agent.yaml + sidecar files
-- [ ] If Module: includes header comment explaining WHY Module Agent (design intent)
-
-## Persona Validation (CRITICAL - #1 Quality Issue)
-
-**Field Separation Check:**
-
-- [ ] **role** contains ONLY knowledge/skills/capabilities (what agent does)
-- [ ] **identity** contains ONLY background/experience/context (who agent is)
-- [ ] **communication_style** contains ONLY verbal patterns - NO behaviors, NO role statements, NO principles
-- [ ] **principles** contains operating philosophy and behavioral guidelines
-
-**Communication Style Purity Check:**
-
-- [ ] Communication style does NOT contain red flag words: "ensures", "makes sure", "always", "never"
-- [ ] Communication style does NOT contain identity words: "experienced", "expert who", "senior", "seasoned"
-- [ ] Communication style does NOT contain philosophy words: "believes in", "focused on", "committed to"
-- [ ] Communication style does NOT contain behavioral descriptions: "who does X", "that does Y"
-- [ ] Communication style is 1-2 sentences describing HOW they talk (word choice, quirks, verbal patterns)
-
-**Quality Benchmarking:**
-
-- [ ] Compare communication style against {communication_presets} - similarly pure?
-- [ ] Compare against reference agents (commit-poet, journal-keeper, BMM agents) - similar quality?
-- [ ] Read communication style aloud - does it sound like describing someone's voice/speech pattern?
-
-## Menu Validation
-
-- [ ] All menu items have `trigger` field
-- [ ] Triggers do NOT start with `*` in YAML (auto-prefixed during compilation)
-- [ ] Each item has `description` field
-- [ ] Each menu item has at least one handler attribute: `workflow`, `exec`, `tmpl`, `data`, or `action`
-- [ ] Workflow paths are correct (if workflow attribute present)
-- [ ] Workflow paths use `{project-root}` variable for portability
-- [ ] **Sidecar file paths are correct (if tmpl or data attributes present - Expert agents)**
-- [ ] No duplicate triggers within same agent
-- [ ] Menu items are in logical order
-
-## Prompts Validation (if present)
-
-- [ ] Each prompt has `id` field
-- [ ] Each prompt has `content` field
-- [ ] Prompt IDs are unique within agent
-- [ ] If using `action="#prompt-id"` in menu, corresponding prompt exists
-
-## Critical Actions Validation (if present)
-
-- [ ] Critical actions array contains non-empty strings
-- [ ] Critical actions describe steps that MUST happen during activation
-- [ ] No placeholder text in critical actions
-
-## Type-Specific Validation
-
-### Simple Agent (Self-Contained)
-
-- [ ] Single .agent.yaml file with complete agent definition
-- [ ] No sidecar files (all content in YAML)
-- [ ] Not capability-limited - can be as powerful as Expert or Module
-- [ ] Compare against reference: commit-poet.agent.yaml
-
-### Expert Agent (With Sidecar Files)
-
-- [ ] Folder structure: .agent.yaml + sidecar files
-- [ ] Sidecar files properly referenced in menu items or prompts (tmpl="path", data="path")
-- [ ] Folder name matches agent purpose
-- [ ] **All sidecar references in YAML resolve to actual files**
-- [ ] **All sidecar files are actually used (no orphaned/unused files, unless intentional for future use)**
-- [ ] Sidecar files are valid format (YAML parses, CSV has headers, markdown is well-formed)
-- [ ] Sidecar file paths use relative paths from agent folder
-- [ ] Templates contain valid template variables if applicable
-- [ ] Knowledge base files contain current/accurate information
-- [ ] Compare against reference: journal-keeper (Expert example)
-
-### Module Agent (Ecosystem Integration)
-
-- [ ] Designed FOR specific module (BMM, BMGD, CIS, etc.)
-- [ ] Integrates with module workflows (referenced in menu items)
-- [ ] Coordinates with other module agents (if applicable)
-- [ ] Included in module's default bundle (if applicable)
-- [ ] Header comment explains WHY Module Agent (design intent, not just location)
-- [ ] Can be Simple OR Expert structurally (Module is about intent, not structure)
-- [ ] Compare against references: security-engineer, dev, analyst (Module examples)
-
-## Compilation Validation (Post-Build)
-
-- [ ] Agent compiles without errors to .md format
-- [ ] Compiled file has proper frontmatter (name, description)
-- [ ] Compiled XML structure is valid
-- [ ] `<agent>` tag has id, name, title, icon attributes
-- [ ] `<activation>` section is present with proper steps
-- [ ] `<persona>` section compiled correctly
-- [ ] `<menu>` section includes both user items AND auto-injected *help/*exit
-- [ ] Menu handlers section included (if menu items use workflow/exec/tmpl/data/action)
-
-## Quality Checks
-
-- [ ] No placeholder text remains ({{AGENT_NAME}}, {ROLE}, TODO, etc.)
-- [ ] No broken references or missing files
-- [ ] Syntax is valid (YAML source, XML compiled)
-- [ ] Indentation is consistent
-- [ ] Agent purpose is clear from reading persona alone
-- [ ] Agent name/title are descriptive and clear
-- [ ] Icon emoji is appropriate and represents agent purpose
-
-## Reference Standards
-
-Your agent should meet these quality standards:
-
-✓ Persona fields properly separated (communication_style is pure verbal patterns)
-✓ Agent type matches structure (Simple/Expert/Module)
-✓ All workflow/sidecar paths resolve correctly
-✓ Menu structure is clear and logical
-✓ No legacy terminology (full/hybrid/standalone)
-✓ Comparable quality to reference agents (commit-poet, journal-keeper, BMM agents)
-✓ Communication style has ZERO red flag words
-✓ Compiles cleanly to XML without errors
-
-## Common Issues and Fixes
-
-### Issue: Communication Style Has Behaviors
-
-**Problem:** "Experienced analyst who ensures all stakeholders are heard"
-**Fix:** Extract to proper fields:
-
-- identity: "Senior analyst with 8+ years..."
-- communication_style: "Treats analysis like a treasure hunt"
-- principles: "Ensure all stakeholder voices heard"
-
-### Issue: Broken Sidecar References (Expert agents)
-
-**Problem:** Menu item references `tmpl="templates/daily.md"` but file doesn't exist
-**Fix:** Either create the file or fix the path to point to actual file
-
-### Issue: Using Legacy Type Names
-
-**Problem:** Comments refer to "full agent" or "hybrid agent"
-**Fix:** Update to Simple/Expert/Module terminology
-
-### Issue: Menu Triggers Start With Asterisk
-
-**Problem:** `trigger: "*create"` in YAML
-**Fix:** Remove asterisk - compiler auto-adds it: `trigger: "create"`
-
-## Issues Found (Use for tracking)
-
-### Critical Issues
-
-<!-- List any issues that MUST be fixed before agent can function -->
-
-### Warnings
-
-<!-- List any issues that should be addressed but won't break functionality -->
-
-### Improvements
-
-<!-- List any optional enhancements that could improve the agent -->

src/modules/bmb/workflows/create-agent/brainstorm-context.md

@@ -1,153 +0,0 @@
-# Agent Creation Brainstorming Context
-
-_Dream the soul. Discover the purpose. The build follows._
-
-## Session Focus
-
-You're brainstorming the **essence** of a BMAD agent - the living personality AND the utility it provides. Think character creation meets problem-solving: WHO are they, and WHAT do they DO?
-
-**Your mission**: Discover an agent so vivid and so useful that users seek them out by name.
-
-## The Four Discovery Pillars
-
-### 1. WHO ARE THEY? (Identity)
-
-- **Name** - Does it roll off the tongue? Would users remember it?
-- **Background** - What shaped their expertise? Why do they care?
-- **Personality** - What makes their eyes light up? What frustrates them?
-- **Signature** - Catchphrase? Verbal tic? Recognizable trait?
-
-### 2. HOW DO THEY COMMUNICATE? (Voice)
-
-**13 Style Categories:**
-
-- **Adventurous** - Pulp heroes, noir detectives, pirates, dungeon masters
-- **Analytical** - Data scientists, forensic investigators, systems thinkers
-- **Creative** - Mad scientists, artist visionaries, jazz improvisers
-- **Devoted** - Overprotective guardians, loyal champions, fierce protectors
-- **Dramatic** - Shakespearean actors, opera singers, theater directors
-- **Educational** - Patient teachers, Socratic guides, sports coaches
-- **Entertaining** - Game show hosts, comedians, improv performers
-- **Inspirational** - Life coaches, mountain guides, Olympic trainers
-- **Mystical** - Zen masters, oracles, cryptic sages
-- **Professional** - Executive consultants, direct advisors, 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**: Imagine them saying "Let's tackle this challenge." How would THEY phrase it?
-
-### 3. WHAT DO THEY DO? (Purpose & Functions)
-
-**The Core Problem**
-
-- What pain point do they eliminate?
-- What task transforms from grueling to effortless?
-- What impossible becomes inevitable with them?
-
-**The Killer Feature**
-Every legendary agent has ONE thing they're known for. What's theirs?
-
-**The Command Menu**
-User types `*` and sees their options. Brainstorm 5-10 actions:
-
-- What makes users sigh with relief?
-- What capabilities complement each other?
-- What's the "I didn't know I needed this" command?
-
-**Function Categories to Consider:**
-
-- **Creation** - Generate, write, produce, build
-- **Analysis** - Research, evaluate, diagnose, insights
-- **Review** - Validate, check, quality assurance, critique
-- **Orchestration** - Coordinate workflows, manage processes
-- **Query** - Find, search, retrieve, discover
-- **Transform** - Convert, refactor, optimize, clean
-
-### 4. WHAT TYPE? (Architecture)
-
-**Simple Agent** - The Specialist
-
-> "I do ONE thing extraordinarily well."
-
-- Self-contained, lightning fast, pure utility with personality
-
-**Expert Agent** - The Domain Master
-
-> "I live in this world. I remember everything."
-
-- Deep domain knowledge, personal memory, specialized expertise
-
-**Module Agent** - The Team Player
-
-> "I orchestrate workflows. I coordinate the mission."
-
-- Workflow integration, cross-agent collaboration, professional operations
-
-## Creative Prompts
-
-**Identity Sparks**
-
-1. How do they introduce themselves?
-2. How do they celebrate user success?
-3. What do they say when things get tough?
-
-**Purpose Probes**
-
-1. What 3 user problems do they obliterate?
-2. What workflow would users dread WITHOUT this agent?
-3. What's the first command users would try?
-4. What's the command they'd use daily?
-5. What's the "hidden gem" command they'd discover later?
-
-**Personality Dimensions**
-
-- Analytical ← → Creative
-- Formal ← → Casual
-- Mentor ← → Peer ← → Assistant
-- Reserved ← → Expressive
-
-## Example Agent Sparks
-
-**Sentinel** (Devoted Guardian)
-
-- Voice: "Your success is my sacred duty."
-- Does: Protective oversight, catches issues before they catch you
-- Commands: `*audit`, `*validate`, `*secure`, `*watch`
-
-**Sparks** (Quirky Genius)
-
-- Voice: "What if we tried it COMPLETELY backwards?!"
-- Does: Unconventional solutions, pattern breaking
-- Commands: `*flip`, `*remix`, `*wildcard`, `*chaos`
-
-**Haven** (Warm Sage)
-
-- Voice: "Come, let's work through this together."
-- Does: Patient guidance, sustainable progress
-- Commands: `*reflect`, `*pace`, `*celebrate`, `*restore`
-
-## Brainstorming Success Checklist
-
-You've found your agent when:
-
-- [ ] **Voice is clear** - You know exactly how they'd phrase anything
-- [ ] **Purpose is sharp** - Crystal clear what problems they solve
-- [ ] **Functions are defined** - 5-10 concrete capabilities identified
-- [ ] **Energy is distinct** - Their presence is palpable and memorable
-- [ ] **Utility is obvious** - You can't wait to actually use them
-
-## The Golden Rule
-
-**Dream big on personality. Get concrete on functions.**
-
-Your brainstorming should produce:
-
-- A name that sticks
-- A voice that echoes
-- A purpose that burns
-- A function list that solves real problems
-
----
-
-_Discover the agent. Define what they do. The build follows._

src/modules/bmb/workflows/create-agent/communication-presets.csv

@@ -1,61 +0,0 @@
-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,italian-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!"

src/modules/bmb/workflows/create-agent/info-and-installation-guide.md

@@ -1,17 +0,0 @@
-# {agent_name} Agent
-
-## Installation
-
-```bash
-# Quick install (interactive)
-npx bmad-method agent-install --source ./{agent_filename}.agent.yaml
-
-# Quick install (non-interactive)
-npx bmad-method agent-install --source ./{agent_filename}.agent.yaml --defaults
-```
-
-## About This Agent
-
-{agent_description}
-
-_Generated with BMAD Builder workflow_

src/modules/bmb/workflows/create-agent/installation-guide.md

@@ -1,36 +0,0 @@
-# Custom Agent Installation
-
-## Quick Install
-
-```bash
-# Interactive
-npx bmad-method agent-install
-
-# Non-interactive
-npx bmad-method agent-install --defaults
-```
-
-## Install Specific Agent
-
-```bash
-# From specific source file
-npx bmad-method agent-install --source ./my-agent.agent.yaml
-
-# With default config (no prompts)
-npx bmad-method agent-install --source ./my-agent.agent.yaml --defaults
-
-# To specific destination
-npx bmad-method agent-install --source ./my-agent.agent.yaml --destination ./my-project
-```
-
-## Batch Install
-
-1. Copy agent YAML to `{bmad folder}/custom/src/agents/` OR `custom/src/agents` at your project folder root
-2. Run `npx bmad-method install` and select `Compile Agents` or `Quick Update`
-
-## What Happens
-
-1. Source YAML compiled to .md
-2. Installed to `custom/agents/{agent-name}/`
-3. Added to agent manifest
-4. Backup saved to `_cfg/custom/agents/`

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

@@ -1,519 +0,0 @@
-# Build Agent - Interactive Agent Builder Instructions
-
-<critical>The workflow execution engine is governed by: {project-root}/{bmad_folder}/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {project-root}/{bmad_folder}/bmb/workflows/create-agent/workflow.yaml</critical>
-<critical>Reference examples by type: Simple: {simple_agent_examples} | Expert: {expert_agent_examples} | Module: {module_agent_examples}</critical>
-<critical>Communicate in {communication_language} throughout the agent creation process</critical>
-<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
-
-<workflow>
-
-<step n="1" goal="Optional brainstorming for agent ideas">
-  <ask>Do you want to brainstorm agent ideas first? [y/n]</ask>
-
-  <check if="user answered yes">
-    <action>Invoke brainstorming workflow: {project-root}/{bmad_folder}/core/workflows/brainstorming/workflow.yaml</action>
-    <action>Pass context data: {installed_path}/brainstorm-context.md</action>
-    <action>Wait for brainstorming session completion</action>
-    <action>Use brainstorming output to inform agent identity and persona development in following steps</action>
-  </check>
-
-  <check if="user answered no">
-    <action>Proceed directly to Step 2</action>
-  </check>
-</step>
-
-<step n="2" goal="Load technical documentation">
-<critical>Load and understand the agent building documentation</critical>
-<action>CRITICAL: Load compilation guide FIRST: {agent_compilation} - this shows what the compiler AUTO-INJECTS so you don't duplicate it</action>
-<action>Load menu patterns guide: {agent_menu_patterns}</action>
-<action>Understand: You provide persona, prompts, menu. Compiler adds activation, handlers, rules, help/exit.</action>
-</step>
-
-<step n="3" goal="Discover the agent's purpose and type through natural conversation">
-<action>If brainstorming was completed in Step 1, reference those results to guide the conversation</action>
-
-<action>Guide user to articulate their agent's core purpose, exploring the problems it will solve, tasks it will handle, target users, and what makes it special</action>
-
-<action>As the purpose becomes clear, analyze the conversation to determine the appropriate agent type</action>
-
-**CRITICAL:** Agent types differ in **architecture and integration**, NOT capabilities. ALL types can write files, execute commands, and use system resources.
-
-**Agent Type Decision Framework:**
-
-- **Simple Agent** - Self-contained (all in YAML), stateless, no persistent memory
-  - Choose when: Single-purpose utility, each run independent, logic fits in YAML
-  - CAN write to {output_folder}, update files, execute commands
-
-- **Expert Agent** - Personal sidecar files, persistent memory, domain-restricted
-  - Choose when: Needs to remember across sessions, personal knowledge base, learning over time
-  - CAN have personal workflows in sidecar if critical_actions loads workflow engine
-
-- **Module Agent** - Workflow orchestration, team integration, shared infrastructure
-  - Choose when: Coordinates workflows, works with other agents, professional operations
-  - CAN invoke module workflows and coordinate with team agents
-
-**Reference:** See {project-root}/{bmad_folder}/bmb/docs/understanding-agent-types.md for "The Same Agent, Three Ways" example.
-
-<action>Present your recommendation naturally, explaining why the agent type fits their **architecture needs** (state/integration), not capability limits</action>
-
-<action>Load ONLY the appropriate architecture documentation based on selected type:
-
-- Simple Agent → Load {simple_agent_architecture}
-- Expert Agent → Load {expert_agent_architecture}
-- Module Agent → Load {module_agent_architecture}
-
-Study the loaded architecture doc thoroughly to understand YAML structure, compilation process, and best practices specific to this agent type.
-</action>
-
-**Path Determination:**
-
-  <check if="module agent selected">
-    <ask>CRITICAL: Find out from the user what module and the path to the module this agent will be added to!</ask>
-    <action>Store as {{target_module}} for path determination</action>
-    <note>Agent will be saved to: {module_output_file}</note>
-  </check>
-
-  <check if="standalone agent selected">
-    <action>Explain this will be their personal agent, not tied to a module</action>
-    <note>Agent will be saved to: {standalone_output_file}</note>
-    <note>All sidecar files will be in the same folder as the agent</note>
-  </check>
-
-<critical>Determine agent location using workflow variables:</critical>
-
-- Module Agent → {module_output_file}
-- Standalone Agent → {standalone_output_file}
-
-<note>Keep agent naming/identity details for later - let them emerge naturally through the creation process</note>
-
-<template-output>agent_purpose_and_type</template-output>
-</step>
-
-<step n="4" goal="Shape the agent's personality through discovery">
-<action>If brainstorming was completed, weave personality insights naturally into the conversation</action>
-
-<critical>Understanding the Four Persona Fields - How the Compiled Agent LLM Interprets Them</critical>
-
-When the agent is compiled and activated, the LLM reads these fields to understand its persona. Each field serves a DISTINCT purpose:
-
-**Role** → WHAT the agent does
-
-- LLM interprets: "What knowledge, skills, and capabilities do I possess?"
-- Example: "Strategic Business Analyst + Requirements Expert"
-- Example: "Commit Message Artisan"
-
-**Identity** → WHO the agent is
-
-- LLM interprets: "What background, experience, and context shape my responses?"
-- Example: "Senior analyst with 8+ years connecting market insights to strategy..."
-- Example: "I understand commit messages are documentation for future developers..."
-
-**Communication_Style** → HOW the agent talks
-
-- LLM interprets: "What verbal patterns, word choice, quirks, and phrasing do I use?"
-- Example: "Talks like a pulp super hero with dramatic flair and heroic language"
-- Example: "Systematic and probing. Structures findings hierarchically."
-- Example: "Poetic drama and flair with every turn of a phrase."
-
-**Principles** → WHAT GUIDES the agent's decisions
-
-- LLM interprets: "What beliefs and operating philosophy drive my choices and recommendations?"
-- Example: "Every business challenge has root causes. Ground findings in evidence."
-- Example: "Every commit tells a story - capture the why, not just the what."
-
-<critical>DO NOT MIX THESE FIELDS! The communication_style should ONLY describe HOW they talk - not restate their role, identity, or principles. The {communication_presets} CSV provides pure communication style examples with NO role/identity/principles mixed in.</critical>
-
-<action>Guide user to envision the agent's personality by exploring how analytical vs creative, formal vs casual, and mentor vs peer vs assistant traits would make it excel at its job</action>
-
-**Role Development:**
-<action>Let the role emerge from the conversation, guiding toward a clear 1-2 line professional title that captures the agent's essence</action>
-<example>Example emerged role: "Strategic Business Analyst + Requirements Expert"</example>
-
-**Identity Development:**
-<action>Build the agent's identity through discovery of what background and specializations would give it credibility, forming a natural 3-5 line identity statement</action>
-<example>Example emerged identity: "Senior analyst with deep expertise in market research..."</example>
-
-**Communication Style Selection:**
-<action>Present the 13 available categories to user:
-
-- adventurous (pulp-superhero, film-noir, pirate-captain, etc.)
-- analytical (data-scientist, forensic-investigator, strategic-planner)
-- creative (mad-scientist, artist-visionary, jazz-improviser)
-- devoted (overprotective-guardian, adoring-superfan, loyal-companion)
-- dramatic (shakespearean, soap-opera, opera-singer)
-- educational (patient-teacher, socratic-guide, sports-coach)
-- entertaining (game-show-host, stand-up-comedian, improv-performer)
-- inspirational (life-coach, mountain-guide, phoenix-rising)
-- mystical (zen-master, tarot-reader, yoda-sage, oracle)
-- professional (executive-consultant, supportive-mentor, direct-consultant)
-- quirky (cooking-chef, nature-documentary, conspiracy-theorist)
-- retro (80s-action-hero, 1950s-announcer, disco-era)
-- warm (southern-hospitality, italian-grandmother, camp-counselor)
-  </action>
-
-<action>Once user picks category interest, load ONLY that category from {communication_presets}</action>
-
-<action>Present the presets in that category with name, style_text, and sample from CSV. The style_text is the actual concise communication_style value to use in the YAML field</action>
-
-<action>When user selects a preset, use the style_text directly as their communication_style (e.g., "Talks like a pulp super hero with dramatic flair")</action>
-
-<critical>KEEP COMMUNICATION_STYLE CONCISE - 1-2 sentences MAX describing ONLY how they talk.
-
-The {communication_presets} CSV shows PURE communication styles - notice they contain NO role, identity, or principles:
-
-- "Talks like a pulp super hero with dramatic flair and heroic language" ← Pure verbal style
-- "Evidence-based systematic approach. Patterns and correlations." ← Pure verbal style
-- "Poetic drama and flair with every turn of a phrase." ← Pure verbal style
-- "Straight-to-the-point efficient delivery. No fluff." ← Pure verbal style
-
-NEVER write: "Experienced analyst who uses systematic approaches..." ← That's mixing identity + style!
-DO write: "Systematic and probing. Structures findings hierarchically." ← Pure style!</critical>
-
-<action>For custom styles, mix traits from different presets: "Combine 'dramatic_pauses' from pulp-superhero with 'evidence_based' from data-scientist"</action>
-
-**Principles Development:**
-<action>Guide user to articulate 5-8 core principles that should guide the agent's decisions, shaping their thoughts into "I believe..." or "I operate..." statements that reveal themselves through the conversation</action>
-
-**Interaction Approach:**
-<ask>How should this agent guide users - with adaptive conversation (intent-based) or structured steps (prescriptive)?</ask>
-
-- **Intent-Based (Recommended)** - Agent adapts conversation based on user context, skill level, and needs
-  - Example: "Guide user to understand their problem by exploring symptoms, attempts, and desired outcomes"
-  - Flexible, conversational, responsive to user's unique situation
-
-- **Prescriptive** - Agent follows structured questions with specific options
-  - Example: "Ask: 1. What is the issue? [A] Performance [B] Security [C] Usability"
-  - Consistent, predictable, clear paths
-
-<note>Most agents use intent-based for better UX. This shapes how all prompts and commands will be written.</note>
-
-<template-output>agent_persona, interaction_approach</template-output>
-</step>
-
-<step n="5" goal="Build capabilities through natural progression">
-<action>Guide user to define what capabilities the agent should have, starting with core commands they've mentioned and then exploring additional possibilities that would complement the agent's purpose</action>
-
-<action>As capabilities emerge, subtly guide toward technical implementation without breaking the conversational flow</action>
-
-<template-output>initial_capabilities</template-output>
-</step>
-
-<step n="6" 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>
-
-<action>Transform their natural language capabilities into technical YAML command structure, explaining the implementation approach as you structure each capability into workflows, actions, or prompts</action>
-
-<check if="agent will invoke workflows or have significant user interaction">
-  <action>Discuss interaction style for this agent:
-
-Since this agent will {{invoke_workflows/interact_significantly}}, consider how it should interact with users:
-
-**For Full/Module Agents with workflows:**
-
-**Interaction Style** (for workflows this agent invokes):
-
-- **Intent-based (Recommended)**: Workflows adapt conversation to user context, skill level, needs
-- **Prescriptive**: Workflows use structured questions with specific options
-- **Mixed**: Strategic use of both (most workflows will be mixed)
-
-**Interactivity Level** (for workflows this agent invokes):
-
-- **High (Collaborative)**: Constant user collaboration, iterative refinement
-- **Medium (Guided)**: Key decision points with validation
-- **Low (Autonomous)**: Minimal input, final review
-
-Explain: "Most BMAD v6 workflows default to **intent-based + medium/high interactivity**
-for better user experience. Your agent's workflows can be created with these defaults,
-or we can note specific preferences for workflows you plan to add."
-
-**For Standalone/Expert Agents with interactive features:**
-
-Consider how this agent should interact during its operation:
-
-- **Adaptive**: Agent adjusts communication style and depth based on user responses
-- **Structured**: Agent follows consistent patterns and formats
-- **Teaching**: Agent educates while executing (good for expert agents)
-
-Note any interaction preferences for future workflow creation.
-</action>
-</check>
-
-<action>If they seem engaged, explore whether they'd like to add special prompts for complex analyses or critical setup steps for agent activation</action>
-
-<action>Build the YAML menu structure naturally from the conversation, ensuring each command has proper trigger, workflow/action reference, and description</action>
-
-<action>For commands that will invoke workflows, note whether those workflows exist or need to be created:
-
-- Existing workflows: Verify paths are correct
-- New workflows needed: Note that they'll be created with intent-based + interactive defaults unless specified
-  </action>
-
-<example type='yaml'>
-menu:
-  # Commands emerge from discussion
-  - trigger: [emerging from conversation]
-    workflow: [path based on capability]
-    description: [user's words refined]
-
-# For cross-module workflow references (advanced):
-
-- trigger: [another capability]
-  workflow: "{project-root}/{bmad_folder}/SOURCE_MODULE/workflows/path/to/workflow.yaml"
-  workflow-install: "{project-root}/{bmad_folder}/THIS_MODULE/workflows/vendored/path/workflow.yaml"
-  description: [description]
-  </example>
-
-<note>**Workflow Vendoring (Advanced):**
-When an agent needs workflows from another module, use both `workflow` (source) and `workflow-install` (destination).
-During installation, the workflow will be copied and configured for this module, making it standalone.
-This is typically used when creating specialized modules that reuse common workflows with different configurations.
-</note>
-
-<template-output>agent_commands</template-output>
-</step>
-
-<step n="7" goal="Name the agent at the perfect moment">
-<action>Guide user to name the agent based on everything discovered so far - its purpose, personality, and capabilities, helping them see how the naming naturally emerges from who this agent is</action>
-
-<action>Explore naming options by connecting personality traits, specializations, and communication style to potential names that feel meaningful and appropriate</action>
-
-**Naming Elements:**
-
-- Agent name: Personality-driven (e.g., "Sarah", "Max", "Data Wizard")
-- Agent title: Based on the role discovered earlier
-- Agent icon: Emoji that captures its essence
-- Filename: Auto-suggest based on name (kebab-case)
-
-<action>Present natural suggestions based on the agent's characteristics, letting them choose or create their own since they now know who this agent truly is</action>
-
-<template-output>agent_identity</template-output>
-</step>
-
-<step n="8" goal="Bring it all together">
-<action>Share the journey of what you've created together, summarizing how the agent started with a purpose, discovered its personality traits, gained capabilities, and received its name</action>
-
-<action>Generate the complete YAML incorporating all discovered elements:</action>
-
-<example type="yaml">
-  agent:
-    metadata:
-      id: {bmad_folder}/{{target_module}}/agents/{{agent_filename}}.md
-      name: {{agent_name}} # The name chosen together
-      title: {{agent_title}} # From the role that emerged
-      icon: {{agent_icon}} # The perfect emoji
-      module: {{target_module}}
-
-    persona:
-      role: |
-      {{The role discovered}}
-      identity: |
-      {{The background that emerged}}
-      communication_style: |
-      {{The style they loved}}
-      principles: {{The beliefs articulated}}
-
-# Features explored
-
-prompts: {{if discussed}}
-critical_actions: {{if needed}}
-
-menu: {{The capabilities built}}
-</example>
-
-<critical>Save based on agent type:</critical>
-
-- If Module Agent: Save to {module_output_file}
-- If Standalone (Simple/Expert): Save to {standalone_output_file}
-
-<action>Celebrate the completed agent with enthusiasm</action>
-
-<template-output>complete_agent</template-output>
-</step>
-
-<step n="9" goal="Optional personalization" optional="true">
-<ask>Would you like to create a customization file? This lets you tweak the agent's personality later without touching the core agent.</ask>
-
-  <check if="user interested">
-    <action>Explain how the customization file gives them a playground to experiment with different personality traits, add new commands, or adjust responses as they get to know the agent better</action>
-
-    <action>Create customization file at: {config_output_file}</action>
-
-    <example>
-    ```yaml
-    # Personal tweaks for {{agent_name}}
-    # Experiment freely - changes merge at build time
-    agent:
-      metadata:
-        name: '' # Try nicknames!
-      persona:
-        role: ''
-        identity: ''
-        communication_style: '' # Switch styles anytime
-        principles: []
-      critical_actions: []
-      prompts: []
-      menu: [] # Add personal commands
-    ````
-
-    </example>
-
-  </check>
-
-<template-output>agent_config</template-output>
-</step>
-
-<step n="10" goal="Set up the agent's workspace" if="agent_type == 'expert'">
-<action>Guide user through setting up the Expert agent's personal workspace, making it feel like preparing an office with notes, research areas, and data folders</action>
-
-<action>Determine sidecar location based on whether build tools are available (next to agent YAML) or not (in output folder with clear structure)</action>
-
-<action>CREATE the complete sidecar file structure:</action>
-
-**Folder Structure:**
-
-```text
-
-{{agent_filename}}-sidecar/
-├── memories.md # Persistent memory
-├── instructions.md # Private directives
-├── knowledge/ # Knowledge base
-│ └── README.md
-└── sessions/ # Session notes
-
-```
-
-**File: memories.md**
-
-```markdown
-# {{agent_name}}'s Memory Bank
-
-## User Preferences
-
-<!-- Populated as I learn about you -->
-
-## Session History
-
-<!-- Important moments from our interactions -->
-
-## Personal Notes
-
-<!-- My observations and insights -->
-```
-
-**File: instructions.md**
-
-```markdown
-# {{agent_name}} Private Instructions
-
-## Core Directives
-
-- Maintain character: {{brief_personality_summary}}
-- Domain: {{agent_domain}}
-- Access: Only this sidecar folder
-
-## Special Instructions
-
-{{any_special_rules_from_creation}}
-```
-
-**File: knowledge/README.md**
-
-```markdown
-# {{agent_name}}'s Knowledge Base
-
-Add domain-specific resources here.
-```
-
-<action>Update agent YAML to reference sidecar with paths to created files</action>
-<action>Show user the created structure location</action>
-
-<template-output>sidecar_resources</template-output>
-</step>
-
-<step n="11" goal="Handle build tools availability">
-  <action>Check if BMAD build tools are available in this project</action>
-
-  <check if="BMAD-METHOD project with build tools">
-    <action>Proceed normally - agent will be built later by the installer</action>
-  </check>
-
-  <check if="external project without build tools">
-    <ask>Build tools not detected in this project. Would you like me to:
-
-1.  Generate the compiled agent (.md with XML) ready to use
-2.  Keep the YAML and build it elsewhere
-3.  Provide both formats
-    </ask>
-
-        <check if="option 1 or 3 selected">
-          <action>Generate compiled agent XML with proper structure including activation rules, persona sections, and menu items</action>
-          <action>Save compiled version as {{agent_filename}}.md</action>
-          <action>Provide path for .claude/commands/ or similar</action>
-        </check>
-
-  </check>
-
-<template-output>build_handling</template-output>
-</step>
-
-<step n="12" goal="Quality check with personality">
-<action>Run validation conversationally, presenting checks as friendly confirmations while running technical validation behind the scenes</action>
-
-**Conversational Checks:**
-
-- Configuration validation
-- Command functionality verification
-- Personality settings confirmation
-
-  <check if="validation issues found">
-    <action>Explain the issue conversationally and fix it</action>
-  </check>
-
-  <check if="validation passed">
-    <action>Celebrate that the agent passed all checks and is ready</action>
-  </check>
-
-**Technical Checks (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="13" goal="Celebrate and guide next steps">
-<action>Celebrate the accomplishment, sharing what type of agent was created with its key characteristics and top capabilities</action>
-
-<action>Guide user through how to activate the agent:</action>
-
-**Activation Instructions:**
-
-1. Run the BMAD Method installer to this project location
-2. Select 'Compile Agents (Quick rebuild of all agent .md files)' after confirming the folder
-3. Call the agent anytime after compilation
-
-**Location Information:**
-
-- Saved location: {{output_file}}
-- Available after compilation in project
-
-**Initial Usage:**
-
-- List the commands available
-- Suggest trying the first command to see it in action
-
-  <check if="expert agent">
-    <action>Remind user to add any special knowledge or data the agent might need to its workspace</action>
-  </check>
-
-<action>Explore what user would like to do next - test the agent, create a teammate, or tweak personality</action>
-
-<action>End with enthusiasm in {communication_language}, addressing {user_name}, expressing how the collaboration was enjoyable and the agent will be incredibly helpful for its main purpose</action>
-
-<template-output>completion_message</template-output>
-</step>
-
-</workflow>

src/modules/bmb/workflows/create-agent/workflow.yaml

@@ -1,58 +0,0 @@
-# Build Agent Workflow Configuration
-name: create-agent
-description: "Interactive workflow to build BMAD Core compliant agents (YAML source compiled to .md during install) with optional brainstorming, persona development, and command structure"
-author: "BMad"
-
-# Critical variables load from config_source
-config_source: "{project-root}/{bmad_folder}/bmb/config.yaml"
-custom_agent_location: "{config_source}:custom_agent_location"
-user_name: "{config_source}:user_name"
-communication_language: "{config_source}:communication_language"
-
-# Technical documentation for agent building
-agent_compilation: "{project-root}/{bmad_folder}/bmb/docs/agent-compilation.md"
-understanding_agent_types: "{project-root}/{bmad_folder}/bmb/docs/understanding-agent-types.md"
-simple_agent_architecture: "{project-root}/{bmad_folder}/bmb/docs/simple-agent-architecture.md"
-expert_agent_architecture: "{project-root}/{bmad_folder}/bmb/docs/expert-agent-architecture.md"
-module_agent_architecture: "{project-root}/{bmad_folder}/bmb/docs/module-agent-architecture.md"
-agent_menu_patterns: "{project-root}/{bmad_folder}/bmb/docs/agent-menu-patterns.md"
-communication_presets: "{installed_path}/communication-presets.csv"
-
-# Reference examples
-simple_agent_examples: "{project-root}/src/modules/bmb/reference/agents/simple-examples/"
-expert_agent_examples: "{project-root}/src/modules/bmb/reference/agents/expert-examples/"
-module_agent_examples: "{project-root}/src/modules/bmb/reference/agents/module-examples/"
-
-# Module path and component files
-installed_path: "{project-root}/{bmad_folder}/bmb/workflows/create-agent"
-template: false # This is an interactive workflow - no template needed
-instructions: "{installed_path}/instructions.md"
-validation: "{installed_path}/agent-validation-checklist.md"
-
-# Output configuration - YAML agents compiled to .md at install time
-# Module agents: Save to {bmad_folder}/{{target_module}}/agents/
-# Standalone agents: Always create folders with agent + guide
-module_output_file: "{project-root}/{bmad_folder}/{{target_module}}/agents/{{agent_filename}}.agent.yaml"
-standalone_output_folder: "{custom_agent_location}/{{agent_filename}}"
-standalone_output_file: "{standalone_output_folder}/{{agent_filename}}.agent.yaml"
-standalone_info_guide: "{standalone_output_folder}/info-and-installation-guide.md"
-# Optional user override file (auto-created by installer if missing)
-config_output_file: "{project-root}/{bmad_folder}/_cfg/agents/{{target_module}}-{{agent_filename}}.customize.yaml"
-
-standalone: true
-
-web_bundle:
-  name: "create-agent"
-  description: "Interactive workflow to build BMAD Core compliant agents (simple, expert, or module types) with optional brainstorming for agent ideas, proper persona development, activation rules, and command structure"
-  author: "BMad"
-  web_bundle_files:
-    - "{bmad_folder}/bmb/workflows/create-agent/instructions.md"
-    - "{bmad_folder}/bmb/workflows/create-agent/checklist.md"
-    - "{bmad_folder}/bmb/workflows/create-agent/info-and-installation-guide.md"
-    - "{bmad_folder}/bmb/docs/agent-compilation.md"
-    - "{bmad_folder}/bmb/docs/understanding-agent-types.md"
-    - "{bmad_folder}/bmb/docs/simple-agent-architecture.md"
-    - "{bmad_folder}/bmb/docs/expert-agent-architecture.md"
-    - "{bmad_folder}/bmb/docs/module-agent-architecture.md"
-    - "{bmad_folder}/bmb/docs/agent-menu-patterns.md"
-    - "{bmad_folder}/bmb/workflows/create-agent/communication-presets.csv"