BMAD-METHOD/docs/V6_LOCAL_DEVELOPMENT.md

V6 Local Development Guide

Running Local Development Version

When developing on the V6 fork, DO NOT use npx bmad-method - this downloads the published npm package which does not include fork-specific features like OpenCode integration.

Direct Node Execution (Recommended)

# Install BMAD to a project
node tools/cli/bmad-cli.js install

# Check installation status
node tools/cli/bmad-cli.js status

# List available modules
node tools/cli/bmad-cli.js list

# Uninstall BMAD from a project
node tools/cli/bmad-cli.js uninstall

Using npm Scripts

The following npm scripts are available for convenience:

# Development scripts (uses local version)
npm run dev:install      # Run installer
npm run dev:status       # Check status
npm run dev:list         # List modules
npm run dev:uninstall    # Uninstall

# Legacy aliases (also use local version)
npm run bmad:install     # Same as dev:install
npm run bmad:status      # Same as dev:status
npm run install:bmad     # Same as dev:install

Using npm link (Optional)

For extended testing where you want the bmad command available system-wide:

# From the BMAD-METHOD directory
npm link

# Now you can use 'bmad' anywhere
bmad install
bmad status

# Unlink when done
npm unlink -g bmad-method

Note: You must re-run npm link after:

• Installing/updating dependencies
• Checking out different branches
• Major code changes to the CLI

Why This Matters

Problem: npx Downloads Published Version

# ❌ WRONG - Downloads published version from npm
npx bmad-method install

# What actually happens:
# 1. npx checks npm registry
# 2. Downloads bmad-method@6.0.0-alpha.0 (published version)
# 3. Published version does NOT include fork changes like OpenCode
# 4. Your local OpenCode integration gets overwritten/broken

Solution: Direct Execution

# ✅ CORRECT - Uses your local version
node tools/cli/bmad-cli.js install

# What actually happens:
# 1. Node runs your local CLI file directly
# 2. Uses your local code with all fork features
# 3. OpenCode integration works correctly

Fork-Specific Features

The following features exist ONLY in the fork and will NOT work with the published npm package:

• OpenCode Integration (tools/cli/installers/lib/ide/opencode.js)

  • File reference-based configuration
  • Agent and command merging
  • AGENTS.md generation
  • Prefix customization

• Installer Skip Block (modify install flow)

  • Custom pre-installation logic
  • Modified dependency resolution

Testing Your Changes

Before Testing

# Ensure dependencies are installed
npm install

# Verify your changes are present
test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ OpenCode present" || echo "❌ Missing"

Testing Installation

# Create a test directory
mkdir -p ~/test-bmad-install
cd ~/test-bmad-install

# Run local installer
node ~/dev/tools/BMAD-METHOD/tools/cli/bmad-cli.js install

# Select OpenCode as IDE
# Verify opencode.json/opencode.jsonc is created with file references

Testing After Changes

# Make your code changes...

# Test immediately (no rebuild needed for most changes)
node tools/cli/bmad-cli.js install

Published vs Fork Versions

Feature	Published npm	Fork (Local)
Base V6 installer	✅	✅
Standard IDEs (15)	✅	✅
OpenCode integration	❌	✅
Installer skip block	❌	✅
Latest upstream fixes	✅	Needs merge
Fork improvements	❌	✅

Quick Reference Card

# ✅ CORRECT - Local development
node tools/cli/bmad-cli.js install
npm run dev:install
bmad install  # (after npm link)

# ❌ WRONG - Downloads published version
npx bmad-method install
npx bmad install

Troubleshooting

"Command not found: bmad"

• You haven't run npm link
• Use direct node execution instead: node tools/cli/bmad-cli.js install

"OpenCode not appearing in IDE list"

• You're using npx bmad-method instead of local version
• Solution: Use node tools/cli/bmad-cli.js install

"Changes not reflected when running installer"

• You're using npx or a globally installed version
• Solution: Use direct node execution
• Verify: which bmad should show your linked local version, not a global install

"Cannot find module 'comment-json'"

• Dependencies not installed
• Solution: npm install from BMAD-METHOD directory