thuongtin/bmalph.md

## bmalph.md

      
    Raw
  

              bmalph.md
            
          
    bmalph – Hướng dẫn từ cơ bản đến thành thạo

Giới thiệu tổng quan

bmalph là một Unified AI Development Framework – khung phát triển AI thống nhất, kết hợp BMAD-METHOD (planning) và Ralph (autonomous implementation) thành một pipeline liền mạch.
Điểm quan trọng từ các phiên bản gần đây là multi-platform: bmalph có thể cài đặt hướng dẫn/commands cho nhiều AI coding assistants (Claude Code, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, Aider). Trong đó Phase 4 (Ralph autonomous loop) chỉ khả dụng trên các nền tảng có CLI (hiện tại: Claude Code claude hoặc Codex CLI codex).
Thông tin dự án (cập nhật ngày 2026-02-25):

Repository: github.com/LarsCowe/bmalph
Giấy phép: MIT (mã nguồn mở)
Phiên bản stable mới nhất (npm/release): v2.4.0 (published 2026-02-23)
Nhánh main: đang ahead 4 commits so với tag v2.4.0 (chủ yếu test + hardening cho Ralph)
Stars/Forks: 81 ⭐ · 8 forks (snapshot 2026-02-25)
Ngôn ngữ: TypeScript ~73.9% · Shell ~26.0% · JavaScript ~0.1%
Bundled/Upstream: BMAD-METHOD (bundled commit aa573bdb) + Ralph (bundled, không track upstream)
Hỗ trợ platform: Claude Code, OpenAI Codex, Cursor, Windsurf, GitHub Copilot, Aider
Yêu cầu: Node.js 20+, Bash; Phase 4 cần jq + CLI (claude hoặc codex) trong PATH

Điểm mới đáng chú ý từ v2.4.0:

Thêm CLI command bmalph implement với pre-flight validation.
Thêm CLI command bmalph reset.
implement có re-run protection và giữ tiến độ @fix_plan.md.
status phát hiện phase từ artifacts tốt hơn (Phase 1-3).
Loại bỏ tham chiếu cũ tới /bmalph-reset (không có slash command này).


      graph TB
    CENTER["🔗 bmalph"]

    subgraph planning ["📋 BMAD Planning"]
        P1["6+ Agent chuyên biệt"]
        P2["50 Slash Commands"]
        P3["Phase 1-3: Analysis → Planning → Solutioning"]
    end

    subgraph execution ["⚡ Ralph Execution"]
        E1["Autonomous Loop"]
        E2["TDD: Test First → Code → Commit"]
        E3["Circuit Breaker + Response Analyzer"]
    end

    subgraph glue ["🧩 bmalph Glue"]
        G1["CLI: init · upgrade · doctor · status · implement · reset"]
        G2["BMAD → Ralph Transition"]
        G3["Smart Merge + Specs Changelog"]
    end

    subgraph oss ["🌐 Mã nguồn mở"]
        O1["MIT License · npm install -g bmalph"]
    end

    CENTER --- planning
    CENTER --- execution
    CENTER --- glue
    CENTER --- oss

    style CENTER fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style planning fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style execution fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style glue fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style oss fill:#1e272e,color:#dfe6e9,stroke:#fdcb6e,stroke-width:2px
    style P1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style P2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style P3 fill:#0984e3,color:#fff,stroke:#74b9ff
    style E1 fill:#00b894,color:#fff,stroke:#55efc4
    style E2 fill:#00b894,color:#fff,stroke:#55efc4
    style E3 fill:#00b894,color:#fff,stroke:#55efc4
    style G1 fill:#e17055,color:#fff,stroke:#fab1a0
    style G2 fill:#e17055,color:#fff,stroke:#fab1a0
    style G3 fill:#e17055,color:#fff,stroke:#fab1a0
    style O1 fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
Hỗ trợ nền tảng (Multi-platform)

bmalph hoạt động với nhiều AI coding assistants. Điểm quan trọng cần nhớ:

BMAD planning (Phase 1–3): hỗ trợ trên tất cả platform.
Ralph autonomous loop (Phase 4): chỉ hỗ trợ trên platform có CLI (hiện tại: Claude Code và OpenAI Codex).


Platform
ID
Tier
Instructions file
Commands


Claude Code
claude-code
full
CLAUDE.md
.claude/commands/ directory


OpenAI Codex
codex
full
AGENTS.md
Inline trong instructions file


Cursor
cursor
instructions-only
.cursor/rules/bmad.mdc
Không có


Windsurf
windsurf
instructions-only
.windsurf/rules/bmad.md
Không có


GitHub Copilot
copilot
instructions-only
.github/copilot-instructions.md
Không có


Aider
aider
instructions-only
CONVENTIONS.md
Không có


Tiers:

full — Phases 1–4: BMAD planning + Ralph autonomous implementation.
instructions-only — Phases 1–3: BMAD planning, không có Ralph.

Platform resolution khi init: --platform > auto-detect theo marker files > prompt tương tác > mặc định claude-code.
Tại sao cần bmalph?

Trước khi bmalph xuất hiện, nếu bạn muốn dùng cả BMAD và Ralph, bạn phải:

Cài đặt thủ công BMAD-METHOD vào dự án (chạy npx bmad-method install, chọn module, cấu hình)
Cài đặt thủ công Ralph (clone repo, copy files, thiết lập prompt template)
Tự tay chuyển đổi artifacts từ BMAD (PRD, architecture, stories) sang format Ralph (@fix_plan.md)
Tự quản lý version, update, và đồng bộ giữa hai hệ thống

bmalph giải quyết tất cả vấn đề trên bằng một lệnh duy nhất: bmalph init. Nó bundle cả BMAD và Ralph, tự động cài đặt, và cung cấp cả CLI bmalph implement lẫn slash command /bmalph-implement để chuyển đổi liền mạch từ planning sang execution.
Triết lý cốt lõi


Plan First, Execute Autonomously: Lên kế hoạch kỹ lưỡng với BMAD agents (Phase 1-3), rồi để Ralph tự động triển khai (Phase 4). Không nhảy thẳng vào code.
Fresh Context Per Iteration: Ralph khởi tạo AI coding session mới cho mỗi story (qua driver claude-code hoặc codex), tránh context window exhaustion và "hallucination drift".
Human-in-the-Loop Planning, Hands-off Execution: Con người tham gia sâu ở giai đoạn planning (hỏi đáp, ra quyết định), nhưng giai đoạn execution gần như hoàn toàn tự động.
Incremental Development: Hỗ trợ phát triển theo vòng lặp – plan epic 1, implement, plan epic 2, implement – không cần làm xong toàn bộ planning trước.

bmalph so với các phương pháp khác


Tiêu chí
Vibe Coding
BMAD Method (đơn lẻ)
Ralph (đơn lẻ)
bmalph


Cách tiếp cận
Prompt → Code
Agent personas → Workflows → Artifacts
PRD → prd.json → Auto-loop
BMAD planning → Ralph execution


Planning
Không có
Rất chi tiết (PRD, Architecture, Stories)
Cơ bản (prd.json)
BMAD-level chi tiết


Execution
Thủ công / 1 shot
Thủ công (dev-story)
Autonomous loop
Autonomous loop (Ralph)


Chuyển đổi
N/A
N/A
Tự viết prd.json
Tự động (bmalph implement / /bmalph-implement)


Phù hợp với
Prototype nhanh
Dự án cần planning kỹ
Dự án đã có PRD
Dự án end-to-end


      graph LR
    A["🎲 Vibe Coding"] -->|"Prompt mơ hồ"| B["Kết quả không ổn định"]
    C["📋 BMAD only"] -->|"Planning tốt"| D["Execution thủ công"]
    E["⚡ Ralph only"] -->|"Loop mạnh"| F["Planning yếu"]
    G["🔗 bmalph"] -->|"Planning + Auto-execution"| H["End-to-end pipeline"]

    style A fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style B fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style C fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style D fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px
    style E fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style F fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px
    style G fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style H fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px

    
      Loading

  
Hiểu BMAD-METHOD và Ralph (Upstream Projects)

Trước khi đi vào bmalph, hãy hiểu rõ hai hệ thống mà nó tích hợp.
BMAD-METHOD – Breakthrough Method of Agile AI-Driven Development

BMAD là khung làm việc phát triển phần mềm Agile được dẫn dắt bởi AI. Nó cung cấp các "đặc vụ" AI chuyên biệt (agent personas) – mỗi agent đóng vai trò như một chuyên gia trong team: Product Manager, Architect, Developer, QA, UX Designer, Analyst, Scrum Master, Tech Writer... Các agent này hướng dẫn bạn qua 4 giai đoạn phát triển với hệ thống 50+ workflows có cấu trúc.

  
      graph LR
    subgraph phase1 ["Phase 1: Analysis"]
        A1["Analyst Agent"]
        A2["Brainstorm · Research · Product Brief"]
    end

    subgraph phase2 ["Phase 2: Planning"]
        B1["PM · UX Designer"]
        B2["PRD · UX Design"]
    end

    subgraph phase3 ["Phase 3: Solutioning"]
        C1["Architect · PM"]
        C2["Architecture · Epics · Stories · IR Gate"]
    end

    subgraph phase4 ["Phase 4: Implementation"]
        D1["Developer · QA"]
        D2["Code · Test · Review"]
    end

    phase1 --> phase2 --> phase3 --> phase4

    style phase1 fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style phase2 fill:#1e272e,color:#dfe6e9,stroke:#00b894,stroke-width:2px
    style phase3 fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:2px
    style phase4 fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style A1 fill:#0984e3,color:#fff,stroke:#74b9ff
    style A2 fill:#0984e3,color:#fff,stroke:#74b9ff
    style B1 fill:#00b894,color:#fff,stroke:#55efc4
    style B2 fill:#00b894,color:#fff,stroke:#55efc4
    style C1 fill:#e17055,color:#fff,stroke:#fab1a0
    style C2 fill:#e17055,color:#fff,stroke:#fab1a0
    style D1 fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style D2 fill:#6c5ce7,color:#fff,stroke:#a29bfe

    
      Loading

  
Điểm mạnh của BMAD:

Agent personas chuyên biệt hóa cao, mô phỏng team thực tế
Thích ứng theo quy mô dự án (Scale-Domain-Adaptive)
Party Mode: nhiều agent cùng thảo luận trong một phiên
/bmad-help: trợ giúp nhận biết ngữ cảnh, biết bạn đang ở đâu và cần làm gì

Hạn chế khi dùng đơn lẻ: Phần implementation (Phase 4) vẫn là thủ công – bạn phải gọi /dev-story cho từng story một, trong từng phiên chat riêng.
Ralph – Autonomous AI Agent Loop

Ralph là một bash loop tự động sinh ra từ ý tưởng của Geoffrey Huntley. Cơ chế hoạt động rất đơn giản nhưng hiệu quả:

  
      graph TD
    START["🚀 Start Ralph Loop"] --> PICK["Pick next unchecked story<br/>từ @fix_plan.md"]
    PICK --> SPAWN["Spawn FRESH AI session<br/>(clean context)"]
    SPAWN --> IMPLEMENT["AI implements story<br/>TDD: Tests → Code"]
    IMPLEMENT --> CHECK{"Checks pass?<br/>typecheck + tests"}
    CHECK -->|"✅ Yes"| COMMIT["Commit changes<br/>Mark story ✓"]
    CHECK -->|"❌ No"| CIRCUIT{"Circuit breaker<br/>triggered?"}
    CIRCUIT -->|"No"| SPAWN
    CIRCUIT -->|"Yes"| STOP["🛑 Stop: investigate"]
    COMMIT --> MORE{"More stories?"}
    MORE -->|"Yes"| PICK
    MORE -->|"No"| DONE["✅ All stories done!"]

    style START fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style PICK fill:#0984e3,color:#fff,stroke:#74b9ff
    style SPAWN fill:#00b894,color:#fff,stroke:#55efc4
    style IMPLEMENT fill:#00b894,color:#fff,stroke:#55efc4
    style CHECK fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style COMMIT fill:#00b894,color:#fff,stroke:#55efc4
    style CIRCUIT fill:#e17055,color:#fff,stroke:#fab1a0
    style STOP fill:#e17055,color:#fff,stroke:#fab1a0
    style MORE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style DONE fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px

    
      Loading

  
Điểm mạnh của Ralph:

Fresh context per iteration: Mỗi story chạy trong AI coding session mới, tránh context pollution
Circuit breaker: Phát hiện loop vô hạn, tự động dừng khi stuck
Response analyzer: Nhận diện output lặp lại hoặc bị kẹt
State + logs rõ ràng: trạng thái và lịch sử chạy được ghi trong .ralph/status.json, .ralph/.ralph_session và .ralph/logs/

Hạn chế khi dùng đơn lẻ: Ralph cần có sẵn prd.json hoặc @fix_plan.md – nó không có khả năng planning chi tiết. Bạn phải tự viết PRD và stories.
bmalph = BMAD + Ralph, Connected

bmalph giải quyết hạn chế của cả hai: dùng BMAD để planning kỹ lưỡng, rồi tự động chuyển đổi artifacts sang format Ralph để execution tự động.


Concern
BMAD-METHOD
Ralph
bmalph


Phase
Planning & Design
Autonomous Execution
Cả hai + Transition


Output
PRD, Architecture, Stories
Working code, commits
End-to-end


Human involvement
Cao (guided elicitation)
Thấp (set-and-forget)
Cao ở planning, thấp ở execution


AI session model
1 conversation dài per workflow
Nhiều instance ngắn per story
Cả hai


Memory model
In-session context + docs
Git + progress.txt
Docs + Git + Specs Changelog


Cài đặt và thiết lập dự án

Yêu cầu chuẩn bị


      graph TD
    subgraph req ["Yêu cầu chuẩn bị"]
        N["Node.js v20+"]
        B["Bash"]
        P["AI coding assistant (platform hỗ trợ)"]
    end

    subgraph phase4 ["Phase 4 (Ralph) – thêm yêu cầu"]
        CLI["CLI trong PATH: `claude` hoặc `codex`"]
        JQ["jq (JSON processor)"]
    end

    subgraph optional ["Khuyến nghị"]
        G["Git"]
        T["tmux (cho --monitor mode)"]
    end

    N --> READY["✅ Sẵn sàng cài đặt bmalph"]
    B --> READY
    P --> READY

    READY --> NOTE["(Nếu dùng Ralph: cần CLI + jq)"]
    CLI --> NOTE
    JQ --> NOTE

    subgraph windows ["Windows"]
        W1["Git Bash (khuyến nghị)"]
        W2["WSL"]
    end

    B -.->|"Windows cần"| windows

    style req fill:#1e272e,color:#dfe6e9,stroke:#0984e3,stroke-width:2px
    style phase4 fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style optional fill:#1e272e,color:#dfe6e9,stroke:#636e72,stroke-width:1px
    style windows fill:#1e272e,color:#dfe6e9,stroke:#e17055,stroke-width:1px
    style N fill:#0984e3,color:#fff,stroke:#74b9ff
    style B fill:#0984e3,color:#fff,stroke:#74b9ff
    style P fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style CLI fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style JQ fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style G fill:#636e72,color:#fff,stroke:#b2bec3
    style T fill:#636e72,color:#fff,stroke:#b2bec3
    style W1 fill:#e17055,color:#fff,stroke:#fab1a0
    style W2 fill:#e17055,color:#fff,stroke:#fab1a0
    style READY fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style NOTE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24,stroke-width:2px

    
      Loading

  
Node.js 20+ – Runtime cho CLI
Bash – Ralph loop cần bash. Trên Windows, dùng Git Bash hoặc WSL
CLI cho full-tier platform – Cần claude (Claude Code) hoặc codex (OpenAI Codex) trong PATH để chạy Phase 4
Git (khuyến nghị) – Quản lý mã nguồn, Ralph tự tạo commit
tmux (tùy chọn) – Cho chế độ --live streaming 3-pane layout

Bước 1: Cài đặt bmalph

npm install -g bmalph
Kiểm tra cài đặt:
bmalph --version
# Output: 2.4.0
Bước 2: Khởi tạo dự án

cd my-project
bmalph init
Lệnh bmalph init sẽ hỏi bạn tên và mô tả dự án. Hoặc truyền trực tiếp:
bmalph init --name my-app --description "My awesome app"
Chỉ định platform ngay từ đầu (khuyến nghị khi không dùng Claude Code):
bmalph init --name my-app --platform codex
Preview trước khi cài:
bmalph init --dry-run
Bước 3: Kiểm tra sức khỏe cài đặt

bmalph doctor
Lệnh doctor kiểm tra 15+ tiêu chí: thư mục BMAD/Ralph có đủ không, instructions/command delivery theo platform đã đúng chưa, CLI phụ trợ (bash, jq) có sẵn chưa, phiên bản có khớp không, v.v.
# JSON output cho scripting
bmalph doctor --json
Cấu trúc thư mục sau khi cài đặt

my-project/
├── _bmad/                         # BMAD agents, workflows, core
│   ├── _config/
│   │   ├── config.yaml            # Platform config
│   │   ├── task-manifest.csv
│   │   ├── workflow-manifest.csv
│   │   └── bmad-help.csv
│   ├── core/
│   └── bmm/
├── _bmad-output/                  # BMAD planning artifacts (generated)
│   ├── planning-artifacts/
│   ├── implementation-artifacts/
│   └── brainstorming/
├── .ralph/                        # Ralph autonomous loop
│   ├── ralph_loop.sh
│   ├── ralph_import.sh
│   ├── ralph_monitor.sh
│   ├── .ralphrc
│   ├── RALPH-REFERENCE.md
│   ├── drivers/                   # claude-code.sh, codex.sh
│   ├── lib/
│   ├── docs/generated/
│   ├── specs/
│   ├── logs/
│   ├── PROMPT.md
│   ├── PROJECT_CONTEXT.md
│   ├── SPECS_CHANGELOG.md
│   ├── SPECS_INDEX.md
│   ├── @AGENT.md
│   └── @fix_plan.md
├── bmalph/
│   ├── config.json                # name, description, platform
│   └── state/
└── <instructions file theo platform>
   # Claude: CLAUDE.md + .claude/commands/
   # Codex: AGENTS.md (commands inline)


      graph TD
    subgraph project ["my-project/"]
        BMAD["📁 _bmad/<br/>BMAD agents & workflows"]
        OUTPUT["📁 _bmad-output/<br/>Planning artifacts"]
        RALPH["📁 .ralph/<br/>Ralph autonomous loop"]
        STATE["📁 bmalph/<br/>State management"]
        INSTR["📄 Platform instructions file<br/>CLAUDE.md / AGENTS.md / ..."]
        CMD_DELIVERY["🧩 Command delivery<br/>Directory / Inline / None"]
    end

    BMAD -->|"Phase 1-3 tạo ra"| OUTPUT
    OUTPUT -->|"bmalph implement / /bmalph-implement"| RALPH
    STATE -->|"Theo dõi"| BMAD
    STATE -->|"Theo dõi"| RALPH
    INSTR -->|"Hướng dẫn platform"| BMAD
    CMD_DELIVERY -->|"Tùy platform"| BMAD

    style project fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style BMAD fill:#0984e3,color:#fff,stroke:#74b9ff
    style OUTPUT fill:#00b894,color:#fff,stroke:#55efc4
    style RALPH fill:#e17055,color:#fff,stroke:#fab1a0
    style STATE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style INSTR fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style CMD_DELIVERY fill:#6c5ce7,color:#fff,stroke:#a29bfe

    
      Loading

  
Quy trình làm việc toàn diện

Tổng quan 4 Phase

Workflow của bmalph chia thành 4 giai đoạn rõ ràng. Phase 1-3 sử dụng BMAD agents, Phase 4 chuyển sang Ralph autonomous loop.

  
      graph LR
    P1["Phase 1<br/>🔍 Analysis"] --> P2["Phase 2<br/>📋 Planning"]
    P2 --> P3["Phase 3<br/>🏗️ Solutioning"]
    P3 -->|"bmalph implement<br/>hoặc /bmalph-implement"| P4["Phase 4<br/>⚡ Implementation"]

    P1 -.- A1["Analyst agent<br/>Brainstorm · Research · Brief"]
    P2 -.- A2["PM · UX Designer<br/>PRD · UX Design"]
    P3 -.- A3["Architect · PM<br/>Architecture · Epics · Stories"]
    P4 -.- A4["Ralph Loop<br/>Auto-implement stories"]

    style P1 fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style P2 fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style P3 fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px
    style P4 fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:2px
    style A1 fill:#2d3436,color:#dfe6e9,stroke:#0984e3
    style A2 fill:#2d3436,color:#dfe6e9,stroke:#00b894
    style A3 fill:#2d3436,color:#dfe6e9,stroke:#e17055
    style A4 fill:#2d3436,color:#dfe6e9,stroke:#6c5ce7

    
      Loading

  
