claude-plugins/plugins/ralph/commands/convert.md

---
description: Convertește un PRD markdown în format prd.json pentru loop-ul autonom Ralph. Folosește acest skill când utilizatorul are un PRD generat și vrea să-l convertească pentru execuție autonomă cu Ralph.
---

# Skill: Ralph PRD Converter

Convertește un PRD markdown existent în format `prd.json` pentru sistemul Ralph de execuție autonomă.

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

- 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

## Workflow

### Pas 1: Verifică PRD-ul existent

```bash
ls tasks/prd-*.md
```

Dacă nu există un PRD, sugerează să folosească skill-ul `/ralph:prd` mai întâi.

### Pas 2: Citește PRD-ul și extrage user stories

Citește fișierul PRD și identifică:
- Numele proiectului
- User stories cu acceptance criteria
- Dependențe între stories

### Pas 3: Detectează Tech Stack

**Verifică fișierele de config pentru a determina stack-ul:**

```
package.json       → Node.js/JavaScript
pyproject.toml     → Python
go.mod             → Go
Cargo.toml         → Rust
pom.xml            → Java
```

**Extrage comenzi din config:**

Pentru `package.json`:
```javascript
// Citește scripts section:
{
  "scripts": {
    "dev": "next dev",           // → START_COMMAND
    "build": "next build",       // → BUILD_COMMAND
    "lint": "eslint .",          // → LINT_COMMAND
    "typecheck": "tsc --noEmit"  // → TYPECHECK_COMMAND
  }
}
```

**Mapare comenzi standard:**

| Stack | Start | Build | Lint | Typecheck |
|-------|-------|-------|------|-----------|
| Next.js | npm run dev | npm run build | npm run lint | npm run typecheck |
| Node/Express | npm start | npm run build | npm run lint | npm run typecheck |
| Python/FastAPI | uvicorn main:app --reload | - | ruff check . | mypy . |
| Go | go run . | go build | golangci-lint run | - |
| Rust | cargo run | cargo build | cargo clippy | - |

### Pas 4: Creează structura Ralph

```bash
mkdir -p scripts/ralph/logs scripts/ralph/archive scripts/ralph/screenshots
```

### Pas 5: Generează .claude/settings.json

**IMPORTANT**: Generează configurația pentru permissions allow-list bazat pe tech stack detectat.

```bash
mkdir -p .claude
```

**Template settings.json per stack:**

#### Next.js / TypeScript:
```json
{
  "permissions": {
    "allow": [
      "Bash(npm run dev)",
      "Bash(npm run build)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(npx prisma:*)",
      "Bash(npm test)",
      "Bash(npm run test:*)"
    ]
  }
}
```

#### Node.js / Express:
```json
{
  "permissions": {
    "allow": [
      "Bash(npm start)",
      "Bash(npm run dev)",
      "Bash(npm run build)",
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(npm run test:*)"
    ]
  }
}
```

#### Python / FastAPI:
```json
{
  "permissions": {
    "allow": [
      "Bash(uvicorn:*)",
      "Bash(python -m pytest:*)",
      "Bash(pytest:*)",
      "Bash(ruff check:*)",
      "Bash(ruff format:*)",
      "Bash(mypy:*)",
      "Bash(pip install:*)",
      "Bash(alembic:*)"
    ]
  }
}
```

#### Go:
```json
{
  "permissions": {
    "allow": [
      "Bash(go run:*)",
      "Bash(go build:*)",
      "Bash(go test:*)",
      "Bash(golangci-lint:*)",
      "Bash(go mod:*)"
    ]
  }
}
```

#### Generic (fără config detectat):
```json
{
  "permissions": {
    "allow": [
      "Bash(npm run:*)",
      "Bash(npm test)",
      "Bash(npm start)"
    ]
  }
}
```

**Verifică și merging:**
- Dacă `.claude/settings.json` există deja, citește-l și merge permissions
- Nu suprascrie setări existente, doar adaugă cele lipsă

### Pas 6: Generează prd.json

Convertește user stories în format JSON cu următoarea structură:

```json
{
  "projectName": "feature-name",
  "branchName": "ralph/feature-name",
  "description": "Descriere din PRD",
  "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], I want [feature] so that [benefit]",
      "priority": 1,
      "acceptanceCriteria": [
        "Criteriu specific și verificabil",
        "npm run typecheck passes"
      ],
      "requiresBrowserCheck": true,
      "passes": false,
      "notes": ""
    }
  ]
}
```

**Câmpuri noi:**
- `techStack` - informații despre stack-ul detectat
- `techStack.commands` - comenzile reale din proiect
- `techStack.port` - portul pentru dev server
- `requiresBrowserCheck` - true dacă story-ul are UI

### Pas 7: Validează mărimea stories

**CRITIC**: Fiecare story trebuie să fie completabil într-un singur context window.

#### Story de mărime corectă:
- Adaugă un câmp în baza de date
- Creează un component UI simplu
- Adaugă un endpoint API
- Scrie tests pentru o funcție specifică

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

Dacă găsești stories prea mari, sparge-le în sub-stories mai mici.

