Ralph Zero

Ralph Orchestrator Skill with Feedback Learning

Ralph Zero - Your agents can now orchestrate Ralph using Skills!

Works with Claude Code, Cursor, Copilot, Amp, or any Agent Skills agent

Ralph Zero is an orchestrator system wrapped in an Agent Skills package over Geoffrey Huntley's Ralph Loop that implements complex multi-step features through looped agent sessions with error handling, process scheduling, memory management, and feedback learning.

System Architecture

graph LR
    subgraph inputs["1. You Provide"]
        direction TB
        prd_md["Feature Requirements<br/>prd.md"]
        config["Project Settings<br/>ralph.json"]
    end

    subgraph control["2. Ralph Zero Manages"]
        direction TB
        settings["Settings Handler<br/>reads your config"]
        tracker["Progress Tracker<br/>knows what's done"]
        memory["Memory Builder<br/>remembers patterns"]
        starter["Agent Starter<br/>launches fresh AI"]
        checks["Code Validator<br/>runs your tests"]
        teacher["Learning System<br/>saves discoveries"]
    end

    subgraph agent["3. AI Agent Works"]
        direction TB
        fresh["Clean Slate<br/>no prior context"]
        work["Writes Code<br/>documents learnings"]
    end

    subgraph saved["4. Data Saved"]
        direction TB
        tasks["prd.json<br/>task checklist"]
        history["progress.txt<br/>what happened"]
        patterns["AGENTS.md<br/>learned tricks"]
    end

    subgraph results["5. You Get"]
        direction TB
        code["Working Code<br/>tested & committed"]
        branch["Feature Branch<br/>ready to merge"]
    end

    prd_md -.->|converts to| tasks
    config --> settings
    
    tasks --> tracker
    tracker -->|picks next| memory
    patterns -.->|injects| memory
    history -.->|adds| memory
    
    memory -->|builds prompt| starter
    starter -->|spawns| fresh
    fresh --> work
    
    work -->|submits| checks
    checks -->|passed| code
    checks -->|failed| tracker
    
    work -.->|shares| teacher
    teacher -.->|updates| patterns
    tracker -.->|logs to| history
    
    code --> branch

    classDef inputClass fill:#e3f2fd,stroke:#1976d2,stroke-width:3px,color:#000
    classDef controlClass fill:#fff3e0,stroke:#f57c00,stroke-width:3px,color:#000
    classDef agentClass fill:#f3e5f5,stroke:#7b1fa2,stroke-width:3px,color:#000
    classDef savedClass fill:#e8f5e9,stroke:#388e3c,stroke-width:3px,color:#000
    classDef resultClass fill:#fce4ec,stroke:#c2185b,stroke-width:3px,color:#000

    class prd_md,config inputClass
    class settings,tracker,memory,starter,checks,teacher controlClass
    class fresh,work agentClass
    class tasks,history,patterns savedClass
    class code,branch resultClass

Loading

The Ralph Zero Loop

Start: You write a feature request, Ralph Zero breaks it into tasks

Loop: For each task, Ralph Zero:

1. Builds a memory package from past learnings
2. Starts a fresh AI agent with that memory
3. Agent writes code and documents what it learned
4. Validates code passes all your tests
5. Commits working code, saves learnings for next task

Result: Complete feature with tested code and accumulated knowledge

Overview

Ralph Zero transforms how AI agents build software by providing:

• Intelligent Orchestration - Python-based meta-layer manages stateless agent iterations
• Feedback Learning - System learns patterns via mandatory AGENTS.md documentation
• Quality-Driven Execution - Configurable gates (typecheck, tests, browser) enforce standards
• Universal Compatibility - Works with Claude Code, Cursor, Copilot, Amp, any Agent Skills agent
• Context Synthesis - Injects "memory" from AGENTS.md and progress.txt into each iteration

Installation

Universal Installation (Works with Most Agents)

