docs: Add CLAUDE.md - Comprehensive AI assistant guide for Ralph

[NathanWCarlson]

Summary

Add comprehensive documentation for AI assistants working with Ralph, the autonomous AI agent loop system for Amp CLI. This guide provides essential context about the project architecture, conventions, and best practices for both developing Ralph itself and using it in other projects.

Key Changes

• New CLAUDE.md file with complete Ralph system documentation including:
  • Project overview and repository structure
  • Key concepts (fresh context per iteration, memory persistence hierarchy)
  • Story sizing and ordering guidelines (critical for success)
  • Command reference for running Ralph and developing the flowchart
  • Technology stack details
  • PRD format specification with acceptance criteria requirements
  • Detailed conventions for AI assistants working on Ralph vs. using Ralph
  • Progress report format and codebase patterns documentation
  • Quality requirements and stop conditions
  • Archiving and deployment information
  • Common patterns for modifying core components

Notable Details

• Emphasizes the "fresh context per iteration" model as central to Ralph's design
• Provides clear story sizing guidance to prevent context window overflows
• Documents the three-tier memory persistence hierarchy (prd.json → progress.txt → git)
• Includes specific formatting requirements for progress reports and codebase patterns
• References Geoffrey Huntley's Ralph pattern as the conceptual foundation
• Covers both the bash orchestration layer and the React flowchart visualization
• Provides debugging commands and quality gate requirements

This documentation serves as the primary reference for AI assistants (like Claude) to understand and work effectively with the Ralph system.

[greptile-apps]

Greptile Overview

Greptile Summary

Added comprehensive CLAUDE.md documentation for AI assistants working with Ralph. The guide accurately documents the autonomous agent loop architecture, fresh context model, memory persistence hierarchy, and best practices for both developing Ralph and using it in projects.

Key Strengths:

• Accurate technical details verified against actual implementation (ralph.sh, prompt.md, prd.json.example, package.json)
• Clear distinction between working on Ralph itself vs using Ralph in other projects
• Concrete story sizing examples with the critical "2-3 sentences" rule to prevent context overflow
• Well-documented three-tier memory persistence (prd.json → progress.txt → git)
• Comprehensive command reference for running Ralph and developing the flowchart
• Proper formatting requirements for progress reports and codebase patterns
• Quality requirements and stop conditions clearly defined

Documentation Alignment:

• Complements existing AGENTS.md (concise agent instructions) and README.md (user documentation)
• CLAUDE.md serves as the detailed reference specifically for AI assistants
• All file paths, commands, and technical specifications verified as accurate
• Technology stack versions match actual dependencies (React 19, @xyflow/react 12, Vite 7, TypeScript 5.9)

Confidence Score: 5/5

• This PR is safe to merge with no risks - adds high-quality documentation only
• Perfect score because this is a pure documentation addition with no code changes, all technical details are accurate when verified against implementation, the documentation is comprehensive and well-structured, and it provides essential guidance for AI assistants working with Ralph
• No files require special attention

Important Files Changed

Filename	Overview
CLAUDE.md	Comprehensive AI assistant documentation added - accurate, well-structured, and aligned with existing guides

Sequence Diagram

sequenceDiagram
    participant Dev as Developer
    participant Ralph as ralph.sh
    participant Amp as Amp Instance
    participant Git as Git Repository
    participant PRD as prd.json
    participant Progress as progress.txt
    
    Dev->>Ralph: ./ralph.sh [max_iterations]
    
    loop For each iteration (max 10)
        Ralph->>PRD: Read prd.json
        Ralph->>Amp: Spawn fresh Amp instance with prompt.md
        
        Amp->>PRD: Read task list
        Amp->>Progress: Read Codebase Patterns section
        Amp->>Git: Check current branch
        
        Amp->>Amp: Pick highest priority story (passes: false)
        Amp->>Amp: Implement single user story
        Amp->>Amp: Run quality checks (typecheck, lint, test)
        
        alt Quality checks pass
            Amp->>Git: Commit with format: feat: [Story ID] - [Title]
            Amp->>PRD: Update story (passes: true)
            Amp->>Progress: Append progress report with learnings
            Amp->>Amp: Check if all stories complete
            
            alt All stories complete
                Amp->>Ralph: Output <promise>COMPLETE</promise>
                Ralph->>Dev: Exit successfully
            else More stories pending
                Amp->>Ralph: End iteration normally
                Ralph->>Ralph: Continue to next iteration
            end
        else Quality checks fail
            Amp->>Progress: Document failure and learnings
            Ralph->>Ralph: Continue to next iteration
        end
    end
    
    Ralph->>Dev: Max iterations reached or complete

Loading