Skip to content
Back to search

smart-ralph

MarketplaceWorks with Claude CodeGitHub

Spec-driven development with smart compaction. Claude Code plugin combining Ralph Wiggum loop with structured specification workflow.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tzachbon-smart-ralph/badge.svg)](/listings/tzachbon-smart-ralph)

HTML

<a href="/listings/tzachbon-smart-ralph"><img src="/api/listings/tzachbon-smart-ralph/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](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`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 49 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "smart-ralph",
  3. "owner": {
  4. "name": "tzachbon"
  5. },
  6. "metadata": {
  7. "description": "Spec-driven development with task-by-task execution"
  8. },
  9. "plugins": [
  10. {
  11. "name": "ralph-specum",
  12. "description": "Spec-driven development with research, requirements, design, tasks, autonomous execution, and epic triage. Fresh context per task.",
  13. "version": "4.12.2",
  14. "author": {
  15. "name": "tzachbon"
  16. },
  17. "source": "./plugins/ralph-specum",
  18. "category": "development",
  19. "tags": [
  20. "ralph",
  21. "spec-driven",
  22. "autonomous",
  23. "research",
  24. "tasks",
  25. "epic",
  26. "triage"
  27. ]
  28. },
  29. {
  30. "name": "ralph-speckit",
  31. "description": "Spec-driven development using GitHub spec-kit methodology. Constitution-first approach with specify, plan, tasks, and implement phases.",
  32. "version": "0.5.2",
  33. "author": {
  34. "name": "tzachbon"
  35. },
  36. "source": "./plugins/ralph-speckit",
  37. "category": "development",
  38. "tags": [
  39. "ralph",
  40. "speckit",
  41. "spec-driven",
  42. "constitution",
  43. "specify",
  44. "plan",
  45. "tasks"
  46. ]
  47. }
  48. ]
  49. }
