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:
- Generate
requirements.md and pause for approval
- After
/ralph-specum: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)
/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: