bmad-copilot-adapter

Official prompt executor that enables BMAD-METHOD workflows to run natively inside GitHub Copilot Chat. Not a fork — a pure read-only bridge.

⚠️ Important: This extension is distributed as source code only. You must build and install it yourself — it is not available on the VS Code Marketplace.

Installation

Note: This extension is not published to the VS Code Marketplace. You must build and install it manually from source.

Step 1 — Build and Install the Extension

git clone https://github.com/pi-docket/bmad-method-vscode.git
cd bmad-method-vscode/bmad-copilot
npm install
npm run vsce:package
code --install-extension releases/bmad-copilot-adapter-0.2.5.vsix

Step 2 — Install BMAD-METHOD in Your Project

cd /path/to/your-project
npx bmad-method install                  # interactive menu — select GitHub Copilot as tool
npx bmad-copilot-adapter bootstrap       # detect prompts and verify setup

Tip: After building the extension, you can optionally add the CLI tool as a dev dependency in your projects:

npm install --save-dev bmad-copilot-adapter

Overview

bmad-copilot-adapter is a VS Code extension that bridges the BMAD-METHOD command system into GitHub Copilot Chat. It reads the official .prompt.md and agent .md files generated by the BMAD installer and passes them directly to the Copilot LLM — no workflow parsing, no prompt reconstruction, no token management.

CLI:         bmad:bmm:create-prd
Copilot:     @bmad /run bmad-bmm-create-prd

What It Does

• Registers the @bmad chat participant with 8 slash commands
• Discovers and indexes BMAD commands from _bmad/_config/ manifests
• Reads official prompt files and sends them as-is to the LLM
• Provides CLI bootstrap, update, and status commands
• Spawns the real BMAD CLI for install operations

What It Does NOT Do

• ❌ Parse, rewrite, or transform prompt file content
• ❌ Mirror or convert prompts from other IDE formats
• ❌ Pre-read or inline {project-root} file references
• ❌ Manage token budgets or truncate prompts
• ❌ Bundle, modify, or replace any part of bmad-method
• ❌ Create or overwrite files in .github/ or _bmad/
• ❌ Auto-install bmad-method — it only validates prompts

Quick Start

Prerequisites: You must have already built and installed the VS Code extension (see Installation section above).

Step 1 — Install BMAD-METHOD in Your Project

cd /path/to/your-project
npx bmad-method install

The interactive menu lets you pick modules (e.g. bmm, bmb, tea). Select GitHub Copilot as your tool to generate .github/prompts/.

This creates:

• _bmad/ — Core framework and module files
• _bmad/_config/ — CSV command manifests
• .github/agents/ — Copilot agent files (bmad-agent-*.md)
• .github/prompts/ — Copilot prompt files (.prompt.md, if applicable)

Step 2 — Bootstrap the Adapter

npx bmad-copilot-adapter bootstrap

This will:

1. Check Node.js version (≥ 18)
2. Verify .github/agents/ or .github/prompts/ exists (warns if missing)
3. Verify the VS Code extension is installed
4. Print a summary of discovered commands

Step 3 — Verify in VS Code

Open Copilot Chat (Ctrl+Shift+I) and type:

@bmad /status

You should see ✅ for _bmad/ directory and GitHub Copilot prompt files.

Building from Source

This extension is distributed as source code only. To build and install:

# Clone the repository
git clone https://github.com/pi-docket/bmad-method-vscode.git
cd bmad-method-vscode/bmad-copilot

# Install dependencies
npm install

# Build the extension
npm run build

# Package as VSIX
npm run vsce:package

# Install in VS Code
code --install-extension releases/bmad-copilot-adapter-0.2.5.vsix

Updating: When new versions are released, pull the latest changes, rebuild, and reinstall:

git pull
npm install
npm run vsce:package
code --install-extension releases/bmad-copilot-adapter-0.2.5.vsix --force

CLI Commands

The adapter provides a CLI for terminal-based project management:

npx bmad-copilot-adapter bootstrap   # Full first-time setup
npx bmad-copilot-adapter update      # Rescan after re-installing BMAD
npx bmad-copilot-adapter status      # Show full diagnostics
npx bmad-copilot-adapter --version   # Show adapter version
npx bmad-copilot-adapter --help      # Show CLI help

| Command | Purpose | | ----------- | ---------------------------------------------------------------------------------- | | bootstrap | Verify Node ≥18, check prompts, verify extension, print summary | | update | Rescan .github/agents/ & prompts/, count manifests, write sentinel for VS Code | | status | Full diagnostic: Node, _bmad/, prompts, CSV health, VS Code |

Usage

Slash Commands

| Command | Description | | ------------------- | ------------------------------------ | | @bmad /status | Check BMAD installation health | | @bmad /install | Open terminal with BMAD installer | | @bmad /update | Invalidate cache and rescan commands | | @bmad /help | Show available commands and guidance | | @bmad /run <name> | Execute any BMAD command by name | | @bmad /agents | List installed BMAD agents | | @bmad /workflows | List installed workflows by phase | | @bmad /tasks | List installed tasks and tools |

Examples

@bmad /run bmad-bmm-create-prd
@bmad /run bmad-agent-bmm-pm
@bmad /help create prd
@bmad /agents

Free-text

You can also type naturally — the adapter matches your input to known commands:

@bmad I want to create a PRD
@bmad bmad-bmm-create-prd

Troubleshooting

@bmad shows 0 commands

If you open Copilot Chat and @bmad /status reports 0 commands:

1. Ensure .github/agents/ exists and contains bmad-agent-*.md files (or .github/prompts/ has bmad*.prompt.md files).

2. Rescan the command registry:

   npx bmad-copilot-adapter update

3. If still 0 commands, the BMAD installer may not have generated prompt files. Re-run:

   npx bmad-method install --tools github-copilot

4. Reload the VS Code window (Ctrl+Shift+P → Developer: Reload Window).

Why this happens: The adapter discovers commands by scanning .github/agents/, .github/prompts/ and _bmad/_config/ CSV manifests. If prompt/agent files are missing (e.g. --tools github-copilot was not used during install) or if the extension was activated before files existed, the registry will be empty. Running update writes a sentinel file that triggers the extension's file watcher to rescan.

Extension not activating

• Ensure GitHub Copilot Chat is installed and active.
• The extension activates only when you type @bmad in Copilot Chat.
• Check the Output panel → "BMAD Copilot" for error logs.

npx commands not found

If npx bmad-copilot-adapter fails:

• Ensure you have Node.js ≥ 18 and npm ≥ 7 (npx is bundled).
• Try running with the full package name: npx bmad-copilot-adapter@latest --version
• Or install locally first: npm install --save-dev bmad-copilot-adapter

Command Name Mapping

BMAD CLI uses colons (:), Copilot Chat uses dashes (-):

| CLI Syntax | Copilot Chat | | --------------------- | -------------------------------- | | bmad:bmm:create-prd | @bmad /run bmad-bmm-create-prd | | bmad:agent:bmm:pm | @bmad /run bmad-agent-bmm-pm | | bmad:help | @bmad /help |

Configuration

| Setting | Default | Description | | --------------- | ------- | -------------------------------------------------- | | bmad.bmadDir | "" | Override path to _bmad/ (auto-detected if empty) | | bmad.autoScan | true | Scan commands on extension activation | | bmad.verbose | false | Verbose logging to BMAD output channel |

Architecture

This extension follows the Official Prompt Executor model — a pure read-only adapter:

extension.ts          → Lifecycle, activation, integrity check, watchers
  └─ chatBridge.ts    → Prompt executor, slash command routing
       ├─ commandRegistry.ts  → CSV scanning, prompt/agent file mapping
       └─ cliBridge.ts        → CLI process spawner (install)

Execution Flow

@bmad /run X  → find .github/prompts/X.prompt.md or .github/agents/X.md
              → (if missing → show error with install guidance)
              → read file, strip YAML frontmatter
              → pass body AS-IS to Copilot LLM

Design Principles

