ralph-bmad-bridge

Ralph Specum

Spec-driven development with smart compaction. A Claude Code plugin that combines the Ralph Wiggum agentic loop with structured specification workflow.

Features

• Spec-Driven Workflow: Automatically generates requirements, design, and tasks from a goal description
• Smart Compaction: Strategic context management between phases and tasks
• Persistent Progress: Learnings and state survive compaction via progress file
• Two Modes: Interactive (pause per phase) or fully autonomous
• BMAD Bridge: Import BMAD planning artifacts (PRD, epics, architecture) into ralph-specum specs via /ralph-bmad:import
• Loop Safety: Pre-loop git checkpoint, circuit breaker, per-task metrics, and read-only detection
• Role Boundaries: Mechanical enforcement of file access rules per agent role

Installation

From Marketplace (Recommended)

# Add the marketplace
/plugin marketplace add tzachbon/ralph-specum

# Install the plugin
/plugin install ralph-specum@ralph-specum

# Restart Claude Code to load

From GitHub Repository

# Clone the repo
git clone https://github.com/tzachbon/ralph-specum.git

# Install from local path
/plugin install /path/to/ralph-specum

# Or install directly from GitHub
/plugin install https://github.com/tzachbon/ralph-specum

Local Development

# Clone and link for development
git clone https://github.com/tzachbon/ralph-specum.git
cd ralph-specum
/plugin install .

Packaged Distribution

When installed via the Codex-packaged distribution (ralph-specum-codex), commands are exposed with the ralph-specum- prefix:

$ralph-specum-triage "Build a multi-tenant SaaS platform"
$ralph-specum-research
$ralph-specum-requirements
$ralph-specum-design
$ralph-specum-tasks
$ralph-specum-implement
$ralph-specum-start my-feature "Build user authentication"
$ralph-specum-cancel
$ralph-specum-status
$ralph-specum-feedback
$ralph-specum-help
$ralph-specum-index
$ralph-specum-refactor
$ralph-specum-rollback
$ralph-specum-switch

See the Codex plugin README for full Codex-specific documentation.

Quick Start

Interactive Mode (Recommended)

/ralph-specum "Add user authentication with JWT tokens" --mode interactive --dir ./auth-spec

This will:

1. Generate requirements.md and pause for approval
2. After /ralph-specum:approve, generate design.md and pause
3. After approval, generate tasks.md and pause
4. After approval, execute all tasks (compacting after each)

Autonomous Mode

# The smart way (auto-detects resume or new)
/ralph-specum:start user-auth Add JWT authentication

# Quick mode (skip spec phases, auto-generate everything)
/ralph-specum:start "Add user auth" --quick

# The step-by-step way
/ralph-specum:new user-auth Add JWT authentication
/ralph-specum:requirements
/ralph-specum:design
/ralph-specum:tasks
/ralph-specum:implement

---

Commands

Command	Description
/ralph-specum "goal" [options]	Start the spec-driven loop
/ralph-specum:approve	Approve current phase (interactive mode)
/ralph-specum:cancel	Cancel active loop and cleanup
/ralph-specum:feedback	Collect and process user feedback
/ralph-specum:help	Show help
/ralph-specum:index	Index/rebuild spec directory
/ralph-specum:refactor	Refactor existing spec
/ralph-specum:rollback	Rollback to git checkpoint
/ralph-specum:switch	Switch to another spec

---

How It Works

flowchart TB
    subgraph Input
        G[Goal Description]
    end

    subgraph Spec["Specification Phases"]
        R[Requirements]
        D[Design]
        T[Tasks]
    end

    subgraph Exec["Execution Phase"]
        E1[Task 1]
        E2[Task 2]
        EN[Task N]
    end

    subgraph Output
        C[Complete]
    end

    G --> R
    R -->|compact| D
    D -->|compact| T
    T -->|compact| E1
    E1 -->|compact| E2
    E2 -->|compact| EN
    EN --> C

    R -.->|interactive| A1{Approve?}
    D -.->|interactive| A2{Approve?}
    T -.->|interactive| A3{Approve?}

    A1 -->|yes| D
    A2 -->|yes| T
    A3 -->|yes| E1

State Management

flowchart LR
    subgraph Files["Persistent State"]
        P[".ralph-progress.md<br/>Learnings & Progress"]
        S[".ralph-state.json<br/>Loop State"]
    end

    subgraph Compaction
        CM[Context Window<br/>Management]
    end

    P -->|survives| CM
    S -->|tracks| CM
    CM -->|preserves key context| P

Smart Compaction

Each phase transition uses targeted compaction:

Phase	Preserves
Requirements	User stories, acceptance criteria, FR/NFR, glossary
Design	Architecture, patterns, file paths
Tasks	Task list, dependencies, quality gates
Per-task	Current task context only

Progress File

The .ralph-progress.md file carries state across compactions: