BMAD Workflow CLI

AI-powered development lifecycle automation — from vision to verified code.

Built on the BMAD Method

This CLI is the automation engine for the BMAD Method — a comprehensive, open-source methodology for AI-assisted software development.

🧠 BMAD Method

The methodology and agents — templates, personas, workflows, and best practices for structuring AI-driven development.

Start here to understand the philosophy and set up your project.

⚡ BMAD Workflow CLI (this repo)

The automation layer — orchestrates the BMAD workflow, spawning AI agents to execute PRD → Epic → Story → Dev → QA pipelines at scale.

Use this to automate and accelerate execution.

New to BMAD? Start with the BMAD Method repository to understand the methodology, then come back here to automate it.

Note: This CLI is an independent project that implements the BMAD Method. We are not affiliated with bmad-code-org but build upon their excellent open-source methodology.

What This CLI Does

The BMAD Workflow CLI provides five core capabilities for AI-assisted development:

┌──────────────────────────────────────────────────────────────────────────┐
│                                                                          │
│  1. WORKFLOW      Full PRD → Epic → Story → Dev pipeline orchestration   │
│                                                                          │
│  2. DECOMPOSE     Break big goals into executable task graphs            │
│                                                                          │
│  3. PRD TOOLS     Validate and auto-fix PRD format with AI               │
│                                                                          │
│  4. STORY TOOLS   Create, develop, list, move, and QA stories            │
│                                                                          │
│  5. QA PIPELINE   Deep dive review → Dev fix-forward → Gate validation   │
│                                                                          │
└──────────────────────────────────────────────────────────────────────────┘

Key Features

| Feature | Description | |---------|-------------| | Full Lifecycle Automation | PRD → Epic → Story → Dev → QA in one command | | Decompose Command | Break any goal into dependency-managed task graphs | | Pipelined Execution | Story creation and dev run concurrently (44% faster) | | Multi-Provider Support | Claude and Gemini AI providers | | QA Workflow | Automated review cycles with gate validation | | Per-File Mode | Generate one task per file for large migrations | | Story Format Output | Tasks output as BMAD-compatible stories | | BMAD Agent Integration | Use any BMAD agent (analyst, architect, dev, pm, qa, etc.) |

Installation

Prerequisites

• Node.js 20+ - Download
• Claude CLI - Install and run claude auth login
• BMAD Method - Set up in your project

Install

npm install -g @hyperdrive.bot/bmad-workflow

Verify:

bmad-workflow --version
bmad-workflow --help

Quick Start

1. Full Pipeline (PRD → Code)

# Run complete workflow from a PRD
bmad-workflow workflow docs/PRD-my-feature.md

# What happens:
# ✓ Parses PRD, extracts epics
# ✓ Creates epic files with AI
# ✓ Generates stories from each epic
# ✓ Develops each story (pipelined)
# 🎉 Done!

2. Decompose Any Goal

# Break a big goal into tasks
bmad-workflow decompose "Migrate entire codebase to TypeScript" \
  --per-file --file-pattern "src/**/*.js"

# What happens:
# ✓ AI analyzes the goal
# ✓ Creates dependency graph
# ✓ Generates task for each file
# ✓ Executes in parallel layers

3. QA Your Stories

# Run QA workflow with fix-forward cycles
bmad-workflow stories qa "docs/stories/AUTH-*.md" --max-retries 3

# What happens:
# ✓ QA agent reviews each story
# ✓ Dev agent fixes issues
# ✓ Re-validates until PASS or max retries
# ✓ Moves to done/ or back to stories/

Commands Overview

workflow — Full Pipeline Orchestration

Execute the complete PRD → Epic → Story → Dev pipeline:

# Basic usage
bmad-workflow workflow docs/PRD-feature.md

# Skip phases
bmad-workflow workflow docs/PRD-feature.md --skip-dev
bmad-workflow workflow docs/epics/epic-1.md --skip-epics

# Tune performance
bmad-workflow workflow docs/PRD-feature.md --parallel 5 --pipeline

# Dry run
bmad-workflow workflow docs/PRD-feature.md --dry-run --verbose

Flags:

• --parallel <n> — Max concurrent operations (default: 3)
• --pipeline / --no-pipeline — Enable/disable concurrent execution
• --skip-epics, --skip-stories, --skip-dev — Skip phases
• --dry-run — Preview without execution
• --provider <claude|gemini> — AI provider
• --auto-fix — Auto-fix PRD format if parsing fails

decompose — Task Graph Decomposition

Break large goals into executable task graphs with dependency management:

# Basic decomposition
bmad-workflow decompose "Add user authentication"

# Per-file mode (great for migrations)
bmad-workflow decompose "Convert to TypeScript" \
  --per-file --file-pattern "src/**/*.js"

# Output as BMAD stories
bmad-workflow decompose "Refactor API layer" \
  --story-format --story-prefix "REFACTOR"

# Plan only (don't execute)
bmad-workflow decompose "Redesign database schema" --plan-only

# Execute immediately
bmad-workflow decompose "Add dark mode" --execute --max-parallel 5

# Use specific BMAD agent
bmad-workflow decompose "Design new API" --agent architect --plan-only

Flags:

• --per-file — Create one task per file
• --file-pattern <glob> — Files to process in per-file mode
• --story-format — Output tasks as BMAD stories
• --story-prefix <prefix> — Story ID prefix (e.g., "MIGRATE")
• --plan-only — Generate graph without executing
• --execute — Execute immediately (skip confirmation)
• --max-parallel <n> — Concurrent tasks (default: 3)
• --agent <name> — BMAD agent for planning (analyst, architect, dev, pm, etc.)
• --context <file> — Additional context files (repeatable)

Session Output:

docs/decompose-sessions/session-2024-01-15T10-30-00/
├── SESSION_README.md    # Overview and instructions
├── goal.yaml            # Original goal and options
├── task-graph.yaml      # Full dependency graph
├── master-prompt.md     # Combined prompt for all tasks
├── prompts/             # Individual task prompts
│   ├── task-001.md
│   ├── task-002.md
│   └── ...
├── outputs/             # Task execution outputs
└── execution-report.yaml # Results and metrics

prd — PRD Tools

prd validate — Check PRD Structure

# Validate and preview extraction
bmad-workflow prd validate docs/PRD-feature.md

# Output as JSON
bmad-workflow prd validate docs/PRD-feature.md --json

Shows: epic count, existing files, story counts, what would be created.

prd fix — Auto-Fix PRD Format

# Fix PRD format with AI
bmad-workflow prd fix docs/PRD-feature.md

# With architecture context
bmad-workflow prd fix docs/PRD-feature.md --reference docs/architecture.md

# Use Gemini instead of Claude
bmad-workflow prd fix docs/PRD-feature.md --provider gemini

Creates backup (.bak) before modifying.

epics — Epic Management

epics create — Generate Epics from PRD

# Create all epics
bmad-workflow epics create docs/prd.md

# Create specific range
bmad-workflow epics create docs/prd.md --start 2 --count 3

# With context files
bmad-workflow epics create docs/prd.md --reference docs/architecture.md

epics list — List All Epics

bmad-workflow epics list
bmad-workflow epics list --json

stories — Story Lifecycle

stories create — Generate Stories from Epic

# Create all stories
bmad-workflow stories create docs/epics/epic-1.md

# High concurrency
bmad-workflow stories create epic.md --parallel 10

# Start from specific story
bmad-workflow stories create epic.md --start 3

# Use specific BMAD agent
bmad-workflow stories create epic.md --agent sm --task create-next-story

stories develop — Execute Development

# Develop matching stories
bmad-workflow stories develop "docs/stories/AUTH-*.md"

# With interval between stories
bmad-workflow stories develop "stories/*.md" --interval 60

# With architecture reference
bmad-workflow stories develop "stories/*.md" --reference docs/architecture.md

stories qa — QA Workflow with Fix-Forward

The QA command runs a complete quality assurance workflow:

# QA all AUTH stories
bmad-workflow stories qa "docs/qa/stories/AUTH-*.md"

# With retry cycles
bmad-workflow stories qa "stories/*.md" --max-retries 3

# Custom QA focus
bmad-workflow stories qa "stories/*.md" --qa-prompt "Focus on security"

# Custom dev instructions
bmad-workflow stories qa "stories/*.md" --dev-prompt "Prioritize performance fixes"

QA Workflow Phases:

1. QA Deep Dive — Tea agent reviews implementation against acceptance criteria
2. Dev Fix-Forward — Dev agent addresses findings (if CONCERNS/FAIL)
3. Re-Validation — Repeat until PASS/WAIVED or max retries
4. Movement — PASS/WAIVED → done/, FAIL/CONCERNS → stories/

Gate Statuses:

• PASS — All criteria met, moved to done
• CONCERNS — Minor issues, may need fixes
• FAIL — Significant issues, needs rework
• WAIVED — Accepted as-is with known limitations

stories list — List Stories

bmad-workflow stories list
bmad-workflow stories list --status=ready --epic=4
bmad-workflow stories list --json