1. Pure adapter — never modifies, generates, or converts files.
2. Strict upstream alignment — only reads files produced by the official BMAD installer.
3. No prompt reconstruction — prompt body is passed unmodified to the LLM.
4. No workflow parsing — the LLM interprets workflow instructions, matching native Copilot behavior.
5. No bundling — bmad-method is a peer dependency, never included in the package.

See ARCHITECTURE.md for the full architecture document.

Development

git clone https://github.com/pi-docket/bmad-method-vscode.git
cd bmad-method-vscode
npm install
npm run build

Press F5 in VS Code to launch the Extension Development Host.

Scripts

| Script | Description | | ---------------------- | --------------------------------- | | npm run build | Clean build to dist/ | | npm run compile | TypeScript compile only | | npm run watch | Compile in watch mode | | npm run lint | Type-check without emitting | | npm run vsce:package | Build VSIX package to releases/ |

Publishing & Versioning

Note: The VS Code extension (VSIX) is not published to the Marketplace. Users must build it from source. The CLI tool may be available via npm for convenience.

This project follows Semantic Versioning:

| Version Bump | When | | ----------------------- | -------------------------------- | | patch (0.2.0 → 0.2.1) | Bug fixes, documentation updates | | minor (0.2.0 → 0.3.0) | New features, new slash commands | | major (0.x → 1.0.0) | Breaking changes, API changes |

Release Process

Version tags are created in git to mark releases:

# Update version in package.json
npm version patch  # or minor, major

# Tag and push
git push origin main --follow-tags

Users can then clone the repository at a specific tag and build the VSIX:

git clone --branch v0.2.5 https://github.com/pi-docket/bmad-method-vscode.git
cd bmad-method-vscode/bmad-copilot
npm install
npm run vsce:package
code --install-extension releases/bmad-copilot-adapter-0.2.5.vsix

Folder Structure

Source (development)

bmad-copilot/
├── bin/bmad-copilot-adapter.js     CLI entry point
├── src/
│   ├── extension.ts                VS Code entry point
│   ├── chatBridge.ts               Prompt executor (core)
│   ├── cliBridge.ts                CLI process spawner
│   ├── commandRegistry.ts          CSV scanning, command index
│   ├── types.ts                    Shared interfaces
│   ├── promptMirror.ts             @deprecated
│   ├── bmadRuntime.ts              @deprecated
│   └── cli/
│       ├── index.ts                CLI router
│       ├── bootstrap.ts            Bootstrap command
│       ├── update.ts               Update command
│       └── status.ts               Status command
├── package.json
├── tsconfig.json
├── README.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── TESTING.md
└── LICENSE

Published (npm / VSIX)

bmad-copilot-adapter/
├── bin/
│   └── bmad-copilot-adapter.js     CLI entry
├── dist/
│   ├── extension.js
│   ├── chatBridge.js
│   ├── cliBridge.js
│   ├── commandRegistry.js
│   ├── types.js
│   └── cli/
│       ├── index.js
│       ├── bootstrap.js
│       ├── update.js
│       └── status.js
├── package.json
├── README.md
├── ARCHITECTURE.md
└── LICENSE

Safety & Disclaimer

• This package does not modify any files in _bmad/, .github/prompts/, or .github/agents/.
• It does not bundle any part of bmad-method.
• It only reads official prompt files and forwards them to the Copilot LLM.
• Users must install bmad-method separately — it is a peer dependency.
• No internal workflow logic, config merging, or CLI execution is replicated.
• No mirroring, conversion, or prompt transformation of any kind.

Compatibility

| Requirement | Minimum Version | | ------------------- | ----------------------------------- | | VS Code | ≥ 1.93.0 | | Node.js | ≥ 18.0.0 | | BMAD-METHOD | ≥ 6.0.0-Beta.1 | | GitHub Copilot Chat | Required (extension must be active) |

Platform support: Windows, macOS, Linux.

License

MIT — see LICENSE for details.

This package is an independent adapter. It does not include, fork, or modify any part of the upstream BMAD-METHOD codebase. Refer to the BMAD-METHOD repository for its own license terms.