interface ExitCodes {
  SUCCESS: 0;         // Command completed successfully
  ERROR: 1;           // Command failed (generic error)
  INVALID_ARGS: 2;    // Invalid command-line arguments
  NOT_FOUND: 3;       // Resource not found (file, directory, package)
  PERMISSION: 4;      // Permission denied
  ALREADY_EXISTS: 5;  // Resource already exists
  VALIDATION: 6;      // Validation failed
}

# Success (exit code 0)
npx bmad-method install --full
echo $?  # Output: 0

# Validation failure (exit code 6)
npx bmad-method validate  # when config has errors
echo $?  # Output: 6

# Permission error (exit code 4)
npx bmad-method install -d /root/protected
echo $?  # Output: 4

# Invalid arguments (exit code 2)
npx bmad-method install --unknown-option
echo $?  # Output: 2

interface InstallOptions {
  full?: boolean;              // -f, --full: Install complete BMad Method
  expansionOnly?: boolean;     // -x, --expansion-only: Only expansion packs
  directory?: string;          // -d, --directory: Installation path
  ide?: string[];              // -i, --ide: IDE identifiers (multiple allowed)
  expansionPacks?: string[];   // -e, --expansion-packs: Pack IDs (multiple allowed)
}

interface UpdateOptions {
  force?: boolean;             // --force: Overwrite modified files
  dryRun?: boolean;            // --dry-run: Preview changes only
}

interface FlattenOptions {
  input?: string;              // -i, --input: Source directory (default: cwd)
  output?: string;             // -o, --output: Output XML file (default: flattened-codebase.xml)
}

interface BuildOptions {
  agentsOnly?: boolean;        // -a, --agents-only: Build only agent bundles
  teamsOnly?: boolean;         // -t, --teams-only: Build only team bundles
  expansionsOnly?: boolean;    // -e, --expansions-only: Build only expansion bundles
  noExpansions?: boolean;      // --no-expansions: Skip expansion packs
  noClean?: boolean;           // --no-clean: Skip cleaning output directories
  expansion?: string;          // --expansion <name>: Build specific pack only
}

interface UpgradeOptions {
  project?: string;            // -p, --project: V3 project path (default: cwd)
  dryRun?: boolean;            // --dry-run: Preview changes only
  noBackup?: boolean;          // --no-backup: Skip backup creation
}

interface ValidIDEs {
  type: 'cursor' | 'claude-code' | 'windsurf' | 'trae' | 'roo' | 'kilo' |
        'cline' | 'crush' | 'github-copilot' | 'qwen-code' | 'opencode' |
        'iflow-cli' | 'auggie-cli' | 'gemini' | 'codex' | 'codex-web';
}

interface ValidExpansionPacks {
  type: 'bmad-godot-game-dev' | 'bmad-2d-unity-game-dev' | 'bmad-2d-phaser-game-dev' |
        'bmad-creative-writing' | 'bmad-infrastructure-devops';
}

npx bmad-method install [options]

# Options:
#   -f, --full                     Install complete BMad Method
#   -x, --expansion-only           Install only expansion packs (no bmad-core)
#   -d, --directory <path>         Installation directory (default: current directory)
#   -i, --ide <ide...>             Configure for specific IDE(s) - can specify multiple
#   -e, --expansion-packs <packs> Install specific expansion packs (can specify multiple)

### Supported IDEs

