namuh-eng/ralph-to-ralph

---

Note for AI agents: This README is structured as step-by-step instructions you can follow to set up and run the pipeline for a user. Each step includes verification commands. If you’re an agent reading this, start at Setup.

---

Proof It Works

We pointed Ralph-to-Ralph at resend.com during Ralphthon Seoul 2026 and walked away (see the result: opensend):

The clone sends real emails via AWS SES, verifies real domains, auto-configures DNS via Cloudflare, and deployed itself to AWS App Runner. It placed 2nd at the hackathon.

---

How It Works

A single watchdog orchestrator (ralph/ralph-watchdog.sh) drives four phases. It auto-restarts failures, tracks token cost against a budget cap, refuses to enter QA until the workspace proves it builds, and detects zero-progress QA stalls. Up to 5 build-QA cycles per feature.

Every loop phase is backed by either Codex (default, reasoning_effort=low — empirically best across all four loops) or Claude. You pick during onboarding; the choice lands in ralph-config.json as inspectAgent / buildAgent / qaAgent / architectureAgent (plus reasoningEffort for codex), and each loop reads its own field at runtime.

---

Prerequisites

You can install these ahead of time, or onboarding will prompt you when it needs them.

Coding CLI

The agent that drives Inspect, Architecture, Build, and QA. You pick one during onboarding and the choice applies to every loop.

Codex at low reasoning effort is the empirical best across every loop and is the default. You can override per phase by editing inspectAgent / buildAgent / qaAgent / architectureAgent in ralph-config.json after onboarding — the loop scripts read those fields at runtime via ralph/lib/agent-runner.sh.

Browser Agent

Used by Inspect and QA to drive the target product and your clone.

Anything else with a CLI works, but the inspect and QA prompts are tuned for Ever CLI — expect rougher edges with other agents.

Cloud CLI

Pick one and authenticate it. Onboarding will ask if it doesn’t find one already installed.

Want Railway, Fly.io, Render, or self-hosted? Pick “custom” during onboarding and describe your stack — onboarding generates a stack-specific preflight script.

---

Stack

Onboarding picks one of three first-class stacks based on your answers (language + framework), writes the choice to ralph-config.json, and runs the matching template’s setup script.

The TypeScript template ships the most pre-wired tooling — Drizzle for DB, Playwright for E2E, full make test-e2e and make db-push targets. Python and Go templates are minimal scaffolds; the build agent installs database drivers and feature-specific dependencies as the PRD requires them.

After onboarding, .ralph-setup-done records the template name and BUILD_GUIDE.md (in the repo root) has stack-specific build instructions. Templates live in .claude/skills/ralph-to-ralph-onboard/templates/.

---

Setup

Follow these steps in order. Each step has a verification command — run it before moving to the next step.

Step 1: Clone and install

Step 1 — Fork this repo on GitHub (top-right “Fork” button). This gives you your own copy to push SaaS features into, and lets you pull pipeline improvements from upstream later.

Step 2 — Clone your fork:

git clone https://github.com/YOUR_USERNAME/ralph-to-ralph.git
cd ralph-to-ralph

# Optional: track upstream for future pipeline improvements
git remote add upstream https://github.com/namuh-eng/ralph-to-ralph.git

Then continue:

Verify:

ls ralph-config.json 2>/dev/null || echo "No config yet (expected — created by onboarding)"
ls .ralph-setup-done 2>/dev/null || echo "Stack not set up yet (expected — done by onboarding)"

Step 2: Configure environment

cp .env.example .env

Then set these values in .env:

Verify:

# Check that .env exists and has content
test -f .env && echo ".env exists" || echo "ERROR: .env missing"
grep -c '=' .env  # Should show number of configured variables

Step 3: Onboard a target product

Onboarding researches the target product, configures the stack, installs dependencies, and starts the build loop.

Recommended: Onboarding skill inside a coding agent

Open this repo in your coding agent and invoke the onboarding skill:

The agent researches the product live, explains what needs to be set up in plain English, walks you through each decision, installs anything missing (browser agent, cloud CLI), and verifies your setup before kicking off the build loop. This is the path we recommend — it adapts to whatever’s already on your machine.

Alternative: Script

./ralph/onboard.sh

A bash script that asks for target URL, clone name, cloud provider, deploy preference, and browser agent — then hands off to Claude for research and config generation. Useful for non-interactive environments. Produces the same ralph-config.json as the skill.

Verify onboarding completed:

# Config exists and has required fields
python3 -c "
import json, sys
c = json.load(open('ralph-config.json'))
required = ['targetUrl', 'targetName', 'language', 'stackProfile']
missing = [k for k in required if k not in c]
if missing:
    print(f'FAIL: missing fields: {missing}', file=sys.stderr)
    sys.exit(1)
print(f'OK: target={c[\"targetUrl\"]}, lang={c[\"language\"]}, stack={c[\"stackProfile\"]}')
"

# Stack is set up and project compiles
test -f .ralph-setup-done && echo "Stack: $(cat .ralph-setup-done)"
make check && make test

---

Architecture Reference

Pipeline Flow

./ralph/onboard.sh                      # Onboard → ralph-config.json
    ↓
./ralph/ralph-watchdog.sh               # Orchestrator (cost cap, build-proof gate)
    ↓
┌─────────────────────────────────────────────────────┐
│  Phase 1: INSPECT (Claude + Ever CLI)               │
│  → Browse target, scrape docs (Scrapling)           │
│  → Generate prd.json (50+ features)                 │
└────────────────────────┬────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│  Phase 1.5: ARCHITECTURE (Claude architect)         │
│  → PRD → architecture-decisions.json                │
│  → Topology, data model, infra, auth, packaging     │
└────────────────────────┬────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│  Phase 2: BUILD (Claude, one feature at a time)     │
│   ├─ Phase 2.5 Structure: vertical slice ≤4 phases  │
│   ├─ TDD: tests first, then implement               │
│   └─ make check && make test → commit → push        │
└────────────────────────┬────────────────────────────┘
                         ↓
┌─────────────────────────────────────────────────────┐
│  Phase 3: QA (Codex + Ever CLI)                     │
│  → Functional / API Contract / Security / A11y      │
│  → Fix and re-test (up to 5 cycles)                 │
└────────────────────────┬────────────────────────────┘
                         ↓
                All features pass? → Deploy
                No?                → Back to Phase 2

File Map

