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"