bmalph

BMAD-METHOD planning + Ralph autonomous implementation, wired through platform-specific instructions, skills, and command indexes.

<p align="center"> <img src="docs/bmalph-diagram.png" alt="bmalph workflow diagram" width="800" /> </p>

What is bmalph?

bmalph bundles and installs two AI development systems:

• BMAD-METHOD — Planning agents and workflows (Phases 1-3)
• Ralph — Autonomous implementation loop (Phase 4)

bmalph provides:

• bmalph init — Install both systems
• bmalph upgrade — Update to latest versions
• bmalph doctor — Check installation health
• bmalph implement — Transition from BMAD to Ralph
• bmalph run — Start Ralph loop with live dashboard
• bmalph check-updates — Check for upstream updates
• bmalph status — Show project status and phase
• bmalph reset — Remove all bmalph files
• ~~bmalph watch~~ — (deprecated) Use bmalph run instead

Supported Platforms

bmalph works with multiple AI coding assistants. Each platform gets BMAD planning (Phases 1-3). The Ralph autonomous loop (Phase 4) requires a CLI-based platform.

| Platform | ID | Tier | Instructions File | Commands | | -------------- | ------------- | ------------------- | --------------------------------- | ------------------------------------- | | Claude Code | claude-code | full | CLAUDE.md | .claude/commands/ directory | | OpenAI Codex | codex | full | AGENTS.md | Codex Skills (.agents/skills/) | | OpenCode | opencode | full | AGENTS.md | OpenCode Skills (.opencode/skills/) | | Cursor | cursor | full (experimental) | .cursor/rules/bmad.mdc | _bmad/COMMANDS.md | | Windsurf | windsurf | instructions-only | .windsurf/rules/bmad.md | _bmad/COMMANDS.md | | GitHub Copilot | copilot | full (experimental) | .github/copilot-instructions.md | _bmad/COMMANDS.md | | Aider | aider | instructions-only | CONVENTIONS.md | _bmad/COMMANDS.md |

Tiers:

• full — Phases 1-4. BMAD planning + Ralph autonomous implementation loop.
• instructions-only — Phases 1-3. BMAD planning only. Ralph is not available.

Prerequisites

• Node.js 20+
• Bash (WSL or Git Bash on Windows)
• A supported AI coding platform (see table above)
• For Ralph loop (Phase 4): Claude Code (claude), Codex CLI (codex), OpenCode (opencode), Copilot CLI (copilot), or Cursor CLI (cursor-agent; older agent installs are also supported)

Installation

npm install -g bmalph

Quick Start

cd my-project
bmalph init --name my-project

# To target a specific platform, add --platform (e.g. codex, cursor, windsurf)
# Without --platform, bmalph auto-detects strong project markers and
# prompts interactively when detection is ambiguous or missing

Workflow

Step 1: Initialize

cd my-project
bmalph init

Platform resolution: --platform flag > auto-detect from project markers > interactive prompt > default claude-code

Strong markers such as .cursor/, .claude/, .opencode/, .windsurf/, .github/copilot-instructions.md, and .aider.conf.yml are auto-detected directly. Root-only AGENTS.md and CLAUDE.md are treated as weak hints and may still trigger the interactive platform prompt.

This installs:

• _bmad/ — BMAD agents and workflows
• .ralph/ — Ralph loop, libs, templates (drivers for claude-code, codex, opencode, copilot, and cursor)
• bmalph/ — State management (config.json, stores selected platform)
• Updates the platform's instructions file with BMAD workflow instructions (e.g. CLAUDE.md, AGENTS.md, .cursor/rules/bmad.mdc)
• Delivers BMAD commands using the platform's native mechanism (Claude Code: .claude/commands/; Codex: .agents/skills/; OpenCode: .opencode/skills/; Cursor, Windsurf, Copilot, and Aider: _bmad/COMMANDS.md)

Migrating from standalone BMAD

If you already have BMAD installed (a _bmad/ directory), bmalph init works as a migration path:

• _bmad/ (framework files) will be replaced with the bmalph-managed version
• _bmad-output/ (your planning artifacts: PRDs, architecture, stories) is not touched
• If you've customized framework files inside _bmad/, commit first so you can review changes with git diff

Step 2: Plan with BMAD (Phases 1-3)

