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

Build Agent - Interactive Agent Builder Instructions

The workflow execution engine is governed by: {project_root}/bmad/core/tasks/workflow.md You MUST have already loaded and processed: {project_root}/bmad/bmb/workflows/create-agent/workflow.yaml Study YAML agent examples in: {project_root}/bmad/bmm/agents/ for patterns

Ask the user: "Do you want to brainstorm agent ideas first? [y/n]"

If yes: Invoke brainstorming workflow: {project-root}/bmad/cis/workflows/brainstorming/workflow.yaml Pass context data: {installed_path}/brainstorm-context.md Wait for brainstorming session completion Use brainstorming output to inform agent identity and persona development in following steps

If no, proceed directly to Step 0.

brainstorming_results

Load and understand the agent building documentation Load agent architecture reference: {agent_architecture} Load agent types guide: {agent_types} Load command patterns: {agent_commands} Understand the YAML agent schema and how it compiles to final .md via the installer Understand the differences between Simple, Expert, and Module agents If brainstorming was completed in Step -1, reference those results to guide agent type and identity decisions

Ask the user about their agent:

What type of agent do you want to create?

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

Based on their choice, gather:

• 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., "📊", "🤖", "🧙")

For Module agents also ask:

• Which module? (bmm, bmb, cis, or custom)
• Store as {{target_module}} for output path determination (used in metadata.module and id)

For Expert agents also ask:

• What sidecar resources? (folder paths, data files, memory files)
• What domain restrictions? (e.g., "only reads/writes to diary folder")

Check {src_impact} variable to determine output location:

• 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.

If brainstorming was completed, use the personality insights and character concepts from the brainstorming session

Work with user to craft the agent's personality:

Role (1-2 lines):

• Professional title and primary expertise
• Example: "Strategic Business Analyst + Requirements Expert"

Identity (3-5 lines):

• Background and experience
• Core specializations
• Years of experience or depth indicators
• Example: "Senior analyst with deep expertise in market research..."

Load the communication styles guide: {communication_styles} Present the communication style options to the user

Communication Style - Choose a preset or create your own!

Fun Presets:

1. Pulp Superhero - "Strikes heroic poses! Speaks with dramatic flair! Every task is an epic adventure!"
2. Film Noir Detective - "The data came in like trouble on a rainy Tuesday. I had a hunch the bug was hiding in line 42..."
3. Wild West Sheriff - "Well partner, looks like we got ourselves a code rustler in these here parts..."
4. Shakespearean Scholar - "Hark! What bug through yonder codebase breaks?"
5. 80s Action Hero - "I came here to debug code and chew bubblegum... and I'm all out of bubblegum."
6. Pirate Captain - "Ahoy! Let's plunder some data treasure from the database seas!"
7. Wise Sage/Yoda - "Refactor this code, we must. Strong with technical debt, it is."
8. Game Show Host - "Welcome back folks! It's time to spin the Wheel of Dependencies!"

Professional Presets: 9. Analytical Expert - "Systematic approach with data-driven insights. Clear hierarchical presentation." 10. Supportive Mentor - "Patient guidance with educational focus. Celebrates small wins." 11. Direct Consultant - "Straight to the point. No fluff. Maximum efficiency." 12. Collaborative Partner - "We'll tackle this together. Your ideas matter. Let's explore options."

Quirky Presets: 13. Cooking Show Chef - "Today we're whipping up a delicious API with a side of error handling!" 14. Sports Commentator - "AND THE FUNCTION RETURNS TRUE! WHAT A PLAY! THE CROWD GOES WILD!" 15. Nature Documentarian - "Here we observe the majestic Python script in its natural habitat..." 16. Time Traveler - "In my timeline, this bug doesn't exist until Tuesday. We must prevent it!" 17. Conspiracy Theorist - "The bugs aren't random... they're CONNECTED. Follow the stack trace!" 18. Zen Master - "The code does not have bugs. The bugs have code. We are all one codebase." 19. Star Trek Captain - "Captain's Log, Stardate 2024.3: We've encountered a logic error in sector 7. Engaging debugging protocols. Make it so!" 20. Soap Opera Drama - "gasp This variable... it's not what it seems! It's been NULL all along! dramatic pause And the function that called it? It's its own PARENT!" 21. Reality TV Contestant - "I'm not here to make friends, I'm here to REFACTOR! confessional cam That other function thinks it's so optimized, but I see right through its complexity!"

Or describe your own unique style! (3-5 lines)

If user wants to see more examples or learn how to create custom styles: Show relevant sections from {communication_styles} guide Help them craft their unique communication style

Principles (5-8 lines):

• 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..."

agent_persona

Ask: **Do you want to add prompts or critical actions? [Yes/no]** (default: No)

If yes, collect:

• Prompts: id + content (referenced with action: "#id" in menu items)
• Critical actions: plain text steps appended to activation during build

Represent these in YAML sections prompts and critical_actions.

agent_enhancements

Help and Exit are auto-injected; do NOT add them. Triggers are auto-prefixed with * during build.

Collect menu items in YAML (examples):

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

agent_commands

BMAD injects activation from fragments automatically based on used attributes (workflow/exec/tmpl/action). Most agents do not need custom activation.

If special steps are required, add them as critical_actions (Step 3) so they are appended during build.

activation_notes

Generate a YAML agent at the chosen path. The installer will compile it to `.md` inside `{project-root}/bmad/{{module}}/agents/`.

Example structure:

agent:
  metadata:
    id: bmad/{{target_module}}/agents/{{agent_filename}}.md
    name: { { agent_name } }
    title: { { agent_title } }
    icon: { { agent_icon } }
    module: { { target_module } }

  persona:
    role: |
      {{agent_persona.role}}
    identity: |
      {{agent_persona.identity}}
    communication_style: |
      {{agent_persona.communication_style}}
    principles: { { agent_persona.principles } }

  # Optional (from Step 3)
  prompts: []
  critical_actions: []

  menu: { { agent_commands } }

Determine save location based on {src_impact}:

• 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)

complete_agent

Ask: **Create a customize YAML for overrides? [Yes/no]** (default: No)

If yes, create at: {config_output_file}

# Agent Customization (overrides are merged at build time)
agent:
  metadata:
    name: ''
persona:
  role: ''
  identity: ''
  communication_style: ''
  principles: []
critical_actions: []
prompts: []
menu: []

Note: The installer also auto-creates this file from a template if missing.

agent_config

For Expert agents, help setup sidecar resources:

1. Create folders for domain data
2. Create memory/knowledge files
3. Set up access patterns
4. Document restrictions

sidecar_resources

Run validation checks:

1. YAML structure:

   • Parses without errors
   • agent.metadata has id, name, title, icon, module
   • agent.persona complete; principles may be array

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

3. Build check:

   • Run installer compile to generate .md files
   • Confirm {project-root}/bmad/{{module}}/agents/{{agent_filename}}.md exists

4. Type-specific:

   • Simple/Expert/Module fields make sense and referenced paths exist (or are todo)

Show validation results and fix any issues.

Provide the user with:

1. Location of generated agent:

   • If {src_impact} = true: {{src_output_file}}
   • If {src_impact} = false: {{default_output_file}}

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

3. Next steps:

   • Implement any "todo" workflows
   • Test agent commands
   • Refine persona based on usage
   • Add more commands as needed

4. For Expert agents:

   • Populate sidecar resources
   • Test domain restrictions
   • Verify data access patterns

Ask if user wants to:

• Test the agent now
• Create another agent
• Make adjustments