ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad-claude-integration/README.md

5.8 KiB
Raw Blame History

BMAD-METHOD Claude Code Integration

This integration brings the power of BMAD-METHOD (Business Modeling and Architecture Design Method) to Claude Code through subagents, enabling natural interaction with specialized AI agents for software development workflows.

Overview

The BMAD Claude integration implements a hybrid message queue architecture that:

  • Preserves the original BMAD-METHOD agent behaviors
  • Enables concurrent multi-agent sessions
  • Handles interactive elicitation phases naturally
  • Maintains full context without summarization
  • Provides clear agent identification during conversations

Architecture

Core Components

  1. Message Queue System (core/message-queue.js)

    • Handles asynchronous communication between agents
    • Preserves full context in structured messages
    • Supports retry logic and TTL management

  2. Elicitation Broker (core/elicitation-broker.js)

    • Manages interactive Q&A phases
    • Tracks elicitation history per session
    • Enables natural conversation flow

  3. Session Manager (core/session-manager.js)

    • Handles multiple concurrent agent conversations
    • Provides clear visual differentiation between agents
    • Manages session switching and suspension

  4. BMAD Loader (core/bmad-loader.js)

    • Loads original BMAD agent definitions
    • Parses YAML configurations and markdown content
    • Maintains compatibility with upstream changes

  5. Router Subagents (routers/)

    • Thin wrappers around original BMAD agents
    • Handle message routing and context preservation
    • Enable both automatic and manual invocation

Installation

Prerequisites

  • Claude Code installed with ~/.claude directory
  • Node.js v18 or higher
  • BMAD-METHOD repository cloned

Quick Install

cd /path/to/BMAD-METHOD/bmad-claude-integration
npm install
npm run install:local

Manual Installation

  1. Install dependencies:

    npm install

  2. Generate router subagents:

    npm run generate:routers

  3. Run the installer:

    node installer/install.js

Usage

Natural Language Invocation

Simply describe what you need and Claude Code will automatically route to the appropriate BMAD agent:

  • "Create a user story for login feature" → Routes to PM agent
  • "Design a microservices architecture" → Routes to Architect agent
  • "Review this code for quality" → Routes to QA agent

Slash Commands

Use explicit commands for direct agent invocation:

  • /bmad-pm - Invoke Project Manager
  • /bmad-architect - Invoke Architect
  • /bmad-dev - Invoke Developer
  • /bmad-sessions - View active sessions
  • /bmad-switch <number> - Switch between sessions

Managing Concurrent Sessions

The integration supports multiple active agent conversations:

🟢 1. 📋 Project Manager
   Session: session-123456
   Status: active | Last active: 10:30 AM
   📝 In elicitation phase

🟡 2. 🏗️ Architect
   Session: session-789012
   Status: suspended | Last active: 10:25 AM

💡 Use /switch <number> to switch between sessions

Elicitation Handling

When an agent needs user input, you'll see clear identification:

📋 **Project Manager Question**
─────────────────────────────────
What type of authentication do you need for the login feature?

*Responding to Project Manager in session session-123456*

Simply respond naturally - no special format required.

File Structure

bmad-claude-integration/
├── core/                  # Core system components
│   ├── message-queue.js   # Message handling
│   ├── elicitation-broker.js # Elicitation management
│   ├── session-manager.js # Session handling
│   └── bmad-loader.js     # BMAD file loader
├── routers/              # Generated router subagents
│   ├── bmad-router.md    # Main router
│   └── *-router.md       # Individual agent routers
├── hooks/                # Optional Claude hooks
├── installer/            # Installation scripts
├── lib/                  # Utilities
│   └── router-generator.js
└── tests/                # Test suites

Message Flow

  1. User Request → Main Router analyzes and routes
  2. Router → Creates/resumes session, sends message to queue
  3. Agent Execution → Task subagent loads BMAD definition
  4. Elicitation → Broker manages Q&A if needed
  5. Response → Formatted with agent identification back to user

Testing

Run the test suite:

npm test              # Run all tests
npm run test:ai      # Run AI judge tests

Troubleshooting

Agents Not Responding

  • Check if subagents are installed: ls ~/.claude/agents/bmad-*.md
  • Verify message queue: node core/message-queue.js metrics
  • Check active sessions: /bmad-sessions

Context Loss

  • Ensure message queue is initialized: npm run queue:init
  • Check session files: ls ~/.bmad/sessions/

Elicitation Issues

  • Verify broker is working: node core/elicitation-broker.js active
  • Check elicitation sessions: ls ~/.bmad/queue/elicitation/

Development

Adding New Features

  1. Modify core components as needed
  2. Regenerate routers: npm run generate:routers
  3. Test thoroughly with AI judge
  4. Update documentation

Debugging

Enable debug mode:

DEBUG=bmad:* npm run install:local

View message queue:

node core/message-queue.js list
node core/message-queue.js metrics

Contributing

This integration is designed to be minimally invasive to the parent BMAD-METHOD repository. When contributing:

  1. Don't modify original BMAD files
  2. Keep router logic thin
  3. Test with multiple concurrent sessions
  4. Ensure elicitation works naturally
  5. Maintain clear agent identification

License

Same as BMAD-METHOD - see parent repository for details.