Work interactively with BMAD agents in your AI coding assistant.

• Claude Code — use /bmalph to see your current phase and available commands.
• OpenAI Codex — use Codex Skills such as $analyst and $create-prd.
• Cursor — Read _bmad/COMMANDS.md and ask Cursor to run the BMAD master agent.
• Windsurf, Copilot, Aider — use _bmad/COMMANDS.md as the command reference and ask the assistant to follow the named BMAD workflow.

| Phase | Agent | Commands | | ------------- | ---------------- | ------------------ | | 1 Analysis | Analyst | BP, MR, DR, TR, CB | | 2 Planning | PM / UX Designer | CP, VP, EP, CU | | 3 Solutioning | Architect / PM | CA, CE, IR |

Validation commands (validate-brief, validate-prd, validate-ux, validate-architecture, validate-epics-stories) run the same workflow in Validate mode. In Claude Code, invoke them as slash commands; on other platforms use the equivalent entry from _bmad/COMMANDS.md or Codex Skills.

Phase 1 — Analysis

• BP Brainstorm Project — guided facilitation through brainstorming techniques
• MR Market Research — market analysis, competitive landscape, customer needs
• DR Domain Research — industry domain deep dive
• TR Technical Research — technical feasibility, architecture options
• CB Create Brief — guided experience to nail down your product idea

Phase 2 — Planning

• CP Create PRD — expert led facilitation to produce your PRD (required)
• VP Validate PRD — validate PRD is comprehensive and cohesive
• EP Edit PRD — improve and enhance an existing PRD
• CU Create UX — guidance through realizing the plan for your UX

Phase 3 — Solutioning

• CA Create Architecture — guided workflow to document technical decisions (required)
• CE Create Epics and Stories — create the epics and stories listing (required)
• IR Implementation Readiness — ensure PRD, UX, architecture, and stories are aligned (required)

Anytime Commands

Available in any phase for supporting tasks:

• QS Quick Spec — lightweight spec for small tasks without full planning
• QD Quick Dev — quick implementation for small tasks
• DP Document Project — analyze existing project to produce documentation
• GPC Generate Project Context — scan codebase to generate LLM-optimized context
• CC Correct Course — navigate significant changes mid-project
• WD Write Document — tech writer agent for documentation
• MG Mermaid Generate — create Mermaid diagrams
• VD Validate Document — review documents against standards
• BSP Brainstorming — interactive idea generation techniques (core, distinct from BP)
• ID Index Docs — create lightweight doc index for LLM scanning
• SD Shard Document — split large documents into smaller files
• ES Editorial Review (Structure) — propose document reorganization
• AR Adversarial Review — critical content review for QA
• US Update Standards — update tech-writer documentation standards
• EC Explain Concept — create technical explanations with examples
• _bmad/COMMANDS.md — generated command reference for platforms without native slash commands

Note: EP means Edit PRD in the bmm workflow (Phase 2) and Editorial Review — Prose in the core module. PM is Party Mode in core. The bmm meanings are the primary workflow codes.

Step 3: Implement with Ralph (Phase 4)

Note: Ralph is only available on full tier platforms (Claude Code, OpenAI Codex, OpenCode, GitHub Copilot, Cursor). Instructions-only platforms (Windsurf, Aider) support Phases 1-3 only. GitHub Copilot and Cursor support is experimental.

Run bmalph implement from the terminal, or use the /bmalph-implement slash command in Claude Code.

This transitions your BMAD artifacts into Ralph's format:

1. Reads your stories from BMAD output
2. Generates .ralph/@fix_plan.md with ordered tasks
3. Copies specs to .ralph/specs/ with changelog tracking
4. Instructs you to start the Ralph autonomous loop

Then start Ralph:

bmalph run

Advanced: Ralph loads the platform drivers internally. Start the loop with bmalph run, or run bash .ralph/ralph_loop.sh directly if you need to bypass the CLI.

Ralph picks stories one by one, implements with TDD, and commits. The loop stops when all stories are done or the circuit breaker triggers.

Incremental Development

bmalph supports iterative development cycles:

BMAD (Epic 1) → bmalph implement → Ralph works on Epic 1
     ↓
BMAD (add Epic 2) → bmalph implement → Ralph sees changes + picks up Epic 2

**Smart Merge