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](https://github.com/snarktank/ralph) pentru Claude Code CLI, cu îmbunătățiri inspirate din [coleam00/ai-agents-masterclass](https://github.com/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
  ```bash
  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

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

### Pas 4: Monitorizare

```bash
# 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

```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**:

```bash
# 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:**
```json
{
  "permissions": {
    "allow": [
      "npm run dev", "npm run build", "npm run lint",
      "npm run typecheck", "npx prisma *", "npm test"
    ]
  }
}
```

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

## Credite

- [snarktank/ralph](https://github.com/snarktank/ralph) - Ralph original pentru Amp
- [coleam00/ai-agents-masterclass](https://github.com/coleam00/ai-agents-masterclass) - Inspirație pentru îmbunătățiri
- [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) - Browser CLI pentru verificări UI