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.

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

Execution model

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:

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