Midtrans-Middleware/.bmad/bmb/docs/agent-menu-patterns.md

BMAD Agent Menu Patterns

Design patterns for agent menus in YAML source files.

Menu Structure

Agents define menus in YAML, with triggers auto-prefixed with * during compilation:

menu:
  - trigger: action-name
    [handler]: [value]
    description: 'What this command does'

Note: *help and *exit are auto-injected by the compiler - DO NOT include them.

Handler Types

1. Action Handler (Prompts & Inline)

For simple and expert agents with self-contained logic.

Reference to Prompt ID:

prompts:
  - id: analyze-code
    content: |
      <instructions>
      Analyze the provided code for patterns and issues.
      </instructions>

      <process>
      1. Identify code structure
      2. Check for anti-patterns
      3. Suggest improvements
      </process>      

menu:
  - trigger: analyze
    action: '#analyze-code'
    description: 'Analyze code patterns'

Inline Instruction:

menu:
  - trigger: quick-check
    action: 'Perform a quick syntax validation on the current file'
    description: 'Quick syntax check'

When to Use:

• Simple/Expert agents with self-contained operations
• #id for complex, multi-step prompts
• Inline text for simple, one-line instructions

2. Workflow Handler

For module agents orchestrating multi-step processes.

menu:
  - trigger: create-prd
    workflow: '{project-root}/.bmad/bmm/workflows/prd/workflow.yaml'
    description: 'Create Product Requirements Document'

  - trigger: brainstorm
    workflow: '{project-root}/.bmad/core/workflows/brainstorming/workflow.yaml'
    description: 'Guided brainstorming session'

  # Placeholder for unimplemented workflows
  - trigger: future-feature
    workflow: 'todo'
    description: 'Coming soon'

When to Use:

• Module agents with workflow integration
• Multi-step document generation
• Complex interactive processes
• Use "todo" for planned but unimplemented features

3. Exec Handler

For executing tasks directly.

menu:
  - trigger: validate
    exec: '{project-root}/.bmad/core/tasks/validate-workflow.xml'
    description: 'Validate document structure'

  - trigger: advanced-elicitation
    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
    description: 'Advanced elicitation techniques'

When to Use:

• Single-operation tasks
• Core system operations
• Utility functions

4. Template Handler

For document generation with templates.

menu:
  - trigger: create-brief
    exec: '{project-root}/.bmad/core/tasks/create-doc.xml'
    tmpl: '{project-root}/.bmad/bmm/templates/brief.md'
    description: 'Create project brief'

When to Use:

• Template-based document creation
• Combine exec with tmpl path
• Structured output generation

5. Data Handler

Universal attribute for supplementary information.

menu:
  - trigger: team-standup
    exec: '{project-root}/.bmad/bmm/tasks/standup.xml'
    data: '{project-root}/.bmad/_cfg/agent-manifest.csv'
    description: 'Run team standup'

  - trigger: analyze-metrics
    action: 'Analyze these metrics and identify trends'
    data: '{project-root}/_data/metrics.json'
    description: 'Analyze performance metrics'

When to Use:

• Add to ANY handler type
• Reference data files (CSV, JSON, YAML)
• Provide context for operations

Platform-Specific Menus

Control visibility based on deployment target:

menu:
  - trigger: git-flow
    exec: '{project-root}/.bmad/bmm/tasks/git-flow.xml'
    description: 'Git workflow operations'
    ide-only: true # Only in IDE environments

  - trigger: advanced-elicitation
    exec: '{project-root}/.bmad/core/tasks/advanced-elicitation.xml'
    description: 'Advanced elicitation'
    web-only: true # Only in web bundles

Trigger Naming Conventions

Action-Based (Recommended)

# Creation
- trigger: create-prd
- trigger: build-module
- trigger: generate-report

# Analysis
- trigger: analyze-requirements
- trigger: review-code
- trigger: validate-architecture

# Operations
- trigger: update-status
- trigger: sync-data
- trigger: deploy-changes

Domain-Based

# Development
- trigger: brainstorm
- trigger: architect
- trigger: refactor

# Project Management
- trigger: sprint-plan
- trigger: retrospective
- trigger: standup

Bad Patterns

# TOO VAGUE
- trigger: do
- trigger: run
- trigger: process

# TOO LONG
- trigger: create-comprehensive-product-requirements-document

# NO VERB
- trigger: prd
- trigger: config

Menu Organization

Recommended Order

menu:
  # Note: *help auto-injected first by compiler

  # 1. Primary workflows (main value)
  - trigger: workflow-init
    workflow: '...'
    description: 'Start here - initialize workflow'

  - trigger: create-prd
    workflow: '...'
    description: 'Create PRD'

  # 2. Secondary operations
  - trigger: validate
    exec: '...'
    description: 'Validate document'

  # 3. Utilities
  - trigger: party-mode
    workflow: '...'
    description: 'Multi-agent discussion'

  # Note: *exit auto-injected last by compiler

Grouping by Phase

menu:
  # Analysis Phase
  - trigger: brainstorm
    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
    description: 'Brainstorm ideas'

  - trigger: research
    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/research/workflow.yaml'
    description: 'Conduct research'

  # Planning Phase
  - trigger: prd
    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
    description: 'Create PRD'

  - trigger: architecture
    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
    description: 'Design architecture'

Description Best Practices

