by LarsCowe
Unified AI Development Framework - BMAD phases with Ralph execution loop
# Add to your Claude Code skills
git clone https://github.com/LarsCowe/bmalphBMAD-METHOD planning + Ralph autonomous implementation, wired through platform-specific instructions, skills, and command indexes.
bmalph bundles and installs two AI development systems:
bmalph provides:
bmalph init — Install both systemsbmalph upgrade — Update to latest versionsbmalph doctor — Check installation healthbmalph implement — Transition from BMAD to Ralphbmalph run — Start Ralph loop with live dashboardbmalph check-updates — Check for upstream updatesbmalph status — Show project status and phaseNo comments yet. Be the first to share your thoughts!
bmalph reset — Remove all bmalph filesbmalph watch~~ — (deprecated) Use bmalph run insteadbmalph 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:
claude), Codex CLI (codex), OpenCode (opencode), Copilot CLI (copilot), or Cursor CLI (cursor-agent; older agent installs are also supported)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 strong project markers and
# prompts interactively when detection is ambiguous or missing
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)CLAUDE.md, AGENTS.md, .cursor/rules/bmad.mdc).claude/commands/; Codex: .agents/skills/; OpenCode: .opencode/skills/; Cursor, Windsurf, Copilot, and Aider: _bmad/COMMANDS.md)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_bmad/, commit first so you can review changes with git diffWork interactively with BMAD agents in your AI coding assistant.
/bmalph to see your current phase and available commands.$analyst and $create-prd._bmad/COMMANDS.md and ask Cursor to run the BMAD master agent._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 techniquesMR Market Research — market analysis, competitive landscape, customer needsDR Domain Research — industry domain deep diveTR Technical Research — technical feasibility, architecture optionsCB Create Brief — guided experience to nail down your product ideaPhase 2 — Planning
CP Create PRD — expert led facilitation to produce your PRD (required)VP Validate PRD — validate PRD is comprehensive and cohesiveEP Edit PRD — improve and enhance an existing PRDCU Create UX — guidance through realizing the plan for your UXPhase 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 planningQD Quick Dev — quick implementation for small tasksDP Document Project — analyze existing project to produce documentationGPC Generate Project Context — scan codebase to generate LLM-optimized contextCC Correct Course — navigate significant changes mid-projectWD Write Document — tech writer agent for documentationMG Mermaid Generate — create Mermaid diagramsVD Validate Document — review documents against standardsBSP Brainstorming — interactive idea generation techniques (core, distinct from BP)ID Index Docs — create lightweight doc index for LLM scanningSD Shard Document — split large documents into smaller filesES Editorial Review (Structure) — propose document reorganizationAR Adversarial Review — critical content review for QAUS Update Standards — update tech-writer documentation standardsEC Explain Concept — create technical explanations with examples_bmad/COMMANDS.md — generated command reference for platforms without native slash commandsNote:
EPmeans Edit PRD in the bmm workflow (Phase 2) and Editorial Review — Prose in the core module.PMis 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, 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:
.ralph/@fix_plan.md with ordered tasks.ralph/specs/ with changelog trackingThen start Ralph:
bmalph run
Advanced: Ralph loads the platform drivers internally. Start the loop with
bmalph run, or runbash .ralph/ralph_loop.shdirectly 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.
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