BeMadRalphy

Be(ads) + (B)Mad + Ralphy + OpenSpec — four tools, one pipeline, zero gaps. CLI-only.

End-to-end automated coding: idea in → planning → task graph → swarm-aware execution → living specs → deployment.

Status

BeMadRalphy runs end-to-end locally with real external CLI integrations.

Current implementation includes:

• idea.md/plan.md intake with .bemadralphy/intake.yaml output
• BMAD bootstrap (bmad install) and generated planning artifacts under _bmad-output/
• Steering file generation (AGENTS.md, CLAUDE.md, Cursor/Windsurf/Cline/Kiro rules)
• tasks.md generation plus Beads sync (bd init, bd create, bd ready, bd close, bd update)
• Per-phase state persistence in .bemadralphy/state.yaml
• Engine execution through explicit CLI contracts for all supported engines
• OpenSpec lifecycle integration (openspec init, openspec validate, openspec archive)

Start Here

• First local run guide: docs/getting-started.md
• Contributor/developer setup: docs/onboarding.md
• Architecture and flow details: docs/architecture.md

What is BeMadRalphy?

BeMadRalphy is a CLI orchestrator that merges:

• BMAD-METHOD — Agile AI-driven planning (product briefs, PRDs, architecture, epics & stories)
• Beads — Git-backed graph issue tracker and persistent AI memory
• Ralphy — Autonomous AI coding loop with multi-engine support (site)
• OpenSpec — Living specifications and delta-based change tracking

Into a single, seamless pipeline that takes you from a rough idea to a deployed, documented, and tested codebase — with minimal human intervention.

The 9-Phase Pipeline

flowchart TD
  subgraph explore [Phase 0: Explore]
    ExploreCmd[bemadralphy explore]
    ExploreReport[Exploration report]
  end
  subgraph intake [Phase 1: Idea Intake]
    IdeaMD[idea.md]
    DetectMode{Greenfield or brownfield?}
    IntakeYAML[intake.yaml]
  end
  subgraph planning [Phase 2: Planning]
    Brief[Product brief]
    PRD[PRD]
    Arch[Architecture]
    Stories[Epics and stories]
  end
  subgraph steer [Phase 3: Agent Steering]
    AllFiles[14+ steering files]
  end
  subgraph scaffold [Phase 4: Scaffolding]
    GitInit[git init + monorepo]
    PkgJson[package.json]
  end
  subgraph tasks [Phase 5: Task Sync]
    Beads[(Beads graph)]
    TasksMD[tasks.md]
  end
  subgraph exec [Phase 6: Execution]
    Detect{Swarm capable?}
    NativeSwarm[Native swarm]
    ProcessParallel[Process parallel]
  end
  subgraph verify [Phase 7: Verification]
    Completeness[Completeness]
    Correctness[Correctness]
    Coherence[Coherence]
  end
  subgraph post [Phase 8: Post-Execution]
    CodeReview[Code review]
    Docs[Documentation]
    Deploy[Deployment]
  end
  ExploreCmd --> ExploreReport --> IdeaMD
  IdeaMD --> DetectMode --> IntakeYAML
  IntakeYAML --> Brief --> PRD --> Arch --> Stories
  Stories --> AllFiles --> GitInit --> PkgJson
  PkgJson --> Beads --> TasksMD
  TasksMD --> Detect
  Detect -->|yes| NativeSwarm
  Detect -->|no| ProcessParallel
  NativeSwarm --> Completeness
  ProcessParallel --> Completeness
  Completeness --> Correctness --> Coherence
  Coherence --> CodeReview --> Docs --> Deploy

AI Engine Support

• claude (native swarm): ralphy --claude --max-iterations 1 <task>
• kimi (native swarm): kimi <task>
• codex (native swarm): ralphy --codex --max-iterations 1 <task>
• cursor: ralphy --cursor --max-iterations 1 <task>
• opencode: ralphy --opencode --max-iterations 1 <task>
• qwen: ralphy --qwen --max-iterations 1 <task>
• copilot: ralphy --copilot --max-iterations 1 <task>
• gemini: gemini <task>
• ralphy: ralphy --max-iterations 1 <task>

Autonomy Modes

CLI Commands

# Initialize a new project
npx bemadralphy init

# Notes:
# - Creates .bemadralphy/, openspec/, and _bmad-output/
# - Initializes `bd` and `openspec`
# - Fails fast if required CLIs are missing

# Run the full pipeline
npx bemadralphy run

# Run with specific options
npx bemadralphy run --mode auto --engine claude --max-parallel 5 --budget 50

# Explore before planning (optional)
npx bemadralphy explore "How should I structure authentication?"

# Check pipeline status
npx bemadralphy status

The idea.md File

BeMadRalphy starts with an idea.md file in your project root. It can be as simple or detailed as you want. The current scaffolding writes intake results to .bemadralphy/intake.yaml.

Minimal example

I want to build a SaaS dashboard for tracking fitness goals.

Detailed example with YAML front-matter

---
project_type: full-stack
stack:
  frontend: Next.js
  backend: Hono
  language: TypeScript
runtime: bun
monorepo: true
database: Postgres
auth: Clerk
tests: Vitest
deployment: Vercel
---

A SaaS dashboard for tracking fitness goals. Users can log workouts,
track progress over time, set goals, and get AI-powered recommendations.

