Skip to content

CLAUDE.md

Latest commit

 

History

History
72 lines (53 loc) · 2.88 KB

CLAUDE.md

File metadata and controls

72 lines (53 loc) · 2.88 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is Ralph?

Ralph is an autonomous AI agent loop that runs Claude Code repeatedly until all PRD items are complete. Each iteration spawns a fresh Claude Code instance with clean context. Memory persists via git history, progress.txt, and prd.json.

Commands

# Run Ralph (from directory containing prd.json)
./ralph.sh [max_iterations]     # Default: 10 iterations

# Run Ralph with BMAD agents (experimental)
./ralph-bmad.sh [max_iterations]

# Flowchart visualization
cd flowchart && npm install     # Install dependencies
cd flowchart && npm run dev     # Start dev server
cd flowchart && npm run build   # Build for production
cd flowchart && npm run lint    # Run ESLint

Architecture

Ralph consists of three main components:

  1. ralph.sh - Bash loop that spawns fresh Claude Code instances, checks for completion signal (<promise>COMPLETE</promise>), and handles archiving
  2. prompt.md - Instructions given to each Claude Code instance defining the autonomous workflow
  3. Skills (skills/prd/, skills/ralph/) - Skills for generating PRDs and converting them to JSON

Execution Flow

  1. Read prd.json and progress.txt
  2. Pick highest priority story where passes: false
  3. Implement that single story
  4. Run quality checks (typecheck, tests)
  5. Commit if checks pass
  6. Update prd.json to mark story as passes: true
  7. Append learnings to progress.txt
  8. Repeat until all stories pass

Key Design Principles

  • Fresh context per iteration: Each iteration starts with no memory of previous work. Context is reconstructed from git history, progress.txt, and prd.json.
  • Small tasks: Each story must be completable in one context window. If too big, split it.
  • Dependency ordering: Stories execute in priority order; earlier stories must not depend on later ones.
  • AGENTS.md updates: After each iteration, update relevant AGENTS.md files with discovered patterns for future iterations.

File Structure

File Purpose
ralph.sh Main bash loop spawning Claude Code instances
ralph-bmad.sh Experimental BMAD integration version
prompt.md Instructions for each Claude Code instance
prd.json User stories with passes status
progress.txt Append-only learnings between iterations
skills/prd/SKILL.md PRD generation skill
skills/ralph/SKILL.md PRD-to-JSON conversion skill
flowchart/ React Flow visualization (Vite + TypeScript)
docs/bmad-integration.md BMAD integration documentation

Flowchart App

The flowchart/ directory contains an interactive React Flow visualization built with:

  • React 19 + TypeScript
  • Vite 7
  • @xyflow/react for flow diagrams

Deployed to GitHub Pages at https://snarktank.github.io/ralph/