Spec-driven development for Claude Code. Task-by-task execution with fresh context per task.
Ralph Loop + Spec-Driven Development = <3
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!"
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.
v2.0.0+ requires the Ralph Loop plugin for task execution:
/plugin install ralph-loop@claude-plugins-officialNote: The plugin is named ralph-loop (implementing the Ralph Wiggum technique). Some documentation may reference ralph-wiggum - both refer to the same plugin, use ralph-loop.
Ralph Loop provides the execution loop. Smart Ralph provides the spec-driven workflow on top.
First, ensure you have the Ralph Loop plugin installed:
/plugin install ralph-loop@claude-plugins-officialTroubleshooting: If you get a "marketplace not found" error:
# Add the official marketplace (if not already added)
/plugin marketplace add anthropics/claude-code
# Then install Ralph Loop
/plugin install ralph-loop@claude-plugins-official# Add the marketplace
/plugin marketplace add tzachbon/smart-ralph
# Install the plugin
/plugin install ralph-specum@smart-ralph
# Restart Claude Code/plugin install https://github.com/tzachbon/smart-ralphgit clone https://github.com/tzachbon/smart-ralph.git
cd smart-ralph/plugins/ralph-specum
claude --plugin-dir $(pwd)# 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| 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:status |
Show all specs and progress |
/ralph-specum:switch <name> |
Change active spec |
/ralph-specum:cancel |
Cancel loop, cleanup state |
/ralph-specum:help |
Show help |
"I want a feature!"
|
v
+---------------------+
| Research | <- Analyzes codebase, searches web
+---------------------+
|
v
+---------------------+
| Requirements | <- User stories, acceptance criteria
+---------------------+
|
v
+---------------------+
| Design | <- Architecture, patterns, decisions
+---------------------+
|
v
+---------------------+
| Tasks | <- POC-first task breakdown
+---------------------+
|
v
+---------------------+
| Execution | <- Task-by-task with fresh context
+---------------------+
|
v
"I did it!"
Each phase uses a specialized sub-agent:
| Phase | Agent | Superpower |
|---|---|---|
| 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 |
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
smart-ralph/
├── .claude-plugin/
│ └── marketplace.json
├── plugins/
│ ├── ralph-specum/ # Original spec workflow
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── agents/ # Sub-agent definitions
│ │ ├── commands/ # Slash commands
│ │ ├── hooks/ # Stop watcher (logging only)
│ │ ├── templates/ # Spec templates
│ │ └── schemas/ # Validation schemas
│ └── ralph-speckit/ # Spec-kit methodology
│ ├── .claude-plugin/
│ │ └── plugin.json
│ ├── agents/ # spec-executor, qa-engineer
│ ├── commands/ # /speckit:* commands
│ └── templates/ # Constitution, spec, plan templates
└── README.md
Specs live in ./specs/ in your project:
./specs/
├── .current-spec # Active spec name
└── my-feature/
├── .ralph-state.json # Loop state (deleted on completion)
├── .progress.md # Progress tracking
├── research.md
├── requirements.md
├── design.md
└── tasks.md
ralph-speckit is an alternative plugin implementing GitHub's spec-kit methodology with constitution-first governance.
| Feature | ralph-specum | ralph-speckit |
|---|---|---|
| Directory | ./specs/ |
.specify/specs/ |
| Naming | my-feature/ |
001-feature-name/ |
| Constitution | None | .specify/memory/constitution.md |
| Spec structure | research, requirements, design, tasks | spec (WHAT/WHY), plan (HOW), tasks |
| Traceability | Basic | Full FR/AC annotations |
# Install Ralph Loop dependency first
/plugin install ralph-loop@claude-plugins-official
# Install ralph-speckit
/plugin install ralph-speckit@smart-ralph# Initialize constitution (first time only)
/speckit:constitution
# Create and develop a feature
/speckit:start user-auth "Add JWT authentication"
/speckit:specify
/speckit:plan
/speckit:tasks
/speckit:implement| Command | What it does |
|---|---|
/speckit:constitution |
Create/update project constitution |
/speckit:start <name> [goal] |
Create new feature with auto ID |
/speckit:specify |
Define feature spec (WHAT/WHY) |
/speckit:plan [tech] |
Create technical plan with research |
/speckit:tasks |
Generate task breakdown by user story |
/speckit:implement |
Execute tasks task-by-task |
/speckit:status |
Show current feature status |
/speckit:switch <name> |
Switch active feature |
/speckit:cancel |
Cancel execution loop |
/speckit:clarify |
Optional: clarify ambiguous requirements |
/speckit:analyze |
Optional: check spec consistency |
.specify/
├── memory/
│ └── constitution.md # Project-level principles
├── .current-feature # Active feature pointer
└── specs/
├── 001-user-auth/
│ ├── .speckit-state.json
│ ├── .progress.md
│ ├── spec.md # Requirements (WHAT/WHY)
│ ├── research.md
│ ├── plan.md # Technical design (HOW)
│ └── tasks.md
└── 002-payment-flow/
└── ...
- ralph-specum: Quick iterations, personal projects, simple features
- ralph-speckit: Enterprise projects, team collaboration, audit trails needed
"Ralph Loop plugin not found"?
Install the dependency: /plugin install ralph-loop@claude-plugins-official
If still not found, add the official marketplace first:
/plugin marketplace add anthropics/claude-code
/plugin install ralph-loop@claude-plugins-official"stop-handler.sh: No such file or directory"? Old v1.x installation conflict. Reinstall the plugin or see TROUBLESHOOTING.md.
Task keeps failing?
After max iterations, the loop stops. Check .progress.md for errors. Fix manually, then /ralph-specum:implement to resume.
Want to start over?
/ralph-specum:cancel cleans up state (both Ralph Loop and Smart Ralph state files). Then start fresh.
Resume existing spec?
Just /ralph-specum:start - it auto-detects and continues where you left off.
"Loop state conflict"?
Another Ralph loop may be running. Use /cancel-ralph to reset Ralph Loop state, then retry.
More issues? See the full Troubleshooting Guide.
Ralph Loop dependency required
Starting with v2.0.0, Smart Ralph delegates task execution to the official Ralph Loop plugin.
Migration from v1.x: See MIGRATION.md for detailed guide.
Quick version:
- Install Ralph Loop:
/plugin install ralph-loop@claude-plugins-official - Restart Claude Code
- Existing specs continue working. No spec file changes needed.
What changed:
- Custom stop-handler removed. Ralph Loop provides the execution loop.
/implementnow invokes/ralph-loopinternally/cancelnow calls/cancel-ralphfor cleanup- Same task format, same verification, same workflow. Just different internals.
Why:
- Less code to maintain (deleted ~300 lines of bash)
- Official plugin gets updates and fixes
- Better reliability for the execution loop
PRs welcome! This project is friendly to first-time contributors.
- Fork it
- Create your feature branch (
git checkout -b feature/amazing) - Commit your changes
- Push to the branch
- Open a PR
- Ralph agentic loop pattern by Geoffrey Huntley
- Built for Claude Code
- Inspired by every developer who wished their AI could just figure out the whole feature
Made with confusion and determination
"The doctor said I wouldn't have so many nosebleeds if I kept my finger outta there."
MIT License
