Ralph Zero

Ralph Zero: Next-Generation Autonomous Development

Ralph Zero is an intelligent orchestration system that autonomously implements complex features by breaking them into verifiable stories and executing each through fresh agent iterations with comprehensive quality verification and cognitive feedback loops.

What Makes Ralph Zero Different

Ralph Zero is not the original bash-based Ralph implementations. It is a complete reimagining that combines:

1. Universal Agent Compatibility - Works with any Agent Skills-compatible agent (Claude Code, Cursor, Copilot, Amp)
2. Python-Based Orchestration - Robust meta-layer with intelligent state management and context synthesis
3. Cognitive Feedback Loops - System learns and improves via mandatory AGENTS.md pattern documentation
4. Context Synthesizer - Universal "memory injection" that works across all agents, not just those with auto-handoff
5. Quality-Driven Execution - Configurable gates (typecheck, tests, browser verification) enforce standards

When to Use Ralph Zero

✅ Use Ralph Zero when:

• Implementing features with 3+ atomic, verifiable user stories
• Working on features too complex for single agent session
• Need autonomous execution with quality guarantees
• Want the system to learn patterns as it works
• Have well-defined acceptance criteria per story
• Project has automated quality checks (typecheck, tests)

❌ Don't use for:

• Single-file changes or quick fixes
• Exploratory coding without clear requirements
• Projects without type safety or automated tests
• Urgent hotfixes requiring immediate human oversight

Quick Start

1. Installation

Project-local installation (recommended):

# From your project root
git clone https://github.com/davidkimai/ralph-zero.git .claude/skills/ralph-zero
cd .claude/skills/ralph-zero
pip install -e .

Global installation:

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

For other agents, adjust the skills directory:

• Cursor: ~/.cursor/skills/ralph-zero
• VS Code Copilot: ~/.vscode/copilot/skills/ralph-zero
• Amp: ~/.config/amp/skills/ralph-zero

2. Create a PRD

Use the prd sub-skill to generate structured requirements:

Load the prd skill and create a PRD for [describe your feature]

Example:

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

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

3. Convert PRD to prd.json

Use the ralph-convert sub-skill:

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

This validates story structure, checks dependencies, and generates prd.json with all stories marked incomplete.

4. Run Ralph Zero

Via CLI (direct execution):

ralph-zero run --max-iterations 50

Via your agent:

Load ralph-zero skill and run autonomous loop with max 50 iterations

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
• Update prd.json and progress.txt
• Continue until all stories pass or max iterations reached

How It Works

Architecture Overview

┌─────────────────────────────────────────────┐
│     Python Orchestrator (ralph_zero.py)    │
│                                             │
│  • Context Synthesizer (AGENTS.md + progress)
│  • Quality Gates (typecheck, tests, etc.)  │
│  • State Manager (atomic prd.json updates) │
│  • Librarian Check (enforces learning)     │
└─────────────────┬───────────────────────────┘
                  │
                  ▼
      ┌───────────────────────┐
      │  Fresh Agent Instance │
      │  (stateless per story)│
      └───────────────────────┘
                  │
                  ▼
      ┌───────────────────────┐
      │   Persistent State    │
      │  • prd.json (tasks)   │
      │  • AGENTS.md (patterns)
      │  • progress.txt (history)
      └───────────────────────┘

Key Principles

1. Stateless Iterations: Each story gets a fresh agent instance with no conversation memory
2. Synthesized Context: Orchestrator injects AGENTS.md + recent progress as "memory"
3. Quality Gates: Code must pass all blocking checks before commit
4. Cognitive Feedback: Agents update AGENTS.md with discovered patterns
5. Atomic Stories: Each story completable in one context window (~30min-2hrs)

Sub-Skills

Ralph Zero includes helper skills for the full autonomous development workflow:

• prd - Generate structured PRD from feature description
• ralph-convert - Convert markdown PRD to prd.json
• ralph-execute - Execute autonomous development loop

Configuration

Create ralph.json in your project root:

{
  "agent_command": "auto",
  "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

Ralph Zero provides a comprehensive CLI:

# Run autonomous 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]

# Manually archive current run
ralph-zero archive <branch_name>

Project Files

Ralph Zero creates and manages these files:

Story Requirements

For Ralph Zero to work effectively:

✅ Right-Sized Stories

Each story must be completable in one iteration.

Good examples:

• "Add status column to database with migration"
• "Create StatusBadge component with color logic"
• "Add filter dropdown to task list header"

Too large (split these):

• "Build entire dashboard" → 5-10 smaller stories
• "Add authentication system" → 8-12 smaller stories

✅ Verifiable Acceptance Criteria

Every story must include "Typecheck passes" as final criterion.

Good criteria:

• "Add status column: 'pending' | 'in_progress' | 'done'"
• "Badge colors: gray=pending, blue=in_progress, green=done"
• "Typecheck passes"

Bad criteria (too vague):

• "Works correctly"
• "Good UX"
• "Handles edge cases"

✅ Dependency Ordering

Stories execute in priority order. No forward dependencies.

Correct order:

1. Database schema/migrations
2. Backend logic/API
3. UI components
4. Dashboards/views

Cognitive Feedback Loop

Ralph Zero enforces learning via the Librarian Check:

• Tracks code changes vs AGENTS.md updates
• Warns if patterns not documented after 3 iterations
• Ensures knowledge compounds across iterations

Good AGENTS.md entries:

## Pattern: SQL Aggregations
Use `sql<number>` template literal for complex queries
Example: `const result = await sql<number>`SELECT SUM(amount) FROM...``

## Gotcha: Migration Order
Always run migrations before starting dev server.
Stale schema causes confusing typecheck errors.

Advanced Usage

Parallel Execution

Use git worktrees for concurrent feature development:

git worktree add ../feature-a ralph/feature-a
git worktree add ../feature-b ralph/feature-b

cd ../feature-a && ralph-zero run
cd ../feature-b && ralph-zero run

Custom Quality Gates

Add project-specific checks to ralph.json:

{
  "quality_gates": {
    "security-scan": {
      "cmd": "npm audit --audit-level=moderate",
      "blocking": false,
      "timeout": 30
    },
    "bundle-size": {
      "cmd": "./scripts/check-bundle-size.sh",
      "blocking": true,
      "timeout": 45
    }
  }
}

Resume Interrupted Runs

Ralph Zero automatically resumes from current prd.json state:

ralph-zero run  # Continues where it left off

Troubleshooting

Issue: prd.json not found

Solution: Create prd.json using ralph-convert skill or manually

Issue: Agent repeatedly fails same story

Solution: Story is too large. Split into 2-3 smaller stories

Issue: Quality checks failing

Solution: Verify commands in ralph.json match your project setup

Issue: Context overflow warnings

Solution: Increase context_config.token_budget or reduce max_progress_lines

For more help, see docs/TROUBLESHOOTING.md.

Examples

Complete working examples in assets/examples/:

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

Comparison: Ralph Zero vs Original Ralph

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

• Documentation: docs/
• Architecture: SPEC_RALPH_ZERO.md
• Issues: https://github.com/davidkimai/ralph-zero/issues
• Agent Skills Spec: https://agentskills.io/specification