Key features:
- User authentication with social login
- Workout logging with exercise library
- Progress charts and analytics
- Goal setting and tracking
- AI coach for personalized recommendations

BeMadRalphy extracts what you've already decided and only asks about the rest.

Greenfield vs Brownfield

Brownfield is auto-detected (looks for package.json, src/, etc.) or forced with --brownfield.

Living Specs (OpenSpec-compatible)

After the initial build, BeMadRalphy generates living specifications in openspec/specs/:

openspec/
├── specs/
│   ├── auth/spec.md
│   ├── workouts/spec.md
│   └── goals/spec.md
├── changes/
│   └── archive/

For subsequent brownfield changes, new requirements are expressed as delta specs (ADDED/MODIFIED/REMOVED) against the current specs. On completion, deltas merge into the main specs.

Target Project Structure (after scaffolding)

your-project/
├── .bemadralphy/          # State, cost log, failures log, intake.yaml
│   ├── state.yaml
│   ├── cost.log
│   └── failures.log
├── .beads/                # Beads task graph
│   └── issues.jsonl
├── _bmad/                 # BMAD playbooks (read-only)
├── _bmad-output/          # Planning artifacts
│   ├── product-brief.md
│   ├── prd.md
│   ├── architecture.md
│   └── stories/
├── openspec/              # Living specs
│   └── specs/
├── docs/
│   ├── adr/               # Architecture Decision Records
│   ├── onboarding.md
│   └── runbook.md
├── src/                   # Your application code
├── tests/
├── .github/
│   ├── workflows/
│   ├── ISSUE_TEMPLATE/
│   └── pull_request_template.md
├── AGENTS.md              # Universal agent steering
├── CLAUDE.md              # Claude-specific steering
├── .cursorrules           # Cursor-specific steering
├── idea.md                # Your original idea
├── .bemadralphy/intake.yaml  # Processed intake
├── tasks.md               # Human-readable task list
├── package.json
└── README.md

Configuration (planned)

.bemadralphy/state.yaml

Tracks pipeline state for resumability:

phase: execution
mode: hybrid
engine: claude
last_gate: architecture
tasks_completed: 12
tasks_total: 24
cost_usd: 3.47

Flags

Installation

Quick Install (Recommended)

# npm
npm install -g bemadralphy

# pnpm
pnpm add -g bemadralphy

# bun
bun add -g bemadralphy

# yarn
yarn global add bemadralphy

# or use the install script
curl -fsSL https://raw.githubusercontent.com/hxp-pxh/BeMadRalphy/main/install.sh | bash

Docker

# Pull from GitHub Container Registry
docker pull ghcr.io/hxp-pxh/bemadralphy:latest

# Run
docker run -v $(pwd):/workspace ghcr.io/hxp-pxh/bemadralphy init

For detailed first-run setup, see docs/getting-started.md.

Install required external CLIs

# Ralphy
sudo npm install -g ralphy-cli

# BMAD
sudo npm install -g bmad-method

# Beads
sudo npm install -g @beads/bd

# OpenSpec
sudo npm install -g @fission-ai/openspec

Verify:

ralphy --version
bmad --version
bd --version
openspec --version

Install BeMadRalphy dependencies

npm install
npm run build
node dist/cli.js --help

Prerequisites

• Node.js 18+ or Bun 1.0+
• Git
• Ralphy CLI (ralphy) for execution fallback and parallel orchestration
• BMAD CLI (bmad)
• Beads CLI (bd)
• OpenSpec CLI (openspec)

Fail-Fast Behavior

init and run are strict by design for local-product reliability:

• Missing required CLIs fail immediately with actionable errors.
• Planning fails if BMAD command fails or required artifacts are missing.
• Sync fails if stories cannot be parsed or Beads writes fail.
• Execute fails for unknown/unavailable engines.
• Verify/Post fail if OpenSpec commands fail.

Typical recovery flow:

# 1) Verify toolchain
ralphy --version && bmad --version && bd --version && openspec --version

# 2) Re-run setup and checks
npm install
npm run verify
node dist/cli.js init

# 3) Run pipeline
node dist/cli.js run --mode auto --engine ralphy

Quick Start

# 1. Create a new directory
mkdir my-awesome-app && cd my-awesome-app

# 2. Initialize BeMadRalphy
npx bemadralphy init

# 3. Write your idea
echo "A todo app with real-time sync and offline support" > idea.md

# 4. Run the pipeline
npx bemadralphy run

For full expected outputs and fail-fast troubleshooting, see docs/getting-started.md.

That's it. BeMadRalphy will:

1. Ask clarifying questions about your stack preferences
2. Generate a full PRD and architecture
3. Create all the steering files for your AI agents
4. Scaffold the project
5. Execute all tasks with tests
6. Verify the implementation
7. Generate documentation and deploy

Contributing

See CONTRIBUTING.md for guidelines on:

• Fork/clone workflow
• Branch naming conventions
• Commit message format
• PR process
• Code standards

License

MIT — Copyright (c) 2026 hxp-pxh

Acknowledgments

BeMadRalphy builds on the shoulders of giants:

• BMAD-METHOD — The planning framework
• Beads — The task graph and memory layer
• Ralphy — The execution loop inspiration (site)
• OpenSpec — The living spec model