ralph-to-ralph/
├── ralph/
│   ├── onboard.sh                 # Onboarding script (alternative to the skill)
│   ├── onboard-prompt.md          # Onboarding agent instructions
│   ├── ralph-watchdog.sh          # Orchestrator: inspect → architecture → build → QA
│   ├── inspect-ralph.sh           # Phase 1 runner
│   ├── build-ralph.sh             # Phase 2 runner
│   ├── qa-ralph.sh                # Phase 3 runner — assembles prompt from ralph/qa/*.md
│   ├── inspect-prompt.md          # Inspect agent instructions
│   ├── inspect-spec.md            # Inspection strategy
│   ├── architecture-prompt.md     # Architect agent instructions (Phase 1.5)
│   ├── build-prompt.md            # Build agent instructions
│   ├── structure-prompt.md        # Vertical-slicing instructions (Phase 2.5, invoked by Build)
│   ├── qa/                        # Modular QA prompts: base, api, security, a11y, footer
│   ├── pre-setup.md               # Pre-configured setup (read by all agents)
│   ├── ever-cli-reference.md      # Ever CLI command reference
│   ├── deployment-profiles.json   # fast-starter / production-aws / advanced-custom
│   ├── ralph-state.schema.json    # Watchdog state schema (validated by `make validate`)
│   ├── ralph-state.template.json  # Empty state template
│   └── docs/                      # Architecture diagram + supporting docs
├── .claude/skills/
│   └── ralph-to-ralph-onboard/    # Interactive onboarding skill (Claude Code)
│       ├── SKILL.md               # Skill definition + flow
│       ├── references/            # Long-form prompt fragments
│       ├── scripts/setup-stack.sh # Generic stack scaffolding script
│       └── templates/             # Stack templates: typescript-nextjs, python-fastapi, go-chi
├── schemas/                       # JSON schemas validated by `make validate`
│   ├── ralph-config.schema.json
│   ├── prd-item.schema.json
│   ├── qa-report-entry.schema.json
│   └── architecture-decision.schema.json
├── scripts/
│   ├── start.sh                   # Thin restart wrapper around the watchdog
│   ├── preflight.sh               # Provisions cloud infrastructure
│   ├── generate-demo-keys.sh      # Generates API keys for demos
│   ├── validate-schemas.mjs       # Validates state files against JSON schemas
│   └── scrape-docs.py             # Deterministic doc scraper (Scrapling + trafilatura)
├── src/                           # Source code (scaffolded by onboarding)
├── tests/                         # Unit tests + factories + watchdog verification
├── tests/e2e/                     # E2E tests
├── packages/sdk/                  # SDK package (if target product has one)
├── hack/run_silent.sh             # Output formatter used by Makefile
├── agent_docs/learnings/          # Long-running notes from past clone runs
├── docker-compose.dev.yml         # Local dev stack: Postgres, Redis, Mailpit
├── .env.example                   # Documented environment variables
├── ralph-config.json              # Generated by onboarding (single source of truth)
├── prd.json                       # Product requirements (generated by Inspect phase)
├── BUILD_GUIDE.md                 # Stack-specific build instructions (from template)
├── CLAUDE.md                      # Instructions for Claude agents (Build)
├── AGENTS.md                      # Instructions for Codex agent (QA)
├── Makefile                       # Contract targets — real recipes appended by onboarding
└── .ralph-setup-done              # Marker file — contains template name

Commands

Pass VERBOSE=1 (or use make check-verbose / test-verbose) to see full output instead of the silent-on-success summary.

Agent Roles

The QA agent uses progressive disclosure — qa-ralph.sh assembles the prompt from the modules above based on feature category (auth, crud, infrastructure, settings, etc.). Not every feature runs all four sub-phases.

What Gets Built

The pipeline produces a fully functional, deployed product — not a mockup.

---

Customization

Changing the target product

Re-run onboarding. Easiest in your coding agent:

For a clean slate (clears ralph-config.json and .ralph-setup-done), use the script form:

./ralph/onboard.sh --reset   # Clear previous config
./ralph/onboard.sh            # Start fresh

Modifying agent behavior

The pipeline is controlled by prompt files:

Running phases individually

The watchdog (ralph/ralph-watchdog.sh) is the production entry point — it handles process-level restarts, cost caps, build-proof gating before QA, and stall detection. Run a single phase only when iterating manually:

./ralph/inspect-ralph.sh    # Phase 1 only — generate / refresh prd.json
./ralph/build-ralph.sh                  # Phase 2 only — needs prd.json
./ralph/qa-ralph.sh                     # Phase 3 only — needs a built clone

These scripts have no process-level restart logic — if they crash, they stay crashed. Fine for short sessions; for unattended end-to-end runs, always use the watchdog.

---

FAQ

---

Contributing

We welcome contributions — bug fixes, new features, documentation, or new target product test runs.

1. Fork the repository
2. Create a feature branch (git checkout -b my-feature)
3. Make your changes
4. Run make check && make test to verify
5. Commit with a clear message
6. Open a pull request

If you’re unsure about a change, open an issue first to discuss it.

Team

Ralph-to-Ralph was built by:

• Jaeyun Ha — github.com/jaeyunha
• Ashley Ha — github.com/ashley-ha

Built at Ralphthon Seoul 2026.

---

Inspiration

Inspired by @GeoffreyHuntley’s “software eats itself” post.

License

Apache License 2.0 — use it, modify it, ship it. Includes an explicit patent grant.