Phase 1: Analysis

Mục tiêu: Hiểu rõ vấn đề, thị trường và ý tưởng sản phẩm.
Mở Claude Code tại thư mục dự án, gõ /bmalph để xem phase hiện tại và các lệnh có sẵn.


Mã lệnh
Slash Command
Mô tả


BP
/analyst → Brainstorm Project
Brainstorm ý tưởng sản phẩm có hướng dẫn


MR
Market Research
Phân tích thị trường, đối thủ, nhu cầu khách hàng


DR
Domain Research
Nghiên cứu chuyên sâu lĩnh vực ngành


TR
Technical Research
Khả thi kỹ thuật, lựa chọn kiến trúc


CB
Create Brief
Tạo Product Brief – tóm tắt ý tưởng sản phẩm


Ví dụ thực hành:
# Mở Claude Code
claude

# Gõ slash command
/bmalph
# → Hiển thị: Phase 1 - Analysis, các lệnh có sẵn

/analyst
# → Analyst agent (Mary) hướng dẫn bạn brainstorm
# → Đặt câu hỏi về target user, pain points, value proposition
# → Kết thúc: tạo product-brief.md trong _bmad-output/


Mẹo: Luôn mở phiên chat mới cho mỗi workflow quan trọng. Điều này giúp tránh context window exhaustion và đảm bảo agent tập trung vào nhiệm vụ hiện tại.

Phase 2: Planning

Mục tiêu: Tạo PRD chi tiết và thiết kế UX.


Mã lệnh
Slash Command
Mô tả


CP
/create-prd
Tạo Product Requirements Document (bắt buộc)


VP
/validate-prd
Kiểm tra PRD đã đầy đủ và nhất quán chưa


EP
Edit PRD
Cải thiện PRD hiện có


CU
/ux-designer
Thiết kế UX/wireframes


Ví dụ thực hành:
# Phiên chat mới
/create-prd
# → PM agent (John) hướng dẫn bạn tạo PRD
# → Hỏi về personas, user journeys, features, metrics
# → Tạo prd.md trong _bmad-output/planning-artifacts/

# Validate PRD
/validate-prd
# → Kiểm tra tính nhất quán, đầy đủ
# → Đưa ra suggestions nếu thiếu sót

Phase 3: Solutioning

Mục tiêu: Thiết kế kiến trúc, chia nhỏ thành epics/stories, và kiểm tra sẵn sàng triển khai.


Mã lệnh
Slash Command
Mô tả


CA
/create-architecture
Thiết kế kiến trúc kỹ thuật (bắt buộc)


CE
/create-epics-stories
Tạo epics và stories (bắt buộc)


IR
Implementation Readiness
Kiểm tra sẵn sàng triển khai (bắt buộc)


Ví dụ thực hành:
# Phiên chat mới
/create-architecture
# → Architect agent (Winston) thảo luận tech stack
# → System design, ADR (Architecture Decision Records)
# → Tạo architecture.md

# Phiên chat mới
/create-epics-stories
# → PM phân rã PRD thành Epics → User Stories
# → Mỗi story có acceptance criteria rõ ràng
# → Tạo epic-stories.md

# Phiên chat mới - Implementation Readiness Gate
# → Kiểm tra PRD, UX, Architecture, Stories alignment
# → Phải PASS gate này mới nên chuyển sang Phase 4


Quan trọng: Bước Implementation Readiness (IR) là quality gate quan trọng nhất. Nó đảm bảo mọi thứ đã align trước khi giao cho Ralph tự động chạy. Nếu IR phát hiện vấn đề, hãy quay lại sửa trước khi tiếp tục.

Phase 4: Implementation (Ralph Loop)

Đây là bước chuyển giao từ BMAD sang Ralph – điểm đặc biệt nhất của bmalph.
Bước 1: Transition
# Trong terminal (khuyến nghị)
bmalph implement

# Hoặc trong Claude Code
/bmalph-implement
Lệnh transition này thực hiện:

Đọc stories từ _bmad-output/
Sinh @fix_plan.md trong .ralph/ – danh sách task có thứ tự
Copy specs vào .ralph/specs/ với changelog tracking
Tạo/refresh PROJECT_CONTEXT.md, SPECS_CHANGELOG.md, SPECS_INDEX.md

Bước 2: Start Ralph Loop
# Claude Code
bash .ralph/drivers/claude-code.sh

# OpenAI Codex
bash .ralph/drivers/codex.sh
Ralph sẽ:

Pick story tiếp theo chưa checked trong @fix_plan.md
Spawn AI coding session mới qua platform driver
AI implement story đó (TDD: viết test trước, code sau)
Commit changes
Mark story là done [x]
Loop lại bước 1

Bước 3: Monitor
# Xem progress
bash .ralph/ralph_monitor.sh

# Hoặc xem logs
ls .ralph/logs/
Nhấn Ctrl+C bất cứ lúc nào để dừng loop.

  
      sequenceDiagram
    participant U as 👤 Bạn
    participant CC as 🖥️ Claude Code
    participant BMAD as 📋 BMAD Agents
    participant TR as 🔀 bmalph implement
    participant R as ⚡ Ralph Loop

    Note over U,BMAD: Phase 1-3: Planning

    U->>CC: /bmalph (check phase)
    CC->>BMAD: Load agent context
    U->>BMAD: /analyst → /create-prd → /create-architecture
    BMAD-->>U: PRD, Architecture, Stories

    Note over U,R: Phase 4: Transition + Execution

    U->>TR: bmalph implement
    TR->>TR: Parse stories → Generate @fix_plan.md
    TR->>TR: Copy specs → SPECS_CHANGELOG.md
    TR-->>U: "Ready! Run bash .ralph/drivers/<platform>.sh"

    U->>R: bash .ralph/drivers/claude-code.sh
    loop Mỗi story
        R->>CC: Spawn fresh AI session
        CC->>CC: Implement story (TDD)
        CC->>CC: Run checks (typecheck + tests)
        CC-->>R: Done, commit
        R->>R: Mark [x] in @fix_plan.md
    end
    R-->>U: ✅ All stories complete!

    
      Loading

  
Hệ thống Agent và Slash Commands

Các Agent chính

bmalph tích hợp 6+ agent personas từ BMAD, mỗi agent có chuyên môn riêng:

  
      graph TD
    subgraph agents ["🤖 bmalph Agent Personas"]
        ANALYST["🔍 Analyst<br/>Research & Analysis"]
        PM["📋 Product Manager<br/>PRD & Story Management"]
        ARCH["🏗️ Architect<br/>Technical Design"]
        DEV["💻 Developer<br/>Code Implementation"]
        QA["🧪 QA (Quinn)<br/>Test Automation"]
        UX["🎨 UX Designer<br/>User Experience"]
        SM["📊 Scrum Master<br/>Sprint Management"]
        TW["📝 Tech Writer<br/>Documentation"]
    end

    style agents fill:#1e272e,color:#dfe6e9,stroke:#6c5ce7,stroke-width:2px
    style ANALYST fill:#0984e3,color:#fff,stroke:#74b9ff
    style PM fill:#00b894,color:#fff,stroke:#55efc4
    style ARCH fill:#e17055,color:#fff,stroke:#fab1a0
    style DEV fill:#6c5ce7,color:#fff,stroke:#a29bfe
    style QA fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style UX fill:#00cec9,color:#fff,stroke:#81ecec
    style SM fill:#636e72,color:#fff,stroke:#b2bec3
    style TW fill:#636e72,color:#fff,stroke:#b2bec3

    
      Loading

  
Agent
Slash Command
Phase
Chức năng chính


Analyst
/analyst
1
Brainstorm, research thị trường/kỹ thuật/domain


Product Manager
/pm
2-3
Tạo PRD, chia epics/stories, quản lý scope


Architect
/architect
3
Thiết kế kiến trúc, ADR, tech stack decisions


Developer
/dev
4
Implement code, code review


QA (Quinn)
/qa
4
Test automation, quality assurance


UX Designer
/ux-designer
2
Wireframes, user flows, design system


Scrum Master
/sm
2-4
Sprint planning, retrospective


Tech Writer
/tech-writer
Any
Documentation, technical writing


Quick Flow Solo Dev
/quick-flow-solo-dev
Any
Quick spec + dev cho task nhỏ


Danh sách Slash Commands quan trọng

bmalph hiện có 50 slash commands (45 BMAD + 5 bmalph).
Lưu ý theo platform:

Claude Code: command được cài thành files trong .claude/commands/.
OpenAI Codex: command/agent được inline trong AGENTS.md.
Cursor/Windsurf/Copilot/Aider: không cài slash command, dùng agent theo tên.

Dưới đây là các command quan trọng nhất:
Commands điều hướng:


Command
Mô tả


/bmalph
Master agent – xem phase hiện tại, navigate


/bmad-help
Trợ giúp nhận biết ngữ cảnh


/bmalph-implement
Chuyển đổi BMAD → Ralph


/bmalph-status
Trạng thái phase + Ralph progress


/bmalph-upgrade
Cập nhật bundled assets


/bmalph-doctor
Health check cho dự án


Commands theo Phase:


Phase
Command
Output


1
/analyst
Product Brief


2
/create-prd
PRD document


2
/ux-designer
UX Design


3
/create-architecture
Architecture document


3
/create-epics-stories
Epics & Stories


3
/implementation-readiness
Readiness gate report


3
/validate-architecture
Architecture validation


Anytime Commands (dùng bất kỳ lúc nào):


Code
Mô tả


QS
Quick Spec – spec nhanh cho task nhỏ


QD
Quick Dev – implement nhanh từ spec


DP
Document Project – phân tích codebase tạo docs


GPC
Generate Project Context – scan codebase tạo LLM context


CC
Correct Course – điều chỉnh hướng đi giữa chừng


WD
Write Document – tạo tài liệu kỹ thuật


MG
Mermaid Generate – tạo Mermaid diagrams


BSP
Brainstorming – interactive idea generation


VD
Validate Document – review tài liệu theo chuẩn


ID
Index Docs – tạo doc index cho LLM scan


SD
Shard Document – tách tài liệu lớn thành file nhỏ


Incremental Development (Phát triển gia tăng)

Một trong những tính năng mạnh nhất của bmalph là hỗ trợ phát triển theo vòng lặp, thay vì phải planning xong toàn bộ rồi mới implement.

  
      graph TD
    PLAN1["📋 BMAD: Plan Epic 1"] --> IMPL1["/bmalph-implement"]
    IMPL1 --> RALPH1["⚡ Ralph: Implement Epic 1"]
    RALPH1 --> PLAN2["📋 BMAD: Plan Epic 2"]
    PLAN2 --> IMPL2["/bmalph-implement (lần 2)"]
    IMPL2 --> RALPH2["⚡ Ralph: Implement Epic 2"]
    RALPH2 --> PLAN3["📋 BMAD: Plan Epic 3..."]

    style PLAN1 fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style IMPL1 fill:#e17055,color:#fff,stroke:#fab1a0
    style RALPH1 fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style PLAN2 fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style IMPL2 fill:#e17055,color:#fff,stroke:#fab1a0
    style RALPH2 fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style PLAN3 fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px

    
      Loading

  
Smart Merge

Khi bạn chạy /bmalph-implement lần thứ hai (sau khi Ralph đã hoàn thành một số stories):

Completed stories ([x]) được giữ nguyên trong @fix_plan.md mới
New stories từ BMAD được thêm vào cuối danh sách dưới dạng [ ] (pending)
Ralph chỉ pick up những stories chưa done

Specs Changelog

File .ralph/SPECS_CHANGELOG.md tự động ghi lại những thay đổi trong specs so với lần chạy trước. Điều này giúp Ralph (và bạn) biết cái gì mới, cái gì đã modified – đặc biệt hữu ích khi architecture hoặc PRD thay đổi giữa chừng.

CLI Reference

Tổng hợp lệnh CLI


Command
Mô tả


bmalph init
Cài đặt BMAD + Ralph vào dự án


bmalph upgrade
Cập nhật bundled assets lên phiên bản mới


bmalph doctor
Kiểm tra sức khỏe cài đặt (15+ checks)


bmalph check-updates
Kiểm tra bundled BMAD commit so với upstream BMAD


bmalph status
Hiển thị trạng thái dự án và phase hiện tại


bmalph implement
Chuyển artifacts BMAD sang format Ralph


bmalph reset
Gỡ toàn bộ file bmalph khỏi dự án


Global Options


Flag
Mô tả


--verbose
Bật debug logging


--no-color
Tắt colored output


--quiet
Giảm thiểu output (cho scripting)


-C, --project-dir <path>
Chạy tại thư mục chỉ định


--version
Hiện version


--help
Hiện help


Init Options


Flag
Mô tả
Default


-n, --name <name>
Tên dự án
Tên thư mục


-d, --description <desc>
Mô tả dự án
(prompted)


--platform <id>
claude-code, codex, cursor, windsurf, copilot, aider
auto-detect


--dry-run
Preview changes


Implement Options


Flag
Mô tả


--force
Override pre-flight validation errors / bỏ re-run protection


Doctor / Status / Check-updates Options


