claude-plugins/plugins/ralph/README.md

Ralph Plugin

Ralph este un loop autonom de agent AI care rulează Claude Code în mod repetat până când toate task-urile dintr-un PRD sunt complete.

Adaptat din snarktank/ralph pentru Claude Code CLI, cu îmbunătățiri inspirate din coleam00/ai-agents-masterclass.

Comenzi disponibile

Comandă	Descriere
/ralph:prd	Generează PRD structurat cu detecție context și întrebări adaptive
/ralph:convert	Convertește PRD markdown în prd.json și configurează proiectul

Features

Detecție Automată Context

• Detectează automat tech stack-ul din fișierele de config (package.json, pyproject.toml, etc.)
• Adaptează întrebările: ~10 pentru proiecte noi vs ~5-7 pentru features în proiecte existente
• Extrage comenzile reale din proiect (npm scripts, etc.)

Întrebări Interactive

• Folosește AskUserQuestion pentru UX interactiv (nu text simplu)
• Web research opțional pentru best practices (WebSearch)
• Întrebări adaptive bazate pe context detectat

Verificare Vizuală Browser

• Folosește agent-browser CLI pentru verificări UI
• Snapshots compacte cu referințe (@e1, @e2) - eficiente cu tokeni
• Screenshots salvate automat pentru referință

Configurare Automată

• Generează .claude/settings.json cu allow-list per tech stack
• Actualizează prompt.md cu comenzile reale ale proiectului
• Arhivare automată a rulărilor anterioare

Workflow

┌─────────────────────────────────────────────────────────────┐
│                      WORKFLOW RALPH                          │
├─────────────────────────────────────────────────────────────┤
│  1. /ralph:prd                                               │
│     ├─ Detectează context proiect (existent vs nou)         │
│     ├─ Pune întrebări adaptive cu AskUserQuestion           │
│     ├─ (Opțional) WebSearch pentru best practices           │
│     └─ Generează PRD în /tasks/prd-*.md                     │
│                                                              │
│  2. /ralph:convert                                           │
│     ├─ Detectează tech stack și comenzi                     │
│     ├─ Generează .claude/settings.json (allow-list)         │
│     ├─ Copiază și configurează scripts/ralph/               │
│     └─ Creează prd.json cu techStack info                   │
│                                                              │
│  3. ./scripts/ralph/ralph.sh [max_iterations]               │
│     ├─ Selectează story cu prioritate minimă                │
│     ├─ Lansează Claude Code (context curat)                 │
│     ├─ Implementează + quality checks                       │
│     ├─ Verificare browser pentru UI (agent-browser)         │
│     ├─ Commit + marchează passes: true                      │
│     └─ Repetă până toate complete                           │
└─────────────────────────────────────────────────────────────┘

Cerințe

Obligatorii

• Claude Code CLI instalat și autentificat
• jq pentru procesare JSON
• Git repository

Recomandate (pentru verificări UI)

• agent-browser - pentru verificări vizuale browser

  npm install -g agent-browser && agent-browser install
  

Utilizare

Pas 1: Generează PRD

/ralph:prd

Vreau să adaug funcționalitate de export CSV pentru dashboard.

Claude va:

1. Detecta dacă există proiect (package.json, etc.)
2. Pune întrebări adaptive:
   • Proiect nou: ~10 întrebări (stack, arhitectură, UI, auth, etc.)
   • Feature în proiect existent: ~5-7 întrebări (tip, UI, DB, security)
3. Opțional: WebSearch pentru best practices
4. Genera PRD în /tasks/prd-export-csv.md

Pas 2: Convertește în JSON

/ralph:convert

Convertește PRD-ul din tasks/prd-export-csv.md

Claude va:

1. Detecta tech stack și extrage comenzile din package.json/etc.
2. Genera .claude/settings.json cu allow-list
3. Crea structura scripts/ralph/ cu fișierele configurate
4. Genera prd.json cu techStack info

Pas 3: Rulează Ralph

./scripts/ralph/ralph.sh 20  # 20 iterații max

Pas 4: Monitorizare

# Status stories
jq '.userStories[] | {id, title, passes}' scripts/ralph/prd.json

# Progress log
cat scripts/ralph/progress.txt

# Screenshots UI
ls scripts/ralph/screenshots/

Structura proiectului

După /ralph:convert:

your-project/
├── .claude/
│   └── settings.json     # Permissions allow-list (generat)
├── scripts/ralph/
│   ├── ralph.sh          # Script principal
│   ├── prompt.md         # Instrucțiuni per iterație (cu comenzi reale)
│   ├── prd.json          # Task-uri cu techStack (generat)
│   ├── progress.txt      # Learnings (generat)
│   ├── logs/             # Logs per iterație
│   ├── archive/          # Arhive rulări anterioare
│   └── screenshots/      # Screenshots verificări UI
└── tasks/
    └── prd-*.md          # PRD-uri markdown

Format prd.json

{
  "projectName": "feature-name",
  "branchName": "ralph/feature-name",
  "description": "Descriere feature",
  "techStack": {
    "type": "nextjs",
    "commands": {
      "start": "npm run dev",
      "build": "npm run build",
      "lint": "npm run lint",
      "typecheck": "npm run typecheck",
      "test": "npm test"
    },
    "port": 3000
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "Titlu story",
      "description": "As a user...",
      "priority": 1,
      "acceptanceCriteria": ["..."],
      "requiresBrowserCheck": true,
      "passes": false,
      "notes": ""
    }
  ]
}

Verificare Browser cu agent-browser

Pentru stories cu UI (requiresBrowserCheck: true), Ralph folosește agent-browser CLI:

# Navighează
agent-browser navigate "http://localhost:3000"

# Snapshot (referințe compacte @e1, @e2, etc.)
agent-browser snapshot

# Interacțiuni
agent-browser click @e5
agent-browser fill @e3 "value"

# Screenshot
agent-browser screenshot ./scripts/ralph/screenshots/US-001.png

# Console errors
agent-browser console

De ce agent-browser (nu Playwright MCP):

• Referințe compacte (@e1, @e2) - consum minim tokeni
• Fiecare iterație Ralph are context limitat
• CLI simplu, fără server MCP
• Optimizat pentru agenți AI

Reguli pentru stories bune

Mărime corectă (1 context window)

• Adaugă un câmp în DB + migration
• Creează un component UI simplu
• Adaugă un endpoint API
• Scrie tests pentru o funcție

Ordinea priorităților

1. Schema/Database (priority: 1-10)
2. Backend logic (priority: 11-20)
3. API endpoints (priority: 21-30)
4. UI components (priority: 31-40)
5. Integration/polish (priority: 41-50)

Acceptance Criteria

• Specifice și verificabile
• Include comanda typecheck reală din proiect
• Pentru UI: "Verificare vizuală browser că [behavior]"

settings.json Auto-Generate

Per tech stack detectat:

Next.js/TypeScript:

{
  "permissions": {
    "allow": [
      "npm run dev", "npm run build", "npm run lint",
      "npm run typecheck", "npx prisma *", "npm test"
    ]
  }
}

Python/FastAPI:

{
  "permissions": {
    "allow": [
      "uvicorn * --reload", "python -m pytest",
      "ruff check .", "mypy .", "alembic *"
    ]
  }
}

Credite

• snarktank/ralph - Ralph original pentru Amp
• coleam00/ai-agents-masterclass - Inspirație pentru îmbunătățiri
• vercel-labs/agent-browser - Browser CLI pentru verificări UI