npm - @hyperdrive.bot/bmad-workflow - Versions diffs - 1.0.2 → 1.0.4 - Mend

@hyperdrive.bot/bmad-workflow 1.0.2 → 1.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (2) hide show

package/README.md +373 -790
package/package.json +5 -6

package/README.md CHANGED Viewed

@@ -1,1017 +1,600 @@
-# BMAD Orchestrator CLI
+# BMAD Workflow CLI
-[![CI](https://github.com/your-org/super-repo/actions/workflows/ci.yml/badge.svg)](https://github.com/your-org/super-repo/actions/workflows/ci.yml)
-[![Tests](https://github.com/your-org/super-repo/actions/workflows/test.yml/badge.svg)](https://github.com/your-org/super-repo/actions/workflows/test.yml)
-[![codecov](https://codecov.io/gh/your-org/super-repo/branch/main/graph/badge.svg)](https://codecov.io/gh/your-org/super-repo)
-[![oclif](https://img.shields.io/badge/cli-oclif-brightgreen.svg)](https://oclif.io)
-[![Version](https://img.shields.io/npm/v/bmad-workflow.svg)](https://npmjs.org/package/bmad-workflow)
-[![Downloads/week](https://img.shields.io/npm/dw/bmad-workflow.svg)](https://npmjs.org/package/bmad-workflow)
-A professional command-line tool for orchestrating AI-driven development workflows. Built with oclif framework, this CLI manages PRD → Epic → Story → Development workflows, spawning Claude AI agents to generate documentation and implement features.
-## Table of Contents
-- [Features](#features)
-- [Pipelined Workflow Architecture](#pipelined-workflow-architecture)
-- [Installation](#installation)
-  - [Prerequisites](#prerequisites)
-  - [Global Installation](#global-installation-recommended)
-  - [Local Installation](#local-installation-project-specific)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [Commands](#commands)
-- [Common Workflows](#common-workflows)
-- [Troubleshooting](#troubleshooting)
-- [Development](#development)
-- [License](#license)
+> **AI-powered development lifecycle automation — from vision to verified code.**
-## Features
+[![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)
-- **PRD to Epic Generation**: Parse Product Requirement Documents and generate epic files
-- **Epic to Story Generation**: Break down epics into implementable user stories
-- **Automated Development**: Execute development workflows with AI agents
-- **Pipelined Workflow Execution**: Story creation and development run concurrently for 44% faster execution
-- **Parallel Processing**: Support for concurrent epic/story creation with configurable concurrency
-- **Type-Safe**: Built with TypeScript in strict mode for reliability
-- **Comprehensive Testing**: Unit, integration, and e2e test infrastructure
-- **Structured Logging**: Production-ready logging with Pino
-- **Real-Time Progress Tracking**: Visual progress indicators showing concurrent phase execution
-- **Dry-Run Mode**: Preview actions without execution
-- **Graceful Cancellation**: Cancel workflows with Ctrl+C without corrupting state
-- **Flexible Execution Modes**: Choose between pipelined (default) or sequential execution
+---
-## Pipelined Workflow Architecture
+## Built on the BMAD Method
-The BMAD CLI features a **pipelined workflow architecture** that executes story creation and development phases **concurrently**, significantly reducing total workflow time.
+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.
-### How It Works
+<table>
+<tr>
+<td width="50%">
-Traditional sequential workflow processes one phase at a time:
+### 🧠 [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.
-```
-Sequential: [Create All Stories] → [Develop All Stories]
-             └─ 15 × 60s = 900s ─┘   └─ 15 × 120s = 1800s ─┘
-             Total: 2700s (45 minutes)
-```
+**Start here** to understand the philosophy and set up your project.
-Pipelined workflow overlaps story creation and development:
+</td>
+<td width="50%">
-```
-Pipelined:  [Create Stories ─────────────────────┐
-             └→ Queue → [Dev Worker 1] → Done   │
-             └→ Queue → [Dev Worker 2] → Done   │ Concurrent Execution
-             └→ Queue → [Dev Worker 3] → Done   │
-             └→ Queue → [Dev Worker...] → Done  ┘
-             Total: ~1500s (25 minutes) - 44% faster
-```
+### ⚡ 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.
-**Key Components:**
+**Use this** to automate and accelerate execution.
-- **Story Queue**: Thread-safe FIFO queue coordinates story handoff from creation to development
-- **Producer Phase**: Story creation enqueues completed stories as they finish
-- **Worker Pool**: Multiple concurrent dev workers consume from queue (configurable via `--parallel`)
-- **Pipeline Coordinator**: Orchestrates concurrent phases using Promise.allSettled
+</td>
+</tr>
+</table>
-### Performance Benefits
+> **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.*
-| Workflow Size | Sequential | Pipelined | Time Saved |
-| ------------- | ---------- | --------- | ---------- |
-| 5 stories     | 15 min     | 10 min    | 33%        |
-| 10 stories    | 30 min     | 18 min    | 40%        |
-| 15 stories    | 45 min     | 25 min    | 44%        |
-| 20 stories    | 60 min     | 35 min    | 42%        |
+---
-**Performance scales with:**
+## What This CLI Does
-- Number of stories in epic (more stories = greater benefit)
-- Worker pool size (`--parallel` flag)
-- Story creation vs development time ratio
+The BMAD Workflow CLI provides **five core capabilities** for AI-assisted development:
-### When to Use Each Mode
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                                                                          │
+│  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   │
+│                                                                          │
+└──────────────────────────────────────────────────────────────────────────┘
+```
-**Pipelined Mode (Default, Recommended):**
+---
-- ✅ Processing multiple stories (3+)
-- ✅ Normal operation with adequate API rate limits
-- ✅ Maximizing throughput
-- ✅ Modern development workflows
+## Key Features
-**Sequential Mode (`--no-pipeline`):**
+| 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.) |
-- ⚠️ Debugging workflow issues
-- ⚠️ API rate limit constraints
-- ⚠️ Single story processing
-- ⚠️ Backward compatibility requirements
+---
 ## Installation
 ### Prerequisites
-Before installing the BMAD Orchestrator CLI, ensure you have:
-- **Node.js 18.x LTS or higher** - [Download Node.js](https://nodejs.org/)
-- **Claude CLI** - Required for AI agent operations. Install and authenticate Claude CLI before using this tool.
-- **Git** - For repository operations and version control
+- **Node.js 20+** - [Download](https://nodejs.org/)
+- **Claude CLI** - [Install](https://docs.anthropic.com/claude/docs/claude-cli) and run `claude auth login`
+- **BMAD Method** - [Set up in your project](https://github.com/bmad-code-org/BMAD-METHOD#quick-start)
-### Global Installation (Recommended)
-Install the CLI globally to use `bmad-workflow` command anywhere:
+### Install
 ```bash
-npm install -g @bmad/workflow-cli
+npm install -g @hyperdrive.bot/bmad-workflow
 ```
-Verify the installation:
+Verify:
 ```bash
 bmad-workflow --version
 bmad-workflow --help
 ```
-### Local Installation (Project-specific)
-Install as a development dependency in your project:
+---
-```bash
-npm install --save-dev @bmad/workflow-cli
-```
+## Quick Start
-Run via npx:
+### 1. Full Pipeline (PRD → Code)
 ```bash
-npx bmad-workflow --version
-npx bmad-workflow --help
-```
+# Run complete workflow from a PRD
+bmad-workflow workflow docs/PRD-my-feature.md
-Or add to your package.json scripts:
-```json
-{
-  "scripts": {
-    "workflow": "bmad-workflow"
-  }
-}
+# What happens:
+# ✓ Parses PRD, extracts epics
+# ✓ Creates epic files with AI
+# ✓ Generates stories from each epic
+# ✓ Develops each story (pipelined)
+# 🎉 Done!
 ```
-Then run with:
+### 2. Decompose Any Goal
 ```bash
-npm run workflow -- --help
-```
-## Quick Start
-1. **Navigate to your project directory:**
-   ```bash
-   cd your-project
-   ```
+# Break a big goal into tasks
+bmad-workflow decompose "Migrate entire codebase to TypeScript" \
+  --per-file --file-pattern "src/**/*.js"
-2. **Create BMAD configuration:**
-   Create `.bmad-core/core-config.yaml` with your project settings:
-   ```yaml
-   # Required: PRD configuration
-   prdFile: docs/prd.md
-   prdSharded: true
-   prdShardedLocation: docs/prd
+# What happens:
+# ✓ AI analyzes the goal
+# ✓ Creates dependency graph
+# ✓ Generates task for each file
+# ✓ Executes in parallel layers
+```
-   # Required: Epic configuration
-   epicFilePattern: epic-{n}*.md
+### 3. QA Your Stories
-   # Required: Architecture configuration
-   architectureSharded: true
-   architectureShardedLocation: docs/architecture
+```bash
+# Run QA workflow with fix-forward cycles
+bmad-workflow stories qa "docs/stories/AUTH-*.md" --max-retries 3
-   # Required: Story location
-   devStoryLocation: docs/stories
+# 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/
+```
-   # Optional: Files to load during development
-   devLoadAlwaysFiles:
-     - docs/architecture/coding-standards.md
-     - docs/architecture/tech-stack.md
+---
-   # Optional: QA configuration
-   qaLocation: docs/qa
-   ```
+## Commands Overview
-3. **Run your first workflow:**
+### `workflow` — Full Pipeline Orchestration
-   ```bash
-   bmad-workflow workflow docs/prd.md
-   ```
+Execute the complete PRD → Epic → Story → Dev pipeline:
-   This will:
-   - Parse the PRD document
-   - Generate epics from the PRD
-   - Create user stories from each epic
-   - Execute development workflows for each story
+```bash
+# Basic usage
+bmad-workflow workflow docs/PRD-feature.md
-## Configuration
+# Skip phases
+bmad-workflow workflow docs/PRD-feature.md --skip-dev
+bmad-workflow workflow docs/epics/epic-1.md --skip-epics
-The BMAD CLI requires a `.bmad-core/core-config.yaml` file in your project root. This file defines paths and settings for the workflow orchestration.
+# Tune performance
+bmad-workflow workflow docs/PRD-feature.md --parallel 5 --pipeline
-### Configuration File Format
+# Dry run
+bmad-workflow workflow docs/PRD-feature.md --dry-run --verbose
+```
-Create `.bmad-core/core-config.yaml` with the following structure:
+**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
-```yaml
-# PRD Configuration
-prdFile: docs/prd.md # Path to main PRD file
-prdVersion: v4 # PRD version (optional)
-prdSharded: true # Whether PRD is split across multiple files
-prdShardedLocation: docs/prd # Directory containing PRD shards
+---
-# Epic Configuration
-epicFilePattern: epic-{n}*.md # Pattern for epic filenames ({n} = epic number)
+### `decompose` — Task Graph Decomposition
-# Architecture Configuration
-architectureFile: docs/architecture.md # Path to main architecture file (optional)
-architectureVersion: v4 # Architecture version (optional)
-architectureSharded: true # Whether architecture is split across files
-architectureShardedLocation: docs/architecture # Directory containing architecture files
+Break large goals into executable task graphs with dependency management:
-# Story Configuration
-devStoryLocation: docs/stories # Directory for active stories
+```bash
+# Basic decomposition
+bmad-workflow decompose "Add user authentication"
-# QA Configuration
-qaLocation: docs/qa # Directory for QA artifacts
+# Per-file mode (great for migrations)
+bmad-workflow decompose "Convert to TypeScript" \
+  --per-file --file-pattern "src/**/*.js"
-# Development Configuration (Optional)
-devLoadAlwaysFiles: # Files loaded during development
-  - docs/architecture/coding-standards.md
-  - docs/architecture/tech-stack.md
-  - docs/architecture/source-tree.md
+# Output as BMAD stories
+bmad-workflow decompose "Refactor API layer" \
+  --story-format --story-prefix "REFACTOR"
-# Markdown Exploder (Optional)
-markdownExploder: true # Enable markdown section splitting
+# Plan only (don't execute)
+bmad-workflow decompose "Redesign database schema" --plan-only
-# Debug Log (Optional)
-devDebugLog: .ai/debug-log.md # Path to debug log file
+# Execute immediately
+bmad-workflow decompose "Add dark mode" --execute --max-parallel 5
-# Slash Command Prefix (Optional)
-slashPrefix: BMad # Prefix for slash commands
+# Use specific BMAD agent
+bmad-workflow decompose "Design new API" --agent architect --plan-only
 ```
-### Validating Configuration
-Validate your configuration file:
+**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)
-```bash
-bmad-workflow config validate
+**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
 ```
-This command will:
-- Check if the configuration file exists
-- Validate YAML syntax
-- Verify required fields are present
-- Check field types and values
-- Report specific errors with suggestions
+---
-### Viewing Configuration
+### `prd` — PRD Tools
-Display your current configuration:
+#### `prd validate` — Check PRD Structure
 ```bash
-# Display as YAML (human-readable)
-bmad-workflow config show
+# Validate and preview extraction
+bmad-workflow prd validate docs/PRD-feature.md
-# Display as JSON (machine-readable)
-bmad-workflow config show --json
+# Output as JSON
+bmad-workflow prd validate docs/PRD-feature.md --json
 ```
-## Commands
-### Workflow Commands
+Shows: epic count, existing files, story counts, what would be created.
-#### `workflow` - Complete PRD → Epic → Story → Dev Orchestration
-Execute the complete workflow from a single entry point:
+#### `prd fix` — Auto-Fix PRD Format
 ```bash
-# Start workflow from PRD
-bmad-workflow workflow docs/PRD-feature.md
-# Start from epic, skip development
-bmad-workflow workflow docs/epics/epic-1.md --skip-dev
-# Dry run to preview actions
-bmad-workflow workflow docs/PRD-feature.md --dry-run
+# Fix PRD format with AI
+bmad-workflow prd fix docs/PRD-feature.md
-# Custom parallelization and intervals
-bmad-workflow workflow docs/PRD-feature.md --parallel 5 --prd-interval 60
+# With architecture context
+bmad-workflow prd fix docs/PRD-feature.md --reference docs/architecture.md
-# Use sequential mode for backward compatibility
-bmad-workflow workflow docs/PRD-feature.md --no-pipeline
-# Pipelined mode (default) - story creation and dev run in parallel
-bmad-workflow workflow docs/PRD-feature.md --pipeline
+# Use Gemini instead of Claude
+bmad-workflow prd fix docs/PRD-feature.md --provider gemini
 ```
-**Flags:**
-- `--dry-run` - Preview actions without execution
-- `--parallel <n>` - Max concurrent epic/story creations (default: 3)
-- `--prd-interval <seconds>` - Seconds between epic creation batches (default: 60)
-- `--epic-interval <seconds>` - Seconds between story creation batches (default: 60)
-- `--story-interval <seconds>` - Seconds between story development (default: 60)
-- `--skip-epics` - Skip epic creation phase
-- `--skip-stories` - Skip story creation phase
-- `--skip-dev` - Skip development phase
-- `--reference <file>` - Additional context files for AI agents (repeatable)
-- `--prefix <string>` - Filename prefix for generated files
-- `--verbose` - Detailed output mode
-- `--pipeline` - Enable pipelined workflow (story and dev phases in parallel, default: true)
-- `--no-pipeline` - Disable pipelined mode (execute phases sequentially)
+Creates backup (`.bak`) before modifying.
-### Epic Commands
+---
-#### `epics create` - Create Epic Files from PRD
+### `epics` — Epic Management
-Generate epic files from a PRD document:
+#### `epics create` — Generate Epics from PRD
 ```bash
-# Create all epics from PRD
+# Create all epics
 bmad-workflow epics create docs/prd.md
-# Create specific range of epics
+# Create specific range
 bmad-workflow epics create docs/prd.md --start 2 --count 3
-# Create with additional context
-bmad-workflow epics create docs/prd.md --reference docs/architecture.md --interval 5
+# With context files
+bmad-workflow epics create docs/prd.md --reference docs/architecture.md
 ```
-**Flags:**
-- `--start <n>` - Start from epic number N (default: 1)
-- `--count <n>` - Number of epics to create (default: all remaining)
-- `--interval <seconds>` - Seconds to wait between epic creations (default: 0)
-- `--prefix <string>` - Filename prefix for epic files
-- `--reference <file>` - Reference file paths for AI agent context (repeatable)
-#### `epics list` - List All Epics
-Display all epic files with metadata:
+#### `epics list` — List All Epics
 ```bash
-# Display epics in table format
 bmad-workflow epics list
-# Output as JSON
 bmad-workflow epics list --json
 ```
-**Flags:**
-- `--json` - Output as JSON array
+---
-### Story Commands
+### `stories` — Story Lifecycle
-#### `stories create` - Create Story Files from Epic
-Generate story files from an epic:
+#### `stories create` — Generate Stories from Epic
 ```bash
-# Create all stories from epic
-bmad-workflow stories create docs/epics/epic-1-foundation.md
+# Create all stories
+bmad-workflow stories create docs/epics/epic-1.md
-# Create with high concurrency
+# High concurrency
 bmad-workflow stories create epic.md --parallel 10
-# Create starting from specific story
+# Start from specific story
 bmad-workflow stories create epic.md --start 3
-# Create with additional context
-bmad-workflow stories create epic.md --reference docs/architecture.md --reference docs/api-spec.md
+# Use specific BMAD agent
+bmad-workflow stories create epic.md --agent sm --task create-next-story
 ```
-**Flags:**
-- `--parallel <n>` - Max concurrent story creations (default: 7)
-- `--interval <seconds>` - Seconds between batches (default: 30)
-- `--start <n>` - Story number to start from
-- `--prefix <string>` - Filename prefix for stories
-- `--reference <file>` - Additional context files for AI agents (repeatable)
-#### `stories develop` - Execute Development Workflow
-Develop stories using Claude AI dev agents:
+#### `stories develop` — Execute Development
 ```bash
-# Develop all AUTH stories
+# Develop matching stories
 bmad-workflow stories develop "docs/stories/AUTH-*.md"
-# Develop with custom interval
-bmad-workflow stories develop "**/*-auth-*.md" --interval 60
+# With interval between stories
+bmad-workflow stories develop "stories/*.md" --interval 60
-# Develop with architecture reference
+# With architecture reference
 bmad-workflow stories develop "stories/*.md" --reference docs/architecture.md
 ```
-**Flags:**
-- `--interval <seconds>` - Seconds to wait between stories (default: 30)
-- `--reference <file>` - Additional context files for dev agents (repeatable)
-**Note:** Stories are developed sequentially (one at a time) to prevent conflicts.
+#### `stories qa` — QA Workflow with Fix-Forward
-#### `stories list` - List All Stories
-Display all stories with filtering options:
+The QA command runs a complete quality assurance workflow:
 ```bash
-# List all stories
-bmad-workflow stories list
+# QA all AUTH stories
+bmad-workflow stories qa "docs/qa/stories/AUTH-*.md"
-# List only draft stories
-bmad-workflow stories list --status=draft
+# With retry cycles
+bmad-workflow stories qa "stories/*.md" --max-retries 3
-# List stories from epic 4
-bmad-workflow stories list --epic=4
+# Custom QA focus
+bmad-workflow stories qa "stories/*.md" --qa-prompt "Focus on security"
-# List ready stories from epic 4 as JSON
-bmad-workflow stories list --status=ready --epic=4 --json
+# Custom dev instructions
+bmad-workflow stories qa "stories/*.md" --dev-prompt "Prioritize performance fixes"
 ```
-**Flags:**
-- `--status <value>` - Filter by story status (draft, ready, done, inprogress, failed)
-- `--epic <n>` - Filter by epic number
-- `--json` - Output results as JSON
+**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/`
-#### `stories move` - Move Stories to QA Directory
+**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
-Move completed story files to QA directory:
+#### `stories list` — List Stories
 ```bash
-# Move all stories matching pattern
-bmad-workflow stories move "4.7-*.md"
-# Move without confirmation
-bmad-workflow stories move "4.*-*.md" --force
-# Move specific story
-bmad-workflow stories move "STORY-123-*.md"
-```
-**Flags:**
-- `--force` - Skip confirmation prompt
-### Config Commands
-#### `config show` - Display Current Configuration
-```bash
-# Display as YAML
-bmad-workflow config show
-# Display as JSON
-bmad-workflow config show --json
+bmad-workflow stories list
+bmad-workflow stories list --status=ready --epic=4
+bmad-workflow stories list --json
 ```
-#### `config validate` - Validate Configuration File
+#### `stories move` — Move to QA Directory
 ```bash
-bmad-workflow config validate
+bmad-workflow stories move "4.7-*.md"
+bmad-workflow stories move "STORY-*.md" --force
 ```
-## Common Workflows
+---
-### Complete PRD Implementation
+### `config` — Configuration
-Execute the full PRD → Epic → Story → Dev pipeline:
+#### `config validate`
 ```bash
-bmad-workflow workflow docs/PRD-new-feature.md --parallel 5
+bmad-workflow config validate
 ```
-### Incremental Epic Creation
-Create epics one batch at a time with delays:
+#### `config show`
 ```bash
-# Create first 3 epics
-bmad-workflow epics create docs/prd.md --start 1 --count 3 --interval 60
-# Create next batch
-bmad-workflow epics create docs/prd.md --start 4 --count 3 --interval 60
+bmad-workflow config show
+bmad-workflow config show --json
 ```
-### Parallel Story Generation
+---
-Generate all stories from an epic with high concurrency:
+## Configuration
-```bash
-bmad-workflow stories create docs/epics/epic-2-backend.md --parallel 10 --interval 30
-```
+Create `.bmad-core/core-config.yaml` in your project root:
-### Sequential Story Development
+```yaml
+# PRD Configuration
+prdFile: docs/prd.md
+prdSharded: true
+prdShardedLocation: docs/prd
-Develop stories one at a time with delays:
+# Epic Configuration
+epicFilePattern: epic-{n}*.md
-```bash
-bmad-workflow stories develop "docs/stories/FEAT-*.md" --interval 120
-```
+# Architecture
+architectureSharded: true
+architectureShardedLocation: docs/architecture
-### Dry Run Preview
+# Story Configuration
+devStoryLocation: docs/stories
-Preview workflow actions without executing:
+# QA Configuration
+qaLocation: docs/qa
-```bash
-bmad-workflow workflow docs/PRD-feature.md --dry-run --verbose
+# Development Context (always loaded by agents)
+devLoadAlwaysFiles:
+  - docs/architecture.md
+  - docs/coding-standards.md
+  - project-context.md
 ```
-## Troubleshooting
-### Common Errors and Solutions
+---
-#### "Configuration file not found"
+## Pipelined Execution
-**Error:**
+By default, story creation and development run **concurrently**:
 ```
-Configuration file not found at '.bmad-core/core-config.yaml'.
-Ensure you're running this command from the project root directory.
-```
-**Solutions:**
-1. Check that you're in the project root directory:
-   ```bash
-   pwd  # Should show your project root
-   ls .bmad-core/core-config.yaml  # Should exist
-   ```
-2. Create the configuration file if it doesn't exist:
-   ```bash
-   mkdir -p .bmad-core
-   # Copy the configuration example from the Configuration section above
-   ```
-3. Verify file permissions:
-   ```bash
-   ls -la .bmad-core/core-config.yaml
-   # Ensure you have read permissions
-   ```
-#### "Invalid YAML syntax in configuration file"
-**Error:**
+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
 ```
-Invalid YAML syntax in '.bmad-core/core-config.yaml' at line 5:
-unexpected end of the stream within a double quoted scalar
-```
-**Solutions:**
-1. Check YAML syntax using an online validator
-2. Common YAML errors:
-   - Missing quotes around strings with special characters
-   - Incorrect indentation (use spaces, not tabs)
-   - Unclosed quotes or brackets
-3. Validate your configuration:
-   ```bash
-   bmad-workflow config validate
-   ```
-#### "Claude CLI not found"
-**Error:**
-```
-Agent execution failed
-→ Exit code: 127
-→ Error output: claude: command not found
-💡 Suggestion: Ensure Claude CLI is installed and accessible in your PATH.
-Run "claude --version" to verify.
-```
-**Solutions:**
-1. Install Claude CLI:
-   ```bash
-   # Follow Anthropic's official installation guide
-   # https://docs.anthropic.com/claude/docs/claude-cli
-   ```
-2. Authenticate Claude CLI:
+Control with `--pipeline` (default) or `--no-pipeline`.
-   ```bash
-   claude auth login
-   ```
+---
-3. Verify installation:
+## AI Providers
-   ```bash
-   claude --version
-   which claude
-   ```
+Supports multiple AI providers:
-4. Add Claude CLI to PATH (if not already):
-   ```bash
-   # For bash/zsh
-   export PATH="/path/to/claude:$PATH"
-   # Add to ~/.bashrc or ~/.zshrc for persistence
-   ```
-#### "File not found: docs/prd.md"
-**Error:**
+```bash
+# Claude (default)
+bmad-workflow workflow docs/prd.md --provider claude
-```
-✗ Error: File not found: docs/prd.md
-💡 Suggestion: Check that you're in the project root directory and
-the path 'docs/prd.md' is correct.
+# Gemini
+bmad-workflow decompose "Add feature" --provider gemini
 ```
-**Solutions:**
+---
-1. Verify the file exists:
+## BMAD Agent Integration
-   ```bash
-   ls -la docs/prd.md
-   ```
+Use any BMAD agent for specialized tasks:
-2. Check your current directory:
+| 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
-   pwd
-   cd /path/to/your/project
-   ```
-3. Use absolute path if needed:
-   ```bash
-   bmad-workflow workflow /absolute/path/to/docs/prd.md
-   ```
-#### "Permission denied" on File Operations
-**Error:**
-```
-✗ Error: Permission denied: docs/stories
-💡 Suggestion: Check that you're in the project root directory and
-the path 'docs/stories' is correct.
+```bash
+bmad-workflow decompose "Design API" --agent architect
+bmad-workflow stories create epic.md --agent sm
 ```
-**Solutions:**
-1. Check file/directory permissions:
-   ```bash
-   ls -la docs/stories
-   ```
+---
-2. Fix permissions if needed:
-   ```bash
-   chmod 755 docs/stories
-   ```
-3. Ensure you have write access to the directory:
-   ```bash
-   # Create directory if it doesn't exist
-   mkdir -p docs/stories
-   ```
-#### "Invalid epic format at line 42"
-**Error:**
+## Project Structure
 ```
-✗ Error: Invalid epic format at line 42
-💡 Suggestion: Problem at line 42: "## Epic A: Title".
-Check the expected format for this section.
+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
 ```
-**Solutions:**
-1. Check the epic numbering format - must use numbers:
-   ```markdown
-   <!-- ✓ Correct -->
-   ## Epic 1: Foundation
+---
-   ## Epic 2: Backend Services
+## Contributing
-   <!-- ✗ Incorrect -->
+### Contributing to the CLI (this repo)
-   ## Epic A: Foundation
-   ## Epic B: Backend Services
-   ```
-2. Verify markdown structure in PRD/epic files
-3. Use consistent heading levels (## for epics)
-#### "Configuration validation failed"
-**Error:**
-```
-✗ Error: Invalid field "prdFile"
-💡 Suggestion: Field 'prdFile' expects string, got number.
-Example: 'docs/prd.md'
+```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
 ```
-**Solutions:**
-1. Check field types in configuration:
+### Contributing to the BMAD Method
-   ```yaml
-   # ✓ Correct
-   prdFile: docs/prd.md
-   prdSharded: true
+Want to improve agent personas, templates, or workflows?
-   # ✗ Incorrect
-   prdFile: 123
-   prdSharded: "yes"
-   ```
+👉 [**BMAD-METHOD Contributing Guide**](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/CONTRIBUTING.md)
-2. Run validation to see all errors:
+### Development Scripts
-   ```bash
-   bmad-workflow config validate
-   ```
+| 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 |
-3. Refer to the Configuration section for field requirements
+---
-#### "Workflow completed with failures"
+## Troubleshooting
-When workflows complete with failures, check the summary output for specific error details:
+### "Claude CLI not found"
 ```bash
-# Run with verbose mode for detailed error output
-bmad-workflow workflow docs/prd.md --verbose
+claude auth login
+claude --version
 ```
-**Common causes:**
-- Agent timeout (increase intervals with --interval flags)
-- API rate limits (reduce --parallel count)
-- Invalid file formats (check PRD/epic structure)
-- Missing dependencies (verify configuration files exist)
-### Pipeline-Specific Issues
-#### "Pipeline mode enabled but running sequentially"
-If you notice the pipeline is not executing concurrently:
-**Possible causes:**
-1. **Dry-run mode enabled** - Pipeline only works in execution mode:
-   ```bash
-   # Remove --dry-run to use pipeline
-   bmad-workflow workflow docs/prd.md
-   ```
-2. **Only one phase enabled** - Pipeline requires both story and dev phases:
-   ```bash
-   # Correct: both phases enabled (default)
-   bmad-workflow workflow docs/prd.md
-   # Won't pipeline: dev phase skipped
-   bmad-workflow workflow docs/prd.md --skip-dev
-   ```
-3. **Explicitly disabled** - Check for `--no-pipeline` flag:
-   ```bash
-   # Use --pipeline or omit flag (default is pipeline mode)
-   bmad-workflow workflow docs/prd.md --pipeline
-   ```
-#### Pipeline Performance Not as Expected
-If pipeline mode isn't showing performance improvements:
-1. **Low story count** - Pipeline benefits scale with story count:
-   - 1-2 stories: Minimal benefit
-   - 3-5 stories: ~30% improvement
-   - 10+ stories: ~40-44% improvement
-2. **Worker pool size too small** - Increase concurrency:
-   ```bash
-   # Increase to 5 workers (default is 3)
-   bmad-workflow workflow docs/prd.md --parallel 5
-   ```
-3. **Story creation bottleneck** - If stories create slowly, increase story creation parallelism:
+### "Configuration file not found"
-   ```bash
-   bmad-workflow stories create epic.md --parallel 10
-   ```
-4. **API rate limits** - Monitor for rate limit errors and adjust intervals:
-   ```bash
-   bmad-workflow workflow docs/prd.md --story-interval 90
-   ```
-#### Workers Not Processing Stories
-If dev workers appear idle while stories are queued:
-**Solutions:**
-1. Check verbose output for worker status:
-   ```bash
-   bmad-workflow workflow docs/prd.md --verbose
-   ```
-2. Verify stories are completing creation successfully
-3. Check for errors in story phase that prevent queue enqueuing
-4. Monitor worker logs for processing errors
-### Performance Issues
-#### Slow Epic/Story Creation
-If creation is slow:
-1. **Increase parallelization:**
-   ```bash
-   bmad-workflow workflow docs/prd.md --parallel 10
-   ```
-2. **Reduce intervals:**
-   ```bash
-   bmad-workflow workflow docs/prd.md --prd-interval 30 --epic-interval 30
-   ```
-3. **Process in batches:**
-   ```bash
-   bmad-workflow epics create docs/prd.md --start 1 --count 5
-   bmad-workflow epics create docs/prd.md --start 6 --count 5
-   ```
-#### High Memory Usage
-If experiencing high memory usage:
-1. **Reduce concurrency:**
-   ```bash
-   bmad-workflow workflow docs/prd.md --parallel 3
-   ```
-2. **Process smaller batches**
-3. **Monitor with verbose mode:**
-   ```bash
-   bmad-workflow workflow docs/prd.md --verbose
-   ```
-### Getting Help
-If you encounter issues not covered here:
-1. **Run with verbose mode** for detailed logs:
-   ```bash
-   bmad-workflow workflow docs/prd.md --verbose
-   ```
-2. **Check configuration validation:**
-   ```bash
-   bmad-workflow config validate
-   ```
-3. **Verify prerequisites:**
-   ```bash
-   node --version  # Should be 18.x or higher
-   claude --version  # Should return Claude CLI version
-   ```
-4. **Report issues** with:
-   - Error message and suggestion
-   - Command used
-   - Configuration file (sanitized)
-   - Node.js and CLI versions
-## Documentation
-### Architecture & API Documentation
-For in-depth technical documentation:
-- **[Architecture Overview](docs/ARCHITECTURE.md)** - System design, components, and data flow
-- **[API Documentation](docs/api/README.md)** - Complete API reference for all services, commands, and models
-- **[Contributing Guide](docs/CONTRIBUTING.md)** - Development guidelines and contribution process
-### Documentation Structure
-```
-docs/
-├── ARCHITECTURE.md        # System architecture and design patterns
-├── CONTRIBUTING.md        # Contribution guidelines and standards
-└── api/                   # API reference documentation
-    ├── README.md          # API overview and conventions
-    ├── commands/          # Command API documentation
-    ├── services/          # Service layer API docs
-    └── models/            # Type definitions and interfaces
+```bash
+ls .bmad-core/core-config.yaml
+bmad-workflow config validate
 ```
-## Development
-### Local Development Setup
-If you're contributing to the BMAD Orchestrator CLI:
+### Decompose session issues
+Check the session directory:
 ```bash
-# Clone the repository
-cd packages/cli/bmad-workflow
-# Install dependencies
-npm install
-# Build from source
-npm run build
-# Run locally using dev script
-./bin/dev --help
+ls docs/decompose-sessions/session-*/
+cat docs/decompose-sessions/session-*/SESSION_README.md
 ```
-For detailed development guidelines, testing practices, and coding standards, see **[CONTRIBUTING.md](docs/CONTRIBUTING.md)**.
+### QA gate not updating
-### Project Structure
+Ensure stories have proper markdown structure with `## QA Results` section.
-```
-packages/cli/bmad-workflow/
-├── src/
-│   ├── commands/          # oclif command classes
-│   ├── services/          # Business logic layer
-│   ├── models/            # TypeScript types and interfaces
-│   └── utils/             # Pure utility functions
-├── test/
-│   ├── commands/          # Command integration tests
-│   ├── services/          # Service unit tests
-│   ├── fixtures/          # Test data
-│   └── helpers/           # Test utilities
-├── tsconfig.json          # TypeScript configuration (strict mode)
-├── package.json           # Project manifest
-└── README.md              # This file
-```
+---
-### Build
+## Roadmap
-Compile TypeScript to JavaScript:
+- [ ] OpenAI GPT-4 provider support
+- [ ] Web UI for workflow visualization
+- [ ] GitHub Actions integration
+- [ ] VS Code extension
+- [ ] Custom agent templates
+- [ ] Parallel QA execution
-```bash
-npm run build
-```
+Have an idea? [Open an issue](https://gitlab.com/dev_squad/repo/cli/bmad-orchestrator/-/issues)!
-### Linting
+---
-Run ESLint to check code quality:
+## Community & Resources
-```bash
-npm run lint
-```
+### BMAD Ecosystem
-### Testing
+| 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 |
-Run the test suite:
+### Get Help
-```bash
-npm run test
-```
+- **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)
-Run tests with coverage:
+### Learn More
-```bash
-npm run test:coverage
-```
+- 📖 [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)
-### TypeScript Configuration
+---
-This project uses TypeScript strict mode with the following flags enabled:
+## License
-- `noImplicitAny`
-- `strictNullChecks`
-- `strictFunctionTypes`
-- `strictPropertyInitialization`
-- `noImplicitThis`
-- `alwaysStrict`
+MIT - see [LICENSE](LICENSE)
-## License
+---
-MIT
+<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>