docs: add local development guide and clarify fork-only features

- Created docs/V6_LOCAL_DEVELOPMENT.md with comprehensive guide
- Added dev:install, dev:status, dev:list, dev:uninstall npm scripts
- Updated OpenCode preservation docs with fork-only warnings
- Clarified that npx downloads published version without OpenCode
- Documented direct node execution as primary development method

This resolves the issue where npx bmad-method was downloading the
published npm package instead of using the local fork version with
OpenCode integration.

OPENCODE_INTEGRATION_SUMMARY.md

@@ -4,20 +4,42 @@
 
 Successfully implemented OpenCode integration for BMAD Method V6 following the V6 installer architecture patterns.
 
+## ⚠️ IMPORTANT: Fork-Only Feature
+
+**This OpenCode integration is a fork-specific feature and is NOT included in the published npm package.**
+
+### Using OpenCode (Local Development Only)
+
+```bash
+# ✅ CORRECT - Use local development version
+node tools/cli/bmad-cli.js install
+# or
+npm run dev:install
+
+# ❌ WRONG - Downloads published version WITHOUT OpenCode
+npx bmad-method install
+```
+
+**See `docs/V6_LOCAL_DEVELOPMENT.md` for complete instructions on using the local development version.**
+
 ## What Was Done
 
 ### 1. Added Missing Dependency
+
 **File**: `package.json`
+
 - Added `comment-json: ^4.2.5` to dependencies
 - Required for parsing JSONC files with comments
 
 ### 2. Implemented OpenCode Installer
+
 **File**: `tools/cli/installers/lib/ide/opencode.js`
 **Lines**: 590 lines of code
 
 Implemented full-featured OpenCode installer with:
 
 #### Core Features
+
 - ✅ Detects existing `opencode.json` or `opencode.jsonc` files
 - ✅ Creates minimal configuration if none exists
 - ✅ Idempotent merges - safe to run multiple times
@@ -27,22 +49,26 @@ Implemented full-featured OpenCode installer with:
 - ✅ Expansion pack support with auto-discovery
 
 #### Configuration Options
+
 - ✅ Optional agent prefix: `bmad-` (e.g., `bmad-dev` instead of `dev`)
 - ✅ Optional command prefix: `bmad:tasks:` (e.g., `bmad:tasks:create-doc`)
 - ✅ Forced prefixes for expansion pack agents/commands
 
 #### Documentation Generation
+
 - ✅ Generates/updates `AGENTS.md` for system prompt memory
 - ✅ Includes agent directory table with whenToUse descriptions
 - ✅ Lists available tasks with source file links
 - ✅ Provides usage instructions
 
 #### Metadata Extraction
+
 - ✅ Extracts `whenToUse` from agent YAML blocks
 - ✅ Extracts `Purpose` from task files
 - ✅ Cleans and summarizes descriptions for readability
 
 ### 3. Architecture Compliance
+
 The implementation follows V6 patterns by:
 
 - ✅ Extending `BaseIdeSetup` class
@@ -89,42 +115,43 @@ The implementation follows V6 patterns by:
 ### Example Output Structure
 
 **opencode.jsonc**:
+
 ```jsonc
 {
   "$schema": "https://opencode.ai/config.json",
-  "instructions": [
+  "instructions": [".bmad-core/core-config.yaml", ".bmad-core/modules/bmm/config.yaml"],
-    ".bmad-core/core-config.yaml",
-    ".bmad-core/modules/bmm/config.yaml"
-  ],
   "agent": {
     "bmad-dev": {
       "prompt": "{file:./.bmad-core/agents/dev.md}",
       "mode": "all",
       "tools": { "write": true, "edit": true, "bash": true },
-      "description": "Code implementation, debugging, refactoring..."
+      "description": "Code implementation, debugging, refactoring...",
     },
     "bmad-orchestrator": {
       "prompt": "{file:./.bmad-core/agents/bmad-orchestrator.md}",
       "mode": "primary",
       "tools": { "write": true, "edit": true, "bash": true },
-      "description": "Workflow coordination, multi-agent tasks..."
+      "description": "Workflow coordination, multi-agent tasks...",
-    }
+    },
   },
   "command": {
     "bmad:tasks:create-doc": {
       "template": "{file:./.bmad-core/tasks/create-doc.md}",
-      "description": "Generate comprehensive technical documentation"
+      "description": "Generate comprehensive technical documentation",
-    }
+    },
-  }
+  },
 }
 ```
 
 **AGENTS.md** (excerpt):
