BMAD-METHOD planning + Ralph autonomous implementation, glued by slash commands.

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

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.

Tiers:

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

• 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), or Copilot CLI (copilot) in PATH

npm install -g bmalph

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 or prompts interactively

cd my-project
bmalph init

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

This installs:

• _bmad/ — BMAD agents and workflows
• .ralph/ — Ralph loop, libs, templates (drivers for claude-code, codex, and copilot)
• 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)
• Installs slash commands for supported platforms (Claude Code: .claude/commands/ directory; Codex: inline in AGENTS.md; other platforms: commands not installed)

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

Work interactively with BMAD agents in your AI coding assistant. On Claude Code, use the /bmalph slash command to see your current phase and available commands. On other platforms, ask the agent about BMAD phases or run bmalph status in terminal.

Validation commands (/validate-brief, /validate-prd, /validate-ux, /validate-architecture, /validate-epics-stories) run the same workflow in Validate mode.

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-help — list all available 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.

Note: Ralph is only available on full tier platforms (Claude Code, OpenAI Codex, GitHub Copilot). Instructions-only platforms (Cursor, Windsurf, Aider) support Phases 1-3 only. GitHub Copilot 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: You can also run drivers directly with bash .ralph/drivers/claude-code.sh, bash .ralph/drivers/codex.sh, or bash .ralph/drivers/copilot.sh.

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

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: When you run bmalph implement again after Ralph has made progress:

• Completed stories ([x]) are preserved in the new fix_plan
• New stories from BMAD are added as pending ([ ])

Specs Changelog: .ralph/SPECS_CHANGELOG.md shows what changed in specs since the last run, so Ralph knows what's new or modified.

Deprecated: Use bmalph run instead. The watch command will be removed in a future release.

bmalph installs 51 slash commands (45 BMAD + 6 bmalph). Command delivery varies by platform:

• Claude Code — installed as files in .claude/commands/ (invoke with /command-name)
• OpenAI Codex — inlined in AGENTS.md (reference agents by name)
• Cursor, Windsurf, Copilot, Aider — not delivered as slash commands; use agents by name in chat

Key commands (Claude Code syntax):

For full list, run /bmad-help in Claude Code.

Use bmalph implement (or /bmalph-implement in Claude Code) to transition from BMAD planning to Ralph implementation.

project/
├── _bmad/                     # BMAD agents, workflows, core
│   ├── _config/               # Generated configuration
│   │   ├── config.yaml        # Platform config
│   │   ├── task-manifest.csv  # Combined task manifest
│   │   ├── workflow-manifest.csv # Combined workflow manifest
│   │   └── bmad-help.csv      # Combined help manifest
│   ├── core/
│   │   ├── agents/            # Master agent
│   │   ├── tasks/             # Workflow tasks
│   │   ├── workflows/         # Brainstorming, party-mode, etc.
│   │   ├── module.yaml        # Core module metadata
│   │   └── module-help.csv    # Core module help entries
│   └── bmm/
│       ├── agents/            # Analyst, PM, Architect, Dev, QA, etc.
│       ├── data/              # Templates (project-context-template.md)
│       ├── workflows/         # Phase 1-4 workflows
│       ├── teams/             # Agent team definitions
│       ├── module.yaml        # BMM module metadata
│       └── module-help.csv    # BMM module help entries
├── _bmad-output/              # BMAD planning artifacts (generated)
│   ├── planning-artifacts/    # PRD, architecture, stories
│   ├── implementation-artifacts/ # Sprint plans (optional)
│   └── brainstorming/         # Brainstorm sessions (optional)
├── .ralph/                    # Ralph autonomous loop (drivers for claude-code, codex, and copilot)
│   ├── ralph_loop.sh          # Main loop script
│   ├── ralph_import.sh        # Import requirements into Ralph
│   ├── ralph_monitor.sh       # Monitor loop progress
│   ├── .ralphrc               # Ralph configuration
│   ├── RALPH-REFERENCE.md     # Ralph usage reference
│   ├── drivers/               # Platform driver scripts
│   │   ├── claude-code.sh     # Claude Code driver (uses `claude`)
│   │   ├── codex.sh           # OpenAI Codex driver (uses `codex exec`)
│   │   └── copilot.sh         # GitHub Copilot driver (uses `copilot`, experimental)
│   ├── lib/                   # Shell libraries
│   ├── docs/generated/        # Generated documentation
│   ├── specs/                 # Copied from _bmad-output during transition
│   ├── logs/                  # Loop execution logs
│   ├── PROMPT.md              # Iteration prompt template
│   ├── PROJECT_CONTEXT.md     # Extracted project context (after bmalph implement)
│   ├── SPECS_CHANGELOG.md     # Spec diff since last run (after bmalph implement)
│   ├── SPECS_INDEX.md         # Prioritized spec file index (after bmalph implement)
│   ├── @AGENT.md              # Agent build instructions
│   └── @fix_plan.md           # Generated task list (after bmalph implement)
├── bmalph/                    # State management
│   ├── config.json            # Project config (name, description, platform)
│   └── state/                 # Phase tracking data
├── .claude/                   # Claude Code specific
│   └── commands/              # Slash commands (claude-code only)
└── <instructions file>        # Varies by platform (see Supported Platforms)

