# Ralph2

> Ralph 2.0 — Autonomous phased build system. Reads a PRD, generates scoped briefs, dispatches worker agents per phase, runs find→fix→verify gates between phases, checkpoints to disk for cross-session continuity. Usage: /ralph2 [prd-path]

- Skill: `ezos26/ralph2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add ezos26/ralph2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ezos26/ralph2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: ezos26 (https://skillmd.com/u/ezos26)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ezos26/ralph2

---


# Ralph 2.0 — Phased Autonomous Build System

Orchestrator-driven build system that treats context windows as managed resources. Each phase gets a fresh worker with a scoped brief. Quality gates run between every phase. State checkpoints to disk so sessions can resume cleanly.

## When to Use

- Building a multi-phase feature from a PRD
- Any task too large for a single context window
- When you need verified, incremental progress with no accumulated context degradation

## Trigger Phrases

- `/ralph2`
- `/ralph2 [prd-path]`
- "run ralph 2"
- "build this with ralph"

## Input Detection

Parse user input for:
- **PRD path**: explicit path, or auto-detect by globbing `docs/**/*PRD*`, `docs/**/*prd*`, `**/*plan*PRD*`
- **Resume**: if `.ralph/state.yaml` exists in the project root, offer to resume

If no PRD found, ask the user.

---

## Overview

```
Orchestrator (this skill, main context)
  │
  ├── Stage 0: Codebase scan → .ralph/codebase-map.md
  ├── Stage 1: Decompose PRD → phase briefs
  │
  ├── Stage 2: Execute phases (loop)
  │   │
  │   ├── Dispatch worker agent (brief → code)
  │   ├── Deterministic gate (typecheck, lint, build)
  │   ├── Audit agents FIND (2 agents, read-only, parallel)
  │   ├── Fix agent FIXES (1 agent, all severities)
  │   ├── Verify agent CONFIRMS (1 agent, read-only)
  │   ├── Commit
  │   └── Checkpoint to .ralph/state.yaml
  │
  └── Stage 3: Final /ralph-review (full 6-agent audit)
```

---

## Stage 0: Ground Truth

Before generating any briefs, build a grounded understanding of the codebase. This prevents briefs from referencing files that don't exist or patterns that have changed.

### 0A: Read Project Context

Read these files (skip if missing):
1. `CLAUDE.md` — project constraints, dev commands
2. `AGENTS.md` — patterns, conventions, tech stack
3. `package.json` — dependencies, scripts, workspace structure
4. The PRD file — full implementation plan

Extract:
- **Quality gate commands**: typecheck, lint, test, build (detect from package.json scripts + CLAUDE.md)
- **Project conventions**: import patterns, naming, file organization
- **Known constraints**: isolation rules, API contracts, deployment concerns

### 0B: Codebase Scanner

Run targeted searches to build a map of what actually exists:

```
For each file referenced in the PRD:
  1. Verify it exists (glob)
  2. Read it — note key exports, functions, patterns
  3. Flag any discrepancies with what the PRD assumes
```

Write the result to `.ralph/codebase-map.md`:

```markdown
# Codebase Map
Generated: {date}
PRD: {path}

## Files Referenced in PRD
| File | Exists | Key Exports / Notes |
|------|--------|---------------------|
| src/db/schema.ts | YES | reportOrders, reportDomains, reportOutputs, tierEnum |
| src/lib/stripe.ts | YES | TIER_PRICES, createCheckout() |
| ... | ... | ... |

## Discrepancies
- PRD says X but code shows Y

## Quality Gate Commands
- Typecheck: `pnpm typecheck`
- Lint: {command or "none"}
- Test: {command or "none"}
- Build: {command or "none"}
```

### 0C: Initialize State

Create `.ralph/state.yaml`:

```yaml
project: {name from PRD or directory}
prd: {path}
started: {ISO timestamp}
codebase_map: .ralph/codebase-map.md
quality_gates:
  typecheck: "pnpm typecheck"
  lint: null
  test: null
  build: null

phases: []  # populated in Stage 1
final_review: pending
```

---

## Stage 1: Decompose PRD into Phase Briefs

Read the PRD. For each phase/section, generate a self-contained brief.

### Brief Generation Rules

1. **One brief per phase** — each brief maps to one worker agent invocation
2. **Self-contained** — the worker never reads the PRD. Everything it needs is in the brief.
3. **Grounded** — file paths come from codebase-map.md (verified to exist), not assumed
4. **Bounded** — clear "done when" criteria the gate can check deterministically
5. **Context-aware** — if Phase 2 depends on Phase 1, the Phase 2 brief states what Phase 1 produced

### Brief Template

Write each brief to `.ralph/briefs/{N}-{slug}.md`:

```markdown
# Phase {N} Brief: {Title}

## Context
You are implementing Phase {N} of {project name}.
{Previous phase summary: what was built, what now exists.}

## Objective
{2-3 sentences: what this phase accomplishes and why.}

## Files to Read First
{Ordered list. Include line ranges for large files. Only files relevant to this phase.}
1. `{path}` — {why: "tier config pattern to copy", "current schema to extend", etc.}

## Files to Modify
{Exact list with specific instructions per file.}

### `{file path}`
- {specific change 1}
- {specific change 2}

## Files to Create
{If any. Include the pattern to follow.}

### `{new file path}`
- Follow pattern from `{existing file path}`
- {specific requirements}

## Constraints
{Project-specific rules this worker must follow.}
- {constraint 1}
- {constraint 2}

## Patterns to Follow
{Only the patterns relevant to this phase, extracted from AGENTS.md/CLAUDE.md.}

## Done When
{Deterministic criteria. These feed directly into the gate.}
- [ ] `pnpm typecheck` passes
- [ ] {specific file} exports {specific function/type}
- [ ] {specific behavior is wired}
```

### Update State

After generating all briefs, update `.ralph/state.yaml`:

```yaml
phases:
  - id: "1-schema"
    brief: .ralph/briefs/1-schema.md
    status: pending
    complexity: simple    # simple | medium | complex
    gate: typecheck_only  # typecheck_only | find_fix_verify

  - id: "2-checkout"
    brief: .ralph/briefs/2-checkout.md
    status: pending
    complexity: medium
    gate: find_fix_verify
    depends_on: ["1-schema"]
```

**Complexity scoring:**
- **Simple** (schema-only, config-only, single file): typecheck gate only
- **Medium** (2-3 files, clear patterns): find→fix→verify gate
- **Complex** (4+ files, cross-cutting, business logic): find→fix→verify gate

### Present Plan to User

Before executing, show the user:

```
Ralph 2.0 — Execution Plan
===========================
PRD: {path}
Phases: {count}
Estimated workers: {count} (phases) + {count} (audit/fix/verify agents)

Phase 1: {title} [{complexity}] — gate: {gate type}
Phase 2: {title} [{complexity}] — gate: {gate type}
...

Proceed? (y/n)
```

Wait for user confirmation before executing.

---

## Stage 2: Execute Phases

For each phase in order:

### Step 2.1: Dispatch Worker

Launch a **general-purpose agent** with the phase brief as its prompt.

```
Agent tool:
  subagent_type: "general-purpose"
  description: "Phase {N}: {title}"
  prompt: {contents of .ralph/briefs/{N}-{slug}.md}
```

The worker:
- Reads referenced files
- Makes the changes described in the brief
- Does NOT run typecheck or tests — that's the gate's job
- Returns a summary of what it changed

After the worker completes, note which files were changed.

### Step 2.2: Deterministic Gate

Run quality checks BEFORE spending tokens on AI audit:

```bash
{typecheck command}
```

If typecheck fails:
1. Read the error output
2. Fix the errors directly (orchestrator fixes these — they're deterministic)
3. Re-run typecheck
4. Max 3 attempts, then escalate to user

Also run lint and test if available. These are hard gates — must pass.

**Phase-specific commands:** After standard gates pass, run any phase-specific verification commands from the PRD. Common examples:

| Phase type | Command to run | Why |
|---|---|---|
| Schema/migration | `{db:generate command}` (e.g. `pnpm db:generate`) | Schema changes WITHOUT a migration = deploy blocker |
| New CSS classes referenced | Grep the stylesheet to verify all referenced classes exist | Missing classes = silent rendering failures |
| New env vars added | Verify they appear in both env validation AND `.env.example` | Missing vars = runtime crash in deploy |
| New Trigger.dev jobs | Verify task ID strings match between trigger file and worker dispatch | Mismatched IDs = jobs never fire |

**The PRD often lists these in its "Verify" sections — execute them, don't skip them.** This is the #1 source of deploy blockers when omitted.

**If phase complexity is `simple` and deterministic gates pass → skip to Step 2.6 (commit).**

### Step 2.3: Audit — FIND Only

Launch 2 Explore agents in parallel (`run_in_background: true`). These agents **only read and report**. They do NOT write code.

**Agent 1: Integration Auditor**

```
{project context from Stage 0}

## Phase {N} Brief (what the worker was told to build)
{paste the brief}

## Files Changed
{list of files the worker modified/created}

## Your Job: Integration Audit (READ ONLY — do NOT fix anything)

For each file changed, verify:
1. Follows project conventions (from CLAUDE.md / AGENTS.md)
2. Respects isolation rules (e.g., Worker cannot import from src/lib/)
3. API contract compliance (if applicable)
4. Existing functionality unbroken — check that unchanged code paths still work
5. New code wires into existing systems correctly (registrations, exports, imports)

## OUTPUT FORMAT (MANDATORY)
INTEGRATION AUDIT — Phase {N}
==============================
Files Reviewed: {count}

Findings:
- [H-001]: {title} | {file:line} | {description}
- [M-001]: {title} | {file:line} | {description}
- [L-001]: {title} | {file:line} | {description}

Or: "No findings — phase looks clean."
```

**Agent 2: Gotcha Hunter**

```
{project context from Stage 0}

## Phase {N} Brief (what the worker was told to build)
{paste the brief}

## Files Changed
{list of files the worker modified/created}

## Your Job: Gotcha Hunt (READ ONLY — do NOT fix anything)

Search all changed files for:
1. Hardcoded values (URLs, prices, limits, magic numbers) that should use constants/helpers
2. Missing `await` on async function calls
3. `console.log` statements that should be removed or converted to proper logging
4. TODO/FIXME/HACK comments left behind
5. Commented-out code that should be deleted
6. Copy-paste errors (duplicated logic that diverged)
7. Type assertions (`as any`, `as unknown`) that bypass safety

### Cross-File Reference Check
8. CSS/HTML: for every CSS class name used in templates/HTML, verify the class is defined in the stylesheet
9. Imports: verify imported functions/types actually exist in the target module
10. String IDs: verify task IDs, queue names, template slugs match their definitions

## OUTPUT FORMAT (MANDATORY)
GOTCHA HUNT — Phase {N}
========================
Files Reviewed: {count}

Findings:
- [H-001]: {title} | {file:line} | {description}
- [M-001]: {title} | {file:line} | {description}
- [L-001]: {title} | {file:line} | {description}

Or: "No findings — phase looks clean."
```

### Parallel Product Builds — Extra Audit Scope

When the PRD builds a **second product type alongside an existing one** (e.g., "sale readiness" alongside "activation"), both audit agents must also verify:

1. **Email templates:** Does the notification use a product-appropriate template or template model? Reusing activation email metrics (e.g., `keep_count`/`drop_count`) for a different product type will confuse customers.
2. **Display names:** Every user-visible string derived from enum values (tier names, strategy labels, status messages) must have a display name mapping — raw enum values like `portfolio_deep` must NOT appear in PDFs, emails, or UI.
3. **PDF sections:** If the new product has different per-item fields than the existing product, verify all fields are surfaced consistently (e.g., don't show `reason` in 3 of 4 section types but omit it from the 4th).
4. **Shared pipelines:** If the new product reuses an existing pipeline (e.g., data collection), verify that product-specific parameters (tiers, limits, feature flags) are mapped correctly — not silently cast with `as`.
5. **DB migrations:** Verify that schema changes have corresponding migration files generated.

### Step 2.4: Fix — Dedicated Fix Agent

After both audit agents report back, consolidate all findings.

**If zero findings from both agents → skip to Step 2.6 (commit).**

Otherwise, launch a **single general-purpose agent** with the consolidated findings:

```
Agent tool:
  subagent_type: "general-purpose"
  description: "Fix Phase {N} findings"
  prompt: (below)
```

```
## Project Context
{CLAUDE.md constraints, key conventions, isolation rules}

## Findings to Fix

{Consolidated list from both auditors, numbered globally}

1. [H-001] {title} — {file:line} — {description}
2. [M-001] {title} — {file:line} — {description}
3. [L-001] {title} — {file:line} — {description}
...

## Instructions

Fix ALL findings above (HIGH, MEDIUM, and LOW).

Rules:
- Read each flagged file before modifying it
- Fix only what's described — do not refactor surrounding code
- Do not add tests, comments, or documentation beyond the fix
- Do not run typecheck or verify — another agent handles that
- Report what you changed for each finding
```

### Step 2.5: Verify Fixes

After the fix agent completes:

**1. Deterministic re-check:**
```bash
{typecheck command}
```
Must pass. If it fails, fix directly (orchestrator) — max 2 attempts.

**2. Verification agent** — launch an Explore agent (read-only):

```
## Files Modified by Fix Agent
{list of files changed}

## Original Findings
{the findings list}

## Your Job: Verify Fixes (READ ONLY)

For each finding, confirm:
1. The fix actually resolves the issue (not just papered over)
2. The fix didn't introduce new issues
3. The fix follows project conventions

## OUTPUT FORMAT (MANDATORY)
FIX VERIFICATION — Phase {N}
=============================
Per Finding:
- [H-001]: {RESOLVED / INCOMPLETE / REGRESSION}
  {evidence}
- [M-001]: {RESOLVED / INCOMPLETE / REGRESSION}
  {evidence}

New Issues Introduced: {list or "none"}
Overall: {PASS / NEEDS ANOTHER CYCLE}
```

**If verification reports INCOMPLETE or REGRESSION:**
- Launch one more fix cycle (Steps 2.4 + 2.5) with only the unresolved findings
- Max 2 total cycles
- If still failing after 2 cycles → commit what works, log the unresolved findings, ask user

### Step 2.6: Commit & Checkpoint

Commit all phase work + fixes:

```
Phase {N}: {brief title}

{one-line summary of what was built}
{one-line per audit finding that was fixed, if any}

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
```

Update `.ralph/state.yaml`:

```yaml
  - id: "{N}-{slug}"
    status: complete
    commit: {sha}
    findings_found: {count}
    findings_resolved: {count}
    findings_unresolved: {count}
    fix_cycles: {count}
```

Update `.ralph/context.md` (append):

```markdown
## Phase {N}: {title}
- Commit: {sha}
- Changed: {file list}
- Decisions: {any deviations from the brief and why}
- Gotchas discovered: {anything the next phase should know}
- Unresolved: {any findings that couldn't be fixed}
```

### Step 2.7: Context Window Check

Before starting the next phase, assess your own context usage:

- **If context is getting heavy** (you've run 3+ phases with full gates): consider running `/last-rites` to create a handoff, then the next session resumes from `.ralph/state.yaml`.
- **If context is fine**: proceed to next phase.

The orchestrator should prioritize staying sharp over powering through. A fresh context window reading `.ralph/state.yaml` + `.ralph/context.md` + the next brief is better than a degraded context trying to push through.

---

## Stage 3: Final Review

After all phases complete, run `/ralph-review` as the final quality gate.

This is the full 6-agent audit with cross-examination from the ralph-review skill. It audits the entire body of work across all phases.

If `/ralph-review` finds issues, its remediation cycle handles them.

After final review passes, update state:

```yaml
final_review: complete
completed: {ISO timestamp}
```

---

## Resume Protocol

When invoked and `.ralph/state.yaml` exists:

1. Read `.ralph/state.yaml` — determine current progress
2. Read `.ralph/context.md` — get cross-phase knowledge
3. Read `.ralph/codebase-map.md` — get grounded file state
4. Find the next pending phase
5. Read its brief
6. Continue from Step 2.1

Show the user:

```
Ralph 2.0 — Resuming
======================
Project: {name}
Progress: {N}/{total} phases complete
Last completed: Phase {N} ({title}) — {commit sha}
Next: Phase {N+1} ({title})

Continue? (y/n)
```

If the codebase has changed since the last checkpoint (files modified outside Ralph), re-run Stage 0B (codebase scanner) to update the map before proceeding.

---

## .ralph/ Directory Structure

```
.ralph/
  state.yaml              # progress tracker — source of truth
  context.md              # cross-phase knowledge (structured, append-only)
  codebase-map.md         # grounded file inventory
  briefs/
    1-schema.md           # self-contained worker brief
    2-checkout.md
    3-synthesis.md
    ...
  audits/
    2-checkout.md         # consolidated audit findings (preserved for reference)
    3-synthesis.md
    ...
```

**Important:** `.ralph/` should be gitignored. It's orchestration state, not project code. Add to `.gitignore` if not already present.

---

## Context File Structure

`.ralph/context.md` uses a fixed structure — never freeform:

```markdown
# Ralph 2.0 Context
Project: {name}
PRD: {path}

## Decisions
{Decisions made during execution and why. One bullet per decision.}

## Known Issues
{Issues discovered but not yet resolved.}

## Deviations from PRD
{Anything that diverged from the original plan and why.}

## New Patterns Introduced
{Any new patterns or conventions established during this build.}

## Per-Phase Notes

### Phase 1: {title}
- Commit: {sha}
- Changed: {files}
- Gotchas: {anything relevant for later phases}

### Phase 2: {title}
...
```

---

## Failure Escalation Rules

| Condition | Action |
|-----------|--------|
| Typecheck fails 3x after worker | Escalate to user with error output |
| Audit finds 10+ HIGH findings | Mark brief as flawed, ask user before fixing |
| Fix agent cycles > 2 | Commit what works, log unresolved, ask user |
| Verify agent finds regressions after 2 fix cycles | Stop, present full state to user |
| Worker produces no changes | Brief may be wrong — re-read target files, regenerate brief |
| Codebase changed between sessions | Re-run codebase scanner, re-validate remaining briefs |

---

## Key Principles

1. **Context windows are managed resources** — checkpoint and restart rather than degrade
2. **Deterministic before probabilistic** — run typecheck before AI auditors
3. **Separation of concerns** — workers build, auditors find, fixers fix, verifiers verify. No agent wears two hats.
4. **Briefs are grounded** — file paths verified against actual codebase, not assumed from PRD
5. **Build on verified ground** — never start Phase N+1 until Phase N passes its gate
6. **State lives on disk** — `.ralph/state.yaml` is the source of truth, survives session boundaries
7. **The brief generator is the system** — bad briefs → bad workers. Invest in brief quality.
8. **Fail loudly, not silently** — escalate to user rather than loop or paper over issues