ezos26/claude-skills/ralph

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)

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

# 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"}

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

# 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}

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"]

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)

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

{typecheck command}

{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."

{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."