Skip to content
/

BMAD-AT-CLAUDE

bmad-at-claude · 24601/BMAD-AT-CLAUDE · ★ 235 · last commit 2026-02-23

Ports the full BMAD agile agent workflow (10 named personas, planning+implementation phases) into Claude Code's native hook and subagent infrastructure.

Best whenBMAD planning agents should run as router subagents triggered by natural language rather than explicit slash-commands, reducing friction for teams migrating …
Skip ifLoading all agent files on activation, Dev agent reading PRD or architecture docs directly
vs seeds
bmad-methodseed into Claude Code; adds 4 hook scripts (UserPromptSubmit, SubagentStop, PreToolUse, custom session-switch), a JavaSc…
Primitive shape 14 total
Subagents 10 Hooks 4
00

Summary

BMAD-AT-CLAUDE — Summary

BMAD-AT-CLAUDE is a port of the BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) specifically adapted for Claude Code's native subagent and hook infrastructure. The project ships the full BMAD v4.33 agent suite (10 named persona agents: Analyst, PM, Architect, Dev, QA, Scrum Master, etc.) plus a custom Claude Code integration layer featuring a JavaScript message queue, elicitation broker, session manager, and hook scripts wired to UserPromptSubmit, SubagentStop, and PreToolUse lifecycle events. Install is a Node.js multi-step installer that writes router subagents to ~/.claude/routers/ and configures ~/.claude/settings.json. The npx bmad-method flatten subcommand produces an XML snapshot of the entire codebase for AI consumption — a capability absent in the upstream BMAD-METHOD. The package.json is the upstream bmad-method@4.33.0 package, meaning this repo sits on top of the official BMAD release rather than forking it.

differs_from_seeds: Closest to bmad-method (seed) — shares identical agent personas (Analyst/PM/Architect/Dev/QA/SM/UX), the same *command prefix convention, and the same YAML-in-markdown agent definition format. The architectural delta is the Claude Code integration layer: BMAD-METHOD ships zero hooks and expects the user to manually switch agents via web UI or IDE paste; BMAD-AT-CLAUDE adds 4 shell hook scripts (UserPromptSubmit, SubagentStop, PreToolUse, custom bmad-session-switch.sh), a JavaScript message queue for multi-agent session state, and an elicitation broker that surfaces BMAD's interactive Q&A phases inside the Claude Code terminal rather than requiring a separate web session.

01

Overview

BMAD-AT-CLAUDE — Overview

Origin

BMAD-AT-CLAUDE (GitHub: 24601/BMAD-AT-CLAUDE) is a community port of the BMAD-METHOD by an independent contributor (handle: 24601). Created circa 2025, it packages bmad-method@4.33.0 as a dependency and builds a Claude Code–native orchestration layer on top. The repo has 235 stars, 17 forks, 28 contributors, and was last pushed in February 2026.

Core Philosophy

The project README opens with:

"Foundations in Agentic Agile Driven Development, known as the Breakthrough Method of Agile AI-Driven Development, yet so much more. Transform any domain with specialized AI expertise: software development, entertainment, creative writing, business strategy to personal wellness just to name a few."

The two innovation pillars, carried over from upstream BMAD, are:

  1. Agentic Planning: Dedicated planning agents (Analyst, PM, Architect) collaborate with the human to produce detailed PRD and Architecture documents before coding begins.
  2. Context-Engineered Development: The Scrum Master agent transforms those plans into "hyper-detailed development stories" that contain all implementation context, so the Dev agent never needs to re-query the plan.

The Claude Code integration layer adds a third concern: keeping multiple concurrent BMAD agent sessions alive in the same terminal, with graceful elicitation phase handling and context preservation across context-compaction events.

What Makes It Distinct

The integration readme describes a "hybrid message queue architecture" where:

  • A core/message-queue.js handles async communication between agents with retry logic and TTL.
  • An elicitation-broker.js manages BMAD's interactive Q&A phases (the phases where agents pause to ask clarifying questions), storing history per session.
  • A session-manager.js allows multiple concurrent agent conversations, distinguishing visually between active agents.
  • bmad-loader.js parses the upstream BMAD agent YAML+markdown definitions so the integration layer stays current with upstream releases automatically.
  • Router subagents (routers/) are thin wrappers that route Claude Code's natural-language input to the correct BMAD agent.

The natural language routing means: "Design a microservices architecture" → Architect agent; "Create a user story" → PM agent; "Review this code" → QA agent — without the user typing *agent architect.

