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": [
      "npm run dev",
      "npm run build",
      "npm run lint",
      "npm run typecheck",
      "npx prisma generate",
      "npx prisma migrate dev",
      "npx prisma db push",
      "npm test",
      "npm run test:*"
    ]
  }
}
```

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

#### Python / FastAPI:
```json
{
  "permissions": {
    "allow": [
      "uvicorn * --reload",
      "python -m pytest",
      "ruff check .",
      "ruff format .",
      "mypy .",
      "pip install *",
      "alembic upgrade head",
      "alembic revision *"
    ]
  }
}
```

#### Go:
```json
{
  "permissions": {
    "allow": [
      "go run .",
      "go build",
      "go test ./...",
      "golangci-lint run",
      "go mod tidy"
    ]
  }
}
```

#### Generic (fără config detectat):
```json
{
  "permissions": {
    "allow": [
      "npm run *",
      "npm test",
      "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ă și actualizează fișierele Ralph

**Copiază template-urile din plugin:**
- `scripts/ralph/ralph.sh` - scriptul principal (din templates/ralph.sh)
- `scripts/ralph/prompt.md` - instrucțiunile per iterație (din templates/prompt.md)

**Actualizează prompt.md cu comenzile reale:**

Înlocuiește placeholder-ii din prompt.md:
```
{START_COMMAND}    → npm run dev (sau comanda reală)
{BUILD_COMMAND}    → npm run build
{LINT_COMMAND}     → npm run lint
{TYPECHECK_COMMAND}→ npm run typecheck
{TEST_COMMAND}     → npm test
{PORT}             → 3000 (sau portul real)
```

**Template prompt.md actualizat:**

În secțiunea Quality Checks, înlocuiește:
```markdown
### 5. Quality Checks
Rulează TOATE verificările înainte de commit:
```bash
{TYPECHECK_COMMAND}   # Type checking
{LINT_COMMAND}        # Linting
{TEST_COMMAND}        # Tests (dacă există)
```
```

### 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` - cu comenzile reale ale proiectului
- `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. **Actualizează prompt.md** - cu comenzile reale ale proiectului