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

description

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

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:

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

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.

mkdir -p .claude

Template settings.json per stack:

Next.js / TypeScript:

{
  "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:

{
  "permissions": {
    "allow": [
      "npm start",
      "npm run dev",
      "npm run build",
      "npm run lint",
      "npm test",
      "npm run test:*"
    ]
  }
}

Python / FastAPI:

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

Go:

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

Generic (fără config detectat):

{
  "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ă:

{
  "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:

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