RALPH v5 — Discovery Brief

1. What Is Ralph Today?

Ralph is Forge's autonomous coding agent — an external bash loop that spawns fresh Claude Code instances per task. It's the build factory that executes queued coding work while Jason sleeps, works on other things, or is between sessions.

Current Architecture (v4 — Production)

┌─────────────────────────────────────────────┐
│ systemd timer (every 60s)                    │
│ → ralph-poller.sh                            │
│   ├── Check Supabase ralph_queue             │
│   ├── Call Gatekeeper (:5015/v1/gate)        │
│   ├── Atomic task claim (PATCH status)       │
│   └── nohup ralph.sh "project" "task" &      │
└─────────────────────────────────────────────┘
           ↓ spawns fresh process
┌─────────────────────────────────────────────┐
│ ralph.sh (672 lines)                         │
│ ├── Model Router (4-tier cascade)            │
│ │   ├── T0: Claude Max CLI (free, preferred) │
│ │   ├── T1: Ollama Qwen 7B (free, simple)   │
│ │   ├── T2: LiteLLM API (paid, budget-capped)│
│ │   └── T3: Poll & Wait (24h max)           │
│ ├── Self-healing (env strip, escalation)     │
│ ├── Circuit breaker (3 consecutive fails)    │
│ ├── Factory Pulse events → Supabase          │
│ ├── Host mode (forge) / Docker mode (other)  │
│ └── Queue drain (chain next task on success) │
└─────────────────────────────────────────────┘
           ↓ fresh Claude instance
┌─────────────────────────────────────────────┐
│ claude -p "task description"                 │
│ ├── Fresh 200k context window                │
│ ├── Reads CLAUDE.md + skills automatically   │
│ ├── Executes task, writes code, runs tests   │
│ ├── Git commit on success                    │
│ └── Exits → loop continues                   │
└─────────────────────────────────────────────┘

What's Working

