---
name: ralph
description: Autonomous PRD creation and conversion for Claude Code autonomous loops - context detection, adaptive questions, browser verification
metadata:
  {
    "openclaw": { "emoji": "🔄", "requires": { "anyBins": ["claude", "jq", "git"] } },
  }
---

# Ralph - Autonomous Loop for PRD Implementation

**Ralph** este un sistem pentru crearea și execuția autonomă a Product Requirements Documents (PRD) cu Claude Code.

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                           │
└─────────────────────────────────────────────────────────────┘
```

## Când să folosești acest skill

### Folosește `/ralph:prd` când:
- Utilizatorul vrea să adauge o funcționalitate nouă
- Vrea să planifice înainte de a implementa
- Menționează "PRD", "requirements", "cerințe", "planifică feature"

### Folosește `/ralph:convert` când:
- Utilizatorul are deja un PRD markdown generat (în `/tasks/prd-*.md`)
- Vrea să pregătească task-urile pentru execuție autonomă cu Ralph
- Sau vrea să inițializeze structura Ralph într-un proiect

## 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 rapidă

### Pas 1: Generează PRD

Invocă skill-ul și descrie feature-ul:

```
/ralph:prd

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

Claude va detecta contextul, pune întrebări adaptive și genera PRD-ul.

### Pas 2: Convertește în JSON

```
/ralph:convert

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

### Pas 3: Rulează Ralph

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

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

## Instrucțiuni pentru Agent

Când utilizatorul invocă `/ralph:prd` sau `/ralph:convert`:

1. **Citește documentația specifică comenzii** din `commands/prd.md` sau `commands/convert.md`
2. **Urmează workflow-ul exact** din documentație
3. **Folosește template-urile** din `templates/` când este necesar
4. **Salvează output-ul** în locația corectă (`tasks/` pentru PRD, `scripts/ralph/` pentru conversie)

## 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** pentru verificări vizuale eficiente.

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

## Template Files Location

Template-urile pentru acest skill sunt în:
- `templates/prompt.md` - Instrucțiuni pentru fiecare iterație Ralph
- `templates/ralph.sh` - Script-ul principal de execuție
- `templates/prd-template.json` - Template JSON pentru PRD
- `commands/prd.md` - Documentație detaliată pentru `/ralph:prd`
- `commands/convert.md` - Documentație detaliată pentru `/ralph:convert`
- `examples/` - Exemple de PRD-uri generate