# 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:

```yaml
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:**

```yaml
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:**

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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.

```yaml
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:

```yaml
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)

```yaml
# 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

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

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

### Bad Patterns

```yaml
# 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

```yaml
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

```yaml
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

```yaml
# 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

```yaml
# 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

```yaml
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:

```yaml
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

```yaml
# 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

```yaml
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

```yaml
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

```yaml
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

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

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

### Including Auto-Injected Items

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

  - trigger: exit
    description: 'Exit agent'
```

### Missing Prompt Reference

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

### Hardcoded Paths

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