### Pas 8: Setează prioritățile

Ordinea recomandată:
1. Schema/Database changes (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)

Stories care depind de altele trebuie să aibă prioritate mai mare (număr mai mare).

### Pas 9: Verifică acceptance criteria

Fiecare story TREBUIE să aibă:
- Criterii specifice și verificabile (NU vagi ca "funcționează bine")
- Comanda reală de typecheck: `{TYPECHECK_COMMAND} passes`
- Pentru UI: `Verificare vizuală browser: [specific behavior]`

### Pas 10: Copiază template-urile Ralph din plugin

**IMPORTANT**: Copiază fișierele template direct din plugin pentru a asigura consistența.

**Execută următoarele comenzi:**

```bash
# Găsește locația plugin-ului Ralph
RALPH_PLUGIN=$(find /workspace -type f -name "ralph.sh" -path "*/plugins/ralph/templates/*" 2>/dev/null | head -1 | xargs dirname 2>/dev/null)

# Verifică că plugin-ul a fost găsit
if [ -z "$RALPH_PLUGIN" ]; then
    echo "EROARE: Nu am găsit plugin-ul Ralph în /workspace"
    echo "Asigură-te că claude-plugins este clonat în /workspace"
    exit 1
fi

echo "Plugin Ralph găsit în: $RALPH_PLUGIN"

# Copiază template-urile
cp "$RALPH_PLUGIN/prompt.md" scripts/ralph/
cp "$RALPH_PLUGIN/ralph.sh" scripts/ralph/
chmod +x scripts/ralph/ralph.sh

echo "Template-uri copiate din plugin"
```

**Dacă plugin-ul NU este găsit:**
- Informează utilizatorul că trebuie să cloneze `claude-plugins` în `/workspace`
- Sau să specifice manual locația plugin-ului

**NU genera fișierele manual** - copiază-le întotdeauna din plugin pentru a păstra consistența și a beneficia de actualizări.

### Pas 11: Inițializează progress.txt

```bash
echo "# Ralph Progress Log" > scripts/ralph/progress.txt
echo "Started: $(date)" >> scripts/ralph/progress.txt
echo "Project: [project-name]" >> scripts/ralph/progress.txt
echo "Stack: [detected-stack]" >> scripts/ralph/progress.txt
echo "---" >> scripts/ralph/progress.txt
```

### Pas 12: Verificare finală

**Verifică că toate fișierele sunt create:**

```
scripts/ralph/
├── ralph.sh          # Script principal
├── prompt.md         # Instrucțiuni (cu comenzi reale)
├── prd.json          # Task-uri și status
├── progress.txt      # Log inițializat
├── logs/             # Director pentru logs
├── archive/          # Director pentru arhivare
└── screenshots/      # Director pentru verificări vizuale

.claude/
└── settings.json     # Permissions allow-list
```

### Pas 13: Instrucțiuni finale

După completare, informează utilizatorul:

```
PRD convertit în scripts/ralph/prd.json

Structură creată:
  scripts/ralph/        - Fișiere Ralph
  scripts/ralph/screenshots/  - Pentru verificări vizuale
  .claude/settings.json - Permissions pentru comenzi

Tech stack detectat: {stack}
Comenzi configurate:
  Start:     {START_COMMAND}
  Build:     {BUILD_COMMAND}
  Typecheck: {TYPECHECK_COMMAND}
  Lint:      {LINT_COMMAND}
  Test:      {TEST_COMMAND}

Pentru a rula Ralph:
  cd [project-directory]
  ./scripts/ralph/ralph.sh [max_iterations]

Monitorizare:
  cat scripts/ralph/prd.json | jq '.userStories[] | {id, title, passes}'
  cat scripts/ralph/progress.txt

IMPORTANT:
  - Ralph va folosi agent-browser pentru verificări vizuale UI
  - Screenshots se salvează în scripts/ralph/screenshots/
  - Asigură-te că ai agent-browser instalat: npm install -g agent-browser && agent-browser install
```

## Output așteptat

- `scripts/ralph/prd.json` - task-urile în format JSON cu tech stack info
- `scripts/ralph/progress.txt` - log inițializat
- `scripts/ralph/prompt.md` - copiat din plugin (single source of truth)
- `scripts/ralph/ralph.sh` - copiat din plugin (single source of truth)
- `scripts/ralph/screenshots/` - director pentru verificări vizuale
- `.claude/settings.json` - permissions allow-list pentru tech stack
- Structura de directoare completă

## Reguli importante

1. **NU începe implementarea** - acest skill doar convertește PRD-ul
2. **Detectează tech stack** - pentru comenzi și settings.json
3. **Validează mărimea stories** - sparge-le dacă sunt prea mari
4. **Prioritizează corect** - dependențele trebuie respectate
5. **Criterii verificabile** - nu vagi, ci specifice
6. **Inițializează `passes: false`** pentru toate stories
7. **Generează settings.json** - pentru allow-list permissions
8. **COPIAZĂ template-urile din plugin** - NU le genera manual, folosește `find` pentru a localiza plugin-ul și copiază `prompt.md` și `ralph.sh` din templates/