Good Descriptions

# Clear action + object
- description: 'Create Product Requirements Document'

# Specific outcome
- description: 'Analyze security vulnerabilities'

# User benefit
- description: 'Optimize code for performance'

# Context when needed
- description: 'Start here - initialize workflow path'

Poor Descriptions

# Too vague
- description: 'Process'

# Technical jargon
- description: 'Execute WF123'

# Missing context
- description: 'Run'

# Redundant with trigger
- description: 'Create PRD' # trigger: create-prd (too similar)

Prompts Section (Simple/Expert Agents)

Prompt Structure

prompts:
  - id: unique-identifier
    content: |
      <instructions>
      What this prompt accomplishes
      </instructions>

      <process>
      1. First step
      {{#if custom_option}}
      2. Conditional step
      {{/if}}
      3. Final step
      </process>

      <output_format>
      Expected structure of results
      </output_format>      

Semantic XML Tags in Prompts

Use XML tags to structure prompt content:

• <instructions> - What to do
• <process> - Step-by-step approach
• <output_format> - Expected results
• <examples> - Sample outputs
• <constraints> - Limitations
• <context> - Background information

Handlebars in Prompts

Customize based on install_config:

prompts:
  - id: analyze
    content: |
      {{#if detailed_mode}}
      Perform comprehensive analysis with full explanations.
      {{/if}}
      {{#unless detailed_mode}}
      Quick analysis focusing on key points.
      {{/unless}}

      Address {{user_name}} in {{communication_style}} tone.      

Path Variables

Always Use Variables

# GOOD - Portable paths
workflow: "{project-root}/.bmad/bmm/workflows/prd/workflow.yaml"
exec: "{project-root}/.bmad/core/tasks/validate.xml"
data: "{project-root}/_data/metrics.csv"

# BAD - Hardcoded paths
workflow: "/Users/john/project/.bmad/bmm/workflows/prd/workflow.yaml"
exec: "../../../core/tasks/validate.xml"

Available Variables

• {project-root} - Project root directory
• .bmad - BMAD installation folder
• {agent-folder} - Agent installation directory (Expert agents)
• {output_folder} - Document output location
• {user_name} - User's name from config
• {communication_language} - Language preference

Complete Examples

Simple Agent Menu

prompts:
  - id: format-code
    content: |
      <instructions>
      Format the provided code according to style guidelines.
      </instructions>

      Apply:
      - Consistent indentation
      - Proper spacing
      - Clear naming conventions      

menu:
  - trigger: format
    action: '#format-code'
    description: 'Format code to style guidelines'

  - trigger: lint
    action: 'Check code for common issues and anti-patterns'
    description: 'Lint code for issues'

  - trigger: suggest
    action: 'Suggest improvements for code readability'
    description: 'Suggest improvements'

Expert Agent Menu

critical_actions:
  - 'Load {agent-folder}/memories.md'
  - 'Follow {agent-folder}/instructions.md'
  - 'ONLY access {agent-folder}/'

prompts:
  - id: reflect
    content: |
      Guide {{user_name}} through reflection on recent entries.
      Reference patterns from memories.md naturally.      

menu:
  - trigger: write
    action: '#reflect'
    description: 'Write journal entry'

  - trigger: save
    action: 'Update {agent-folder}/memories.md with session insights'
    description: "Save today's session"

  - trigger: patterns
    action: 'Analyze recent entries for recurring themes'
    description: 'View patterns'

Module Agent Menu

menu:
  - trigger: workflow-init
    workflow: '{project-root}/.bmad/bmm/workflows/workflow-status/init/workflow.yaml'
    description: 'Initialize workflow path (START HERE)'

  - trigger: brainstorm
    workflow: '{project-root}/.bmad/bmm/workflows/1-analysis/brainstorm/workflow.yaml'
    description: 'Guided brainstorming'

  - trigger: prd
    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/prd/workflow.yaml'
    description: 'Create PRD'

  - trigger: architecture
    workflow: '{project-root}/.bmad/bmm/workflows/2-planning/architecture/workflow.yaml'
    description: 'Design architecture'

  - trigger: party-mode
    workflow: '{project-root}/.bmad/core/workflows/party-mode/workflow.yaml'
    description: 'Multi-agent discussion'

Validation Checklist

• No duplicate triggers
• Triggers don't start with * (auto-added)
• Every item has a description
• Paths use variables, not hardcoded
• #id references exist in prompts section
• Workflow paths resolve or are "todo"
• No *help or *exit (auto-injected)
• Descriptions are clear and action-oriented
• Platform-specific flags used correctly (ide-only, web-only)

Common Mistakes

Duplicate Triggers

# BAD - compiler will fail
- trigger: analyze
  action: '#first'
  description: 'First analysis'

- trigger: analyze
  action: '#second'
  description: 'Second analysis'

Including Auto-Injected Items

# BAD - these are auto-injected
menu:
  - trigger: help
    description: 'Show help'

  - trigger: exit
    description: 'Exit agent'

Missing Prompt Reference

# BAD - prompt id doesn't exist
menu:
  - trigger: analyze
    action: '#nonexistent-prompt'
    description: 'Analysis'

Hardcoded Paths

# BAD - not portable
menu:
  - trigger: run
    workflow: '/absolute/path/to/workflow.yaml'
    description: 'Run workflow'