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
• RAG Integration (opt-in): Retrieval-augmented generation layer enriches execution context with past spec data; optional install via /ralphharness:rag-onboard

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

Import from BMAD Planning Artifacts

If you've already created planning documents in BMAD, skip the research phase and import directly into a ralphharness spec:

/ralph-bmad:import <bmad-project-path> <spec-name>

Arguments:

• bmad-project-path (required): Path to BMAD project directory (must contain _bmad-output/)
• spec-name (required): Kebab-case name for the new spec

What Gets Generated:

• requirements.md — User stories extracted from PRD functional requirements
• design.md — Architecture decisions and technical decisions
• tasks.md — Story breakdown as executable Phase 1 tasks (ready for /ralphharness:implement)

Example:

# From project root with BMAD artifacts
/ralph-bmad:import . rag-integration

# From external BMAD project
/ralph-bmad:import ../bmad-projects/my-feature feature-name

The import command converts BMAD's structured planning (PRD, epics, architecture) into RalphHarness's executable format. No manual reformatting needed — specs are ready to execute immediately.

---

Commands