Smart Ralph is a Claude Code plugin that turns your vague feature ideas into structured specs, then executes them task-by-task. Like having a tiny product team in your terminal.
You: "Add user authentication"
Ralph: *creates research.md, requirements.md, design.md, tasks.md*
Ralph: *executes each task with fresh context*
Ralph: "I'm helping!"
Why "Ralph"?
Named after the Ralph agentic loop pattern and everyone's favorite Springfield student. Ralph doesn't overthink. Ralph just does the next task. Be like Ralph.
Installation
Claude Code
# Install Smart Ralph
/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph
# Restart Claude Code
The helper skill package also includes $ralph-specum-switch, $ralph-specum-cancel, $ralph-specum-index, $ralph-specum-refactor, $ralph-specum-feedback, and $ralph-specum-help.
Use $ralph-specum-triage first when the goal is large, cross-cutting, or likely to become multiple specs. Use $ralph-specum-start for a single spec or to resume an existing one.
Codex Ralph is approval-gated by default. After each spec artifact, Ralph stops and asks you to approve the current artifact, request changes, or continue to the next step. Quick or autonomous flow happens only when you explicitly ask for it.
Claude Code
# 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
For Codex, the equivalent surface is $ralph-specum plus 14 helper skills installed via the ralph-specum plugin.
| Command | What it does |
|---------|--------------|
| /ralph-specum:start [name] [goal] | Smart entry: resume existing or create new |
| /ralph-specum:start [goal] --quick | Quick mode: auto-generate all specs and execute |
| /ralph-specum:new <name> [goal] | Create new spec, start research |
| /ralph-specum:research | Run/re-run research phase |
| /ralph-specum:requirements | Generate requirements from research |
| /ralph-specum:design | Generate technical design |
| /ralph-specum:tasks | Break design into executable tasks |
| /ralph-specum:implement | Execute tasks one-by-one |
| /ralph-specum:index | Scan codebase and generate component specs |
| /ralph-specum:status | Show all specs and progress |
| /ralph-specum:switch <name> | Change active spec |
| /ralph-specum:triage [name] [goal] | Decompose large features into multiple specs (epics) |
| /ralph-specum:cancel | Cancel loop, cleanup state |
| /ralph-specum:help | Show help |
How It Works
flowchart TD
A["I want a feature!"] --> B{"/start detects scope"}
B -->|Single spec| C[Research]
B -->|"Too big for one spec"| T["/triage"]
C -->|Analyzes codebase, searches web| D[Requirements]
D -->|User stories, acceptance criteria| E[Design]
E -->|Architecture, patterns, decisions| F[Tasks]
F -->|POC-first task breakdown| G[Execution]
G -->|Task-by-task with fresh context| H["I did it!"]
T -->|Explore| T1[Exploration Research]
T1 -->|Brainstorm| T2[Triage Analyst]
T2 -->|Validate| T3[Validation Research]
T3 -->|Finalize| T4["Epic Plan"]
T4 -->|"Spec 1, Spec 2, ..."| C
Make It Work - POC validation, skip tests initially
Refactoring - Clean up the code
Testing - Unit, integration, e2e tests
Quality Gates - Lint, types, CI checks
Current Ralph planning also supports:
--tasks-size fine|coarse to control task granularity
approval checkpoints between spec phases outside quick mode
[P] markers for low-conflict parallel tasks
[VERIFY] and VE tasks for explicit verification work
epic planning through /ralph-specum:triage or $ralph-specum-triage
Codebase Indexing
Starting with v2.12.0, Smart Ralph can scan existing codebases and auto-generate component specs, making legacy code discoverable during new feature research.
Why Index?
When starting a new feature on an existing codebase, the research phase benefits from knowing what's already built. Without indexing, the research agent has limited visibility into your codebase structure.
The /ralph-specum:index command:
Scans your codebase for controllers, services, models, helpers, and migrations
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
