ralph-node

A custom implementation of the Ralph Loop for Node.js — a test-gated, autonomous AI development cycle that turns PRDs into working code.

This is my Ralph loop. There are many like it, but this one is mine.

1. PRD-Driven Development — You write requirements as markdown tasks with test annotations
2. Test Backpressure — Before the AI agent runs, tests are generated from the PRD & reviewed to ensure implementations pass validation
3. Autonomous Implementation — An LLM agent reads the PRD, implements code, and iterates until tests pass
4. Automated Validation — Jest unit tests and Playwright E2E tests gate each task completion
5. Commit & Archive — Completed tasks are checked off, code is committed, and the ledger is updated

Why this exists

This repo is an exercise in applied AI engineering — specifically in designing systems where LLM agents operate reliably under constraints. The goals:

• Create my own implementation of the Ralph Loop based on my readings and experience
• Practice writing PRDs that AI agents can execute without human intervention
• Optimize prompts and constraints for deterministic, test-driven AI output
• Build a forkable starting point for generating different project types (Next.js, React + Vite, static sites) by swapping in a new PRD

How it works

Pick a starting point:

• From scratch — fork this repo and run nvm use && bash init.sh to bootstrap. This lets you optimize the initial PRD and infrastructure.
• From a fork — browse existing forks and start from one that already has an initialized project. This saves tokens by iterating from a checkpoint instead of regenerating from zero.

Any repo — this one or a fork — can serve as the starting point for the next iteration.

Run the Ralph Loop:

1. Write a PRD (PRD.md) with checkbox tasks:

   - [ ] Create a responsive landing page `[test: npx playwright test tests/landing.spec.ts]`
   - [ ] Add dark mode toggle `[test: npx playwright test tests/theme.spec.ts]`

2. Generate test backpressure — failing tests that define "done", which are human verified and optimized post-creation:

   npm run backpressure

3. Run the loop — the agent implements until all tests pass:

   npm run ralph

Key design decisions

• Test-gated commits: code only lands if validation passes — no manual review in the loop
• Targeted backpressure: each PRD task can specify its own test command via [test: ...], so the agent gets fast, focused feedback instead of running the full suite
• Stateless agents with structured handoff: agents have no memory between cycles — context is explicitly injected via a scratchpad (MEMORY.md) and an append-only ledger (.agent-ledger.jsonl)
• Infrastructure isolation: the loop scripts and prompts are protected from agent modification via .aignore and permission settings

Stack

Tool	Role
Claude Code	Default AI engine
OpenCode	Alternative AI engine
Jest	Unit testing
Playwright	E2E testing
Biome	Linting and formatting

License

Apache 2.0