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:
- Generate
requirements.md and pause for approval
- After
/ralphharness:approve, generate design.md and pause
- After approval, generate
tasks.md and pause
- 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