```typescript { .api }
interface SupportedIDEs {
  desktop: [
    'cursor',           // Cursor IDE
    'claude-code',      // Claude Code
    'windsurf',         // Windsurf
    'trae',             // Trae
    'roo',              // Roo Code
    'kilo',             // Kilo Code
    'cline',            // Cline
    'crush',            // Crush
    'github-copilot',   // VS Code with GitHub Copilot
    'qwen-code',        // Qwen Code
    'opencode'          // OpenCode
  ];

  cli: [
    'iflow-cli',        // iFlow CLI
    'auggie-cli',       // Auggie CLI (Augment Code)
    'gemini',           // Gemini CLI
    'codex'             // Codex CLI
  ];

  web: [
    'codex-web'         // Codex Web
  ];
}

.bmad-core/
├── agents/              # 10 agent personas
├── tasks/               # 21 core tasks
├── templates/           # 13 document templates
├── workflows/           # 6 workflow definitions
├── checklists/          # 6 quality checklists
├── agent-teams/         # 4 team configurations
├── data/                # Knowledge base files
└── core-config.yaml     # Project configuration

common/                  # Shared resources
├── tasks/               # 2 common shared tasks
└── utils/               # Common utilities

.bmad-godot-game-dev/    # Example expansion pack
├── agents/
├── tasks/
├── templates/
├── workflows/
├── checklists/
├── data/
└── config.yaml

web-bundles/
├── agents/              # Individual agent bundles
│   ├── analyst.txt
│   ├── dev.txt
│   └── ...
└── teams/               # Team bundles
    ├── team-fullstack.txt
    └── ...

npx bmad-method update [options]

# Options:
--force     # Force update, overwrite modified files
--dry-run   # Show what would be updated

# Behavior:
- Detects existing installation
- Compares versions
- Updates core and expansion packs
- Preserves user modifications (unless --force)
- Creates .bak backups

npx bmad-method update-check

# Queries npm for latest version
# Shows upgrade path if newer available
# Displays installation command

npx bmad-method status

# Shows:
- Installed BMad core version
- Installed expansion packs
- Configured IDEs
- Installation directory
- Configuration file locations
- Web bundles status

npx bmad-method list:expansions

# Displays:
- All available expansion packs
- Versions
- Descriptions

npx bmad-method list:agents

# Displays:
- Core agents (ID, name, role)
- Expansion pack agents (grouped by pack)

npx bmad-method flatten [options]

# Options:
-i, --input <path>   # Input directory (default: current)
-o, --output <path>  # Output file (default: flattened-codebase.xml)

# Examples:
npx bmad-method flatten                      # Flatten current directory
npx bmad-method flatten -i ./src -o src.xml  # Flatten src directory

# Output Format:
<?xml version="1.0" encoding="UTF-8"?>
<codebase>
  <file path="src/index.js"><![CDATA[
    // file contents
  ]]></file>
</codebase>

# Use Cases:
- Brownfield development (document existing project)
- Provide complete codebase context to AI
- Architecture documentation
- Codebase snapshots

npx bmad-method build [options]

# Options:
-a, --agents-only       # Build only agent bundles
-t, --teams-only        # Build only team bundles
-e, --expansions-only   # Build only expansion packs
--no-expansions         # Skip expansion packs
--no-clean              # Skip cleaning output

# Output:
dist/
├── agents/              # Individual agent bundles
├── teams/               # Team bundles
└── expansion-packs/     # Expansion pack bundles

# Usage:
- Creates standalone web bundles
- For ChatGPT, Claude, Gemini
- Agent + all dependencies in single file

npx bmad-method validate

# Validates:
- YAML syntax in agent files
- YAML syntax in team files
- Required fields
- File references in dependencies
- Reports errors and warnings

npx bmad-method upgrade [options]

# Options:
-p, --project <path>  # V3 project path
--dry-run             # Preview changes
--no-backup           # Skip backup (not recommended)

# Migrates V3 project to V4:
- Agent metadata format
- Workflow YAML structure
- Configuration schema
- Template format
- Command syntax

Enter the full path to your project directory where BMad should be installed:
Default: /current/directory

Select what to install/update (use space to select, enter to continue):
☑ BMad Agile Core System (v4.44.3) .bmad-core
☐ Godot Game Development (v4.44.3) .bmad-godot-game-dev
☐ Unity 2D Game Development (v4.44.3) .bmad-2d-unity-game-dev
☐ Phaser 2D Game Development (v4.44.3) .bmad-2d-phaser-game-dev
☐ Creative Writing (v4.44.3) .bmad-creative-writing
☐ Infrastructure DevOps (v4.44.3) .bmad-infrastructure-devops

Will the PRD (Product Requirements Document) be sharded into multiple files?
Yes / No (default: Yes)

Will the architecture documentation be sharded into multiple files?
Yes / No (default: Yes)

Which IDE(s) do you want to configure? (Select with SPACEBAR, confirm with ENTER):
☐ Cursor
☐ Claude Code
☐ iFlow CLI
☐ Windsurf
☐ Trae
☐ Roo Code
☐ Kilo Code
☐ Cline
☐ Gemini CLI
☐ Qwen Code
☐ Crush
☐ Github Copilot
☐ Auggie CLI (Augment Code)
☐ Codex CLI
☐ Codex Web
☐ OpenCode

How would you like to configure GitHub Copilot settings?
- Use recommended defaults (fastest setup)
- Configure each setting manually (customize to your preferences)
- Skip settings configuration (I'll configure manually later)

Prefix agent keys with 'bmad-'? (e.g., 'bmad-dev')
Yes / No (default: Yes)

Prefix command keys with 'bmad:tasks:'? (e.g., 'bmad:tasks:create-doc')
Yes / No (default: Yes)

Select Auggie CLI command locations:
☐ User Commands (Global): Available across all your projects (user-wide)
☐ Workspace Commands (Project): Stored in repository, shared with team

Would you like to include pre-built web bundles?
(standalone files for ChatGPT, Claude, Gemini)
Yes / No (default: No)

What web bundles would you like to include?
- All available bundles (agents, teams, expansion packs)
- Specific teams only
- Individual agents only
- Custom selection

interface FileLocations {
  // Core framework
  core: '.bmad-core/';

  // Expansion packs
  expansions: '.{pack-name}/';

  // IDE configurations
  ideConfigs: {
    cursor: '.cursorrules';
    claudeCode: '.claude/';
    windsurf: '.windsurfrules';
    githubCopilot: ['.github/copilot-instructions.md', '.vscode/settings.json'];
  };

  // Web bundles (optional)
  webBundles: 'web-bundles/';
}

interface CommonErrors {
  'Installation directory does not exist': {
    solution: 'Create directory first or use existing';
  };

  'Node.js version must be >=20.10.0': {
    solution: 'Upgrade Node.js to v20.10.0+';
  };

  'EACCES: permission denied': {
    solution: 'Run with appropriate permissions or choose different directory';
  };

  'Update check timed out': {
    solution: 'Check internet connection, npm registry may be unavailable';
  };

  'No IDE selected': {
    warning: 'No IDE integration will be set up';
    solution: 'Re-run installer and select IDEs with SPACEBAR';
  };
}

interface CLIBestPractices {
  installation: {
    first Time: 'Use interactive mode for guidance';
    automation: 'Use direct mode with options for CI/CD';
    multipleIDEs: 'Configure all IDEs used by team';
  };

  updates: {
    checkFirst: 'Run update-check before updating';
    backup: 'Always backup before major updates';
    testing: 'Test in development before production';
  };

  brownfield: {
    documentFirst: 'Flatten codebase before planning';
    analyze: 'Review flattened XML for completeness';
    iterate: 'Update documentation as needed';
  };

  expansionPacks: {
    selectiveInstall: 'Only install packs you need';
    explore: 'Use list:expansions to discover available';
    updateAll: 'Update keeps all packs in sync';
  };
}

interface ExecutionPatterns {
  // First-time setup
  firstTimeSetup: {
    1: 'npx bmad-method install';
    2: 'Select core + expansion packs';
    3: 'Configure IDEs';
    4: 'Verify with npx bmad-method status';
  };

  // Add expansion pack later
  addExpansionPack: {
    1: 'npx bmad-method list:expansions';
    2: 'npx bmad-method install --expansion-packs {pack-name}';
    3: 'Verify with npx bmad-method status';
  };

  // Brownfield project
  brownfieldProject: {
    1: 'npx bmad-method install';
    2: 'npx bmad-method flatten -i . -o project.xml';
    3: 'Use project.xml in brownfield workflow';
  };

  // Update workflow
  updateWorkflow: {
    1: 'npx bmad-method update-check';
    2: 'npx bmad-method update --dry-run';
    3: 'npx bmad-method update';
    4: 'Verify with npx bmad-method status';
  };
}

# Interactive Installation
npx bmad-method install

# Step 1: Installation Directory
# Prompt: "Enter the full path to your project directory"
# Default: /current/directory
# User: [Enter] (uses default)

# Step 2: Package Selection
# Display:
# ☑ BMad Agile Core System (v4.44.3) .bmad-core
# ☐ Godot Game Development (v4.44.3) .bmad-godot-game-dev
# ☐ Unity 2D Game Development (v4.44.3) .bmad-2d-unity-game-dev
# ☐ Phaser 2D Game Development (v4.44.3) .bmad-2d-phaser-game-dev
# ☐ Creative Writing (v4.44.3) .bmad-creative-writing
# ☐ Infrastructure DevOps (v4.44.3) .bmad-infrastructure-devops
# User: [Space] to select core, [Enter] to continue

# Step 3: Document Sharding
# Prompt: "Will the PRD be sharded into multiple files?"
# Options: Yes / No (default: Yes)
# User: [Enter] (uses Yes)

# Prompt: "Will the architecture documentation be sharded?"
# Options: Yes / No (default: Yes)
# User: [Enter] (uses Yes)

# Step 4: IDE Configuration
# Display: Multi-select list of IDEs
# User: [Space] to select Cursor, [Space] to select Claude Code
# User: [Enter] to confirm

# Step 5: Web Bundles
# Prompt: "Would you like to include pre-built web bundles?"
# Options: Yes / No (default: No)
# User: Yes
# Prompt: "What web bundles would you like?"
# User: "All available bundles"

# Installation completes:
# ✓ Created .bmad-core/ directory
# ✓ Installed 10 agents
# ✓ Installed 23 tasks
# ✓ Installed 13 templates
# ✓ Installed 6 workflows
# ✓ Configured Cursor IDE
# ✓ Configured Claude Code
# ✓ Created web-bundles/ directory
# ✓ Created core-config.yaml

# Non-interactive installation with options
npx bmad-method install \
  --full \
  --directory ./my-project \
  --ide cursor claude-code windsurf \
  --expansion-packs bmad-godot-game-dev

# Output:
# Installing to: ./my-project
# ✓ Core framework installed
# ✓ Expansion pack installed: bmad-godot-game-dev
# ✓ Configured: Cursor
# ✓ Configured: Claude Code
# ✓ Configured: Windsurf

# Flatten entire project for brownfield development
npx bmad-method flatten -i . -o project-complete.xml

# Process:
# 1. Scans current directory recursively
# 2. Respects .gitignore patterns
# 3. Detects binary files (skips or encodes)
# 4. Generates XML output

# Output: project-complete.xml
# <?xml version="1.0" encoding="UTF-8"?>
# <codebase>
#   <file path="src/index.js">
#     <![CDATA[
#       // Actual file contents here
#     ]]>
#   </file>
#   <file path="src/models/User.js">
#     <![CDATA[
#       // User model code
#     ]]>
#   </file>
#   ...
# </codebase>

# Use in brownfield workflow:
# Load PM agent → *create-prd
# PM references project-complete.xml for context

# Step 1: Check for updates
npx bmad-method update-check
# Output:
# ⚠️  bmad-method update available: 4.44.3 → 4.45.0
# 
# Install latest by running:
#   npx bmad-method update

# Step 2: Preview update (dry-run)
npx bmad-method update --dry-run
# Output:
# Would update:
#   .bmad-core/agents/pm.md (modified)
#   .bmad-core/tasks/create-next-story.md (modified)
#   .bmad-core/core-config.yaml (preserved - user modified)
# 
# Would create backups:
#   .bmad-core/agents/pm.md.bak
#   .bmad-core/tasks/create-next-story.md.bak

# Step 3: Apply update
npx bmad-method update
# Output:
# ✓ Updated core framework
# ✓ Created backups for modified files
# ✓ Preserved user modifications
# ✓ Updated expansion packs

# Error: Node version incompatible
npx bmad-method install
# Error: Node.js version must be >=20.10.0
# Current: v18.17.0
# Solution: Upgrade Node.js to v20.10.0 or later

# Error: Permission denied
npx bmad-method install --directory /protected/path
# Error: EACCES: permission denied, mkdir '/protected/path/.bmad-core'
# Solution: Run with appropriate permissions or choose different directory

# Error: Installation directory not found
npx bmad-method install --directory ./non-existent
# Error: Installation directory does not exist
# Solution: Create directory first or use existing directory

# Warning: No IDE selected
npx bmad-method install
# (User skips IDE selection)
# Warning: You have NOT selected any IDEs. No IDE integration will be set up.
# Solution: Re-run installer and select IDEs using SPACEBAR

npm run build                    # Build all web bundles
npm run build:agents            # Build only agent bundles
npm run build:teams             # Build only team bundles
npm run validate                # Validate agent and team configurations
npm run list:agents             # List all available agents

npm run build
# Output: dist/agents/*.txt, dist/teams/*.txt, dist/expansion-packs/**/*.txt

npm run build:agents
# Output: dist/agents/*.txt

npm run build:teams
# Output: dist/teams/*.txt

npm run validate
# Checks: YAML syntax, required fields, file references, dependency resolution

npm run list:agents
# Output: bmad-orchestrator, analyst, pm, architect, ux-expert, po, sm, dev, qa

npm run version:patch           # Bump patch version (4.44.3 → 4.44.4)
npm run version:minor           # Bump minor version (4.44.3 → 4.45.0)
npm run version:major           # Bump major version (4.44.3 → 5.0.0)
npm run version:all:patch       # Bump all versions (core + expansion packs)
npm run version:all:minor       # Bump all minor versions
npm run version:all:major       # Bump all major versions

npm run format                  # Format code with Prettier
npm run format:check            # Check formatting without modifying
npm run lint                    # Lint code with ESLint
npm run lint:fix                # Lint and auto-fix issues
npm run fix                     # Run format + lint:fix
npm run pre-release             # Run validation + format check + lint

npm run flatten                 # Run codebase flattener utility

npm run release:patch           # Trigger patch release via GitHub Actions
npm run release:minor           # Trigger minor release via GitHub Actions
npm run release:major           # Trigger major release via GitHub Actions
npm run release:watch           # Watch GitHub Actions release workflow
npm run preview:release         # Preview release notes before publishing

npm run setup:hooks             # Setup git hooks for development
npm run install:bmad            # Install BMad to current directory

interface NpmScriptsPatterns {
  // Development workflow
  developmentWorkflow: {
    1: 'npm run validate';         // Validate configurations
    2: 'npm run build:agents';     // Build agent bundles
    3: 'npm run format';           // Format code
    4: 'npm run lint';             // Check linting
  };

  // Pre-release workflow
  preReleaseWorkflow: {
    1: 'npm run pre-release';      // Run all checks
    2: 'npm run preview:release';  // Preview release notes
    3: 'npm run release:patch';    // Trigger release
    4: 'npm run release:watch';    // Monitor release
  };

  // Version bump workflow
  versionWorkflow: {
    1: 'npm run version:all:patch'; // Bump versions
    2: 'npm run validate';          // Validate changes
    3: 'git commit -am "Bump versions"';
    4: 'git push';
  };

  // Build workflow
  buildWorkflow: {
    1: 'npm run build';            // Build all bundles
    2: 'ls -la dist/';             // Verify output
    3: 'Upload bundles to web platforms';
  };
}