git clone https://github.com/davidkimai/ralph-zero.git .agent/skills/ralph-zero
cd .agent/skills/ralph-zero
pip install -e .

Agent-Specific Installation

Choose the installation path based on your AI agent platform:

# Claude Code specific
git clone https://github.com/davidkimai/ralph-zero.git .claude/skills/ralph-zero

# Cursor specific
git clone https://github.com/davidkimai/ralph-zero.git .cursor/skills/ralph-zero

# VS Code Copilot specific
git clone https://github.com/davidkimai/ralph-zero.git .vscode/copilot/skills/ralph-zero

# Gemini CLI specific
git clone https://github.com/davidkimai/ralph-zero.git .gemini/skills/ralph-zero

# Amp specific
git clone https://github.com/davidkimai/ralph-zero.git .config/amp/skills/ralph-zero

After cloning to your preferred path:

cd <skills-directory>/ralph-zero
pip install -e .

Global Installation

For system-wide availability (works across all projects):

# Universal path
git clone https://github.com/davidkimai/ralph-zero.git ~/.agent/skills/ralph-zero
cd ~/.agent/skills/ralph-zero
pip install -e .

Quick Start

1. Create a PRD

Load the prd skill and create a PRD for adding task priority levels

The skill guides you through questions and generates tasks/prd-[feature-name].md.

2. Convert to JSON

Load ralph-convert skill and convert tasks/prd-task-priority.md to prd.json

This validates story structure and generates prd.json.

3. Run Ralph Zero

Via CLI:

ralph-zero run --max-iterations 50

Via Agent:

Load ralph-zero skill and run autonomous loop

Ralph Zero will:

• Create/checkout feature branch from PRD
• Work through stories in priority order
• Run quality gates after each story
• Commit only if gates pass
• Continue until all stories complete or max iterations reached

Architecture

┌─────────────────────────────────────────┐
│  Ralph Zero Orchestrator (Python)      │
│  • ConfigManager  • ContextSynthesizer  │
│  • StateManager   • QualityGates        │
│  • AgentInvoker   • LibrarianCheck      │
└──────────────┬──────────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │  Fresh Agent Instance│
    │  (Stateless)         │
    └──────────────────────┘
               │
               ▼
    ┌──────────────────────┐
    │  Persistent State    │
    │  • prd.json          │
    │  • AGENTS.md         │
    │  • progress.txt      │
    └──────────────────────┘

Configuration

Create ralph.json in your project root:

{
  "agent_command": "auto",
  "agent_mode": "cli", // or "api" (requires ANTHROPIC_API_KEY)
  "model": "claude-3-7-sonnet-20250219",
  "max_iterations": 50,
  "quality_gates": {
    "typecheck": {
      "cmd": "npm run typecheck",
      "blocking": true,
      "timeout": 60
    },
    "test": {
      "cmd": "npm test",
      "blocking": true,
      "timeout": 120
    }
  },
  "git": {
    "commit_prefix": "[Ralph]",
    "auto_create_branch": true
  },
  "librarian": {
    "check_enabled": true,
    "warning_after_iterations": 3
  }
}

See assets/examples/ralph.json for complete example.

CLI Commands

# Run autonomous development loop
ralph-zero run [--max-iterations N] [--config PATH]

# Validate prd.json and configuration
ralph-zero validate [--config PATH]

# Show current status
ralph-zero status [--verbose]

# Archive current run
ralph-zero archive <branch_name>

Features

• Stateless Iterations - Fresh agent per story prevents context overflow
• Synthesized Context - Unified "memory" works across all agents
• Quality Gates - Configurable checks (typecheck, tests, lint, browser)
• Cognitive Feedback - Librarian enforces AGENTS.md pattern documentation
• Atomic Stories - Each completable in one iteration (approximately 30min-2hrs)
• Observable State - All decisions logged to orchestrator.log
• Schema Validation - JSON schemas validate config and PRD structure
• Type Safety - Full type hints, mypy compatible
• Git Integration - Automatic branching, atomic commits
• Archiving - Previous runs archived when starting new features