The instructions file and command directory depend on the configured platform. See the Supported Platforms table for details.

Ralph is a bash loop that spawns fresh AI coding sessions using a platform driver matching the configured platform:

• Claude Code driver — invokes claude with --allowedTools and session resume
• Codex driver — invokes codex exec with --sandbox workspace-write
• Copilot driver (experimental) — invokes copilot --autopilot --yolo with plain-text output

Each iteration:

1. Pick the next unchecked story from @fix_plan.md
2. Implement with TDD (tests first, then code)
3. Commit the changes
4. Move to the next story

Safety mechanisms:

• Circuit breaker — prevents infinite loops on failing stories
• Response analyzer — detects stuck or repeating outputs
• Completion — loop exits when all @fix_plan.md items are checked off

Run bmalph run to start the loop with a live dashboard, or bmalph run --no-dashboard for headless mode. Press Ctrl+C to stop the loop at any time.

Ralph requires bash to run. On Windows, install one of:

Git Bash (Recommended)

# Install Git for Windows from https://git-scm.com/downloads
# Git Bash is included and works well with bmalph

WSL (Windows Subsystem for Linux)

# In PowerShell as Administrator
wsl --install
# Then restart and run bmalph from WSL terminal

If you get permission errors:

# Unix/Mac: Make driver scripts executable
chmod +x .ralph/drivers/*.sh

# Check file ownership
ls -la .ralph/

The simplest way to remove all bmalph files:

bmalph reset

Use --dry-run to preview what will be removed, or --force to skip confirmation.

If the CLI is unavailable, remove these directories and files manually:

rm -rf _bmad/ .ralph/ bmalph/

Then remove the bmalph-managed sections from your instructions file. The file depends on your platform:

• Claude Code — remove .claude/commands/ and bmalph section from CLAUDE.md
• Codex — remove bmalph sections from AGENTS.md
• Cursor — remove .cursor/rules/bmad.mdc
• Windsurf — remove .windsurf/rules/bmad.md
• Copilot — remove bmalph sections from .github/copilot-instructions.md
• Aider — remove bmalph sections from CONVENTIONS.md

See the Supported Platforms table for details. After manual removal, run bmalph init to reinitialize.

# Interactive mode (prompts for name/description, auto-detects platform)
bmalph init

# Non-interactive mode
bmalph init --name my-app --description "My awesome app"

# Specify platform explicitly
bmalph init --name my-app --platform codex
bmalph init --name my-app --platform cursor
bmalph init --name my-app --platform windsurf

# Preview what would be created
bmalph init --dry-run

# Human-readable output
bmalph doctor

# JSON output for scripting
bmalph doctor --json

# Update BMAD and Ralph to latest bundled versions
bmalph upgrade

# Preview changes first
bmalph upgrade --dry-run

Claude Code:

# 1. Open Claude Code in your project
claude

# 2. Use the /bmalph slash command to start
#    This shows your current phase and available commands

# 3. Follow the BMAD workflow:
#    Phase 1: /analyst → create product brief
#    Phase 2: /pm → create PRD
#    Phase 3: /architect → create architecture and stories

# 4. Transition to Ralph
#    Run: bmalph implement

# 5. Start autonomous implementation
bmalph run

Other platforms:

# 1. Open your project in your AI coding assistant

# 2. Ask the agent about BMAD phases to start planning
#    Or check status from terminal: bmalph status

# 3. Reference BMAD agents by name (analyst, pm, architect)
#    Follow phases: Analysis → Planning → Solutioning

# 4. For full tier platforms (Codex, Copilot), transition to Ralph:
#    Run: bmalph implement
#    Then: bmalph run

See CONTRIBUTING.md for development setup, test workflow, and commit guidelines.

MIT