Smart Ralph
Turns a feature request into a structured spec, then executes it task by task — spec-driven development for Claude Code and Codex.
Docs state least-privilege external-effect controls (immutable reviewed terminal records, no push/PR/issue authorization), approval checkpoints between phases (except --quick), and rollback via /cancel, resume state, and .ralph-state. cleanup. Deductions: most claims are README assertions — the actual Stop hook and permission scripts were not in evidence; sensitive-data handling (e.g., index recording MCP servers/URLs, credential risk) is unaddressed; publisher identity is unverified.
Version-sync tests, lock lifecycle tests, and Windows/POSIX process-control tests show strong internal consistency; failure surfaces like StateError, terminationUnverified, and controlError are concretely designed. Deductions: failure-message quality is corroborated only indirectly via tests; recovery guidance points to TROUBLESHOOTING.md whose content was not provided; dependency availability only inferred from CI installs of bats/jq/ripgrep.
Targets both Claude Code and Codex with triage, prototype, and codebase-indexing scenarios; native and simulated Windows coverage shows strong environment fit. Deductions: capability boundaries and trigger precision rely on the command table and flowchart; edge conditions (non-git projects, very large repos) are not spelled out.
README is well structured; installation covers both platforms plus local development and migration; MIT LICENSE file present; CI enforces semver bump and version sync; upgrade notes exist. Deductions: known limitations live in TROUBLESHOOTING.md (not provided); dual specum/speckit plugins and a v2→v3 migration slightly burden naming stability; CONTRIBUTING.md content absent, so maintenance responsibility can only be credited for the reference.
Artifacts are structured spec files kept in the project, human-reviewable and editable, with per-task progress and resume — high output usability. Deductions: marginal value over native planning is not quantified; autonomous loop with fresh context per task may raise token cost, and cost/benefit is not discussed.
README claims about locking, exclusive publication, and receipt-gated publication after source deletion are each backed by unit tests — notable cross-source corroboration. Deductions: some key claims (Stop hook behavior, quick-mode transfer policy) have no implementation files in evidence to check; facts and inference are mostly, but not uniformly, separated.
- Trust conclusions rest largely on README claims; review the Stop hook script and plugin source yourself before installing to confirm behavior matches the docs.
- --quick mode bypasses inter-phase approvals; use it only in controlled environments where continuous autonomous execution is acceptable.
- The indexing feature records external URLs, MCP servers, and installed skills; it may capture sensitive environment details — avoid committing it to public repositories.
- Prototype execution launches and terminates processes (taskkill/killpg); validate in an isolated or sandboxed environment before production use.
- TROUBLESHOOTING.md and CONTRIBUTING.md were not part of the evidence; verify recovery and contribution procedures independently.
What does this agent do, and when should you use it?
Smart Ralph (tzachbon/smart-ralph) is an MIT-licensed Claude Code plugin that also supports OpenAI Codex, combining the Ralph Wiggum loop with a structured specification workflow. It first converts a feature request into research, requirements, design, and task files, then executes the spec task by task with focused subagents (research-analyst, product-manager, architect-reviewer, task-planner, spec-executor), each implementation task starting with fresh context. Spec files persist in the project's specs/ directory so you can review or edit each phase; progress is recorded in .progress.md and a stopped session resumes via /ralph-specum:start. Large goals can be split by /ralph-specum:triage into dependency-aware epic specs. The repository also ships an alternative ralph-speckit plugin for GitHub's Spec-Kit methodology and an /ralph-specum:index command that writes searchable component specs for existing codebases.
After you invoke /ralph-specum:start [name] "goal" (Claude Code) or $ralph-specum-start (Codex), Smart Ralph runs a pipeline: research-analyst inspects the codebase and searches the web; product-manager writes user stories and acceptance criteria; architect-reviewer defines architecture and trade-offs; task-planner creates a POC-first task sequence; spec-executor implements tasks one at a time, each task passing through make-it-work POC, refactoring, testing, and quality-gate phases (lint, type, CI checks). /ralph-specum:triage splits oversized goals into epic plans; /ralph-specum:prototype tests one design question at a safe phase boundary using a disposable worktree; /ralph-specum:index scans a project and writes searchable component specs under specs/.index/. The --quick flag generates all phases and executes without stopping for approval; --tasks-size fine|coarse controls granularity; [P] marks low-conflict parallel tasks and [VERIFY]/VE tasks denote explicit verification. State lives in .ralph-state. and .progress.md, with artifacts written to research.md, requirements.md, design.md, and tasks.md under specs/<feature>/.
- Developers adding features to an existing codebase: run /ralph-specum:index first so research agents can reuse indexed component specs
- Users whose goal spans several features or systems: use /ralph-specum:triage to split it into a dependency-aware epic plan
- Teams that want phase-by-phase control: run default mode and approve each artifact between research, requirements, and design
- Solo developers who want fast results: use --quick to generate all spec phases and execute without stopping
- Teams following GitHub's Spec-Kit governance: install the ralph-speckit plugin for a project constitution and requirement-to-task traceability
- Developers unsure about one design decision: run /ralph-specum:prototype at a phase boundary to validate with disposable evidence
What are this agent's strengths and limitations?
- Spec files (research/requirements/design/tasks) persist in the project for review, editing, and resumption, making execution transparent
- Each phase runs in a dedicated subagent, and tasks follow POC validation → refactoring → testing → quality gates with lint, type, and CI checks
- Triage splits large goals into dependency-aware epic plans, and indexing produces searchable component specs that research reuses
- Supports both Claude Code and Codex; since v3.0.0 the execution loop lives in the plugin's Stop hook, removing the need for the separate Ralph Loop plugin
- Tightly bound to the Claude Code and OpenAI Codex host runtimes, with no documented path to other models or environments
- Codex requires reviewing and trusting the bundled Stop hook for automatic execution; otherwise you must run $ralph-specum-implement manually per task
- Upgrading from v2.x requires awareness that v3.0.0 moved execution into the Stop hook; the old Ralph Loop plugin may need uninstalling
- Default mode requires human approval between phases, making the full flow slower; --quick mode skips prototype questions and lets the plugin own design decisions
- The repository publishes no quantitative benchmarks of success rates or performance, so adopters must validate it on their own workloads
How do you install or deploy this agent?
Claude Code: run /plugin marketplace add tzachbon/smart-ralph, then /plugin install ralph-specum@smart-ralph, and restart Claude Code. Codex: run codex plugin marketplace add tzachbon/smart-ralph --sparse .agents/plugins --sparse plugins/ralph-specum-codex, then codex plugin add ralph-specum@smart-ralph; start a new Codex task, run /hooks, review the bundled Stop hook, and trust it for automatic task execution. For local Claude Code development, clone the repository and run claude --plugin-dir ./plugins/ralph-specum.
How do you use this agent?
In Claude Code, run /ralph-specum:start user-auth "Add JWT authentication" for your first spec; add --quick to skip approvals; run /ralph-specum:start with no arguments to resume the active spec. In Codex, use $ralph-specum-start user-auth "Add JWT authentication" or $ralph-specum to let the plugin choose the next action; use $ralph-specum-triage for multi-feature goals. Other key commands: /ralph-specum:research, /ralph-specum:requirements, /ralph-specum:design, /ralph-specum:tasks, /ralph-specum:implement (execute tasks one at a time), /ralph-specum:status (show progress), and /ralph-specum:cancel (cancel execution and remove loop state). On Codex, until the Stop hook is trusted, run $ralph-specum-implement once per task.
How does this agent compare with similar options?
The repository itself offers two workflows: ralph-specum (specs in specs/, best for fast iteration) and ralph-speckit (follows GitHub's Spec-Kit, stores in .specify/specs/ with a project constitution and requirement-to-task traceability, best for team governance and audit trails). Since v3.0.0, Smart Ralph's built-in execution loop also replaces the previously separate Ralph Loop plugin.