Smart Ralph
"Me fail specs? That's unpossible!"
Spec-driven development for Claude Code and Codex. Task-by-task execution with fresh context per task.
Self-contained execution loop. No external dependencies.
Quick Start | Commands | How It Works | Troubleshooting
What is this?
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
Codex
Prerequisite: Install the Codex CLI first:
npm install -g @openai/codex
Run these commands from any directory. They clone the repo to a temp folder, copy the plugin to your Codex plugins directory, and clean up.
# 1. Clone the Smart Ralph repo
git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
# 2. Copy the Codex plugin into your personal plugins directory
mkdir -p ~/.codex/plugins
cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/ralph-specum-codex
# 3. Create a marketplace entry so Codex can discover the plugin
mkdir -p ~/.agents/plugins
cat > ~/.agents/plugins/marketplace.json << 'EOF'
{
"name": "smart-ralph",
"plugins": [{
"name": "ralph-specum",
"source": {"source": "local", "path": "~/.codex/plugins/ralph-specum-codex"},
"policy": {"installation": "AVAILABLE"},
"category": "Productivity"
}]
}
EOF
# 4. Clean up
rm -rf /tmp/smart-ralph
Run these commands from your project root directory (the repo where you want to use Ralph).
# 1. Clone the Smart Ralph repo
git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
# 2. Copy the Codex plugin into your project
mkdir -p ./plugins
cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ./plugins/ralph-specum-codex
# 3. Create a marketplace entry in your project
mkdir -p ./.agents/plugins
cat > ./.agents/plugins/marketplace.json << 'EOF'
{
"name": "smart-ralph",
"plugins": [{
"name": "ralph-specum",
"source": {"source": "local", "path": "./plugins/ralph-specum-codex"},
"policy": {"installation": "AVAILABLE"},
"category": "Productivity"
}]
}
EOF
# 4. Clean up
rm -rf /tmp/smart-ralph
After either method: restart Codex, open the plugin directory, and install ralph-specum.
Optional: Enable the Stop hook for automatic task execution:
# ~/.codex/config.toml
[features]
codex_hooks = true
See plugins/ralph-specum-codex/README.md for full details.
Updating (run from any directory):
rm -rf /tmp/smart-ralph
git clone https://github.com/tzachbon/smart-ralph.git /tmp/smart-ralph
cp -R /tmp/smart-ralph/plugins/ralph-specum-codex ~/.codex/plugins/ralph-specum-codex
rm -rf /tmp/smart-ralph
# Restart Codex
For per-project installs, replace ~/.codex/plugins/ralph-specum-codex with ./plugins/ralph-specum-codex (run from your project root).
- Remove old skills:
rm -rf ~/.codex/skills/ralph-specum* - Follow the install steps above
See the migration guide for details.
Install from GitHub directly:
/plugin install https://github.com/tzachbon/smart-ralph
Local development:
git clone https://github.com/tzachbon/smart-ralph.git
claude --plugin-dir ./smart-ralph/plugins/ralph-specum
Quick Start
Codex
Use $ralph-specum as the default Codex surface. Helper skills mirror the explicit phase entrypoints:
$ralph-specum
$ralph-specum-start
$ralph-specum-triage
$ralph-specum-research
$ralph-specum-requirements
$ralph-specum-design
$ralph-specum-tasks
$ralph-specum-implement
$ralph-specum-status
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
The Agents
Each phase uses a specialized sub-agent:
| Phase | Agent | Superpower |
|-------|-------|------------|
| Triage | triage-analyst | Feature decomposition, dependency graphs, interface contracts |
| Research | research-analyst | Web search, codebase analysis, feasibility checks |
| Requirements | product-manager | User stories, acceptance criteria, business value |
| Design | architect-reviewer | Architecture patterns, technical trade-offs |
| Tasks | task-planner | POC-first breakdown, task sequencing |
| Execution | spec-executor | Autonomous implementation, quality gates |
Task Execution Workflow
Tasks follow a 4-phase structure:
- 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|coarseto 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:triageor$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
- Generates searchable specs for each component
- Indexes external resources (URLs, MCP servers, installed skills)
- Makes existing code discoverable in
/ralph-specum:start
Quick Start
# Full interactive indexing (recommended for first-time)
/ralph-specum:index
# Quick mode - skip interviews, batch scan on