BMAD Commands

Overview

BMAD Commands provide atomic, testable command primitives that BMAD skills compose into workflows. Each command follows a strict contract with typed inputs/outputs, structured error handling, and built-in telemetry.

Design Principles:

• Deterministic: Same inputs always produce same outputs
• Testable: Pure functions with JSON I/O
• Observable: All commands emit telemetry data
• Composable: Commands are building blocks for skills

Available Commands

read_file

Read file contents with metadata.

Usage:

python scripts/read_file.py --path <file-path> --output json

Inputs:

• path

  (required): Path to file to read

Outputs:

• content

  : File contents as text

• line_count

  : Number of lines

• size_bytes

  : File size in bytes

• path

  : Absolute path to file

Example:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path workspace/tasks/task-001.md \
  --output json

Returns:

{
  "success": true,
  "outputs": {
    "content": "# Task Specification\n...",
    "line_count": 45,
    "size_bytes": 1024,
    "path": "/absolute/path/to/task-001.md"
  },
  "telemetry": {
    "command": "read_file",
    "duration_ms": 12,
    "timestamp": "2025-01-15T10:30:00Z",
    "path": "workspace/tasks/task-001.md",
    "line_count": 45
  },
  "errors": []
}

---

run_tests

Execute tests with specified framework and return structured results.

Usage:

python scripts/run_tests.py --path <test-path> --framework <jest|pytest> --timeout <seconds> --output json

Inputs:

• path

  (required): Directory containing tests

• framework

  (optional): Test framework (default: jest)

• timeout

  (optional): Timeout in seconds (default: 120)

Outputs:

• passed

  : Whether all tests passed (boolean)

• summary

  : Human-readable summary

• total_tests

  : Total number of tests

• passed_tests

  : Number passed

• failed_tests

  : Number failed

• coverage_percent

  : Coverage percentage (0-100)

• junit_path

  : Path to JUnit report

Example:

python .claude/skills/bmad-commands/scripts/run_tests.py \
  --path . \
  --framework auto \
  --timeout 120 \
  --output json

Returns:

{
  "success": true,
  "outputs": {
    "passed": true,
    "summary": "10/10 tests passed",
    "total_tests": 10,
    "passed_tests": 10,
    "failed_tests": 0,
    "coverage_percent": 87,
    "junit_path": "./junit.xml"
  },
  "telemetry": {
    "command": "run_tests",
    "framework": "jest",
    "duration_ms": 4523,
    "timestamp": "2025-01-15T10:30:00Z",
    "total_tests": 10,
    "passed_tests": 10,
    "failed_tests": 0
  },
  "errors": []
}

---

generate_architecture_diagram

Generate architecture diagrams from architecture documents (C4 model, deployment, sequence diagrams).

Usage:

python scripts/generate_architecture_diagram.py --architecture <file-path> --type <diagram-type> --output <output-dir>

Inputs:

• architecture

  (required): Path to architecture document

• type

  (required): Diagram type (c4-context, c4-container, c4-component, deployment, sequence)

• output

  (optional): Output directory (default: docs/diagrams)

Outputs:

• diagram_path

  : Path to generated diagram file

• diagram_type

  : Type of diagram generated

• diagram_format

  : Format (svg, png)

• architecture_source

  : Source architecture document

Example:

python .claude/skills/bmad-commands/scripts/generate_architecture_diagram.py \
  --architecture docs/architecture.md \
  --type c4-context \
  --output docs/diagrams

Returns:

{
  "success": true,
  "outputs": {
    "diagram_path": "/path/to/docs/diagrams/c4-context-20250131.svg",
    "diagram_type": "c4-context",
    "diagram_format": "svg",
    "architecture_source": "docs/architecture.md"
  },
  "telemetry": {
    "command": "generate_architecture_diagram",
    "diagram_type": "c4-context",
    "duration_ms": 450,
    "timestamp": "2025-01-31T10:30:00Z"
  },
  "errors": []
}

---

analyze_tech_stack

Analyze technology stack from architecture document, validate compatibility, identify risks.

Usage:

python scripts/analyze_tech_stack.py --architecture <file-path> --output <json|summary>

Inputs:

• architecture

  (required): Path to architecture document

• output

  (optional): Output format (default: json)

Outputs:

• technologies

  : List of detected technologies with categories

• tech_count

  : Number of technologies detected

• categories

  : Technology categories (frontend, backend, database, etc.)

• compatibility

  : Compatibility analysis and warnings

• architecture_source

  : Source architecture document

Example:

python .claude/skills/bmad-commands/scripts/analyze_tech_stack.py \
  --architecture docs/architecture.md \
  --output json

Returns:

{
  "success": true,
  "outputs": {
    "technologies": [
      {"name": "React", "category": "frontend", "version": "18+"},
      {"name": "Node.js", "category": "backend", "version": "20+"},
      {"name": "PostgreSQL", "category": "database", "version": "15+"}
    ],
    "tech_count": 3,
    "categories": ["frontend", "backend", "database"],
    "compatibility": {
      "issues": [],
      "warnings": [],
      "recommendations": ["Verify versions are compatible"]
    },
    "architecture_source": "docs/architecture.md"
  },
  "telemetry": {
    "command": "analyze_tech_stack",
    "tech_count": 3,
    "duration_ms": 180,
    "timestamp": "2025-01-31T10:30:00Z"
  },
  "errors": []
}

---

extract_adrs

Extract Architecture Decision Records (ADRs) from architecture document into separate files.

Usage:

python scripts/extract_adrs.py --architecture <file-path> --output <output-dir>

Inputs:

• architecture

  (required): Path to architecture document

• output

  (optional): Output directory for ADR files (default: docs/adrs)

Outputs:

• adrs_extracted

  : Number of ADRs extracted

• adrs

  : List of ADRs with number, title, and file path

• output_directory

  : Directory where ADRs were saved

• architecture_source

  : Source architecture document

Example:

python .claude/skills/bmad-commands/scripts/extract_adrs.py \
  --architecture docs/architecture.md \
  --output docs/adrs

Returns:

{
  "success": true,
  "outputs": {
    "adrs_extracted": 5,
    "adrs": [
      {
        "number": "001",
        "title": "Technology Stack Selection",
        "file": "/path/to/docs/adrs/ADR-001-technology-stack-selection.md"
      },
      {
        "number": "002",
        "title": "Database Choice",
        "file": "/path/to/docs/adrs/ADR-002-database-choice.md"
      }
    ],
    "output_directory": "/path/to/docs/adrs",
    "architecture_source": "docs/architecture.md"
  },
  "telemetry": {
    "command": "extract_adrs",
    "adrs_count": 5,
    "duration_ms": 120,
    "timestamp": "2025-01-31T10:30:00Z"
  },
  "errors": []
}

---

validate_patterns

Validate architectural patterns against best practices, check appropriateness for requirements.

Usage:

python scripts/validate_patterns.py --architecture <file-path> [--requirements <file-path>] --output <json|summary>

Inputs:

• architecture

  (required): Path to architecture document

• requirements

  (optional): Path to requirements document

• output

  (optional): Output format (default: json)

Outputs:

• detected_patterns

  : List of architectural patterns found

• validation

  : Validation results including warnings and recommendations

• architecture_source

  : Source architecture document

• requirements_source

  : Source requirements document (if provided)

Example:

python .claude/skills/bmad-commands/scripts/validate_patterns.py \
  --architecture docs/architecture.md \
  --requirements docs/prd.md \
  --output json

Returns:

{
  "success": true,
  "outputs": {
    "detected_patterns": [
      {
        "name": "Microservices",
        "category": "architectural",
        "validated": true,
        "warnings": []
      },
      {
        "name": "Repository Pattern",
        "category": "architectural",
        "validated": true,
        "warnings": []
      }
    ],
    "validation": {
      "patterns_validated": 2,
      "patterns_appropriate": 2,
      "anti_patterns_detected": 0,
      "warnings": [],
      "recommendations": [
        "Validate pattern complexity matches team expertise",
        "Ensure pattern choice aligns with scale requirements"
      ]
    },
    "architecture_source": "docs/architecture.md",
    "requirements_source": "docs/prd.md"
  },
  "telemetry": {
    "command": "validate_patterns",
    "patterns_count": 2,
    "anti_patterns_count": 0,
    "duration_ms": 210,
    "timestamp": "2025-01-31T10:30:00Z"
  },
  "errors": []
}

---

Response Format

All commands return JSON with this structure:

{
  "success": boolean,
  "outputs": {
    // Command-specific outputs
  },
  "telemetry": {
    "command": string,
    "duration_ms": number,
    "timestamp": string,
    // Command-specific telemetry
  },
  "errors": [
    // Array of error strings (empty if success=true)
  ]
}

Exit Codes:

• 0

  : Command succeeded (

  success: true

  )

• 1

  : Command failed (

  success: false

  )

---

Using Commands from Skills

To use commands from other skills, execute the script and parse the JSON output.

Example in a skill's SKILL.md:

### Step 1: Read Task Specification

Execute the read_file command:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path workspace/tasks/{task_id}.md \
  --output json

Parse the JSON response and extract `outputs.content` for the task specification.

### Step 2: Run Tests

Execute the run_tests command:

python .claude/skills/bmad-commands/scripts/run_tests.py \
  --path . \
  --framework auto \
  --output json

Parse the JSON response and check `outputs.passed` to verify tests passed.

---

Error Handling

All commands handle errors gracefully and return structured error information:

{
  "success": false,
  "outputs": {},
  "telemetry": {
    "command": "read_file",
    "duration_ms": 5,
    "timestamp": "2025-01-15T10:30:00Z"
  },
  "errors": ["file_not_found"]
}

Common Errors:

• file_not_found

  : File doesn't exist

• path_is_not_file

  : Path is a directory

• permission_denied

  : Insufficient permissions

