Spec-driven development for Claude Code. Task-by-task execution with fresh context per task.
Self-contained execution loop. No external dependencies.
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.
# Install Smart Ralph
/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph
# Restart Claude CodeTroubleshooting & alternative methods
Install from GitHub directly:
/plugin install https://github.com/tzachbon/smart-ralphLocal development:
git clone https://github.com/tzachbon/smart-ralph.git
claude --plugin-dir ./smart-ralph/plugins/ralph-specum# 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:index |
Scan codebase and generate component specs |
/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
Starting with v2.12.0, Smart Ralph can scan existing codebases and auto-generate component specs, making legacy code discoverable during new feature research.
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
# Full interactive indexing (recommended for first-time)
/ralph-specum:index
# Quick mode - skip interviews, batch scan only
/ralph-specum:index --quick
# Dry run - preview what would be indexed
/ralph-specum:index --dry-run
# Index specific directory
/ralph-specum:index --path=src/api/
# Force regenerate all specs
/ralph-specum:index --force /ralph-specum:index
|
v
+---------------------+
| Pre-Scan Interview | <- External URLs? Focus areas? Sparse areas?
+---------------------+
|
v
+---------------------+
| Component Scanner | <- Detects controllers, services, models...
+---------------------+
|
v
+---------------------+
| External Resources | <- Fetches URLs, queries MCP, introspects skills
+---------------------+
|
v
+---------------------+
| Post-Scan Review | <- Validates findings with user
+---------------------+
|
v
specs/.index/
├── index.md # Summary dashboard
├── components/ # Code component specs
└── external/ # External resource specs
| Option | Description |
|---|---|
--path=<dir> |
Limit indexing to specific directory |
--type=<types> |
Filter by type: controllers, services, models, helpers, migrations |
--exclude=<patterns> |
Patterns to exclude (e.g., test, mock) |
--dry-run |
Preview without writing files |
--force |
Regenerate all specs (overwrites existing) |
--changed |
Regenerate only git-changed files |
--quick |
Skip interviews, batch scan only |
For best results, run /ralph-specum:index before starting new features on an existing codebase.
The research phase searches indexed specs to discover relevant existing components. Without an index, you may miss important context about what's already built.
# First time on a codebase? Index it first
/ralph-specum:index
# Then start your feature
/ralph-specum:start my-feature Add user authenticationWhen you run /ralph-specum:start:
- If no index exists, you'll see a hint suggesting to run
/ralph-specum:index - The spec scanner searches both regular specs AND indexed specs
- Indexed components appear in "Related Specs" during research
Components (detected by path/name patterns):
- Controllers:
**/controllers/**/*.{ts,js,py,go} - Services:
**/services/**/*.{ts,js,py,go} - Models:
**/models/**/*.{ts,js,py,go} - Helpers:
**/helpers/**/*.{ts,js,py,go} - Migrations:
**/migrations/**/*.{ts,js,sql}
External Resources (discovered via interview):
- URLs (fetched via WebFetch)
- MCP servers (queried for tools/resources)
- Installed skills (commands/agents documented)
Default Excludes:
node_modules, vendor, dist, build, .git, __pycache__, test files
smart-ralph/
├── .claude-plugin/
│ └── marketplace.json
├── plugins/
│ ├── ralph-specum/ # Spec workflow (self-contained)
│ │ ├── .claude-plugin/
│ │ │ └── plugin.json
│ │ ├── agents/ # Sub-agent definitions
│ │ ├── commands/ # Slash commands
│ │ ├── hooks/ # Stop watcher (controls execution loop)
│ │ ├── 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 |
/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
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 files. Then start fresh.
Resume existing spec?
Just /ralph-specum:start - it auto-detects and continues where you left off.
More issues? See the full Troubleshooting Guide.
Self-contained execution loop (no more ralph-loop dependency)
Starting with v3.0.0, Smart Ralph is fully self-contained. The execution loop is handled by the built-in stop-hook.
Migration from v2.x:
- Update Smart Ralph to v3.0.0+
- Restart Claude Code
- Existing specs continue working. No spec file changes needed.
- You can optionally uninstall ralph-loop if you don't use it elsewhere
What changed:
- Ralph Loop dependency removed
- Stop-hook now controls the execution loop directly
/implementruns the loop internally (no external invocation)/cancelonly cleans up Smart Ralph state files
Why:
- Simpler installation (one plugin instead of two)
- No version compatibility issues between plugins
- Self-contained workflow
Ralph Loop dependency required (superseded by v3.0.0)
v2.0.0 delegated task execution to the Ralph Loop plugin. This is no longer required as of v3.0.0.
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