Position Relative to Upstream BMAD-METHOD

  • Depends on bmad-method@4.33.0 (npm), does not fork it.
  • Adds Claude Code–specific primitives (hooks, router subagents, message queue).
  • Does NOT ship a full bundled .txt team file for web UI use (that's upstream's feature).
  • Retains all upstream agent personas, tasks, templates, and *command conventions.
02

Architecture

BMAD-AT-CLAUDE — Architecture

Distribution

  • Type: standalone-repo (Node.js installer wraps npx bmad-method)
  • Install: Multi-step (cd bmad-claude-integration && npm install && npm run install:local)
  • Runtime: Node.js v18+
  • License: MIT

Directory Structure

BMAD-AT-CLAUDE/
├── bmad-core/                    # Upstream BMAD-METHOD core (via npm)
│   ├── agents/                   # 10 agent persona md files
│   ├── tasks/                    # Reusable task procedures
│   ├── templates/                # Document templates
│   ├── checklists/               # Quality checklists
│   ├── data/                     # Reference data
│   ├── workflows/                # Workflow definitions
│   └── core-config.yaml          # Project configuration
├── bmad-claude-integration/      # Claude Code integration layer
│   ├── core/
│   │   ├── bmad-loader.js        # Loads & parses BMAD agent definitions
│   │   ├── elicitation-broker.js # Manages BMAD interactive Q&A phases
│   │   ├── message-queue.js      # Async inter-agent communication
│   │   └── session-manager.js    # Multi-session management
│   ├── hooks/
│   │   ├── bmad-context-save.sh  # SubagentStop: backs up context
│   │   ├── bmad-elicitation-handler.sh  # PreToolUse: shows elicitation status
│   │   ├── bmad-session-check.sh # UserPromptSubmit: notifies active sessions
│   │   └── bmad-session-switch.sh # Manual session switch/suspend/resume
│   ├── installer/
│   │   ├── install.js            # Writes to ~/.claude/routers/ + settings.json
│   │   └── uninstall.js          # Removes all integration artifacts
│   └── routers/                  # Router subagent thin wrappers
├── expansion-packs/              # Domain-specific agent packs
├── dist/                         # Pre-built team bundle files
├── tools/                        # CLI tools (flattener, installer)
│   ├── flattener/main.js         # codebase-to-XML flattener
│   └── cli.js                    # bmad-method CLI entry
└── package.json                  # depends on bmad-method@4.33.0

Hook Events Used

Hook Script Claude Code Event Purpose
bmad-session-check.sh UserPromptSubmit Notifies user of active BMAD sessions
bmad-context-save.sh SubagentStop Backs up context when subagent completes
bmad-elicitation-handler.sh PreToolUse (optional) Shows current elicitation phase status
bmad-session-switch.sh Custom (manual call) Switch/suspend/resume agent sessions

Target AI Tools

  • Claude Code (primary — hooks and router subagents)
  • Gemini (web UI, via upstream team bundle files)
  • ChatGPT (web UI, via upstream team bundle files)
  • Claude.ai (web UI)

Installer Behavior

Running npm run install:local from bmad-claude-integration/:

  1. Generates router subagents and writes to ~/.claude/routers/
  2. Configures ~/.claude/settings.json with the 3 hook entries
  3. Creates ~/.bmad/sessions/ directory for session state
  4. Optionally backs up existing config before overwriting
03

Components

BMAD-AT-CLAUDE — Components

Agent Personas (10 — from bmad-core/agents/)

Agent Persona Name Role
bmad-orchestrator.md BMad Orchestrator Master orchestrator; routes to all other agents
bmad-master.md BMad Master Knowledge base and help system
analyst.md (unnamed) Business/requirements analyst
pm.md Product Manager PRD creation and management
architect.md System Architect Architecture design
dev.md James Full-stack developer; implements stories
qa.md QA Engineer Quality assurance, test generation
sm.md Scrum Master Sprint planning, story breakdown
po.md Product Owner Backlog management
ux-expert.md UX Expert User experience design

Integration Layer — JavaScript Core (4 files in bmad-claude-integration/core/)

File Purpose
bmad-loader.js Parses upstream BMAD agent YAML+markdown at runtime
elicitation-broker.js Tracks per-session Q&A elicitation history
message-queue.js Async inter-agent messages with retry + TTL
session-manager.js Multi-session switching, suspension, visual differentiation

Hook Scripts (4 in bmad-claude-integration/hooks/)

File Event Purpose
bmad-session-check.sh UserPromptSubmit Check active sessions at prompt
bmad-context-save.sh SubagentStop Backup context on subagent stop
bmad-elicitation-handler.sh PreToolUse (optional) Show elicitation phase transitions
bmad-session-switch.sh Manual switch/suspend/resume sessions

