Smart Ralph

"Me fail specs? That's unpossible!"

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

---

How it works

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

Installation

Claude Code

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

Restart Claude Code after installation.

Codex

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

Start 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.

Quick start

Codex

$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.

Claude Code

/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.

Commands

Claude Code uses /ralph-specum:<name>. Codex uses $ralph-specum-<name> and folds new into $ralph-specum-start.