bmad-commands

name	bmad-commands
description	Atomic command primitives for BMAD operations. Provides type-safe, testable wrappers around file operations and test execution with structured JSON I/O and built-in telemetry. This skill should be used when BMAD workflows need deterministic, reliable primitive operations with observability.
allowed-tools	Bash, Read
acceptance	[{"commands_executed":"All requested commands executed successfully"},{"json_io_valid":"All inputs parsed and outputs generated as valid JSON"},{"telemetry_emitted":"Telemetry data emitted for all command executions"},{"errors_handled":"All errors caught and reported in structured format"},{"deterministic_behavior":"Same inputs produce same outputs (idempotent where applicable)"}]
inputs	{"command":{"type":"enum","values":["read_file","run_tests","generate_architecture_diagram","analyze_tech_stack","extract_adrs","validate_patterns"],"required":true,"description":"Command name to execute"},"command_args":{"type":"object","required":true,"description":"Command-specific arguments (varies by command)","examples":{"read_file":{"path":"workspace/tasks/task-001.md"},"run_tests":{"path":".","framework":"jest","timeout":120},"generate_architecture_diagram":{"architecture":"docs/architecture.md","type":"c4-context","output":"docs/diagrams"}}}}
outputs	{"success":{"type":"boolean","description":"Whether command executed successfully"},"outputs":{"type":"object","description":"Command-specific outputs (varies by command)"},"telemetry":{"type":"object","description":"Telemetry data with command, duration_ms, timestamp","required_fields":["command","duration_ms","timestamp"]},"errors":{"type":"array","description":"Array of error objects (empty if success=true)","item_schema":{"error_code":"string","message":"string","details":"object (optional)"}}}
telemetry	{"emit":"skill.bmad-commands.command-executed","track":["command","duration_ms","success","error_count","timestamp"],"aggregations":["command_usage_frequency","average_duration_by_command","error_rate_by_command"]}

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

---