stories move — Move to QA Directory

bmad-workflow stories move "4.7-*.md"
bmad-workflow stories move "STORY-*.md" --force

config — Configuration

config validate

bmad-workflow config validate

config show

bmad-workflow config show
bmad-workflow config show --json

Configuration

Create .bmad-core/core-config.yaml in your project root:

# PRD Configuration
prdFile: docs/prd.md
prdSharded: true
prdShardedLocation: docs/prd

# Epic Configuration
epicFilePattern: epic-{n}*.md

# Architecture
architectureSharded: true
architectureShardedLocation: docs/architecture

# Story Configuration
devStoryLocation: docs/stories

# QA Configuration
qaLocation: docs/qa

# Development Context (always loaded by agents)
devLoadAlwaysFiles:
  - docs/architecture.md
  - docs/coding-standards.md
  - project-context.md

Pipelined Execution

By default, story creation and development run concurrently:

Sequential:   [Create All Stories] ──────────→ [Develop All Stories]
                    900s                              1800s
              Total: 2700s (45 minutes)

Pipelined:    [Create Stories ─────────────────────┐
               └→ [Dev Worker 1] → Done            │ Concurrent!
               └→ [Dev Worker 2] → Done            │
               └→ [Dev Worker 3] → Done            ┘
              Total: ~1500s (25 minutes) — 44% faster

Control with --pipeline (default) or --no-pipeline.

AI Providers

Supports multiple AI providers:

# Claude (default)
bmad-workflow workflow docs/prd.md --provider claude

# Gemini
bmad-workflow decompose "Add feature" --provider gemini

BMAD Agent Integration

Use any BMAD agent for specialized tasks:

| Agent | Use Case | |-------|----------| | analyst | Requirements analysis, research | | architect | System design, technical decisions | | dev | Implementation, coding | | pm | Product management, prioritization | | sm | Scrum master, story refinement | | tea | QA, testing, validation | | tech-writer | Documentation | | ux-designer | User experience design | | quick-flow-solo-dev | Rapid prototyping |

bmad-workflow decompose "Design API" --agent architect
bmad-workflow stories create epic.md --agent sm

Project Structure

src/
├── commands/
│   ├── workflow.ts          # Main pipeline orchestrator
│   ├── decompose.ts         # Task graph decomposition
│   ├── config/              # Config commands
│   ├── epics/               # Epic commands
│   ├── prd/                 # PRD tools
│   └── stories/             # Story lifecycle
├── services/
│   ├── agents/              # AI provider runners
│   ├── orchestration/       # Pipeline, batch, dependency management
│   ├── parsers/             # PRD, epic, story parsers
│   └── scaffolding/         # File/session scaffolders
├── models/                  # TypeScript interfaces
└── utils/                   # Colors, formatters, progress

Contributing

Contributing to the CLI (this repo)

git clone [email protected]:dev_squad/repo/cli/bmad-orchestrator.git
cd bmad-orchestrator
npm install
npm run build
./bin/dev --help
npm test

Contributing to the BMAD Method

Want to improve agent personas, templates, or workflows?

👉 BMAD-METHOD Contributing Guide

Development Scripts

| Script | Description | |--------|-------------| | npm run build | Compile TypeScript | | npm run lint | Run ESLint | | npm test | Run test suite | | npm run test:coverage | Tests with coverage | | ./bin/dev | Run locally without building |

Troubleshooting

"Claude CLI not found"

claude auth login
claude --version

"Configuration file not found"

ls .bmad-core/core-config.yaml
bmad-workflow config validate

Decompose session issues

Check the session directory:

ls docs/decompose-sessions/session-*/
cat docs/decompose-sessions/session-*/SESSION_README.md

QA gate not updating

Ensure stories have proper markdown structure with ## QA Results section.

Roadmap

• [ ] OpenAI GPT-4 provider support
• [ ] Web UI for workflow visualization
• [ ] GitHub Actions integration
• [ ] VS Code extension
• [ ] Custom agent templates
• [ ] Parallel QA execution

Have an idea? Open an issue!

Community & Resources

BMAD Ecosystem

| Repository | Description | |------------|-------------| | BMAD-METHOD | 🧠 The core methodology — agents, templates, workflows | | bmad-workflow (this repo) | ⚡ CLI automation engine |

Get Help

• BMAD Method Questions: BMAD Discussions
• CLI Issues: GitLab Issues

Learn More

• 📖 BMAD Method Documentation
• 🎓 Getting Started Guide
• 🤖 Agent Personas Reference

License

MIT - see LICENSE