@hyperdrive.bot/bmad-workflow 1.0.3 → 1.0.6

package/README.md

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