---
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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/read_file.py \
  --path workspace/tasks/task-001.md \
  --output json
```

**Returns:**
```json
{
  "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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/run_tests.py \
  --path . \
  --framework auto \
  --timeout 120 \
  --output json
```

**Returns:**
```json
{
  "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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/generate_architecture_diagram.py \
  --architecture docs/architecture.md \
  --type c4-context \
  --output docs/diagrams
```

**Returns:**
```json
{
  "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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/analyze_tech_stack.py \
  --architecture docs/architecture.md \
  --output json
```

**Returns:**
```json
{
  "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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/extract_adrs.py \
  --architecture docs/architecture.md \
  --output docs/adrs
```

**Returns:**
```json
{
  "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:**
```bash
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:**
```bash
python .claude/skills/bmad-commands/scripts/validate_patterns.py \
  --architecture docs/architecture.md \
  --requirements docs/prd.md \
  --output json
```

**Returns:**
```json
{
  "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:

```json
{
  "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:**

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

```json
{
  "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:

```bash
# 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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
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:**
```bash
./.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:**
```bash
./.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`

---