# Bmad Commands

> 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.

- Skill: `majiayu000/bmad-commands` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/bmad-commands`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/bmad-commands/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/bmad-commands

---


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

---