ralphharness

RalphHarness

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 ralphharness 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 informatico-madrid/ralphharness

# Install the plugin
/plugin install ralphharness@ralphharness

# Restart Claude Code to load

From GitHub Repository

# Clone the repo
git clone https://github.com/informatico-madrid/ralphharness.git

# Install from local path
/plugin install /path/to/ralphharness

# Or install directly from GitHub
/plugin install https://github.com/informatico-madrid/ralphharness

Local Development

# Clone and link for development
git clone https://github.com/informatico-madrid/ralphharness.git
cd ralphharness
/plugin install .

Packaged Distribution

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

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

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

Quick Start

Interactive Mode (Recommended)

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

This will:

1. Generate requirements.md and pause for approval
2. After /ralphharness: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)
/ralphharness:start user-auth Add JWT authentication

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

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

---

Commands

Command	Description
/ralphharness "goal" [options]	Start the spec-driven loop
/ralphharness:approve	Approve current phase (interactive mode)
/ralphharness:cancel	Cancel active loop and cleanup
/ralphharness:feedback	Collect and process user feedback
/ralphharness:help	Show help
/ralphharness:index	Index/rebuild spec directory
/ralphharness:refactor	Refactor existing spec
/ralphharness:rollback	Rollback to git checkpoint
/ralphharness: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]
        PR[Parallel Reviewer<br/>external-agent<br/>task_review.md + chat.md]
    end

    subgraph Output
        C[Complete]
    end

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

    subgraph Review["Parallel Review (real-time)"]
        PR -.->|writes to| chat.md[task_review.md]
        PR -.->|reviews each task| E1
        PR -.->|reviews each task| E2
        PR -.->|reviews each task| EN
    end

    EN --> C
    PR -.->|blocks on FAIL| E1

    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