A command that turns a product requirements document, or PRD, into structured user stories and runs an agent repeatedly until those stories are complete. It checks each story, commits passing work, and records progress.

Use it to initialize the workflow, convert a Markdown PRD into executable JSON, and run a limited number of implementation iterations.

It removes much of the manual tracking needed when implementing a list of requirements. Each loop starts with a fresh context and runs type checks, tests, and linting before committing.

ralph — Command by naimkatiman

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods

npx agentmods add commands/naimkatiman/continuous-improvement/ralph

Clone the repo

git clone --depth 1 https://github.com/naimkatiman/continuous-improvement

Per session 18 Only the description is in the session, so the agent can decide to use it. The body loads when it is invoked.

When invoked 661 The whole file, excluding the scripts and references it only reads on demand.

Security scan A 0 findings. Scan, not verified.

Origin original No closer match found in the catalogue.

Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

Model	Per session	Once invoked
Fable 5	$0.00018	$0.00661
Opus 5	$0.00009	$0.00331
Sonnet 5	$0.00004	$0.00132
Haiku 4.5	$0.00002	$0.00066

Measured 3d ago against content hash 02596baabe7c, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

ralph scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 3d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

commands/ralph.md · 104 lines

How it starts

The opening of the file, as written. The whole thing — 104 lines — stays where its author put it; the contents beside it link to each section on GitHub.

/ralph

Ralph is an autonomous AI agent loop that runs repeatedly until all PRD items are complete.

Subcommands

`/ralph init`

Initialize Ralph in your project:

Create scripts/ralph/ directory
Add ralph.sh loop script
Add prompt templates for Amp and Claude Code
Create example prd.json

`/ralph convert <prd-file>`

Convert a markdown PRD to Ralph's executable JSON format:

/ralph convert tasks/prd-auth-feature.md

Output: prd.json with structured user stories

`/ralph run [iterations]`

Run the autonomous loop:

/ralph run 10

Default: 10 iterations. Stops early if all stories complete.

Ralph Loop Behavior

Create branch from PRD branchName
Pick highest priority story where passes: false
Implement story — fresh context, no pollution
Run quality checks — typecheck, tests, lint
Commit if passing — atomic commits per story
Update prd.json — mark passes: true
Log learnings — append to progress.txt
Repeat until done or max iterations

Key Files

File	Purpose
`prd.json`	Executable PRD with user stories
`progress.txt`	Accumulated learnings
`ralph.sh`	The loop script
`AGENTS.md`	Iteration memory (auto-updated)

Workflow Integration

Ralph works best with:

Superpowers — for structured development stages
continuous-improvement — for reflection and learning between iterations
workspace-surface-audit — to verify capabilities before starting

Critical Concepts

Fresh Context Per Iteration

Each story runs in isolation. Previous work is visible only via git history and prd.json.

AGENTS.md Updates

Ralph updates AGENTS.md after each story so subsequent iterations know what's already done.

Browser Verification

For UI stories, Ralph starts a dev server and uses Playwright to verify rendering.

Stop Conditions

All stories pass
Max iterations reached
Critical failure (requires human intervention)

Read the full file on GitHub · 104 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

3d ago First seen · 104 lines · 18 tokens per session scan A 02596baabe7c

Subscribe to this mod's changes

ralph is a command published in the GitHub repository naimkatiman/continuous-improvement (7 stars, last pushed 8d ago), licensed MIT. It adds 18 tokens to every session and 661 once invoked, about $0.0001 per session on Opus 5. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-31.

Building agents LLM Planning ai-agents claude-code coding-agents continuous-improvement hooks

ralph