npm package: @hyperdrive.bot/bmad-workflow
Description: AI-driven development workflow orchestration CLI for BMAD projects
Author: DevSquad
Latest version: 1.0.33

# BMAD Workflow CLI

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

[![npm version](https://img.shields.io/npm/v/@hyperdrive.bot/bmad-workflow.svg)](https://www.npmjs.com/package/@hyperdrive.bot/bmad-workflow)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org/)
[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
[![BMAD Method](https://img.shields.io/badge/Built%20with-BMAD%20Method-blue)](https://github.com/bmad-code-org/BMAD-METHOD)

---

## Built on the BMAD Method

This CLI is the **automation engine** for the [**BMAD Method**](https://github.com/bmad-code-org/BMAD-METHOD) — a comprehensive, open-source methodology for AI-assisted software development.

<table>
<tr>
<td width="50%">

### 🧠 [BMAD Method](https://github.com/bmad-code-org/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.

</td>
<td width="50%">

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

</td>
</tr>
</table>

> **New to BMAD?** Start with the [BMAD Method repository](https://github.com/bmad-code-org/BMAD-METHOD) 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.) |

---

## Channel Transport

Channel transport is an opt-in alternative to subprocess-based agent execution. When enabled via `--use-channels`, the pipeline discovers running Claude Code sessions with Channel support and dispatches task envelopes to them over HTTP. This preserves agent context across multiple invocations (no cold-start overhead) and enables persistent, long-lived agent sessions that accumulate project knowledge throughout a pipeline run. Channel agents must be pre-started before the pipeline runs — the orchestrator does not auto-start them.

[Full documentation](docs/CHANNEL-INTEGRATION.md)

---

## Installation

### Prerequisites

- **Node.js 20+** - [Download](https://nodejs.org/)
- **Claude CLI** - [Install](https://docs.anthropic.com/claude/docs/claude-cli) and run `claude auth login`

> **No BMAD setup required.** The CLI ships with bundled agents, templates, and config. Just `init` and go — it works self-contained in any empty project directory with only a PRD file.

### Install

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

Verify:

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

---

## Quick Start

### Zero to Code in 2 Commands

The CLI works fully self-contained — no BMAD repo setup, no `_bmad/` directory, no config files. Just a PRD file:

```bash
mkdir my-project && cd my-project && git init
bmad-workflow workflow PRD-my-feature.md
```

That's it. Bundled agents, templates, and defaults kick in automatically. Output directories are created on the fly.

This was validated with an isolation test: empty git repo + single PRD file → 3 epics, 9 stories, full working React app with tests — zero external dependencies.

### 1. Full Pipeline (PRD → Code)

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

### 2. Decompose Any Goal

```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. QA Your Stories

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

### `workflow` — Full Pipeline Orchestration

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

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

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

---

### `epics` — Epic Management

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

---

### `stories` — Story Lifecycle

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

---

### `config` — Configuration

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

### Contributing to the CLI (this repo)

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

### Contributing to the BMAD Method

Want to improve agent personas, templates, or workflows?

👉 [**BMAD-METHOD Contributing Guide**](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)

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

```bash
claude auth login
claude --version
```

### "Configuration file not found"

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

### Decompose session issues

Check the session directory:
```bash
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](https://gitlab.com/dev_squad/repo/cli/bmad-orchestrator/-/issues)!

---

## Community & Resources

### BMAD Ecosystem

| Repository | Description |
|------------|-------------|
| [**BMAD-METHOD**](https://github.com/bmad-code-org/BMAD-METHOD) | 🧠 The core methodology — agents, templates, workflows |
| [**bmad-workflow**](https://gitlab.com/dev_squad/repo/cli/bmad-orchestrator) (this repo) | ⚡ CLI automation engine |

### Get Help

- **BMAD Method Questions:** [BMAD Discussions](https://github.com/bmad-code-org/BMAD-METHOD/discussions)
- **CLI Issues:** [GitLab Issues](https://gitlab.com/dev_squad/repo/cli/bmad-orchestrator/-/issues)

### Learn More

- 📖 [BMAD Method Documentation](https://github.com/bmad-code-org/BMAD-METHOD#readme)
- 🎓 [Getting Started Guide](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/getting-started.md)
- 🤖 [Agent Personas Reference](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/bmad-agent)

---

## License

MIT - see [LICENSE](LICENSE)

---

<p align="center">
  <b>Built on the <a href="https://github.com/bmad-code-org/BMAD-METHOD">BMAD Method</a></b><br>
  <i>AI handles the lifecycle. You handle the vision.</i>
</p>