• External bash loop with fresh context per task (Joe's #1)
• 4-tier model cascade with budget controls
• Gatekeeper quality gate (score 0-100, decomposition)
• Self-healing: env var stripping, exponential backoff, circuit breaker
• Factory Pulse observability (events → Supabase → Dashboard)
• Dashboard UI: Ralph status card, task queue, model tier display
• Systemd timer: poller runs every 60s reliably
• Anti-loop protection: spawn tracker (3 fails → mark failed)
• Stale task recovery: reset orphaned "running" tasks
• Queue drain: chain tasks on success without poller delay
• Budget caps: $10/day, $3/task via config/budget.yaml

What's NOT Working / Missing

• Tasks frequently fail quickly (logs show claim → spawn → die within 60s)
• Model routing struggles when Claude Max is occupied by interactive session
• No automated PRD/planning pipeline (relies on manual /discover → /design → /plan)
• No research agent spawning before building
• No formal UAT/QA loop
• No multi-node capability (single VPS only)
• No progress tracking within a task (just pass/fail per attempt)
• Gatekeeper decomposition queues subtasks but doesn't always work cleanly
• Trust levels exist in schema but aren't enforced progressively

2. History: From PRD v2.1 to v4

January 2026: PRD v2.1 Written

• Proposed 13 Python FastAPI microservices
• Inspired by: GSD (4-doc structure), Alex Dunlop (external loop), Joe Njenga (7 mistakes), Claude Code patterns
• Target: Windows local dev (C:\Dev\ralph-orchestrator)
• 6 of 8 foundation services were actually built (Tasks 1-6)
• Services: claude-service, bash-service, github-service, router-service, credit-service, skills-service

January-February 2026: Architecture Pivot

• Moved from Windows local → Hetzner VPS (Linux)
• Pivoted from Python FastAPI services → Bash scripts + Claude Code CLI
• Why: Claude Code CLI provides everything the services were wrapping (bash execution, git operations, code editing, testing)
• Ralph v3 built: Self-healing, external bash loop, systemd integration
• Ralph v4 added: 4-tier model cascade, Factory Pulse, Gatekeeper

What the PRD Got Right

• External bash loop architecture (Joe's #1) — built and working
• Fresh context per task — built and working
• Budget enforcement — built and working
• Max iterations (Joe's #6) — built (5 attempts default)
• Feedback loops / tests (Joe's #5) — built (test detection per mode)

What the PRD Proposed That Was Superseded

What the PRD Proposed That's Still Unbuilt

3. Competitive Landscape: Build Orchestrators in 2026

What Exists Now

Ralph's Unique Position

Ralph is the only build orchestrator that:

1. Uses queue-based task dispatch (not just PR-based or chat-based)
2. Has 4-tier model cascade with budget controls
3. Has self-healing (circuit breaker, env healing, escalation)
4. Integrates with a personal AI operating system (Forge)
5. Is already in production processing real tasks
6. Supports both host and containerized execution modes

Key Insight

Ralph isn't competing with Devin or Cursor — it's a personal build factory optimized for one operator (Jason). The goal isn't general-purpose autonomy but leveraged output for a specific operator.

4. Gap Analysis: What Ralph v5 Should Address

Gap 1: No Planning Pipeline (CRITICAL)

Current: Tasks are manually written and queued. Quality depends entirely on how well the human wrote the task description.

Joe's #4: "Ralph amplifies whatever you feed it — garbage in, garbage out."

Impact: Bad task descriptions → wasted tokens, failed attempts, scope creep.

Solution: Automated PRD pipeline — task description → structured plan → decomposed subtasks → approval gate → execution.

Gap 2: No Research Before Building (HIGH)

Current: Ralph jumps straight into coding. No exploration of existing patterns, libraries, or architecture.

PRD v2.1 proposed: 4 parallel research agents (stack, feature, architecture, pitfall).

Impact: Suboptimal implementations, reinventing wheels, missing best practices.

Solution: Pre-execution research phase, at minimum a quick codebase scan + existing pattern check.

Gap 3: No UAT/QA Loop (HIGH)

Current: Tests pass → task complete. No human verification step. No auto-debug on failure feedback.

Impact: Tasks "pass" but don't actually work as intended. No learning from rejection.

Solution: Optional UAT gate — present changes, collect feedback, auto-debug if rejected.

Gap 4: Single Node Only (MEDIUM)

Current: Ralph runs only on the Hetzner VPS at 178.156.253.142.

Jason mentioned: "Working in a different session on standing up as a separate node."

Impact: Can't scale, can't run while VPS is busy, can't run on other machines.

Solution: Distributed Ralph — queue-based architecture already supports this. Need: API key management, git repo access, result reporting.

Gap 5: Progressive Trust Not Enforced (MEDIUM)

Current: trust_level column exists in ralph_queue but is never checked.

Joe's #7: "Don't start with the jackhammer."

Impact: All tasks treated equally — no distinction between supervised and unsupervised.

Solution: Enforce trust levels: supervised (human watches) → attended (periodic check) → unattended (overnight).

Gap 6: No Task Progress Tracking (LOW)

Current: Binary pass/fail per attempt. No visibility into what Ralph is doing mid-task.

Impact: Can't tell if task is 90% done or completely stuck until it finishes.

Solution: Progress events (started, coding, testing, reviewing) emitted during execution.

Gap 7: Subagent Architecture (LOW)

Current: Single Claude instance per task. No planner/coder/reviewer/tester decomposition.

PRD v2.1 proposed: Full subagent architecture with tool scoping.

Impact: Context budget less efficient, no separation of concerns.

Solution: Claude Code's Task tool already supports subagents. Could be enabled via CLAUDE.md instructions.

5. Build vs Buy vs Extend

Recommendation: EXTEND (v4 → v5)

Ralph v4 is production-tested and working. The foundation is solid:

• External loop
• Fresh context
• Budget controls
• Self-healing
• Observability
• Dashboard

Don't rebuild. Extend what works. The PRD v2.1's 13-microservice architecture was the right instinct but over-engineered — Claude Code CLI already provides most of those capabilities natively.

What to Build (v5 Additions)

What NOT to Build

• Python FastAPI microservices for things Claude Code already does
• Docker-compose orchestration (systemd works fine)
• PowerShell/Windows support (VPS is Linux, that ship sailed)
• Custom PII detection (Presidio already handles this)
• Custom model routing (ClawdRouter + model-router.sh already handle this)
• Custom git service (Claude Code + deploy.sh already handle this)

6. Proposed Architecture: Ralph v5

┌─────────────────────────────────────────────────────────┐
│ RALPH v5: Planned Autonomous Build Factory               │
│                                                          │
│ NEW: Planning Pipeline                                   │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│ │ Task     │→│ Research  │→│ Plan     │→│ Approve  │    │
│ │ Intake   │ │ (quick)   │ │ Decompose│ │ Gate     │    │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
│                                           ↓              │
│ EXISTING: Execution Engine (v4)                          │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐    │
│ │ Poller   │→│ Gatekeeper│→│ Ralph.sh │→│ Claude   │    │
│ │ (60s)    │ │ (quality) │ │ (cascade)│ │ (fresh)  │    │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘    │
│                                           ↓              │
│ NEW: Quality Loop                                        │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐                  │
│ │ Tests    │→│ UAT Gate │→│ Deploy   │                  │
│ │ (auto)   │ │ (optional)│ │ (merge)  │                  │
│ └──────────┘ └──────────┘ └──────────┘                  │
│                                                          │
│ NEW: Multi-node (Future)                                 │
│ ┌──────────┐ ┌──────────┐                                │
│ │ Node 1   │ │ Node 2   │  ← Same queue, different VPS  │
│ │ (Hetzner)│ │ (Future) │                                │
│ └──────────┘ └──────────┘                                │
└─────────────────────────────────────────────────────────┘

7. Risks & Mitigations

8. Joe's 7 Mistakes — Current Status

9. Next Steps

1. Design Phase (/design) — Architecture for v5 additions (planning pipeline, UAT gate, progressive trust)
2. Plan Phase (/plan) — Break into Ralph-executable tasks
3. Build — Ralph builds Ralph v5 (meta! but the right approach since v4 works)

Key Decision for Jason

Multi-node: Do you want Ralph v5 to support running on a second VPS? This is the biggest architectural decision and affects everything else. If yes, the queue-based architecture already supports it — we just need API key distribution, git repo access, and result reporting. If no, we focus on planning pipeline + UAT quality improvements.

10. Files Reference