ralph-claude/README.md

# Ralph pentru Claude Code

**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 Amp) pentru a funcționa cu Claude Code CLI.

## Cum funcționează

```
┌──────────────────────────────────────────────────────────────────┐
│                      CICLUL RALPH                                │
├──────────────────────────────────────────────────────────────────┤
│  1. Citește prd.json → selectează story cu prioritate minimă     │
│  2. Lansează instanță fresh Claude Code (context curat)          │
│  3. Implementează story-ul selectat                              │
│  4. Rulează quality checks (typecheck, tests, lint)              │
│  5. Commit dacă trece → marchează story ca "passes: true"        │
│  6. Salvează learnings în progress.txt                           │
│  7. Repetă până toate story-urile sunt complete                  │
└──────────────────────────────────────────────────────────────────┘
```

## Memoria între iterații

| Mecanism | Descriere |
|----------|-----------|
| `git history` | Commit-uri din iterațiile anterioare |
| `prd.json` | Starea task-urilor (care sunt complete) |
| `progress.txt` | Learnings și patterns descoperite |

## Instalare rapidă

### Cerințe
- Claude Code CLI instalat și autentificat
- `jq` pentru procesare JSON (`apt install jq`)
- Git repository

### Instalare Skills (recomandat)

```bash
git clone git@gitea.romfast.ro:romfast/ralph-claude.git
cd ralph-claude
./install.sh
```

Aceasta instalează skill-urile `/prd` și `/ralph` global în `~/.claude/skills/`.

### Instalare manuală (per proiect)

```bash
# Copiază în proiectul tău
cp -r ralph-claude/scripts/ralph/ /path/to/your/project/scripts/ralph/
chmod +x scripts/ralph/ralph.sh
```

## Utilizare

### Workflow complet

```
1. /prd              → Generează PRD markdown cu întrebări clarificatoare
2. /ralph            → Convertește PRD în prd.json pentru execuție
3. ./ralph.sh        → Rulează loop-ul autonom
```

### Pas 1: Generează PRD

Într-o sesiune Claude Code, folosește skill-ul `/prd`:

```
/prd

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

Claude va:
- Pune întrebări clarificatoare
- Genera PRD structurat în `/tasks/prd-export-csv.md`

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

După ce PRD-ul e aprobat, folosește `/ralph`:

```
/ralph

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

Claude va:
- Crea structura `scripts/ralph/`
- Genera `prd.json` cu user stories
- Inițializa `progress.txt`

### Pas 3: Rulează Ralph

```bash
# Cu 10 iterații (implicit)
./scripts/ralph/ralph.sh

# Cu număr specific de iterații
./scripts/ralph/ralph.sh 20
```

### Pas 4: Monitorizare

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

# Learnings acumulate
cat scripts/ralph/progress.txt

# Logs per iterație
ls scripts/ralph/logs/
```

## Structura proiectului

```
your-project/
├── scripts/ralph/
│   ├── ralph.sh          # Script principal
│   ├── prompt.md         # Instrucțiuni per iterație
│   ├── prd.json          # Task-uri și status (generat)
│   ├── progress.txt      # Learnings (generat)
│   ├── logs/             # Logs per iterație
│   └── archive/          # Rulări anterioare arhivate
├── tasks/
│   └── prd-*.md          # PRD-uri markdown
└── AGENTS.md             # Patterns codebase (opțional)
```

## Format prd.json

```json
{
  "projectName": "export-csv",
  "branchName": "ralph/export-csv",
  "description": "Adaugă export CSV pentru dashboard",
  "userStories": [
    {
      "id": "US-001",
      "title": "Funcție de conversie la CSV",
      "description": "Ca developer, vreau o funcție care convertește date în CSV",
      "priority": 1,
      "acceptanceCriteria": [
        "Funcția acceptă array de obiecte",
        "Returnează string CSV valid",
        "npm run typecheck passes"
      ],
      "passes": false,
      "notes": ""
    }
  ]
}
```

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

### Prea mare (trebuie spart)
- "Implementează autentificarea completă"
- "Creează dashboard-ul admin"
- "Adaugă sistem notificări end-to-end"

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

## Debugging

### Story nu progresează
```bash
# Vezi ultimul log
cat scripts/ralph/logs/iteration-*.log | tail -100
```

### Tests failing
Verifică că proiectul are comenzile necesare:
```bash
npm run typecheck  # sau equivalent
npm run lint       # opțional
npm run test       # opțional
```

### Context overflow
Story-ul e prea mare - sparge-l în părți mai mici.

## Diferențe față de Ralph original

| Aspect | Original (Amp) | Adaptat (Claude Code) |
|--------|----------------|----------------------|
| CLI | `amp` | `claude -p` |
| Flag permisiuni | `--dangerously-allow-all` | `--dangerously-skip-permissions` |
| Skills location | `~/.config/amp/skills/` | `~/.claude/skills/` |
| Output | Direct | + salvat în logs/ |

## Skills incluse

| Skill | Descriere |
|-------|-----------|
| `/prd` | Generează PRD structurat cu întrebări clarificatoare |
| `/ralph` | Convertește PRD markdown în prd.json pentru execuție |

## Credite

- [snarktank/ralph](https://github.com/snarktank/ralph) - Ralph original pentru Amp
- [snarktank/amp-skills](https://github.com/snarktank/amp-skills) - Skills originale

## Licență

MIT