Smart Ralph: spec-driven development for Claude Code and Codex

The problem Smart Ralph solves: a feature request that arrives as one sentence

A single prompt such as "Add JWT authentication" hides a research step, a set of acceptance criteria, an architecture decision and a task breakdown. Smart Ralph's answer is to make all four artifacts explicit files in the project before implementation starts. The README describes the sequence as research, requirements, design and tasks, with an optional triage stage in front for goals that are too large for one spec. The target user is someone already working inside Claude Code or Codex who wants to review or edit each phase rather than accept whatever the model produces in one pass. The spec files stay in the repository, which is the point: they are diffable, reviewable and editable between phases. This is a workflow tool, not a code generator with a nicer prompt.

How the spec pipeline and the execution loop fit together

The README's flowchart shows /start detecting scope. A single spec goes straight into research; a goal that is too big goes through /triage first, which runs exploration research, a triage analyst, validation research and a final epic plan, then emits Spec 1, Spec 2 and so on back into the normal pipeline. Each phase is handled by a named agent: triage-analyst, research-analyst, product-manager, prototype-builder, architect-reviewer, task-planner and spec-executor. Execution is where the Ralph Wiggum loop lives. Tasks follow four phases in order: make it work with a POC, refactor, add unit, integration and end-to-end tests, then run lint, type and CI quality gates. Progress is stored in .progress.md and completed work is marked in tasks.md, so a stopped session can resume. Each implementation task starts with fresh context, which is the compaction idea: the loop does not carry the whole history of previous tasks forward. Planning controls include --tasks-size fine|coarse for granularity, [P] to mark low-conflict parallel tasks, and [VERIFY] plus VE tasks for explicit verification.

Installing Smart Ralph and running a first spec

The README gives marketplace-based installation for both hosts. For Claude Code, add the marketplace and install the plugin, then restart Claude Code.

/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph

For Codex the marketplace add is sparse, pulling only .agents/plugins and plugins/ralph-specum-codex, followed by a plugin add.

codex plugin marketplace add tzachbon/smart-ralph \
  --sparse .agents/plugins \
  --sparse plugins/ralph-specum-codex
codex plugin add ralph-specum@smart-ralph

After installation the README says to start a new Codex task, run /hooks, review the bundled Stop hook, and trust it if you want automatic task execution. Until you trust it, you run $ralph-specum-implement once per task. A first real use is a named spec with a goal, which on Claude Code looks like this.

/ralph-specum:start user-auth "Add JWT authentication"

Adding --quick generates the spec and starts execution without stopping between phases. Run /ralph-specum:start with no arguments to resume the active spec. On Codex the same first run is $ralph-specum-start user-auth "Add JWT authentication", and Codex asks for approval after each spec artifact unless the command includes the exact --quick flag. For local Claude Code development the README points at cloning the repository and running claude --plugin-dir ./plugins/ralph-specum.

Where the workflow pushes back: approvals, hooks and prototypes

The friction is deliberate and worth naming. Outside quick mode there are approval checkpoints between spec phases, so a five-phase spec means five interruptions. Codex adds another: it asks for approval after each spec artifact unless --quick is passed exactly. Automatic execution in Codex depends on trusting the bundled Stop hook; the README does not describe what happens to a half-finished task if that hook is declined mid-run, and it does not document rollback. The prototype feature has its own constraints. Prototype source stays in a sibling worktree or an eligible scratch directory, quick mode transfers no source into the current checkout, and normal mode transfers only paths you approve. Reviewed terminal records are immutable, and local evidence does not authorize a push, remote branch, PR update, issue write or record deletion. If your repository cannot tolerate a sibling worktree, or if you want the tool to commit and open pull requests on its own, Smart Ralph is the wrong shape. It stops at evidence.

Smart Ralph compared with a plain Ralph loop

A plain Ralph loop is prompt plus repetition: run the same instruction against the codebase until the output looks right. There is no artifact between runs, so the only record of intent is the conversation. Smart Ralph keeps the loop but puts a specification pipeline in front of it and persists state in .progress.md and tasks.md. The difference shows up on resumption. A plain loop restarts from the prompt; Smart Ralph resumes the active spec and skips tasks already marked complete. It also changes what review looks like: you review requirements and design files before any code exists, rather than reviewing a diff after the loop has run. The cost is ceremony. For a one-file change, generating research, requirements, design and tasks is more overhead than the change itself, and /ralph-specum:start with --quick is the only way to compress it. The README does not compare Smart Ralph against other spec tools, so any claim about how it stacks up against them would be guesswork.

Maintenance, licence and the cost of upgrading

The repository is not archived and the last push was on 2026-09-10, so it is being touched. The most recent release listed is v4.0.0, "Plugin Best Practices v2", from 2026-02-20, following v3.1.1, "Self-contained execution loop", and v2.0.0, "Ralph Wiggum Integration". The gap between the v4.0.0 release and the latest push suggests ongoing work that has not been cut into a release, though the repository does not say what that work is. The licence is MIT, which permits commercial use and modification; the repository ships a LICENSE file, and anyone redistributing a modified plugin should read it rather than rely on a summary. Upgrade cost is mostly in the Codex path: the README's Codex installation guide covers updates, local development with codex plugin marketplace add ., and migration from the old platforms/codex/ skills. If you installed before that migration, expect to re-point your skills. There is also a /ralph-specum:cancel command that cancels execution and removes loop state, which is the documented way out of a stuck run. The README does not document rollback of already-applied task changes.

Editorial conclusion

Adopt Smart Ralph if you already work inside Claude Code or Codex and want the plan to exist as reviewable files in the repository before code is written. Skip it if you want a one-shot prompt-to-patch tool, or if you cannot grant a Stop hook trust in Codex, since without it you run $ralph-specum-implement once per task by hand. Before committing, verify two things in your own checkout: that /ralph-specum:index produces usable component specs under specs/.index/ for your codebase, and that the prototype worktree behaviour matches what your repository can tolerate.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. tzachbon/smart-ralph on GitHub