BMAD Agent Command Patterns Reference

LLM-Optimized Guide for Command Design

Important: How to Process Action References

When executing agent commands, understand these reference patterns:

```xml

Description → Execute the text “do this specific thing” directly

Description → Find in the current agent and execute its content

Description → Load and execute the external file ```

The # prefix is your signal that this is an internal XML node reference, not a file path.

Command Anatomy

Basic Structure

<menu>
  <item cmd="*trigger" [attributes]>Description</item>
</menu>

Components:

• cmd - The trigger word (always starts with *)
• attributes - Action directives (optional):
  • run-workflow - Path to workflow YAML
  • exec - Path to task/operation
  • tmpl - Path to template (used with exec)
  • action - Embedded prompt/instruction
  • data - Path to supplementary data (universal)
• Description - What shows in menu

Command Types

Quick Reference:

1. Workflow Commands - Execute multi-step workflows (run-workflow)
2. Task Commands - Execute single operations (exec)
3. Template Commands - Generate from templates (exec + tmpl)
4. Meta Commands - Agent control (no attributes)
5. Action Commands - Embedded prompts (action)
6. Embedded Commands - Logic in persona (no attributes)

Universal Attributes:

• data - Can be added to ANY command type for supplementary info
• if - Conditional execution (advanced pattern)
• params - Runtime parameters (advanced pattern)

1. Workflow Commands

Execute complete multi-step processes

```xml

Create Product Requirements Document

Validate PRD Against Checklist

Validate Document (auto-discover checklist)

Analyze dataset (workflow coming soon) ```

Workflow Attributes:

• run-workflow - Execute a workflow to create documents
• validate-workflow - Validate an existing document against its checklist
• workflow - (optional with validate-workflow) Specify the workflow.yaml directly

Best Practices:

• Use descriptive trigger names
• Always use variable paths
• Mark incomplete as “todo”
• Description should be clear action
• Include validation commands for workflows that produce documents

2. Task Commands

Execute single operations

```xml

Validate document against checklist

Run agile team standup ```

Data Property:

• Can be used with any command type
• Provides additional reference or context
• Path to supplementary files or resources
• Loaded at runtime for command execution

3. Template Commands

Generate documents from templates

<item cmd="*brief"
   exec="{project-root}/bmad/core/tasks/create-doc.md"
   tmpl="{project-root}/bmad/bmm/templates/brief.md">
  Produce Project Brief
</item>

<item cmd="*competitor-analysis"
   exec="{project-root}/bmad/core/tasks/create-doc.md"
   tmpl="{project-root}/bmad/bmm/templates/competitor.md"
   data="{project-root}/bmad/_data/market-research.csv">
  Produce Competitor Analysis
</item>

4. Meta Commands

Agent control and information

```xml

Show numbered cmd list Exit with confirmation

Toggle Yolo Mode Show current status Show configuration ```

5. Action Commands

Direct prompts embedded in commands (Simple agents)

Simple Action (Inline)

```xml

List Available Tasks

Summarize Document ```

Complex Action (Referenced)

For multiline/complex prompts, define them separately and reference by id:

<agent name="Research Assistant">
  <!-- Define complex prompts as separate nodes -->
  <prompts>
    <prompt id="deep-analysis">
      Perform a comprehensive analysis following these steps:
      1. Identify the main topic and key themes
      2. Extract all supporting evidence and data points
      3. Analyze relationships between concepts
      4. Identify gaps or contradictions
      5. Generate insights and recommendations
      6. Create an executive summary
      Format the output with clear sections and bullet points.
    </prompt>

    <prompt id="literature-review">
      Conduct a systematic literature review:
      1. Summarize each source's main arguments
      2. Compare and contrast different perspectives
      3. Identify consensus points and controversies
      4. Evaluate the quality and relevance of sources
      5. Synthesize findings into coherent themes
      6. Highlight research gaps and future directions
      Include proper citations and references.
    </prompt>
  </prompts>

  <!-- Commands reference the prompts by id -->
  <menu>
    <item cmd="*help">Show numbered cmd list</item>

    <item cmd="*deep-analyze"
       action="#deep-analysis">
      <!-- The # means: use the <prompt id="deep-analysis"> defined above -->
      Perform Deep Analysis
    </item>

    <item cmd="*review-literature"
       action="#literature-review"
       data="{project-root}/bmad/_data/sources.csv">
      Conduct Literature Review
    </item>

    <item cmd="*exit">Exit with confirmation</item>
  </menu>
</agent>

Reference Convention:

• action="#prompt-id" means: “Find and execute the node with id=‘prompt-id’ within this agent”
• action="inline text" means: “Execute this text directly as the prompt”
• exec="{path}" means: “Load and execute external file at this path”
• The # prefix signals to the LLM: “This is an internal reference - look for a prompt node with this ID within the current agent XML”