Command
Flag
Mô tả


bmalph doctor
--json
JSON output cho automation


bmalph status
--json
JSON output cho automation


bmalph check-updates
--json
JSON output cho automation


Upgrade Options


Flag
Mô tả


--force
Bỏ qua confirmation prompt


--dry-run
Preview changes trước khi upgrade


Reset Options


Flag
Mô tả


--dry-run
Preview các file sẽ bị remove/modify


--force
Skip confirmation prompt


Ví dụ thực hành: Xây dựng Todo App

Để minh họa quy trình end-to-end, hãy cùng đi qua một ví dụ cụ thể.
1. Khởi tạo

mkdir todo-app && cd todo-app
git init
bmalph init --name todo-app --description "A collaborative todo list with real-time sync"
2. Phase 1 – Analysis

# Mở Claude Code
claude

# Kiểm tra trạng thái
/bmalph
# Output: Phase 1 - Analysis. Available commands: BP, MR, DR, TR, CB

# Brainstorm
/analyst
> "Tôi muốn xây dựng ứng dụng todo list collaborative, 
>  hỗ trợ real-time sync giữa các thành viên team"
# → Agent hỏi thêm về target users, features, constraints
# → Tạo product-brief.md

3. Phase 2 – Planning

# Phiên chat MỚI
/create-prd
# → PM hướng dẫn tạo PRD chi tiết
# → Personas, user journeys, features, acceptance criteria
# → Output: prd.md

# Validate
/validate-prd
# → Kiểm tra: ✅ Personas defined, ✅ Features complete, ⚠️ Missing metrics
# → Sửa lại metrics, validate lần nữa → ✅ All pass

4. Phase 3 – Solutioning

# Phiên chat MỚI
/create-architecture
# → Architect thảo luận tech stack
# → "React + Supabase + WebSocket cho real-time"
# → ADR documented, system diagram created
# → Output: architecture.md

# Phiên chat MỚI
/create-epics-stories
# → PM chia thành 3 Epics:
#   Epic 1: Core Todo CRUD
#   Epic 2: User Authentication
#   Epic 3: Real-time Collaboration
# → Mỗi epic có 3-5 stories
# → Output: epic-stories.md

# Phiên chat MỚI - Implementation Readiness
# → IR Gate: ✅ PRD aligned, ✅ Architecture covers all features, 
#   ✅ Stories have clear acceptance criteria

5. Phase 4 – Implementation

# Phiên chat MỚI
/bmalph-implement
# → Reads 12 stories from epic-stories.md
# → Generates .ralph/@fix_plan.md
# → Copies specs to .ralph/specs/
# → "Ready! Run: bash .ralph/drivers/claude-code.sh"

# Start Ralph
bash .ralph/drivers/claude-code.sh

# Ralph output:
# [1/12] US-001: Setup project scaffold...
# ✅ Tests pass. Committed.
# [2/12] US-002: Create Todo model and database...
# ✅ Tests pass. Committed.
# ...
# [12/12] US-012: Real-time cursor presence...
# ✅ Tests pass. Committed.
# 🎉 All stories complete!
6. Incremental – Thêm Epic 4

# Quay lại BMAD, thêm features mới
/create-epics-stories
# → Thêm Epic 4: Mobile Responsive Design

# Transition lại
/bmalph-implement
# → Smart Merge: 12 stories cũ [x], 4 stories mới [ ]

bash .ralph/drivers/claude-code.sh
# → Ralph chỉ implement 4 stories mới


Cơ chế an toàn của Ralph

Ralph được thiết kế với nhiều lớp bảo vệ để tránh các vấn đề khi chạy autonomous:
Circuit Breaker

Nếu một story fail liên tục (AI cứ implement nhưng tests không pass), circuit breaker sẽ tự động dừng loop sau N lần thử. Điều này ngăn Ralph chạy vô hạn và tiêu tốn token.
Response Analyzer

Phân tích output từ mỗi iteration của platform driver. Nếu phát hiện:

Output lặp lại giống hệt lần trước → stuck, dừng
Permission denied → cooldown và thử lại
Pattern bất thường → log warning

Permission Denial Detection

Ralph có cơ chế phát hiện khi CLI bị deny permission (ví dụ không được quyền ghi file) và auto-recovery với cooldown thay vì crash ngay.
Completion Detection

Loop tự exit khi tất cả items trong @fix_plan.md được check [x].

  
      graph TD
    LOOP["Ralph Loop Running"] --> ANALYZE["Response Analyzer"]
    ANALYZE -->|"Normal"| CONTINUE["Continue Loop"]
    ANALYZE -->|"Repeated Output"| CB["Circuit Breaker"]
    ANALYZE -->|"Permission Denied"| RECOVER["Auto-Recovery<br/>Cooldown"]
    ANALYZE -->|"All [x]"| COMPLETE["✅ Loop Complete"]
    CB --> STOP["🛑 Stop: investigate logs"]
    RECOVER --> LOOP

    style LOOP fill:#0984e3,color:#fff,stroke:#74b9ff,stroke-width:2px
    style ANALYZE fill:#fdcb6e,color:#2d3436,stroke:#f9ca24
    style CONTINUE fill:#00b894,color:#fff,stroke:#55efc4
    style CB fill:#e17055,color:#fff,stroke:#fab1a0
    style RECOVER fill:#e17055,color:#fff,stroke:#fab1a0
    style COMPLETE fill:#00b894,color:#fff,stroke:#55efc4,stroke-width:2px
    style STOP fill:#e17055,color:#fff,stroke:#fab1a0,stroke-width:2px

    
      Loading

  
Ralph Configuration (.ralphrc)

File .ralph/.ralphrc cho phép tùy chỉnh hành vi Ralph cho từng dự án:
# .ralph/.ralphrc

# Platform driver (claude-code hoặc codex)
PLATFORM_DRIVER="claude-code"

# Rate limit / timeout
MAX_CALLS_PER_HOUR=100
CLAUDE_TIMEOUT_MINUTES=15
CLAUDE_OUTPUT_FORMAT="json"

# Tool permissions
ALLOWED_TOOLS="Write,Read,Edit,Bash(git *),Bash(npm *),Bash(pytest)"

# Session continuity
SESSION_CONTINUITY=true
SESSION_EXPIRY_HOURS=24

# Circuit breaker thresholds
CB_NO_PROGRESS_THRESHOLD=3
CB_SAME_ERROR_THRESHOLD=5
CB_COOLDOWN_MINUTES=30
Live Mode (tmux 3-pane layout)

Nếu bạn có tmux, chạy với --monitor --live để xem real-time:
bash .ralph/ralph_loop.sh --monitor --live
Tạo layout 3-pane:

Pane 1: Ralph loop output
Pane 2: Claude Code output
Pane 3: Test/build output

Session Continuity

Ralph tự quản lý continuity qua session ID nội bộ (driver dùng --resume tự động). Bạn thường không cần truyền session ID thủ công.
Các lệnh hay dùng:
# Tắt continuity cho lần chạy hiện tại
bash .ralph/ralph_loop.sh --no-continue

