@hyperdrive.bot/bmad-workflow 1.0.2

package/README.md

@@ -0,0 +1,1017 @@
+# BMAD Orchestrator 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)
+
+## Features
+
+- **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
+
+The BMAD CLI features a **pipelined workflow architecture** that executes story creation and development phases **concurrently**, significantly reducing total workflow time.
+
+### How It Works
+
+Traditional sequential workflow processes one phase at a time:
+
+```
+Sequential: [Create All Stories] → [Develop All Stories]
+             └─ 15 × 60s = 900s ─┘   └─ 15 × 120s = 1800s ─┘
+             Total: 2700s (45 minutes)
+```
+
+Pipelined workflow overlaps story creation and development:
+
+```
+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
+```
+
+**Key Components:**
+
+- **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
+
+### Performance Benefits
+
+| 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:**
+
+- Number of stories in epic (more stories = greater benefit)
+- Worker pool size (`--parallel` flag)
+- Story creation vs development time ratio
+
+### When to Use Each Mode
+
+**Pipelined Mode (Default, Recommended):**
+
+- ✅ Processing multiple stories (3+)
+- ✅ Normal operation with adequate API rate limits
+- ✅ Maximizing throughput
+- ✅ Modern development workflows
+
+**Sequential Mode (`--no-pipeline`):**
+
+- ⚠️ 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
+
+### Global Installation (Recommended)
+
+Install the CLI globally to use `bmad-workflow` command anywhere:
+
+```bash
+npm install -g @bmad/workflow-cli
+```
+
+Verify the installation:
+
+```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
+```
+
+Run via npx:
+
+```bash
+npx bmad-workflow --version
+npx bmad-workflow --help
+```
+
+Or add to your package.json scripts:
+
+```json
+{
+  "scripts": {
+    "workflow": "bmad-workflow"
+  }
+}
+```
+
+Then run with:
+
+```bash
+npm run workflow -- --help
+```
+
+## Quick Start
+
+1. **Navigate to your project directory:**
+
+   ```bash
+   cd your-project
+   ```
+
+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
+
+   # Required: Epic configuration
+   epicFilePattern: epic-{n}*.md
+
+   # Required: Architecture configuration
+   architectureSharded: true
+   architectureShardedLocation: docs/architecture
+
+   # Required: Story location
+   devStoryLocation: docs/stories
+
+   # Optional: Files to load during development
+   devLoadAlwaysFiles:
+     - docs/architecture/coding-standards.md
+     - docs/architecture/tech-stack.md
+
+   # Optional: QA configuration
+   qaLocation: docs/qa
+   ```
+
+3. **Run your first workflow:**
+
+   ```bash
+   bmad-workflow workflow docs/prd.md
+   ```
+
+   This will:
+   - Parse the PRD document
+   - Generate epics from the PRD
+   - Create user stories from each epic
+   - Execute development workflows for each story
+
+## Configuration
+
+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.
+
+### Configuration File Format
+
+Create `.bmad-core/core-config.yaml` with the following structure:
+
+```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)
+
+# 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
+
+# Story Configuration
+devStoryLocation: docs/stories # Directory for active stories
+
+# QA Configuration
+qaLocation: docs/qa # Directory for QA artifacts
+
+# Development Configuration (Optional)
+devLoadAlwaysFiles: # Files loaded during development
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/source-tree.md
+
+# Markdown Exploder (Optional)
+markdownExploder: true # Enable markdown section splitting
+
+# Debug Log (Optional)
+devDebugLog: .ai/debug-log.md # Path to debug log file
+
+# Slash Command Prefix (Optional)
+slashPrefix: BMad # Prefix for slash commands
+```
+
+### Validating Configuration
+
+Validate your configuration file:
+
+```bash
+bmad-workflow config validate
+```
+
+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
+
+Display your current configuration:
+
+```bash
+# Display as YAML (human-readable)
+bmad-workflow config show
+
+# Display as JSON (machine-readable)
+bmad-workflow config show --json
+```
+
+## Commands
+
+### Workflow Commands
+
+#### `workflow` - Complete PRD → Epic → Story → Dev Orchestration
+
+Execute the complete workflow from a single entry point:
+
+```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
+
+# Custom parallelization and intervals
+bmad-workflow workflow docs/PRD-feature.md --parallel 5 --prd-interval 60
+
+# 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
+```
+
+**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)
+
+### Epic Commands
+
+#### `epics create` - Create Epic Files from PRD
+
+Generate epic files from a PRD document:
+
+```bash
+# Create all epics from PRD
+bmad-workflow epics create docs/prd.md
+
+# Create specific range of epics
+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
+```
+
+**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:
+
+```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 create` - Create Story Files from Epic
+
+Generate story files from an epic:
+
+```bash
+# Create all stories from epic
+bmad-workflow stories create docs/epics/epic-1-foundation.md
+
+# Create with high concurrency
+bmad-workflow stories create epic.md --parallel 10
+
+# Create starting 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
+```
+
+**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:
+
+```bash
+# Develop all AUTH stories
+bmad-workflow stories develop "docs/stories/AUTH-*.md"
+
+# Develop with custom interval
+bmad-workflow stories develop "**/*-auth-*.md" --interval 60
+
+# Develop 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 list` - List All Stories
+
+Display all stories with filtering options:
+
+```bash
+# List all stories
+bmad-workflow stories list
+
+# List only draft stories
+bmad-workflow stories list --status=draft
+
+# List stories from epic 4
+bmad-workflow stories list --epic=4
+
+# List ready stories from epic 4 as JSON
+bmad-workflow stories list --status=ready --epic=4 --json
+```
+
+**Flags:**
+
+- `--status <value>` - Filter by story status (draft, ready, done, inprogress, failed)
+- `--epic <n>` - Filter by epic number
+- `--json` - Output results as JSON
+
+#### `stories move` - Move Stories to QA Directory
+
+Move completed story files to QA directory:
+
+```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
+```
+
+#### `config validate` - Validate Configuration File
+
+```bash
+bmad-workflow config validate
+```
+
+## Common Workflows
+
+### Complete PRD Implementation
+
+Execute the full PRD → Epic → Story → Dev pipeline:
+
+```bash
+bmad-workflow workflow docs/PRD-new-feature.md --parallel 5
+```
+
+### Incremental Epic Creation
+
+Create epics one batch at a time with delays:
+
+```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
+```
+
+### Parallel Story Generation
+
+Generate all stories from an epic with high concurrency:
+
+```bash
+bmad-workflow stories create docs/epics/epic-2-backend.md --parallel 10 --interval 30
+```
+
+### Sequential Story Development
+
+Develop stories one at a time with delays:
+
+```bash
+bmad-workflow stories develop "docs/stories/FEAT-*.md" --interval 120
+```
+
+### Dry Run Preview
+
+Preview workflow actions without executing:
+
+```bash
+bmad-workflow workflow docs/PRD-feature.md --dry-run --verbose
+```
+
+## Troubleshooting
+
+### Common Errors and Solutions
+
+#### "Configuration file not found"
+
+**Error:**
+
+```
+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:**
+
+```
+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:
+
+   ```bash
+   claude auth login
+   ```
+
+3. Verify installation:
+
+   ```bash
+   claude --version
+   which claude
+   ```
+
+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:**
+
+```
+✗ 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.
+```
+
+**Solutions:**
+
+1. Verify the file exists:
+
+   ```bash
+   ls -la docs/prd.md
+   ```
+
+2. Check your current directory:
+
+   ```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.
+```
+
+**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:**
+
+```
+✗ Error: Invalid epic format at line 42
+💡 Suggestion: Problem at line 42: "## Epic A: Title".
+Check the expected format for this section.
+```
+
+**Solutions:**
+
+1. Check the epic numbering format - must use numbers:
+
+   ```markdown
+   <!-- ✓ Correct -->
+
+   ## Epic 1: Foundation
+
+   ## Epic 2: Backend Services
+
+   <!-- ✗ Incorrect -->
+
+   ## 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'
+```
+
+**Solutions:**
+
+1. Check field types in configuration:
+
+   ```yaml
+   # ✓ Correct
+   prdFile: docs/prd.md
+   prdSharded: true
+
+   # ✗ Incorrect
+   prdFile: 123
+   prdSharded: "yes"
+   ```
+
+2. Run validation to see all errors:
+
+   ```bash
+   bmad-workflow config validate
+   ```
+
+3. Refer to the Configuration section for field requirements
+
+#### "Workflow completed with failures"
+
+When workflows complete with failures, check the summary output for specific error details:
+
+```bash
+# Run with verbose mode for detailed error output
+bmad-workflow workflow docs/prd.md --verbose
+```
+
+**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:
+
+   ```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
+```
+
+## Development
+
+### Local Development Setup
+
+If you're contributing to the BMAD Orchestrator CLI:
+
+```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
+```
+
+For detailed development guidelines, testing practices, and coding standards, see **[CONTRIBUTING.md](docs/CONTRIBUTING.md)**.
+
+### Project Structure
+
+```
+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
+
+Compile TypeScript to JavaScript:
+
+```bash
+npm run build
+```
+
+### Linting
+
+Run ESLint to check code quality:
+
+```bash
+npm run lint
+```
+
+### Testing
+
+Run the test suite:
+
+```bash
+npm run test
+```
+
+Run tests with coverage:
+
+```bash
+npm run test:coverage
+```
+
+### TypeScript Configuration
+
+This project uses TypeScript strict mode with the following flags enabled:
+
+- `noImplicitAny`
+- `strictNullChecks`
+- `strictFunctionTypes`
+- `strictPropertyInitialization`
+- `noImplicitThis`
+- `alwaysStrict`
+
+## License
+
+MIT