+
 ```markdown
 <!-- BEGIN: BMAD-AGENTS-OPENCODE -->
+
 # BMAD-METHOD Agents and Tasks (OpenCode)
 
 ## How To Use With OpenCode
+
 - Run `opencode` in this project directory
 - OpenCode will read your `opencode.json` or `opencode.jsonc` configuration
 - Reference agents by their ID in your prompts (e.g., "As dev, implement...")
@@ -132,7 +159,7 @@ The implementation follows V6 patterns by:
 ## Agents
 
 | Title        | ID                | When To Use                                    |
-|---|---|---|
+| ------------ | ----------------- | ---------------------------------------------- |
 | Dev          | dev               | Code implementation, debugging, refactoring... |
 | Orchestrator | bmad-orchestrator | Workflow coordination...                       |
 
@@ -142,23 +169,28 @@ The implementation follows V6 patterns by:
 ## Key Design Decisions
 
 ### 1. File References vs. File Copying
+
 Unlike most V6 IDEs that copy agent/task files to IDE-specific directories, OpenCode uses **file references**. This:
+
 - Reduces duplication
 - Ensures single source of truth
 - Allows runtime updates without reinstallation
 - Matches OpenCode's design philosophy
 
 ### 2. Prefix Strategy
+
 - **Core agents/tasks**: Optional prefixes (user choice)
 - **Expansion pack agents/tasks**: Forced prefixes to avoid collisions
 - Pattern: `bmad-{module}-{name}` for agents, `bmad:{module}:{name}` for tasks
 
 ### 3. Mode Assignment
+
 - Orchestrator agents (name contains "orchestrator"): `mode: "primary"`
 - All other agents: `mode: "all"`
 - Follows OpenCode's agent activation model
 
 ### 4. Collision Handling
+
 - Detects existing entries by checking if they reference BMAD files
 - Skips non-BMAD entries with warning
 - Updates BMAD-managed entries safely
@@ -167,6 +199,7 @@ Unlike most V6 IDEs that copy agent/task files to IDE-specific directories, Open
 ## Testing
 
 The implementation has been:
+
 - ✅ Structured following V6 architecture patterns
 - ✅ Auto-discovered by IDE manager
 - ✅ Dependency added and installed
@@ -175,6 +208,7 @@ The implementation has been:
 ## Usage
 
 ### Installation
+
 ```bash
 # Interactive (will prompt for prefix preferences)
 npx bmad install -i opencode