# Reset session state nếu cần làm sạch
bash .ralph/ralph_loop.sh --reset-session

Troubleshooting

Bảng xử lý lỗi thường gặp


Vấn đề
Nguyên nhân
Giải pháp


Commands fail
Chưa init
bmalph init


Transition không tìm thấy stories
Chưa tạo stories ở Phase 3
/create-epics-stories trước


Ralph dừng giữa chừng
Circuit breaker
Kiểm tra .ralph/logs/, fix story, rồi chạy lại driver


Doctor báo version drift
Bundled assets cũ
bmalph upgrade


Permission denied (Ralph)
Driver scripts chưa executable
chmod +x .ralph/drivers/*.sh


Windows: bash not found
Thiếu bash
Cài Git Bash hoặc WSL


Sai platform sau init
Auto-detect nhận nhầm
Chạy lại bmalph init --platform <id>


Ralph không chạy được
Platform thuộc instructions-only tier
Dùng claude-code hoặc codex


Ralph loop vô hạn
fix_plan reference sai
Kiểm tra @fix_plan.md format


Reset cài đặt

Nếu mọi thứ rối, reset hoàn toàn:
# Preview reset plan
bmalph reset --dry-run

# Reset thực tế
bmalph reset --force

# Rồi init lại
bmalph init
Kiểm tra sức khỏe chi tiết

# Human-readable
bmalph doctor

# JSON cho scripting/CI
bmalph doctor --json

# Verbose mode để debug
bmalph doctor --verbose
Upgrade an toàn

# Preview trước
bmalph upgrade --dry-run

# Upgrade thực tế
bmalph upgrade

# Bỏ qua confirmation (cho CI/CD)
bmalph upgrade --force

Tips và Best Practices

Nguyên tắc vàng


Mỗi workflow = phiên chat mới. Đừng chạy /create-prd rồi /create-architecture trong cùng một chat. Context cũ sẽ ảnh hưởng chất lượng.


Viết stories nhỏ, right-sized. Ralph implement mỗi story trong một AI session mới. Story quá lớn → AI không fit trong context window → fail. Mỗi story nên hoàn thành được trong ~15 phút.


Luôn qua IR Gate trước khi transition. Implementation Readiness check đảm bảo PRD, Architecture và Stories đã align. Skip bước này = Ralph implement sai hướng.


Dùng bmalph doctor thường xuyên. Đặc biệt sau khi upgrade hoặc khi gặp lỗi lạ.


Commit trước khi chạy Ralph. Ralph tạo commits cho mỗi story. Nếu có uncommitted changes, có thể gây conflict.


Monitor logs. .ralph/logs/ chứa toàn bộ execution history. Nếu Ralph dừng, logs sẽ cho biết tại sao.


Quick Flow cho task nhỏ

Không phải lúc nào cũng cần đi qua 4 phases. Với task nhỏ (bug fix, small feature), dùng Quick Flow:
/quick-flow-solo-dev
# → Agent Barry: Quick Spec → Quick Dev trong 1 phiên
# → Không cần transition sang Ralph


Khi nào dùng Full Flow
Khi nào dùng Quick Flow


Dự án mới, greenfield
Bug fix, patch


Feature phức tạp, multi-epic
Feature nhỏ, 1-2 files


Cần architecture decisions
Đã có architecture rõ ràng


Team collaboration
Solo developer


Party Mode

Khi cần nhiều góc nhìn cho một quyết định phức tạp:
# Invoke Party Mode
# → Load nhiều agents cùng lúc: PM + Architect + Developer
# → Mỗi agent đưa ra quan điểm từ góc nhìn chuyên môn
# → Hữu ích cho architectural decisions, trade-off analysis


So sánh với các framework tương tự


Tiêu chí
bmalph
BMAD (đơn lẻ)
Ralph (đơn lẻ)
Spec-Kit
Beads


Planning depth
⭐⭐⭐⭐⭐
⭐⭐⭐⭐⭐
⭐⭐
⭐⭐⭐⭐
⭐⭐⭐


Autonomous execution
⭐⭐⭐⭐⭐
⭐⭐
⭐⭐⭐⭐⭐
⭐⭐
⭐⭐


Setup complexity
Thấp (1 cmd)
Trung bình
Trung bình
Thấp
Thấp


IDE support
Multi-platform (Claude/Codex/Cursor/Windsurf/Copilot/Aider)
Claude Code, Cursor, nhiều IDE
Claude Code, Amp
18+ agents
Nhiều IDE


Incremental dev
✅ Smart Merge
Thủ công
Thủ công
✅
✅


Safety mechanisms
✅ Circuit breaker
❌
✅ Circuit breaker
❌
❌


Agent personas
6+ specialized
12+ specialized
Không
Không
Không


Best for
End-to-end pipeline
Planning-heavy projects
Execution-heavy projects
Spec-driven dev
Config-driven dev


Cộng đồng và tài nguyên


      graph TD
    CENTER["🔗 bmalph<br/>Học tập & Cộng đồng"]

    CENTER --> REPO["📦 GitHub Repo<br/>github.com/LarsCowe/bmalph"]
    CENTER --> NPM["📦 npm<br/>npm install -g bmalph"]
    CENTER --> BMAD_DOCS["📚 BMAD Docs<br/>docs.bmad-method.org"]
    CENTER --> RALPH_DOCS["📚 Ralph Docs<br/>github.com/snarktank/ralph"]
    CENTER --> DISCORD["💬 BMAD Discord<br/>discord.gg/gk8jAdXWmj"]

    style CENTER fill:#6c5ce7,color:#fff,stroke:#a29bfe,stroke-width:3px
    style REPO fill:#0984e3,color:#fff,stroke:#74b9ff
    style NPM fill:#e17055,color:#fff,stroke:#fab1a0
    style BMAD_DOCS fill:#00b894,color:#fff,stroke:#55efc4
    style RALPH_DOCS fill:#00b894,color:#fff,stroke:#55efc4
    style DISCORD fill:#fdcb6e,color:#2d3436,stroke:#f9ca24

    
      Loading

  
GitHub: github.com/LarsCowe/bmalph – Source code, issues, contributing guide
npm: npm install -g bmalph – Luôn dùng phiên bản mới nhất
BMAD-METHOD Documentation: docs.bmad-method.org – Tài liệu chi tiết về agents, workflows
Ralph Documentation: github.com/snarktank/ralph – Tham khảo về loop engine
BMAD Discord: discord.gg/gk8jAdXWmj – Cộng đồng hỗ trợ


Kết luận

bmalph là câu trả lời cho câu hỏi "Làm sao để AI tự động phát triển phần mềm một cách có kỷ luật?". Thay vì chọn giữa planning kỹ lưỡng (BMAD) hoặc execution tự động (Ralph), bmalph cho phép bạn có cả hai trong một pipeline thống nhất:

Phase 1-3 (BMAD): Planning chi tiết với agent personas chuyên biệt – đảm bảo bạn biết rõ mình đang xây dựng cái gì, cho ai, và bằng cách nào.
Transition (bmalph implement / /bmalph-implement): Chuyển đổi tự động từ planning artifacts sang execution format – không cần chuyển đổi thủ công.
Phase 4 (Ralph): Autonomous implementation loop – AI tự viết code, chạy tests, commit, story by story cho đến khi xong.

Những điểm mấu chốt cần nhớ


🔗 bmalph = BMAD planning + Ralph execution – unified bằng CLI và slash commands
📋 Luôn plan trước, implement sau – đừng skip Phase 1-3 rồi nhảy thẳng vào Ralph
🔄 Phiên chat mới cho mỗi workflow – tránh context pollution
✅ Qua IR Gate trước khi transition – quality gate quan trọng nhất
⚡ Ralph fresh context per story – mỗi story = AI session mới qua driver (claude-code hoặc codex)
🔁 Incremental development – plan epic 1 → implement → plan epic 2 → implement
🛡️ Circuit breaker bảo vệ bạn – Ralph tự dừng khi stuck, không chạy vô hạn


Nguồn tham khảo: Tài liệu và README từ bmalph, BMAD-METHOD, và Ralph. Tham gia cộng đồng BMAD Discord để cập nhật thông tin mới nhất.
Platform	ID	Tier	Instructions file	Commands
Claude Code	`claude-code`	full	`CLAUDE.md`	`.claude/commands/` directory
OpenAI Codex	`codex`	full	`AGENTS.md`	Inline trong instructions file
Cursor	`cursor`	instructions-only	`.cursor/rules/bmad.mdc`	Không có
Windsurf	`windsurf`	instructions-only	`.windsurf/rules/bmad.md`	Không có
GitHub Copilot	`copilot`	instructions-only	`.github/copilot-instructions.md`	Không có
Aider	`aider`	instructions-only	`CONVENTIONS.md`	Không có
Tiêu chí	Vibe Coding	BMAD Method (đơn lẻ)	Ralph (đơn lẻ)	bmalph
Cách tiếp cận	Prompt → Code	Agent personas → Workflows → Artifacts	PRD → prd.json → Auto-loop	BMAD planning → Ralph execution
Planning	Không có	Rất chi tiết (PRD, Architecture, Stories)	Cơ bản (prd.json)	BMAD-level chi tiết
Execution	Thủ công / 1 shot	Thủ công (dev-story)	Autonomous loop	Autonomous loop (Ralph)
Chuyển đổi	N/A	N/A	Tự viết prd.json	Tự động (`bmalph implement` / `/bmalph-implement`)
Phù hợp với	Prototype nhanh	Dự án cần planning kỹ	Dự án đã có PRD	Dự án end-to-end
Concern	BMAD-METHOD	Ralph	bmalph
Phase	Planning & Design	Autonomous Execution	Cả hai + Transition
Output	PRD, Architecture, Stories	Working code, commits	End-to-end
Human involvement	Cao (guided elicitation)	Thấp (set-and-forget)	Cao ở planning, thấp ở execution
AI session model	1 conversation dài per workflow	Nhiều instance ngắn per story	Cả hai
Memory model	In-session context + docs	Git + progress.txt	Docs + Git + Specs Changelog
Mã lệnh	Slash Command	Mô tả
`BP`	`/analyst` → Brainstorm Project	Brainstorm ý tưởng sản phẩm có hướng dẫn
`MR`	Market Research	Phân tích thị trường, đối thủ, nhu cầu khách hàng
`DR`	Domain Research	Nghiên cứu chuyên sâu lĩnh vực ngành
`TR`	Technical Research	Khả thi kỹ thuật, lựa chọn kiến trúc
`CB`	Create Brief	Tạo Product Brief – tóm tắt ý tưởng sản phẩm
Mã lệnh	Slash Command	Mô tả
`CP`	`/create-prd`	Tạo Product Requirements Document (bắt buộc)
`VP`	`/validate-prd`	Kiểm tra PRD đã đầy đủ và nhất quán chưa
`EP`	Edit PRD	Cải thiện PRD hiện có
`CU`	`/ux-designer`	Thiết kế UX/wireframes
Mã lệnh	Slash Command	Mô tả
`CA`	`/create-architecture`	Thiết kế kiến trúc kỹ thuật (bắt buộc)
`CE`	`/create-epics-stories`	Tạo epics và stories (bắt buộc)
`IR`	Implementation Readiness	Kiểm tra sẵn sàng triển khai (bắt buộc)
Agent	Slash Command	Phase	Chức năng chính
Analyst	`/analyst`	1	Brainstorm, research thị trường/kỹ thuật/domain
Product Manager	`/pm`	2-3	Tạo PRD, chia epics/stories, quản lý scope
Architect	`/architect`	3	Thiết kế kiến trúc, ADR, tech stack decisions
Developer	`/dev`	4	Implement code, code review
QA (Quinn)	`/qa`	4	Test automation, quality assurance
UX Designer	`/ux-designer`	2	Wireframes, user flows, design system
Scrum Master	`/sm`	2-4	Sprint planning, retrospective
Tech Writer	`/tech-writer`	Any	Documentation, technical writing
Quick Flow Solo Dev	`/quick-flow-solo-dev`	Any	Quick spec + dev cho task nhỏ
Command	Mô tả
`/bmalph`	Master agent – xem phase hiện tại, navigate
`/bmad-help`	Trợ giúp nhận biết ngữ cảnh
`/bmalph-implement`	Chuyển đổi BMAD → Ralph
`/bmalph-status`	Trạng thái phase + Ralph progress
`/bmalph-upgrade`	Cập nhật bundled assets
`/bmalph-doctor`	Health check cho dự án
Phase	Command	Output
1	`/analyst`	Product Brief
2	`/create-prd`	PRD document
2	`/ux-designer`	UX Design
3	`/create-architecture`	Architecture document
3	`/create-epics-stories`	Epics & Stories
3	`/implementation-readiness`	Readiness gate report
3	`/validate-architecture`	Architecture validation
Code	Mô tả
`QS`	Quick Spec – spec nhanh cho task nhỏ
`QD`	Quick Dev – implement nhanh từ spec
`DP`	Document Project – phân tích codebase tạo docs
`GPC`	Generate Project Context – scan codebase tạo LLM context
`CC`	Correct Course – điều chỉnh hướng đi giữa chừng
`WD`	Write Document – tạo tài liệu kỹ thuật
`MG`	Mermaid Generate – tạo Mermaid diagrams
`BSP`	Brainstorming – interactive idea generation
`VD`	Validate Document – review tài liệu theo chuẩn
`ID`	Index Docs – tạo doc index cho LLM scan
`SD`	Shard Document – tách tài liệu lớn thành file nhỏ