CLI Tools (in tools/)

Binary/Script Purpose
bmad-npx-wrapper.js npx bmad-method entry; handles install + update
flattener/main.js npx bmad-method flatten — generates flattened-codebase.xml
cli.js Internal build/validate/list:agents commands
installer/bin/bmad.js Runs the interactive installer wizard

Expansion Packs (expansion-packs/)

The repo ships at least 2 sample expansion packs demonstrating domain extensions (game dev, DevOps patterns).

Templates + Tasks

Inherited wholesale from bmad-method@4.33.0:

  • Tasks: create-next-story, create-doc, execute-checklist, etc.
  • Templates: prd-tmpl.md, architecture-tmpl.md, story-tmpl.md, etc.
  • Checklists: architect-checklist.md, story-dod-checklist.md, etc.
05

Prompts

BMAD-AT-CLAUDE — Prompts

Excerpt 1 — BMad Orchestrator Activation + Command List

From bmad-core/agents/bmad-orchestrator.md:

activation-instructions:
  - STEP 1: Read THIS ENTIRE FILE - it contains your complete persona definition
  - STEP 2: Adopt the persona defined in the 'agent' and 'persona' sections below
  - STEP 3: Greet user with your name/role and mention `*help` command
  - DO NOT: Load any other agent files during activation
  - ONLY load dependency files when user selects them for execution via command
  - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands.
agent:
  name: BMad Orchestrator
  id: bmad-orchestrator
  title: BMad Master Orchestrator
  icon: 🎭
  whenToUse: Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult
persona:
  role: Master Orchestrator & BMad Method Expert
  style: Knowledgeable, guiding, adaptable, efficient, encouraging, technically brilliant yet approachable.
  core_principles:
    - Become any agent on demand, loading files only when needed
    - Never pre-load resources - discover and load at runtime
    - Assess needs and recommend best approach/agent/workflow
    - Track current state and guide to next logical steps
    - When embodied, specialized persona's principles take precedence
    - Always use numbered lists for choices
    - Process commands starting with * immediately

Prompting technique: Persona activation via YAML-in-markdown ("ACTIVATION-NOTICE" pattern). The YAML block defines identity, principles, and commands. The "HALT to await" instruction enforces a passive reception mode. This is the BMAD standard persona-md format.

Excerpt 2 — Dev Agent (James) Core Principles

From bmad-core/agents/dev.md:

persona:
  role: Expert Senior Software Engineer & Implementation Specialist
  style: Extremely concise, pragmatic, detail-oriented, solution-focused
  identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing
  focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead

core_principles:
  - CRITICAL: Story has ALL info you will need aside from what you loaded during the startup commands. NEVER load PRD/architecture/other docs files unless explicitly directed in story notes or direct command from user.
  - CRITICAL: ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
  - CRITICAL: FOLLOW THE develop-story command when the user tells you to implement the story
  - Numbered Options - Always use numbered lists when presenting choices to the user

Prompting technique: Explicit prohibition chain ("NEVER load PRD/architecture/other docs") that enforces story-as-sole-context discipline. This is a deliberate context-minimization technique — the dev agent is forbidden from reading the full project docs to prevent context window bloat and hallucination from stale information.

Excerpt 3 — Session Check Hook

From bmad-claude-integration/hooks/bmad-session-check.sh:

#!/bin/bash
SESSIONS_DIR="$HOME/.bmad/sessions"
if [ -d "$SESSIONS_DIR" ] && [ "$(ls -A $SESSIONS_DIR 2>/dev/null)" ]; then
  echo "📋 Active BMAD Sessions available. Use /bmad-sessions to view."
fi

Prompting technique: Hook-injected ambient notification — not a prompt per se, but the output of this hook fires into the Claude Code prompt context on every UserPromptSubmit, reminding the user that prior BMAD agent sessions are suspended and recoverable.

09

Uniqueness

BMAD-AT-CLAUDE — Uniqueness & Positioning

differs_from_seeds

BMAD-AT-CLAUDE is a thin Claude Code integration shell around the bmad-method seed. The canonical seed ships zero hooks and expects users to manually invoke agents via web UI or IDE paste; this port adds 4 hook scripts wired to UserPromptSubmit, SubagentStop, and PreToolUse, plus a JavaScript message queue, elicitation broker, and session manager that turn the multi-agent BMAD workflow into a first-class Claude Code experience. Compared to superpowers (14 skills, autonomous activation via SessionStart), BMAD-AT-CLAUDE uses router subagents + natural language routing rather than skill auto-detection, making agent boundaries explicit and user-controlled. Compared to claude-flow (MCP server, SQLite memory, code-class subagents), BMAD-AT-CLAUDE's agents are persona-md files, install is simpler, but there's no graph/vector memory — state lives in flat files.