@@ -184,11 +218,13 @@ npx bmad install -i opencode --config '{"useAgentPrefix":true,"useCommandPrefix"
 ```
 
 ### Refresh After Updates
+
 ```bash
 npx bmad install -f -i opencode
 ```
 
 ### Cleanup
+
 ```bash
 npx bmad uninstall -i opencode
 ```
@@ -196,7 +232,7 @@ npx bmad uninstall -i opencode
 ## Comparison: V4 vs V6 Implementation
 
 | Aspect            | V4 (tools/installer)    | V6 (tools/cli)                   |
-|--------|---------------------|----------------|
+| ----------------- | ----------------------- | -------------------------------- |
 | Architecture      | Monolithic ide-setup.js | Modular per-IDE files            |
 | Discovery         | Hardcoded switch cases  | Auto-discovery via manager       |
 | Dependencies      | Separate package.json   | Shared root package.json         |

claudedocs/opencode-integration-reference.md

@@ -4,38 +4,54 @@
 
 This document serves as the authoritative reference for preserving the OpenCode integration during upstream merges. OpenCode support is a **fork-specific feature** not present in the upstream BMAD-METHOD repository.
 
+## ⚠️ CRITICAL: Fork-Only Feature
+
+**OpenCode integration exists ONLY in this fork and will NEVER be published to npm.**
+
+- The published npm package `bmad-method@6.0.0-alpha.0` does NOT include OpenCode
+- Running `npx bmad-method install` will download the published version WITHOUT OpenCode
+- You MUST use local development commands to access OpenCode functionality
+
+**See**: `docs/V6_LOCAL_DEVELOPMENT.md` for complete local development instructions.
+
 ## Critical Information
 
 - **Modification Type**: Additive (new files + dependency)
 - **Risk Level**: Low-Medium (new files unlikely to conflict, dependency may need verification)
 - **Recovery Method**: Restore from backup branch
 - **Serena Memory**: `CRITICAL-opencode-fork-integration`
+- **Development Requirement**: Must use local CLI execution (not npx)
 
 ## Files Affected
 
 ### 1. New Files (Additive)
 
 #### `tools/cli/installers/lib/ide/opencode.js`
+
 - **Lines**: 602 (entire file)
 - **Purpose**: OpenCode IDE installer implementation
 - **Status**: Must be present for OpenCode functionality
 
 **Verification**:
+
 ```bash
 test -f tools/cli/installers/lib/ide/opencode.js && echo "✅ Present" || echo "❌ MISSING"
 ```
 
 **Recovery**:
+
 ```bash
 git checkout <backup-branch> -- tools/cli/installers/lib/ide/opencode.js
 ```
 
 #### `OPENCODE_INTEGRATION_SUMMARY.md`
+
 - **Lines**: 231 (entire file)
 - **Purpose**: Implementation documentation and architecture details
 - **Status**: Documentation only (optional but recommended to preserve)
 
 **Recovery**:
+
 ```bash
 git checkout <backup-branch> -- OPENCODE_INTEGRATION_SUMMARY.md
 ```
@@ -43,6 +59,7 @@ git checkout <backup-branch> -- OPENCODE_INTEGRATION_SUMMARY.md
 ### 2. Modified Files
 
 #### `package.json`
+
 - **Modification**: Added `comment-json` dependency
 - **Location**: `dependencies` section
 - **Code**:
@@ -52,22 +69,25 @@ git checkout <backup-branch> -- OPENCODE_INTEGRATION_SUMMARY.md
 - **Purpose**: Required for parsing JSONC files with comments
 
 **Verification**:
+
 ```bash
 grep -q '"comment-json"' package.json && echo "✅ Present" || echo "❌ MISSING"
 ```
 
 **Manual Recovery** (if needed):
+
 ```json
 {
   "dependencies": {
     // ... other dependencies ...
-    "comment-json": "^4.2.5",
+    "comment-json": "^4.2.5"
     // ... more dependencies ...
   }
 }
 ```
 
 Then run:
+
 ```bash
 npm install
 ```
@@ -126,11 +146,13 @@ console.log('   Display Name:', setup.displayName);
 ### Scenario 1: opencode.js Missing
 
 **Symptoms**:
+
 - File check fails
 - IDE manager doesn't list OpenCode
 - Error when trying to install with OpenCode
 
 **Recovery**:
+
 ```bash
 # 1. Find latest backup branch
 BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
@@ -149,10 +171,12 @@ git commit -m "chore: restore OpenCode integration after upstream merge"
 ### Scenario 2: comment-json Dependency Missing
 
 **Symptoms**:
+
 - OpenCode installer throws "Cannot find module 'comment-json'" error
 - IDE manager shows warning about loading OpenCode
 
 **Recovery**:
+
 ```bash
 # Option A: Restore from backup
 BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
@@ -172,6 +196,7 @@ npm list comment-json
 ### Scenario 3: Both Files Missing (Complete Loss)
 
 **Recovery**:
+
 ```bash
 # 1. Find backup branch
 BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
@@ -222,24 +247,42 @@ After merging upstream changes:
 2. ✅ If any checks fail, run recovery procedures
 3. ✅ Run thorough verification
 4. ✅ Test basic functionality (optional)
-5. ✅ Update Serena memory with merge date
+
+### Testing OpenCode After Merge
+
+**CRITICAL**: Do NOT use `npx bmad-method` to test - it downloads the published version!
+
+```bash
+# ✅ CORRECT - Test with local version
+cd /path/to/test/project
+node /path/to/BMAD-METHOD/tools/cli/bmad-cli.js install
+
+# Or use npm script from BMAD-METHOD directory
+npm run dev:install
+
+# Verify OpenCode appears in IDE selection menu
+# Verify opencode.json/opencode.jsonc is created correctly
+```
+
+**See**: `docs/V6_LOCAL_DEVELOPMENT.md` for complete testing guide. 5. ✅ Update Serena memory with merge date
 
 ### Workflow Integration
 
 The `bmad/workflows/merge-upstream/` workflow includes OpenCode checks:
 
 **Step 7.5** (added to existing workflow):
+
 ```yaml
-- name: "Verify OpenCode Integration"
+- name: 'Verify OpenCode Integration'
-  action: "Run OpenCode verification commands"
+  action: 'Run OpenCode verification commands'
   verification:
-    - "File existence check"
+    - 'File existence check'
-    - "Dependency check"
+    - 'Dependency check'
-    - "IDE manager discovery check"
+    - 'IDE manager discovery check'
   on_failure:
-    - "Alert about missing OpenCode integration"
+    - 'Alert about missing OpenCode integration'
-    - "Provide recovery instructions"
+    - 'Provide recovery instructions'
-    - "Link to this reference document"
+    - 'Link to this reference document'
 ```
 
 ## Architecture Details
@@ -303,10 +346,12 @@ console.log('Name:', setup.name);
 ## Quick Reference Card
 
 **Files to Watch**:
+
 - ✅ `tools/cli/installers/lib/ide/opencode.js` (must exist)
 - ✅ `"comment-json": "^4.2.5"` in package.json
 
 **Quick Check**:
+
 ```bash
 test -f tools/cli/installers/lib/ide/opencode.js && \
 grep -q comment-json package.json && \
@@ -314,6 +359,7 @@ echo "✅ All good" || echo "❌ Needs recovery"
 ```
 
 **Quick Recovery**:
+
 ```bash
 BACKUP=$(git branch -a | grep backup-before | tail -1 | xargs)
 git checkout $BACKUP -- tools/cli/installers/lib/ide/opencode.js package.json

docs/V6_LOCAL_DEVELOPMENT.md

@@ -0,0 +1,183 @@
+# 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)
+
+```bash
+# 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:
+
+```bash
+# 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:
+
+```bash
+# 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
+
+```bash
+# ❌ 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
+
+```bash
+# ✅ 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# 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
+
+```bash
+# ✅ 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

package.json

@@ -26,6 +26,10 @@
     "bmad:install": "node tools/cli/bmad-cli.js install",
     "bmad:status": "node tools/cli/bmad-cli.js status",
     "bundle": "node tools/cli/bundlers/bundle-web.js all",
+    "dev:install": "node tools/cli/bmad-cli.js install",
+    "dev:list": "node tools/cli/bmad-cli.js list",
+    "dev:status": "node tools/cli/bmad-cli.js status",
+    "dev:uninstall": "node tools/cli/bmad-cli.js uninstall",
     "flatten": "node tools/flattener/main.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,md,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,md,yaml}\"",