LLM Processing Instructions: When you see action="#some-id" in a command:

1. Look for <prompt id="some-id"> within the same agent
2. Use the content of that prompt node as the instruction
3. If not found, report error: “Prompt ‘some-id’ not found in agent”

Use Cases:

• Quick operations (inline action)
• Complex multi-step processes (referenced prompt)
• Self-contained agents with task-like capabilities
• Reusable prompt templates within agent

6. Embedded Commands

Logic embedded in agent persona (Simple agents)

```xml

Perform calculation Convert format Generate output ```

Command Naming Conventions

Action-Based Naming

*create-    <!-- Generate new content -->
*build-     <!-- Construct components -->
*analyze-   <!-- Examine and report -->
*validate-  <!-- Check correctness -->
*generate-  <!-- Produce output -->
*update-    <!-- Modify existing -->
*review-    <!-- Examine quality -->
*test-      <!-- Verify functionality -->

Domain-Based Naming

*brainstorm      <!-- Creative ideation -->
*architect       <!-- Design systems -->
*refactor        <!-- Improve code -->
*deploy          <!-- Release to production -->
*monitor         <!-- Watch systems -->

Naming Anti-Patterns

```xml

Do something

Product Requirements

Create Product Requirements Document ```

Command Organization

Standard Order

<menu>
  <!-- 1. Always first -->
  <item cmd="*help">Show numbered cmd list</item>

  <!-- 2. Primary workflows -->
  <item cmd="*create-prd" run-workflow="...">Create PRD</item>
  <item cmd="*create-module" run-workflow="...">Build module</item>

  <!-- 3. Secondary actions -->
  <item cmd="*validate" exec="...">Validate document</item>
  <item cmd="*analyze" exec="...">Analyze code</item>

  <!-- 4. Utility commands -->
  <item cmd="*config">Show configuration</item>
  <item cmd="*yolo">Toggle Yolo Mode</item>

  <!-- 5. Always last -->
  <item cmd="*exit">Exit with confirmation</item>
</menu>

Grouping Strategies

By Lifecycle:

<menu>
  <item cmd="*help">Help</item>
  <!-- Planning -->
  <item cmd="*brainstorm">Brainstorm ideas</item>
  <item cmd="*plan">Create plan</item>
  <!-- Building -->
  <item cmd="*build">Build component</item>
  <item cmd="*test">Test component</item>
  <!-- Deployment -->
  <item cmd="*deploy">Deploy to production</item>
  <item cmd="*monitor">Monitor system</item>
  <item cmd="*exit">Exit</item>
</menu>

By Complexity:

<menu>
  <item cmd="*help">Help</item>
  <!-- Simple -->
  <item cmd="*quick-review">Quick review</item>
  <!-- Standard -->
  <item cmd="*create-doc">Create document</item>
  <!-- Complex -->
  <item cmd="*full-analysis">Comprehensive analysis</item>
  <item cmd="*exit">Exit</item>
</menu>

Command Descriptions

Good Descriptions

```xml

Create Product Requirements Document

Perform security vulnerability analysis

Optimize code for performance ```

Poor Descriptions

```xml

Process

Execute WF123

Run ```

The Data Property

Universal Data Attribute

The data attribute can be added to ANY command type to provide supplementary information:

```xml

Creative Brainstorming Session

Analyze Performance Metrics

Generate Quarterly Report ```

Common Data Uses:

• Reference tables (CSV files)
• Configuration data (YAML/JSON)
• Agent manifests (XML)
• Historical context
• Domain knowledge
• Examples and patterns

Advanced Patterns

Conditional Commands

```xml

Advanced configuration mode

Deploy to production ```

Parameterized Commands

```xml

Create new agent with parameters ```

Command Aliases

```xml

Create Product Requirements Document ```

Module-Specific Patterns

BMM (Business Management)

<item cmd="*create-prd">Product Requirements</item>
<item cmd="*market-research">Market Research</item>
<item cmd="*competitor-analysis">Competitor Analysis</item>
<item cmd="*brief">Project Brief</item>

BMB (Builder)

<item cmd="*create-agent">Build Agent</item>
<item cmd="*create-module">Build Module</item>
<item cmd="*create-workflow">Create Workflow</item>
<item cmd="*module-brief">Module Brief</item>

CIS (Creative Intelligence)

<item cmd="*brainstorm">Brainstorming Session</item>
<item cmd="*ideate">Ideation Workshop</item>
<item cmd="*storytell">Story Creation</item>

Command Menu Presentation

How Commands Display

1. *help - Show numbered cmd list
2. *create-prd - Create Product Requirements Document
3. *create-agent - Build new BMAD agent
4. *validate - Validate document
5. *exit - Exit with confirmation

Menu Customization

```xml

━━━━━━━━━━━━━━━━━━━━

═══ Workflows ═══ ```

Error Handling

Missing Resources