README.md · README · 263 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="smart-ralph.png" alt="Smart Ralph" width="500"/>
  3. # Smart Ralph
  4. ### *"Me fail specs? That's unpossible!"*
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![Claude Code](https://img.shields.io/badge/Built%20for-Claude%20Code-blueviolet)](https://claude.ai/code)
  7. [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
  8. **Spec-driven development for Claude Code and Codex.**
  9. 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.
  10. [How it works](#how-it-works) | [Installation](#installation) | [Quick start](#quick-start) | [Commands](#commands) | [Troubleshooting](#troubleshooting)
  11. </div>
  12. ---
  13. ## How it works
  14. 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.
  15. 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.
  16. An optional prototype can test one focused design question without turning disposable source into production code.
  17. ```mermaid
  18. flowchart TD
  19. A["I want a feature!"] --> B{"/start detects scope"}
  20. B -->|Single spec| C[Research]
  21. B -->|"Too big for one spec"| T["/triage"]
  22. C -->|Analyzes codebase, searches web| D[Requirements]
  23. D -->|User stories, acceptance criteria| E[Design]
  24. E -->|Architecture, patterns, decisions| F[Tasks]
  25. F -->|POC-first task breakdown| G[Execution]
  26. G -->|Task-by-task with fresh context| H["I did it!"]
  27. T -->|Explore| T1[Exploration Research]
  28. T1 -->|Brainstorm| T2[Triage Analyst]
  29. T2 -->|Validate| T3[Validation Research]
  30. T3 -->|Finalize| T4["Epic Plan"]
  31. T4 -->|"Spec 1, Spec 2, ..."| C
  32. ```
  33. ## Installation
  34. ### Claude Code
  35. ```bash
  36. /plugin marketplace add tzachbon/smart-ralph
  37. /plugin install ralph-specum@smart-ralph
  38. ```
  39. Restart Claude Code after installation.
  40. ### Codex
  41. ```bash
  42. codex plugin marketplace add tzachbon/smart-ralph \
  43. --sparse .agents/plugins \
  44. --sparse plugins/ralph-specum-codex
  45. codex plugin add ralph-specum@smart-ralph
  46. ```
  47. 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.
  48. 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.
  49. For local Claude Code development, clone this repository and run `claude --plugin-dir ./plugins/ralph-specum`.
  50. ## Quick start
  51. ### Codex
  52. ```text
  53. $ralph-specum-start user-auth "Add JWT authentication"
  54. ```
  55. 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.
  56. ### Claude Code
  57. ```bash
  58. /ralph-specum:start user-auth "Add JWT authentication"
  59. ```
  60. Add `--quick` to generate the spec and start execution without stopping between phases. Run `/ralph-specum:start` without arguments to resume the active spec.
  61. ## Commands
  62. Claude Code uses `/ralph-specum:<name>`. Codex uses `$ralph-specum-<name>` and folds `new` into `$ralph-specum-start`.
  63. | Command | What it does |
  64. |---------|--------------|
  65. | `/ralph-specum:start [name] [goal]` | Resume a spec or create one |
  66. | `/ralph-specum:start [goal] --quick` | Generate all spec phases and execute |
  67. | `/ralph-specum:new <name> [goal]` | Create a spec and wait for approval before research |
  68. | `/ralph-specum:triage [name] [goal]` | Split a large goal into an epic |
  69. | `/ralph-specum:research` | Run or repeat research |
  70. | `/ralph-specum:requirements` | Generate requirements from research |
  71. | `/ralph-specum:prototype` | Run or resume an optional prototype |
  72. | `/ralph-specum:design` | Generate the technical design |
  73. | `/ralph-specum:tasks` | Break the design into executable tasks |
  74. | `/ralph-specum:implement` | Execute tasks one at a time |
  75. | `/ralph-specum:index` | Generate searchable codebase specs |
  76. | `/ralph-specum:refactor` | Update requirements, design, or tasks |
  77. | `/ralph-specum:status` | Show specs and progress |
  78. | `/ralph-specum:switch <name>` | Change the active spec |
  79. | `/ralph-specum:cancel` | Cancel execution and remove loop state |
  80. | `/ralph-specum:feedback [message]` | Submit feedback or report an issue |
  81. | `/ralph-specum:help` | Show command and workflow help |
  82. ## Execution model
  83. Smart Ralph gives each phase to a focused agent.
  84. | Phase | Agent | Responsibility |
  85. |-------|-------|----------------|
  86. | Triage | `triage-analyst` | Split features and map dependencies |
  87. | Research | `research-analyst` | Inspect the codebase and check feasibility |
  88. | Requirements | `product-manager` | Write user stories and acceptance criteria |
  89. | Prototype | `prototype-builder` | Test one design question with disposable evidence |
  90. | Design | `architect-reviewer` | Define architecture and trade-offs |
  91. | Tasks | `task-planner` | Create a POC-first task sequence |
  92. | Execution | `spec-executor` | Implement tasks and run quality gates |
  93. Tasks follow four phases:
  94. 1. Make it work: validate the approach with a POC.
  95. 2. Refactoring: clean up the working implementation.
  96. 3. Testing: add unit, integration, and end-to-end coverage.
  97. 4. Quality gates: run lint, type, and CI checks.
  98. Planning controls include:
  99. - `--tasks-size fine|coarse` for task granularity
  100. - `[P]` for low-conflict parallel tasks
  101. - `[VERIFY]` and VE tasks for explicit verification
  102. - approval checkpoints between spec phases outside quick mode
  103. ### Optional prototypes
  104. - 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.
  105. - In quick mode, Smart Ralph asks no prototype questions, owns the decisions, and always continues to design after the prototype outcome.
  106. - 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.
  107. - Reviewed terminal records are immutable. Local evidence does not authorize a push, remote branch, PR update, issue write, or record deletion.
  108. Smart Ralph stores progress in `.progress.md` and marks completed work in `tasks.md`. Each implementation task starts with fresh context.
  109. ## Codebase indexing
  110. `/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.
  111. ```bash
  112. /ralph-specum:index
  113. /ralph-specum:index --quick
  114. /ralph-specum:index --dry-run
  115. /ralph-specum:index --path=src/api/
  116. ```
  117. | Option | Effect |
  118. |--------|--------|
  119. | `--path=<dir>` | Scan one directory |
  120. | `--type=<types>` | Limit component types |
  121. | `--exclude=<patterns>` | Skip matching paths |
  122. | `--dry-run` | Preview without writing specs |
  123. | `--force` | Regenerate the index |
  124. | `--changed` | Regenerate Git-changed files |
  125. | `--quick` | Skip the pre-scan and post-scan interviews |
  126. 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.
  127. 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.
  128. ## Project structure
  129. 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.
  130. Smart Ralph writes feature specs inside the project where you run it:
  131. ```text
  132. specs/
  133. |-- .current-spec
  134. `-- my-feature/
  135. |-- .ralph-state.json
  136. |-- .progress.md
  137. |-- prototypes/
  138. | `-- <id>.md
  139. |-- research.md
  140. |-- requirements.md
  141. |-- design.md
  142. `-- tasks.md
  143. ```
  144. Smart Ralph deletes `.ralph-state.json` when execution finishes. It keeps `.progress.md` so later tasks can recover decisions and learnings.
  145. Epic plans live under `specs/_epics/<name>/`. Their state files track which specs are ready, blocked, or complete.
  146. ## Ralph Speckit
  147. `ralph-speckit` is the alternative plugin for [GitHub's Spec-Kit methodology](https://github.com/github/spec-kit). It adds a project constitution and requirement-to-task traceability.
  148. | Feature | ralph-specum | ralph-speckit |
  149. |---------|--------------|---------------|
  150. | Directory | `specs/` | `.specify/specs/` |
  151. | Naming | `my-feature/` | `001-feature-name/` |
  152. | Governance | Per-spec workflow | Project constitution |
  153. | Main files | Research, requirements, design, tasks | Spec, plan, tasks |
  154. | Best fit | Fast iteration | Team governance and audit trails |
  155. ```bash
  156. /plugin install ralph-speckit@smart-ralph
  157. /speckit:constitution
  158. /speckit:start user-auth "Add JWT authentication"
  159. /speckit:specify
  160. /speckit:plan
  161. /speckit:tasks
  162. /speckit:implement
  163. ```
  164. The plugin also includes `/speckit:status`, `/speckit:switch`, `/speckit:cancel`, `/speckit:clarify`, and `/speckit:analyze`. See the [Ralph Speckit guide](plugins/ralph-speckit/README.md) for its file layout and command details.
  165. ## Troubleshooting
  166. - Repeated task failure: read `.progress.md`, fix the reported problem, then run `/ralph-specum:implement`.
  167. - Start over: run `/ralph-specum:cancel`, then start a new spec.
  168. - Resume work: run `/ralph-specum:start`. Ralph finds the active spec.
  169. See the [Troubleshooting Guide](TROUBLESHOOTING.md) for installation, state, hook, and recovery problems.
  170. ## Upgrading
  171. Smart Ralph v3.0.0 moved execution into the plugin's Stop hook. Projects that used v2.x no longer need the separate Ralph Loop plugin.
  172. Update Smart Ralph, restart Claude Code, and resume. Existing spec files need no migration. You can uninstall Ralph Loop if no other workflow uses it. Check [GitHub releases](https://github.com/tzachbon/smart-ralph/releases) for later changes.
  173. ## Contributing
  174. PRs are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) for setup, tests, and pull request guidance.
  175. ## Credits
  176. Smart Ralph takes its name from the [Ralph agentic loop pattern](https://ghuntley.com/ralph/) and Springfield's most determined student. Ralph does the next task. Be like Ralph.
  177. - Built for [Claude Code](https://claude.ai/code) and [OpenAI Codex](https://github.com/openai/codex)
  178. - Inspired by developers who wanted their coding agent to handle the whole feature
  179. ---
  180. <div align="center">
  181. **Made with confusion and determination**
  182. *"The doctor said I wouldn't have so many nosebleeds if I kept my finger outta there."*
  183. [MIT License](LICENSE)
  184. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.