Key Positioning

  • For teams already using BMAD-METHOD in web UI who want to migrate to Claude Code terminal.
  • The codebase-flattener (npx bmad-method flatten → flattened-codebase.xml) is a unique artifact not present in upstream BMAD or any seed framework — useful for uploading an entire project to a model with a large context window.

Failure Modes

  1. Version drift: Depends on bmad-method@^4.30.3 but pins at 4.33.0; upstream BMAD releases frequently, causing integration tests to fail.
  2. Hook reliability: The 4 hook scripts use bash file checks (ls -A ~/.bmad/sessions); if Claude Code changes hook stdin format, hooks silently fail.
  3. Message queue depth: The in-memory JS message queue has no persistence — a Node.js process crash loses all queued agent messages. No fallback to disk.
  4. Session file accumulation: ~/.bmad/sessions/ is never automatically pruned; long-running projects accumulate stale session files.
  5. 28 contributors, moderate activity: Last push February 2026 — integration may lag behind upstream BMAD releases.
04

Workflow

BMAD-AT-CLAUDE — Workflow

Phases (inherited from BMAD-METHOD v4.33)

Phase Agent(s) Key Artifact Gate
0 — Orientation BMad Orchestrator None; assess goal *workflow-guidance selects path
1 — Analysis Analyst, PM product-brief.md, prfaq.md User confirms brief before proceeding
2 — Planning PM prd.md PRD reviewer gate — user selects reviewers
3 — Solutioning Architect architecture.md, epic-N.md, story-N.md Architecture step-file sequence; user selects Continue at each step
4 — Implementation Dev, QA, SM Story files, code Story must not be in draft mode before Dev starts

Approval Gates

  1. Workflow selection: User types *workflow-guidance and Orchestrator presents options.
  2. PRD reviewer gate: User explicitly selects which reviewer agents to run before finalizing PRD.
  3. Architecture step sequence: Each sub-step of architecture creation requires user Continue.
  4. Story dispatch: User explicitly provides or confirms story file before Dev starts.
  5. Session continuation: Hook at UserPromptSubmit notifies user if prior BMAD sessions are active; user resumes or starts new.

Artifacts Table

Artifact Written by Location
product-brief.md Analyst docs/
prd.md PM docs/
architecture.md Architect docs/
epic-N.md Architect/SM docs/
story-N.md SM docs/stories/
flattened-codebase.xml npx bmad-method flatten repo root
Session state bmad-context-save.sh ~/.bmad/sessions/

Development Cycle (IDE)

  1. Scrum Master selects next story from backlog.
  2. SM populates story with all context (implementation details, architecture refs).
  3. User opens story file, switches to Dev agent.
  4. Dev reads story ONLY (does not re-read PRD or architecture).
  5. Dev implements, runs tests via *run-tests.
  6. QA agent reviews.
  7. Commit. Repeat for next story.

Multi-Agent Session Flow

User prompt → bmad-session-check.sh hook fires
           → If sessions active, notify user
           → User says "create user story for login"
           → Router identifies → PM agent
           → elicitation-broker manages Q&A
           → PM produces story
           → bmad-context-save.sh on SubagentStop
06

Memory Context

BMAD-AT-CLAUDE — Memory & Context

Session State

  • Storage: File-based, written to ~/.bmad/sessions/ by bmad-context-save.sh hook.
  • Trigger: SubagentStop hook fires automatically when a BMAD subagent completes, backing up conversation state.
  • Persistence: Project-level (per-conversation snapshots in ~/.bmad/).

In-Memory Architecture (JavaScript layer)

The message-queue.js maintains an in-process queue with:

  • TTL management (messages expire)
  • Retry logic for agent communication failures
  • Structured message format (agent-id, content, timestamp)

The elicitation-broker.js maintains per-session elicitation history so that when a BMAD agent's Q&A phase is interrupted by context compaction, the history can be re-injected.

The session-manager.js tracks:

  • Active sessions (which BMAD agent is "live")
  • Suspended sessions (backed up to disk)
  • Visual differentiation cues between agent outputs

Cross-Session Handoff

Yes: the bmad-context-save.sh + ~/.bmad/sessions/ pattern allows resuming a prior BMAD agent session in a new Claude Code conversation. The bmad-session-switch.sh script handles switch, suspend, and resume operations.

Compaction Handling