Project Structure

ralph-zero/
├── SKILL.md                  # Main skill descriptor
├── README.md                 # This file
├── LICENSE                   # MIT license
├── pyproject.toml            # Python build configuration
├── requirements.txt          # Dependencies
│
├── scripts/                  # Python orchestrator
│   ├── ralph_zero.py         # CLI entry point
│   ├── orchestrator/         # Core modules
│   │   ├── config.py         # Configuration management
│   │   ├── state.py          # State management
│   │   ├── context.py        # Context synthesis
│   │   ├── agent.py          # Agent invocation
│   │   ├── quality.py        # Quality gates
│   │   ├── librarian.py      # Cognitive feedback
│   │   ├── core.py           # Main orchestrator
│   │   └── utils.py          # Utilities
│   └── schemas/              # JSON schemas
│       ├── ralph_config.schema.json
│       └── prd.schema.json
│
├── skills/                   # Sub-skills
│   ├── prd/                  # PRD generation
│   ├── ralph-convert/        # PRD to JSON conversion
│   └── ralph-execute/        # Execution (meta)
│
├── assets/                   # Examples and templates
│   ├── examples/
│   └── templates/
│
├── tests/                    # Test suite
│   ├── unit/
│   ├── integration/
│   └── fixtures/
│
└── docs/                     # Documentation

Development

Setup Development Environment

# Install with dev dependencies
pip install -e ".[dev]"

# Run type checking
mypy scripts/

# Run linting
ruff check scripts/

# Format code
black scripts/

# Run tests
pytest

Type Checking

Ralph Zero uses comprehensive type hints:

mypy scripts/orchestrator/

Target: 100% type checking pass

Testing

# Run all tests with coverage
pytest --cov=scripts --cov-report=html

# Run specific test file
pytest tests/unit/test_config.py

# Run with verbose output
pytest -v

Target: Greater than 80% code coverage

API Mode (Optional)

If you prefer direct API invocation instead of a local CLI:

1. Set agent_mode to api in ralph.json.
2. Export ANTHROPIC_API_KEY in your environment.
3. (Optional) pip install anthropic for best compatibility.

When agent_mode is cli (default) or no API key is present, Ralph Zero auto-detects a local agent (Claude CLI, Cursor, Amp, Copilot) and streams the full prompt via STDIN to ensure completion signals are honored.

Comparison to Original Ralph

Feature	Original Ralph	Ralph Zero
Orchestrator	Bash script	Python with types
Agent Support	Amp-specific	Universal (Agent Skills)
Context	Auto-handoff only	Synthesized (works everywhere)
State	Basic	Validated, atomic, logged
Quality Gates	Fixed	Configurable per project
Cognitive Feedback	Optional	Enforced (Librarian)
Observability	Basic logs	Structured JSON logs
Type Safety	N/A	Full mypy compatibility

Documentation

• SKILL.md - Main skill documentation (for agents)
• Architecture - System design deep dive
• Troubleshooting - Common issues and solutions
• Examples - Real-world usage examples
• Migration - Migrating from ralph v1

Examples

Complete working examples in assets/examples/:

• nextjs-feature.json - Next.js + TypeScript + Prisma
• python-api.json - FastAPI + pytest
• react-component.json - React component library

Contributing

Contributions welcome. Please:

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Ensure type checking passes (mypy)
5. Ensure tests pass (pytest)
6. Submit a pull request

Credits

Based on Geoffrey Huntley's Ralph pattern.

Inspired by:

• David Kim's ralph-for-agents - Agent Skills portability
• Snarktank's ralph - Cognitive feedback loops

License

MIT License - See LICENSE file

Links

• GitHub: https://github.com/davidkimai/ralph-zero
• Issues: https://github.com/davidkimai/ralph-zero/issues
• Agent Skills: https://agentskills.io

---

Status: Alpha - Active Development
Version: 0.1.0
Python: 3.10+
License: MIT