Spec-driven development for Claude Code and Codex.
Smart Ralph turns a feature request into a structured spec, then executes it one task at a time with fresh context. The execution loop is self-contained and has no external plugin dependencies.
How it works | Installation | Quick start | Commands | Troubleshooting
Smart Ralph creates research, requirements, design, and task files before implementation. Large goals can start with triage, which splits the work into dependency-aware specs.
The spec files stay in the project, so you can review or edit each phase before execution. Smart Ralph records progress between tasks and can resume after a stopped session.
An optional prototype can test one focused design question without turning disposable source into production code.
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
/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralphRestart Claude Code after installation.
codex plugin marketplace add tzachbon/smart-ralph \
--sparse .agents/plugins \
--sparse plugins/ralph-specum-codex
codex plugin add ralph-specum@smart-ralphStart a new Codex task after installation. Run /hooks, review the bundled Stop hook, and trust it if you want automatic task execution. Until then, run $ralph-specum-implement once per task.
The Codex installation guide covers updates, local development with codex plugin marketplace add ., and migration from the old platforms/codex/ skills.
For local Claude Code development, clone this repository and run claude --plugin-dir ./plugins/ralph-specum.
$ralph-specum-start user-auth "Add JWT authentication"
Use $ralph-specum when you want Smart Ralph to choose the next action. Codex asks for approval after each spec artifact unless the command includes the exact --quick flag. Start with $ralph-specum-triage when a goal spans several features or systems.
/ralph-specum:start user-auth "Add JWT authentication"Add --quick to generate the spec and start execution without stopping between phases. Run /ralph-specum:start without arguments to resume the active spec.
Claude Code uses /ralph-specum:<name>. Codex uses $ralph-specum-<name> and folds new into $ralph-specum-start.
| Command | What it does |
|---|---|
/ralph-specum:start [name] [goal] |
Resume a spec or create one |
/ralph-specum:start [goal] --quick |
Generate all spec phases and execute |
/ralph-specum:new <name> [goal] |
Create a spec and wait for approval before research |
/ralph-specum:triage [name] [goal] |
Split a large goal into an epic |
/ralph-specum:research |
Run or repeat research |
/ralph-specum:requirements |
Generate requirements from research |
/ralph-specum:prototype |
Run or resume an optional prototype |
/ralph-specum:design |
Generate the technical design |
/ralph-specum:tasks |
Break the design into executable tasks |
/ralph-specum:implement |
Execute tasks one at a time |
/ralph-specum:index |
Generate searchable codebase specs |
/ralph-specum:refactor |
Update requirements, design, or tasks |
/ralph-specum:status |
Show specs and progress |
/ralph-specum:switch <name> |
Change the active spec |
/ralph-specum:cancel |
Cancel execution and remove loop state |
/ralph-specum:feedback [message] |
Submit feedback or report an issue |
/ralph-specum:help |
Show command and workflow help |
Smart Ralph gives each phase to a focused agent.
| Phase | Agent | Responsibility |
|---|---|---|
| Triage | triage-analyst |
Split features and map dependencies |
| Research | research-analyst |
Inspect the codebase and check feasibility |
| Requirements | product-manager |
Write user stories and acceptance criteria |
| Prototype | prototype-builder |
Test one design question with disposable evidence |
| Design | architect-reviewer |
Define architecture and trade-offs |
| Tasks | task-planner |
Create a POC-first task sequence |
| Execution | spec-executor |
Implement tasks and run quality gates |
Tasks follow four phases:
- Make it work: validate the approach with a POC.
- Refactoring: clean up the working implementation.
- Testing: add unit, integration, and end-to-end coverage.
- Quality gates: run lint, type, and CI checks.
Planning controls include:
--tasks-size fine|coarsefor task granularity[P]for low-conflict parallel tasks[VERIFY]and VE tasks for explicit verification- approval checkpoints between spec phases outside quick mode
- In normal mode, Smart Ralph may suggest a prototype after research or requirements. You can also run
/ralph-specum:prototypeor$ralph-specum-prototypeat a safe phase boundary. - In quick mode, Smart Ralph asks no prototype questions, owns the decisions, and always continues to design after the prototype outcome.
- Prototype source stays in a sibling worktree or eligible scratch directory. Quick mode transfers no source into the current checkout; normal mode transfers only paths you approve.
- Reviewed terminal records are immutable. Local evidence does not authorize a push, remote branch, PR update, issue write, or record deletion.
Smart Ralph stores progress in .progress.md and marks completed work in tasks.md. Each implementation task starts with fresh context.
/ralph-specum:index scans an existing project and writes searchable component specs under specs/.index/. Research agents use that index to find code that the project already has.
/ralph-specum:index
/ralph-specum:index --quick
/ralph-specum:index --dry-run
/ralph-specum:index --path=src/api/| Option | Effect |
|---|---|
--path=<dir> |
Scan one directory |
--type=<types> |
Limit component types |
--exclude=<patterns> |
Skip matching paths |
--dry-run |
Preview without writing specs |
--force |
Regenerate the index |
--changed |
Regenerate Git-changed files |
--quick |
Skip the pre-scan and post-scan interviews |
The scanner detects controllers, services, models, helpers, and migrations. It can also record external URLs, MCP servers, and installed skills. Run the index before starting a feature in a codebase that Smart Ralph has not seen.
The generated index has a summary dashboard, component specs, and external resource specs. Research searches both feature specs and indexed specs when it gathers context.
Plugin source lives in plugins/ralph-specum/ for Claude Code, plugins/ralph-specum-codex/ for Codex, and plugins/ralph-speckit/ for the Spec-Kit workflow.
Smart Ralph writes feature specs inside the project where you run it:
specs/
|-- .current-spec
`-- my-feature/
|-- .ralph-state.json
|-- .progress.md
|-- prototypes/
| `-- <id>.md
|-- research.md
|-- requirements.md
|-- design.md
`-- tasks.md
Smart Ralph deletes .ralph-state.json when execution finishes. It keeps .progress.md so later tasks can recover decisions and learnings.
Epic plans live under specs/_epics/<name>/. Their state files track which specs are ready, blocked, or complete.
ralph-speckit is the alternative plugin for GitHub's Spec-Kit methodology. It adds a project constitution and requirement-to-task traceability.
| Feature | ralph-specum | ralph-speckit |
|---|---|---|
| Directory | specs/ |
.specify/specs/ |
| Naming | my-feature/ |
001-feature-name/ |
| Governance | Per-spec workflow | Project constitution |
| Main files | Research, requirements, design, tasks | Spec, plan, tasks |
| Best fit | Fast iteration | Team governance and audit trails |
/plugin install ralph-speckit@smart-ralph
/speckit:constitution
/speckit:start user-auth "Add JWT authentication"
/speckit:specify
/speckit:plan
/speckit:tasks
/speckit:implementThe plugin also includes /speckit:status, /speckit:switch, /speckit:cancel, /speckit:clarify, and /speckit:analyze. See the Ralph Speckit guide for its file layout and command details.
- Repeated task failure: read
.progress.md, fix the reported problem, then run/ralph-specum:implement. - Start over: run
/ralph-specum:cancel, then start a new spec. - Resume work: run
/ralph-specum:start. Ralph finds the active spec.
See the Troubleshooting Guide for installation, state, hook, and recovery problems.
Smart Ralph v3.0.0 moved execution into the plugin's Stop hook. Projects that used v2.x no longer need the separate Ralph Loop plugin.
Update Smart Ralph, restart Claude Code, and resume. Existing spec files need no migration. You can uninstall Ralph Loop if no other workflow uses it. Check GitHub releases for later changes.
PRs are welcome. Read CONTRIBUTING.md for setup, tests, and pull request guidance.
Smart Ralph takes its name from the Ralph agentic loop pattern and Springfield's most determined student. Ralph does the next task. Be like Ralph.
- Built for Claude Code and OpenAI Codex
- Inspired by developers who wanted their coding agent to handle 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."