• timeout

  : Operation exceeded timeout

• invalid_path

  : Path validation failed

• unexpected_error

  : Unexpected error occurred

---

Telemetry

All commands emit telemetry data for observability:

• command

  : Command name

• duration_ms

  : Execution time in milliseconds

• timestamp

  : ISO 8601 timestamp
• Command-specific metrics (e.g., line_count, test_count)

This telemetry enables:

• Performance monitoring
• Usage analytics
• Debugging workflows
• Production observability

---

Command Contracts

Full command contracts (inputs, outputs, errors, telemetry) are documented in:

references/command-contracts.yaml

Reference this file when:

• Creating new commands
• Updating existing commands
• Integrating commands into skills
• Understanding command behavior

---

Testing Commands

Test commands independently before using in workflows:

# Test read_file
python .claude/skills/bmad-commands/scripts/read_file.py \
  --path README.md \
  --output json

# Test run_tests (if you have a test suite)
python .claude/skills/bmad-commands/scripts/run_tests.py \
  --path . \
  --framework auto \
  --output json

Verify:

• JSON output is valid
• Exit code is 0 for success, 1 for failure
• Telemetry data is present
• Errors are structured

---

Extending Commands

To add new commands:

1. Create

   scripts/<command_name>.py

2. Follow the standard response format
3. Add command contract to

   references/command-contracts.yaml

4. Update this SKILL.md with usage documentation
5. Make script executable:

   chmod +x scripts/<command_name>.py

6. Test independently before integrating

---

Philosophy

Commands are the foundation layer of BMAD's 3-layer architecture:

1. Commands (this skill): Atomic, testable primitives
2. Skills: Compose commands into workflows
3. Subagents: Orchestrate skills with routing and guardrails

By keeping commands deterministic and testable, we enable:

• Unit testing of the framework itself
• Reliable skill composition
• Observable workflows
• Production-ready operations

---

Utility Scripts

In addition to command primitives, this skill includes utility scripts for UX and system management:

bmad-wizard.py

Interactive command wizard to help users find the right command for their task.

Usage:

python .claude/skills/bmad-commands/scripts/bmad-wizard.py
python .claude/skills/bmad-commands/scripts/bmad-wizard.py --list-all
python .claude/skills/bmad-commands/scripts/bmad-wizard.py --subagent alex

Features:

• Goal-based recommendations
• Interactive command selection
• Browse all commands
• Filter by subagent

Documentation: See

docs/UX-IMPROVEMENTS-GUIDE.md

---

error-handler.py

Professional error handling system with structured errors and remediation guidance.

Usage:

python .claude/skills/bmad-commands/scripts/error-handler.py

Features:

• 10 predefined error templates
• Structured error format
• Remediation steps
• Color-coded severity levels
• JSON output support

Documentation: See

docs/UX-IMPROVEMENTS-GUIDE.md

---

progress-visualizer.py

Real-time progress tracking for workflows with multiple visualization styles.

Usage:

python .claude/skills/bmad-commands/scripts/progress-visualizer.py

Features:

• 7-step workflow tracking
• 4 visualization styles (bar, spinner, dots, minimal)
• ETA calculation
• Elapsed time tracking
• Real-time updates

Documentation: See

docs/UX-IMPROVEMENTS-GUIDE.md

---

monitor-skills.py

Skill validation and monitoring tool for ensuring all skills are properly loaded.

Usage:

python .claude/skills/bmad-commands/scripts/monitor-skills.py
python .claude/skills/bmad-commands/scripts/monitor-skills.py --validate-only
python .claude/skills/bmad-commands/scripts/monitor-skills.py --category planning
python .claude/skills/bmad-commands/scripts/monitor-skills.py --skill implement-feature
python .claude/skills/bmad-commands/scripts/monitor-skills.py --json output.json

Features:

• Discover and validate all skills
• Check YAML frontmatter
• Verify workflow steps
• Export to JSON
• Category filtering

Documentation: See

docs/SKILL-LOADING-MONITORING.md

---

health-check.sh

Quick health check to validate system configuration and skill loading.

Usage:

./.claude/skills/bmad-commands/scripts/health-check.sh

Features:

• Check project structure
• Validate skills by category
• Check Python environment
• Validate required packages
• Check configuration
• Disk space check

Documentation: See

docs/SKILL-LOADING-MONITORING.md

---

deploy-to-project.sh

Smart deployment script for deploying BMAD Enhanced to other projects.

Usage:

./.claude/skills/bmad-commands/scripts/deploy-to-project.sh <target-directory>
./.claude/skills/bmad-commands/scripts/deploy-to-project.sh --full <target-directory>
./.claude/skills/bmad-commands/scripts/deploy-to-project.sh --dry-run <target-directory>

Features:

• Minimal or full deployment modes
• Dry-run mode
• Force overwrite option
• Symlink support for full mode
• Post-deployment instructions

Documentation: See

docs/DEPLOYMENT-TO-PROJECTS.md

---