Fix npx execution issue with bmad CLI

- Added wrapper script (bmad.js) at root to handle npx execution context
- Fixed module resolution in tools/installer/bin/bmad.js for both local and npx contexts
- Updated package.json bin paths to use the wrapper script
- Handles temporary npx directories properly using execSync

This fixes the issue where `npx github:bmadcode/BMAD-METHOD#v4-alpha bmad`
was dropping into a shell instead of executing the command.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: 2 people

README.md

@@ -18,8 +18,8 @@ BMAD-METHOD (Breakthrough Method of AgileAI Driven Development) transforms softw
 - Scrum Master: Story generation and sprint planning
 - Developer: Code implementation
 - QA Specialist: Testing and quality assurance
-- BMAD Orchestrator: Role transformation via slash commands
-- BMAD Master: Universal executor of all capabilities
+- BMAD Orchestrator: Role transformation via slash commands and BMAD Method Tutor
+- BMAD Master: Universal executor of all capabilities without role switching
 
 ### Team Configurations
 
@@ -37,10 +37,10 @@ BMAD-METHOD (Breakthrough Method of AgileAI Driven Development) transforms softw
 
 ### Option 1: Web Bundles (No Installation)
 
-1. Download pre-built bundles from `web-bundles/`
+1. Download pre-built bundles from `bmad-core/web-bundles/`
 2. Upload to ChatGPT or Gemini
 3. Set instructions: "Your critical operating instructions are attached, you ARE the BMad Agent..."
-4. Start with `/help` command
+4. Start with `/help` command if unsure what to do!
 
 ### Option 2: IDE Integration
 

bmad.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * BMAD Method CLI - Direct execution wrapper for npx
+ * This file ensures proper execution when run via npx from GitHub
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+// Check if we're running in an npx temporary directory
+const isNpxExecution = __dirname.includes('_npx') || __dirname.includes('.npm');
+
+// If running via npx, we need to handle things differently
+if (isNpxExecution) {
+  // The actual bmad.js is in tools/installer/bin/
+  const bmadScriptPath = path.join(__dirname, 'tools', 'installer', 'bin', 'bmad.js');
+  
+  // Verify the file exists
+  if (!fs.existsSync(bmadScriptPath)) {
+    console.error('Error: Could not find bmad.js at', bmadScriptPath);
+    console.error('Current directory:', __dirname);
+    process.exit(1);
+  }
+  
+  // Execute with proper working directory
+  try {
+    execSync(`node "${bmadScriptPath}" ${process.argv.slice(2).join(' ')}`, {
+      stdio: 'inherit',
+      cwd: __dirname
+    });
+  } catch (error) {
+    // execSync will throw if the command exits with non-zero
+    // But the stdio is inherited, so the error is already displayed
+    process.exit(error.status || 1);
+  }
+} else {
+  // Local execution - just require the installer directly
+  require('./tools/installer/bin/bmad.js');
+}

package.json

@@ -4,8 +4,8 @@
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {
-    "bmad": "./tools/installer/bin/bmad.js",
-    "bmad-method": "./tools/installer/bin/bmad.js"
+    "bmad": "./bmad.js",
+    "bmad-method": "./bmad.js"
   },
   "scripts": {
     "build": "node tools/cli.js build",

tools/installer/bin/bmad.js

@@ -4,8 +4,28 @@ const { program } = require('commander');
 const inquirer = require('inquirer');
 const chalk = require('chalk');
 const path = require('path');
-const { version } = require('../package.json');
-const installer = require('../lib/installer');
+
+// Handle both execution contexts (from root via npx or from installer directory)
+let version, installer;
+try {
+  // Try installer context first (when run from tools/installer/)
+  version = require('../package.json').version;
+  installer = require('../lib/installer');
+} catch (e) {
+  // Fall back to root context (when run via npx from GitHub)
+  try {
+    version = require('../../../package.json').version;
+    installer = require('../../../tools/installer/lib/installer');
+  } catch (e2) {
+    console.error(chalk.red('Error: Could not load required modules. Please ensure you are running from the correct directory.'));
+    console.error(chalk.yellow('Debug info:'), {
+      __dirname,
+      cwd: process.cwd(),
+      error: e2.message
+    });
+    process.exit(1);
+  }
+}
 
 program
   .version(version)