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.

Execution model

Smart Ralph gives each phase to a focused agent.

Tasks follow four phases:

1. Make it work: validate the approach with a POC.
2. Refactoring: clean up the working implementation.
3. Testing: add unit, integration, and end-to-end coverage.
4. Quality gates: run lint, type, and CI checks.

Planning controls include:

• --tasks-size fine|coarse for task granularity
• [P] for low-conflict parallel tasks
• [VERIFY] and VE tasks for explicit verification
• approval checkpoints between spec phases outside quick mode

Optional prototypes

• In normal mode, Smart Ralph may suggest a prototype after research or requirements. You can also run /ralph-specum:prototype or $ralph-specum-prototype at 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.

Codebase indexing

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

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.

Project structure

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

ralph-speckit is the alternative plugin for GitHub's Spec-Kit methodology. It adds a project constitution and requirement-to-task traceability.

/plugin install ralph-speckit@smart-ralph
/speckit:constitution
/speckit:start user-auth "Add JWT authentication"
/speckit:specify
/speckit:plan
/speckit:tasks
/speckit:implement

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

Troubleshooting

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

Upgrading

Smart