```xml

Coming soon: Advanced feature

Analyze with available tools ```

Testing Commands

Command Test Checklist

• [ ] Unique trigger (no duplicates)
• [ ] Clear description
• [ ] Valid path or “todo”
• [ ] Uses variables not hardcoded paths
• [ ] Executes without error
• [ ] Returns to menu after execution

Common Issues

1. Duplicate triggers - Each cmd must be unique
2. Missing paths - File must exist or be “todo”
3. Hardcoded paths - Always use variables
4. No description - Every command needs text
5. Wrong order - help first, exit last

Quick Templates

Workflow Command

```xml

{Action} {Object Description}

Validate {Object Description} ```

Task Command

<item cmd="*{action}"
   exec="{project-root}/bmad/{module}/tasks/{task}.md">
  {Action Description}
</item>

Template Command

<item cmd="*{document}"
   exec="{project-root}/bmad/core/tasks/create-doc.md"
   tmpl="{project-root}/bmad/{module}/templates/{template}.md">
  Create {Document Name}
</item>

Self-Contained Agent Patterns

When to Use Each Approach

Inline Action (action="prompt")

• Prompt is < 2 lines
• Simple, direct instruction
• Not reused elsewhere
• Quick transformations

Referenced Prompt (action="#prompt-id")

• Prompt is multiline/complex
• Contains structured steps
• May be reused by multiple commands
• Maintains readability

External Task (exec="path/to/task.md")

• Logic needs to be shared across agents
• Task is independently valuable
• Requires version control separately
• Part of larger workflow system

Complete Self-Contained Agent

<agent id="bmad/research/agents/analyst.md" name="Research Analyst" icon="🔬">
  <!-- Embedded prompt library -->
  <prompts>
    <prompt id="swot-analysis">
      Perform a SWOT analysis:

      STRENGTHS (Internal, Positive)
      - What advantages exist?
      - What do we do well?
      - What unique resources?

      WEAKNESSES (Internal, Negative)
      - What could improve?
      - Where are resource gaps?
      - What needs development?

      OPPORTUNITIES (External, Positive)
      - What trends can we leverage?
      - What market gaps exist?
      - What partnerships are possible?

      THREATS (External, Negative)
      - What competition exists?
      - What risks are emerging?
      - What could disrupt us?

      Provide specific examples and actionable insights for each quadrant.
    </prompt>

    <prompt id="competitive-intel">
      Analyze competitive landscape:
      1. Identify top 5 competitors
      2. Compare features and capabilities
      3. Analyze pricing strategies
      4. Evaluate market positioning
      5. Assess strengths and vulnerabilities
      6. Recommend competitive strategies
    </prompt>
  </prompts>

  <menu>
    <item cmd="*help">Show numbered cmd list</item>

    <!-- Simple inline actions -->
    <item cmd="*summarize"
       action="create executive summary of findings">
      Create Executive Summary
    </item>

    <!-- Complex referenced prompts -->
    <item cmd="*swot"
       action="#swot-analysis">
      Perform SWOT Analysis
    </item>

    <item cmd="*compete"
       action="#competitive-intel"
       data="{project-root}/bmad/_data/market-data.csv">
      Analyze Competition
    </item>

    <!-- Hybrid: external task with internal data -->
    <item cmd="*report"
       exec="{project-root}/bmad/core/tasks/create-doc.md"
       tmpl="{project-root}/bmad/research/templates/report.md">
      Generate Research Report
    </item>

    <item cmd="*exit">Exit with confirmation</item>
  </menu>
</agent>

Simple Agent Example

For agents that primarily use embedded logic:

<agent name="Data Analyst">
  <menu>
    <item cmd="*help">Show numbered cmd list</item>

    <!-- Action commands for direct operations -->
    <item cmd="*list-metrics"
       action="list all available metrics from the dataset">
      List Available Metrics
    </item>

    <item cmd="*analyze"
       action="perform statistical analysis on the provided data"
       data="{project-root}/bmad/_data/dataset.csv">
      Analyze Dataset
    </item>

    <item cmd="*visualize"
       action="create visualization recommendations for this data">
      Suggest Visualizations
    </item>

    <!-- Embedded logic commands -->
    <item cmd="*calculate">Perform calculations</item>
    <item cmd="*interpret">Interpret results</item>

    <item cmd="*exit">Exit with confirmation</item>
  </menu>
</agent>

LLM Building Guide

When creating commands:

1. Start with help and exit
2. Choose appropriate command type:
   • Complex multi-step? Use run-workflow
   • Single operation? Use exec
   • Need template? Use exec + tmpl
   • Simple prompt? Use action
   • Agent handles it? Use no attributes
3. Add data attribute if supplementary info needed
4. Add primary workflows (main value)
5. Add secondary tasks
6. Include utility commands
7. Test each command works
8. Verify no duplicates
9. Ensure clear descriptions