Yes (via elicitation-broker): if Claude Code compacts the context, the elicitation phase history is preserved in ~/.bmad/sessions/ and can be re-injected.

Project Documents as Memory

The BMAD workflow treats plan documents as persistent memory:

  • prd.md — requirements memory
  • architecture.md — design decisions memory
  • story-N.md — implementation task memory (self-contained context per story)

The Dev agent principle "Story has ALL info you need" enforces that stories are complete context-bearing units — a form of pre-computed memory injection.

07

Orchestration

BMAD-AT-CLAUDE — Orchestration

Multi-Agent Pattern

  • Yes: 10 named persona agents, each activated by natural language routing or explicit *agent <name> command.
  • Pattern: Sequential (human-driven handoffs between agents) + optional simultaneous via message queue.
  • Subagent definition format: persona-md — each agent is a markdown file with embedded YAML (agent:, persona:, commands:, dependencies:).
  • Spawn mechanism: Claude Code's subagent / router mechanism; the integration layer installs "router subagents" to ~/.claude/routers/ which Claude Code discovers automatically.

Orchestration Pattern

hierarchical — BMad Orchestrator is the root; it routes to specialized agents. Each specialized agent is self-contained ("ACTIVATION-NOTICE: this file contains your complete persona"). The orchestrator can call *agent pm, *agent architect, etc. to switch context.

Isolation

  • None (in-place editing by default).
  • Session suspension via ~/.bmad/sessions/ provides soft isolation between concurrent agent contexts, but no git-worktree or container isolation is present.

Multi-Model Usage

  • No: Single model (whichever Claude model is active in Claude Code). No per-role model routing.
  • Upstream BMAD-METHOD supports web UI (Gemini Gems, ChatGPT Custom GPTs) for planning agents, which could implicitly use different models, but that's not configured in this repo.

Execution Mode

interactive-loop — user triggers agent actions via *commands or natural language; no autonomous background daemon.

Consensus Mechanism

None. Human is the decision authority between agent handoffs (approval gates at each phase).

Prompt Chaining

Yes: SM agent reads PRD + architecture to produce stories; Dev agent reads stories. Each stage's output explicitly becomes the next stage's primary context file.

08

Ui Cli Surface

BMAD-AT-CLAUDE — UI / CLI Surface

CLI Binary

  • Exists: Yes (bmad and bmad-method — both map to tools/bmad-npx-wrapper.js).
  • Invoked as: npx bmad-method <subcommand> or npx bmad-method@next install.
  • Subcommands:
    • install — interactive installer wizard (installs BMAD to a target project)
    • flatten — generates flattened-codebase.xml for AI consumption
    • build — builds agent team bundles
    • list:agents — lists available agents
    • validate — validates agent definitions
  • Is thin wrapper: No — bmad-npx-wrapper.js runs a custom Node.js installer/builder, not a wrapper over the Claude CLI.

Local UI

None. The integration is terminal-only (Claude Code terminal). No web dashboard or desktop app.

IDE Integration

Claude Code only:

  • Router subagents installed to ~/.claude/routers/.
  • Hook scripts configured in ~/.claude/settings.json.
  • Natural language routing inside Claude Code sessions.

Observability

  • ~/.bmad/sessions/ — session state files for debugging.
  • bmad-context-save.sh logs context snapshots.
  • No structured audit log / JSONL replay capability.

Cross-Tool Portability

Medium — the BMAD agent personas work in web UI (Gemini, ChatGPT) via the upstream .txt team bundle files, but the hook integration is Claude Code–specific. The persona files themselves are model-agnostic markdown; it's the hooks that are CC-locked.

Related frameworks

same archetype · same primary tool · same memory type

claude-mem (thedotmack) ★ 78k

Background worker service captures every tool call as an observation, AI-compresses sessions, and auto-injects relevant past…

pi (badlogic/earendil) ★ 55k

A minimal, hackable, multi-provider terminal coding agent that adapts to your workflows via npm-installable TypeScript Extensions…

Agent Skills (Addy Osmani) ★ 46k

Encodes senior-engineer software development lifecycle as 23 auto-routed skills and 7 slash commands for any AI coding agent.

wshobson/agents Plugin Marketplace ★ 36k

Single Markdown source for 83 domain-specialized plugins that auto-generates idiomatic artifacts for five AI coding harnesses.

TabbyML/Tabby ★ 34k

Self-hosted AI coding assistant server (alternative to GitHub Copilot) with admin dashboard, RAG-based completions, and multi-IDE…

Compound Engineering ★ 17k

Make each unit of engineering work compound into easier future work via brainstorm→plan→execute→review→learn cycles.