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.

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

$3 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

$3

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

$3

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

Verify:

`bash
bmad-workflow --version
bmad-workflow --help
`

---

Quick Start

$3

`bash


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!

`

$3

`bash


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

`bash


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

$3

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

`bash


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 — 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 — AI provider
- --auto-fix — Auto-fix PRD format if parsing fails

---

$3

Break large goals into executable task graphs with dependency management:

`bash


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 — Files to process in per-file mode
- --story-format — Output tasks as BMAD stories
- --story-prefix — Story ID prefix (e.g., "MIGRATE")
- --plan-only — Generate graph without executing
- --execute — Execute immediately (skip confirmation)
- --max-parallel — Concurrent tasks (default: 3)
- --agent — BMAD agent for planning (analyst, architect, dev, pm, etc.)
- --context — 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
`

---

$3

#### prd validate — Check PRD Structure

`bash


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

`bash


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.

---

$3

#### epics create — Generate Epics from PRD

`bash


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

`bash
bmad-workflow epics list
bmad-workflow epics list --json
`

---

$3

#### stories create — Generate Stories from Epic

`bash


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

`bash


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:

`bash


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

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

#### stories move — Move to QA Directory

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

---

$3

#### config validate

`bash
bmad-workflow config validate
`

#### config show

`bash
bmad-workflow config show
bmad-workflow config show --json
`

---

Configuration

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

`yaml


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:

`bash


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 |

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

$3

`bash
git clone git@gitlab.com:dev_squad/repo/cli/bmad-orchestrator.git
cd bmad-orchestrator
npm install
npm run build
./bin/dev --help
npm test
`

$3

Want to improve agent personas, templates, or workflows?

👉 BMAD-METHOD Contributing Guide

$3

| 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

$3

`bash
claude auth login
claude --version
`

$3

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

$3

Check the session directory:
`bash
ls docs/decompose-sessions/session-*/
cat docs/decompose-sessions/session-*/SESSION_README.md
`

$3

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

$3

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

$3

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

$3

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

---

License

MIT - see LICENSE

---

Built on the BMAD Method

AI handles the lifecycle. You handle the vision.