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

---