Project

Spec Dev Ralph

Ralph Loop — a starter template for spec-driven development where four Claude Code agents write specs, build, test and review in an autonomous loop.

  • #ai
  • #spec-driven-development
  • #claude-code
  • #agents

Spec Dev Ralph ("Ralph Loop") is my personal open-source starter template and guide for applying Spec-Driven Development with AI agents, in any language or framework: github.com/AleSZanello/spec-dev-ralph.

The idea

Specs are the single source of truth: agents implement from a written spec, never from a vague idea. You describe what to build as short feature briefs in a SPEC_REGISTRY.md; the agents work out how, guided by a project rules.md (architecture, layout, commands, naming, state management).

How it works

I split the work across four specialized agents, each a prompt file run headless through Claude Code:

  • Spec agent — reads a brief and the source code and writes one self-contained spec: the problem, current code state with exact line numbers, files to modify, step-by-step instructions and a testing checklist.
  • Build agent — implements the next unfinished spec exactly, without improvising, then commits and updates the progress tracker.
  • Test agent — runs the suite and records what passed and failed, but never fixes bugs itself.
  • Plan agent — reviews completed work against its specs, unblocks stuck specs and checks that upcoming file references are still accurate.

loop.sh runs one mode for N iterations (or until done) and run.sh chains spec generation and building. Each iteration handles exactly one spec. Completion is detected from project state, not agent output: the loop compares registry entries with spec files on disk, and counts unchecked items in an auto-generated IMPLEMENTATION_PLAN.md that uses [ ], [~], [x] and [?] status markers. The model is selectable (Opus, Sonnet or Haiku), and the repo ships example rules.md files for Flutter, Next.js and Python.

Status

Live.

Related