Spec-driven development automation using AI agents. Works with any language, any framework.
Ralph Loop is an autonomous development system that uses AI agents to turn a list of feature briefs into implemented, tested code — one spec at a time.
The core philosophy:
- Specs are the single source of truth. Every feature starts as a detailed specification that describes exactly what to build. Agents implement FROM the spec, never from vague ideas.
- Separation of concerns. Four specialized agents handle different phases: writing specs, building code, reviewing quality, and running tests. Each agent does one job well.
- Iterative loops. The system runs in a loop — write one spec, build one spec, review, test, repeat — until all work is done.
- You stay in control. You define WHAT to build in the registry. The agents figure out HOW based on your project's rules.
rules.md
|
v
SPEC_REGISTRY +--------+ specs/ +---------+ code +--------+
(feature briefs) | SPEC | -----------> | BUILD | --------> | TEST |
| Agent | writes | Agent | writes | Agent |
+--------+ specs +---------+ code +--------+
^ |
| PLAN Agent |
+---- reviews & ------+
fixes specs
The loop:
- You write brief feature descriptions in
SPEC_REGISTRY.md - Spec Agent reads each brief, reads your code, writes a detailed spec
- Build Agent reads the spec and implements it exactly
- Test Agent runs tests and documents results
- Plan Agent reviews everything, fixes broken specs, unblocks stuck work
- Repeat until the registry is empty
Each iteration handles exactly ONE spec, commits to git, and pushes.
Reads the registry and your source code, then writes one detailed, self-contained specification file. The spec includes the problem description, current code state with exact line numbers, files to modify, step-by-step implementation instructions, and a testing checklist.
Picks the next unfinished spec from the implementation plan and implements it by following the spec's steps exactly. Does not improvise. Commits the work and updates the progress tracker.
Reviews completed work to verify it matches specs. Unblocks stuck specs by investigating failures and updating implementation steps. Validates that upcoming specs have accurate file references.
Runs the full test suite and documents results. Does NOT fix bugs — only records what passed and what failed so the build agent knows what to address.
# Clone or copy the ralph-loop files into your project
cp -r /path/to/ralph-loop my-project/ralphYour project should look like:
my-project/
├── ralph/
│ ├── rules.md # <-- You fill this in
│ ├── SPEC_REGISTRY.md # <-- You add your specs here
│ ├── PROMPT_spec.md
│ ├── PROMPT_build.md
│ ├── PROMPT_plan.md
│ ├── PROMPT_test.md
│ ├── loop.sh
│ └── run.sh
├── docs/
│ ├── specs/ # <-- Generated spec files go here
│ └── IMPLEMENTATION_PLAN.md
└── ... your project files ...
mkdir -p docs/specsThe implementation plan (docs/IMPLEMENTATION_PLAN.md) is created and populated automatically by the spec agent — you don't need to create or maintain it manually.
Open ralph/rules.md and fill in every section with your project's details:
- Architecture and project layout
- Test, build, and run commands
- Naming conventions
- Key frameworks
See the examples/ folder for complete examples (Flutter, Next.js, Python).
Add entries following the template:
---
### 001 — User Authentication
- **Phase**: A — Core Infrastructure (Priority: P0)
- **Status**: NOT WRITTEN
- **Problem**: Users cannot sign in. The app needs OAuth and email auth...
- **Key files**: `src/auth/service.ts`, `src/config/app.ts`, `package.json`
- **Outcome**: Users can sign in with Google or email. Auth state persists...
- **Dependencies**: None# Generate all specs, then build all
ralph/run.sh
# Or step by step:
ralph/loop.sh spec 3 # Generate 3 specs
ralph/loop.sh build 3 # Build 3 specs
ralph/loop.sh test 1 # Run tests once
ralph/loop.sh plan 1 # Review and fix| Command | Description |
|---|---|
ralph/loop.sh spec [N] |
Generate N specs (0 = all remaining) |
ralph/loop.sh build [N] |
Build N specs (0 = all remaining) |
ralph/loop.sh plan [N] |
Run N plan review iterations |
ralph/loop.sh test [N] |
Run N test sessions |
ralph/run.sh |
Full pipeline: all specs then all builds |
ralph/run.sh spec |
Only spec generation (all remaining) |
ralph/run.sh spec 5 |
Only generate 5 specs |
ralph/run.sh build |
Only build (all remaining) |
ralph/run.sh build 3 |
Only build 3 |
ralph/run.sh 5 3 |
Generate 5 specs, then build 3 |
Iteration counts:
0= infinite — runs until all work is doneN > 0= runs exactly N iterations then stops
| Variable | Default | Description |
|---|---|---|
RALPH_MODEL |
opus |
Claude model to use (opus, sonnet, haiku) |
Example:
RALPH_MODEL=sonnet ralph/loop.sh build 5In rules.md, the File Paths section controls where Ralph looks for files:
specs_dir: docs/specs/
implementation_plan: docs/IMPLEMENTATION_PLAN.md
spec_registry: ralph/SPEC_REGISTRY.md
These defaults work for most projects. Change them if your project uses different paths.
The rules.md file is the bridge between Ralph's generic prompts and your specific project. Every agent reads it at the start of every session. Here's how each section is used:
| Section | Used By | Purpose |
|---|---|---|
| Project Overview | All agents | Understand what the project does |
| Agent Rules File | All agents | Read your CLAUDE.md / .cursorrules for extra context |
| Architecture | Spec, Build | Follow your architecture pattern when designing and implementing |
| Project Layout | Spec, Build | Know where files go, understand the directory structure |
| State Management | Spec, Build | Design state correctly for your pattern (Redux, BLoC, etc.) |
| Dependency Injection | Spec, Build | Wire dependencies using your DI approach |
| Naming Conventions | All agents | Name files, classes, and functions consistently |
| Key Frameworks | Spec, Build | Know what tools are available |
| Commands | Build, Test | Run tests, builds, linters, code generators |
| Architecture Docs | Spec, Plan | Read detailed architecture references |
| Component Registry | Spec, Build | Reuse existing components, avoid duplicates |
| Localization | Spec, Build | Handle i18n correctly |
| File Paths | All agents, loop.sh | Find specs, implementation plan, registry |
| Additional Rules | All agents | Follow project-specific constraints |
Tip: Keep rules.md concise (under 200 lines). It's read at the start of every session, so brevity saves context window space.
Bad entry:
### 003 — Fix Auth
- **Problem**: Auth doesn't work.
- **Outcome**: Auth works better.Good entry:
### 003 — Fix Token Refresh
- **Problem**: Users get logged out after 1 hour because the JWT refresh
fails silently in `src/auth/token.ts:47`. The catch block swallows the
error and returns null instead of triggering a re-auth flow.
- **Key files**: `src/auth/token.ts`, `src/auth/service.ts`, `src/middleware/auth.ts`
- **Outcome**: Expired tokens trigger a refresh. If refresh fails, user
sees a re-login prompt. Token errors are logged to Sentry. Session
survives for 30 days with active use.The implementation plan is created and populated automatically by the spec agent. Every time a spec is written, the agent adds a - [ ] NNN — Title entry to docs/IMPLEMENTATION_PLAN.md. You never need to maintain this file manually.
The file has this structure (auto-generated):
# Implementation Plan
## Progress
- [ ] 001 — Feature Name (added when spec 001 is written)
- [ ] 002 — Another Feature (added when spec 002 is written)
- [x] 003 — Third Feature (marked by build agent after implementation)
## Verified Results (populated by test agent)
## Bug Fixes Needed (populated by build/test agents)
## Questions (populated by build/plan agents)Status markers:
[ ]— NOT STARTED (build agent picks these up)[~]— IN PROGRESS (being implemented)[x]— COMPLETED[?]— BLOCKED (with reason in Bug Fixes Needed)
The loop script automatically detects when all work is done:
- Spec mode: Compares the count of
### NNNentries in the registry against the count of.mdfiles in the specs directory. When they match, all specs are written. - Build mode: Counts
- [ ] NNNentries in the implementation plan. When zero remain, all specs are built.
After each iteration, the loop:
- The agent commits its changes during execution
- The loop pushes to the remote
- The next iteration starts fresh
Press Ctrl+C to interrupt cleanly. Progress is saved in git.
Built into the prompts:
- One spec per session: Write or build one thing, then stop
- One fix attempt: If a test fails, try once to fix. If still failing, document and stop
- No retry loops: Don't retry the same failing command more than twice
- Time limit: If stuck on one step for more than 5 minutes, mark blocked and move on
- No self-undo: Never undo your own changes to try again from scratch
- Claude CLI (
claude) installed and authenticated - Git repository initialized with a remote
- Unix-like shell (bash or zsh)
The examples/ directory contains complete rules.md files for:
rules-flutter.md— Flutter app with BLoC state management, GetIt DI, Clean Architecturerules-nextjs.md— Next.js 14+ with App Router, Server Components, Prisma, Zustandrules-python.md— Python API with FastAPI, SQLAlchemy, pytest, Alembic
Copy the one closest to your stack and adapt it.
Can I use this with Cursor/Windsurf instead of Claude CLI?
The loop.sh script is designed for Claude CLI. For other tools, you can use the PROMPT_*.md files as system prompts or instructions — the workflow logic works the same regardless of the AI tool.
How do I handle specs that depend on each other?
Use the Dependencies field in registry entries. The build agent checks that dependencies are marked [x] COMPLETED before starting a spec. If they're not, it marks the spec [?] BLOCKED and moves on.
What if a build fails?
The build agent makes one attempt to fix test failures. If it can't, it marks the spec [?] BLOCKED and documents the failure. Run ralph/loop.sh plan 1 to have the plan agent investigate and fix the spec, then re-run the build.
Can I run multiple loops in parallel? Not recommended — agents would conflict on git commits and the implementation plan file. Run them sequentially.
What model should I use?
opus (default) produces the highest quality specs and implementations. Use sonnet for faster iterations on simpler tasks. Use haiku only for test runs.
Do I need to create the implementation plan manually?
No. The spec agent automatically creates docs/IMPLEMENTATION_PLAN.md and adds a - [ ] NNN — Title entry each time it writes a spec. Just run ralph/loop.sh spec and the plan builds itself.
MIT