Add Ralph skill for autonomous PRD creation and implementation

2026-02-09 08:56:16 +00:00
parent 59abff1bce
commit e82a786885
27 changed files with 2673 additions and 67 deletions
--- a/skills/ralph/README.md
+++ b/skills/ralph/README.md
@@ -0,0 +1,261 @@
+# Ralph Plugin
+
+**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 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                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## 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
+
+### Pas 1: Generează PRD
+
+```
+/ralph:prd
+
+Vreau să adaug funcționalitate de export CSV pentru dashboard.
+```
+
+Claude va:
+1. Detecta dacă există proiect (package.json, etc.)
+2. Pune întrebări adaptive:
+   - Proiect nou: ~10 întrebări (stack, arhitectură, UI, auth, etc.)
+   - Feature în proiect existent: ~5-7 întrebări (tip, UI, DB, security)
+3. Opțional: WebSearch pentru best practices
+4. Genera PRD în `/tasks/prd-export-csv.md`
+
+### Pas 2: Convertește în JSON
+
+```
+/ralph:convert
+
+Convertește PRD-ul din tasks/prd-export-csv.md
+```
+
+Claude va:
+1. Detecta tech stack și extrage comenzile din package.json/etc.
+2. Genera `.claude/settings.json` cu allow-list
+3. Crea structura `scripts/ralph/` cu fișierele configurate
+4. Genera `prd.json` cu techStack info
+
+### Pas 3: Rulează Ralph
+
+```bash
+./scripts/ralph/ralph.sh 20  # 20 iterații max
+```
+
+### Pas 4: Monitorizare
+
+```bash
+# Status stories
+jq '.userStories[] | {id, title, passes}' scripts/ralph/prd.json
+
+# Progress log
+cat scripts/ralph/progress.txt
+
+# Screenshots UI
+ls scripts/ralph/screenshots/
+```
+
+## 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
+```
+
+## 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**:
+
+```bash
+# Navighează
+agent-browser navigate "http://localhost:3000"
+
+# Snapshot (referințe compacte @e1, @e2, etc.)
+agent-browser snapshot
+
+# Interacțiuni
+agent-browser click @e5
+agent-browser fill @e3 "value"
+
+# Screenshot
+agent-browser screenshot ./scripts/ralph/screenshots/US-001.png
+
+# Console errors
+agent-browser console
+```
+
+**De ce agent-browser (nu Playwright MCP):**
+- Referințe compacte (@e1, @e2) - consum minim tokeni
+- Fiecare iterație Ralph are context limitat
+- CLI simplu, fără server MCP
+- Optimizat pentru agenți AI
+
+## 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
+
+### 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)
+
+### Acceptance Criteria
+- Specifice și verificabile
+- Include comanda typecheck reală din proiect
+- Pentru UI: "Verificare vizuală browser că [behavior]"
+
+## settings.json Auto-Generate
+
+Per tech stack detectat:
+
+**Next.js/TypeScript:**
+```json
+{
+  "permissions": {
+    "allow": [
+      "npm run dev", "npm run build", "npm run lint",
+      "npm run typecheck", "npx prisma *", "npm test"
+    ]
+  }
+}
+```
+
+**Python/FastAPI:**
+```json
+{
+  "permissions": {
+    "allow": [
+      "uvicorn * --reload", "python -m pytest",
+      "ruff check .", "mypy .", "alembic *"
+    ]
+  }
+}
+```
+
+## 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