What is a Ralph Loop?

A Ralph Loop is an autonomous agentic coding loop where an AI coding agent iteratively builds software from a well-crafted specification. The name comes from Geoff Huntley’s work on autonomous coding workflows — Ralph is the tireless agent that reads your spec and builds your software.

How It Works

A Ralph Loop has four phases:

1. Feed the Spec

The spec’s PROMPT.md is the agent’s entry point. It tells the agent where to find the requirements (SPEC.md), the technical standards (stdlib/), and the success criteria (SUCCESS_CRITERIA.md).

specmarket run @jaiden/docusign-replacement

The CLI downloads the spec, validates its structure, and feeds PROMPT.md to your local Claude Code agent.

2. Build Loop

The agent enters an iterative build cycle:

Read the specification
Write code (or modify existing code)
Run tests and check success criteria
If checks pass → move to next task
If checks fail → read the error, diagnose, fix, go back to step 3
Repeat until all success criteria are met

This isn’t a one-shot code generation. The agent encounters real problems — dependency conflicts, type errors, failing tests, edge cases — and solves them iteratively, the same way a human developer would.

3. Success Criteria Evaluation

Every spec includes machine-evaluable success criteria:

- [ ] `pnpm test` passes with 0 failures
- [ ] `pnpm build` produces output in dist/
- [ ] TypeScript strict mode: 0 errors
- [ ] All API endpoints respond to health checks

The agent checks these during and after the build. If criteria aren’t met, the loop continues. If the agent can’t make progress after repeated attempts, it reports a stall.

On SpecMarket, every run reports which criteria passed and which failed. A spec’s success rate is calculated from real community runs — not the author’s own tests.

4. The Result

When the loop completes successfully, you have a working application in your local directory. The code is yours. Deploy it wherever you want. Modify it however you like. No subscription. No vendor lock-in.

Why Specs Matter More Than Prompts

A prompt is a wish. A spec is a blueprint.

The difference is structure and specificity:

Prompt	Spec
”Build me a DocuSign replacement”	2,000-word functional specification with defined features, edge cases, and constraints
Model picks its own stack	STACK.md specifies Node.js 20, Next.js 14, Supabase, TypeScript strict
”Make it work”	15 machine-evaluable success criteria
No consistency between runs	stdlib/ patterns ensure consistent code structure
No security guarantees	SECURITY.md defines input validation, auth, rate limiting

Good specs constrain the search space. When the agent doesn’t have to guess what stack to use, what patterns to follow, or how to handle errors, it can focus on building the actual application. This is why structured specs produce dramatically higher success rates than freeform prompts.

The Economics

Running a Ralph Loop costs API tokens. The cost depends on:

Spec complexity: Simple CLI tools cost $5-$10. Full web applications cost $15-$50.
Model used: More capable models (Claude Opus) cost more per token but may succeed in fewer iterations.
Iteration count: Specs with clear success criteria tend to complete in fewer iterations.

Compare this to SaaS subscriptions:

Tool	SaaS Cost (20 users, 1 year)	Spec Cost (one-time)
E-signature	$6,000	~$8-15
CRM basics	$18,000	~$20-30
Form builder	$6,000	~$8-12
Scheduling	$2,400	~$6-10

The output is software you own. The ongoing cost is hosting — typically negligible if you already run servers.

What Makes a Good Ralph Loop

From observing hundreds of runs, these patterns correlate with high success rates:

1. Specific technology choices. “Use Next.js 14 with App Router” beats “use a React framework.” The agent doesn’t waste tokens evaluating options.

2. Explicit success criteria. Automated checks (pnpm test, pnpm build) catch issues the agent can fix. Vague criteria (“should work well”) don’t.

3. Defined patterns. “Put API routes in app/api/, database queries in lib/db/, shared types in lib/types.ts” gives the agent a clear file structure to follow.

4. Reasonable scope. Specs that try to replace 100% of a complex SaaS tool often stall. Specs that target 80% of the core workflow succeed reliably.

5. Error handling instructions. “Return proper HTTP status codes, never throw in API routes, log errors with structured context” prevents common failure modes.

Running a Ralph Loop

Basic Run

specmarket run @creator/spec-name

With a Specific Model

specmarket run @creator/spec-name --model claude-opus-4

In a Docker Sandbox

specmarket run @creator/spec-name --sandbox docker

Viewing Run Details

specmarket report latest

This shows: status, success criteria results, cost, time, and model used.

Getting Started — Install the CLI and run your first spec
Spec Format Reference — How specs are structured
Browse Specs — Find specs to run

Attribution

The Ralph Loop concept was pioneered by Geoff Huntley. SpecMarket builds on this work by creating a marketplace ecosystem where specs are published, run by the community, and improved through transparent metrics.