# Smart Ralph
### *"Me fail specs? That's unpossible!"*
[](https://opensource.org/licenses/MIT)
[](https://claude.ai/code)
[](http://makeapullrequest.com)
**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](#how-it-works) | [Installation](#installation) | [Quick start](#quick-start) | [Commands](#commands) | [Troubleshooting](#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.
```mermaid
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
```bash
/plugin marketplace add tzachbon/smart-ralph
/plugin install ralph-specum@smart-ralph
```
Restart Claude Code after installation.
### Codex
```bash
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](plugins/ralph-specum-codex/README.md#installation) 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
```text
$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
```bash
/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: