feat(ralph): v1.1.0 - Context detection, adaptive questions, browser verification

Major improvements inspired by coleam00/ai-agents-masterclass: - prd.md: Auto-detect project context (package.json, pyproject.toml, etc.) - NEW_PROJECT_MODE: ~10 questions for new projects - FEATURE_MODE: ~5-7 questions for existing projects - Uses AskUserQuestion for interactive UX - Optional WebSearch for best practices - convert.md: Extended functionality - Generates .claude/settings.json with allow-list per tech stack - Extracts real commands from package.json scripts - Adds techStack info to prd.json - Creates screenshots/ directory - prompt.md: Browser verification with agent-browser CLI - Compact refs (@e1, @e2) for minimal token usage - requiresBrowserCheck flag per story - Screenshot saving for UI verification - ralph.sh: Screenshots directory + agent-browser check - README.md: Complete rewrite with new features Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-22 13:15:43 +00:00
parent 3d52ac696c
commit 0050fc66ef
7 changed files with 906 additions and 150 deletions
--- a/plugins/ralph/commands/prd.md
+++ b/plugins/ralph/commands/prd.md
@@ -4,7 +4,7 @@ description: Generează un Product Requirements Document (PRD) structurat pentru

 # Skill: PRD Generator

-Generează un Product Requirements Document (PRD) detaliat pentru funcționalități noi prin întrebări clarificatoare și documentație structurată.
+Generează un Product Requirements Document (PRD) detaliat prin detecție automată a contextului și întrebări adaptive.

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

@@ -14,43 +14,305 @@ Generează un Product Requirements Document (PRD) detaliat pentru funcționalit

 ## Workflow

-### Pas 1: Întrebări de clarificare
+### FAZA 1: Detecție Context Proiect

-Înainte de a genera PRD-ul, pune 3-5 întrebări pentru a înțelege scopul:
+**Verifică existența fișierelor de config pentru a determina modul:**

-```markdown
-Pentru a genera un PRD bun, am câteva întrebări:
-
-**A) Care este scopul principal?**
-1. Funcționalitate nouă pentru utilizatori
-2. Îmbunătățire performanță/scalabilitate
-3. Refactoring/cleanup cod existent
-4. Integrare cu sistem extern
-
-**B) Cine sunt utilizatorii țintă?**
-1. End users (clienți finali)
-2. Admin/Staff intern
-3. Developers (API/SDK)
-4. Sistem automatizat
-
-**C) Ce constrângeri tehnice există?**
-1. Trebuie să folosească framework/librărie existentă
-2. Fără dependențe externe noi
-3. Compatibilitate backwards necesară
-4. Flexibil
-
-**D) Care e prioritatea?**
-1. Urgent (blocant pentru release)
-2. Important (următorul sprint)
-3. Nice-to-have (când e timp)
-
-**E) Ai specificații vizuale sau mockups?**
-1. Da, am wireframes/mockups
-2. Am idee generală în minte
-3. Flexibil, propune tu
+```
+package.json       → Node.js/JavaScript ecosystem
+pyproject.toml     → Python
+requirements.txt   → Python (legacy)
+go.mod             → Go
+Cargo.toml         → Rust
+pom.xml            → Java (Maven)
+build.gradle       → Java (Gradle)
+composer.json      → PHP
+Gemfile            → Ruby
 ```

-### Pas 2: Generează PRD-ul
+**DACĂ găsit config file:**
+1. Citește fișierul de config pentru a extrage:
+   - Dependențe principale (framework-uri, librării)
+   - Scripturi disponibile (pentru package.json)
+   - Versiuni
+2. Analizează structura directoarelor:
+   - `src/`, `app/`, `components/`, `pages/`, `api/`
+   - Identifică patterns: Next.js, React, Express, etc.
+3. Raportează utilizatorului:
+   ```
+   Am detectat un proiect existent:
+   - Stack: Next.js 14, TypeScript, Prisma, TailwindCSS
+   - Structură: App Router (app/), API routes (app/api/)
+   - Scripts: dev, build, lint, typecheck
+   ```
+4. Setează: **FEATURE_MODE**
+
+**DACĂ NU găsit config file:**
+1. Raportează: "Nu am detectat un proiect existent. Vom crea PRD pentru proiect nou."
+2. Setează: **NEW_PROJECT_MODE**
+
+---
+
+### FAZA 2: Întrebări Adaptive cu AskUserQuestion
+
+**IMPORTANT**: Folosește tool-ul `AskUserQuestion` pentru întrebări interactive, NU text simplu.
+
+---
+
+#### IF NEW_PROJECT_MODE:
+
+**Întrebarea 1** (AskUserQuestion):
+```json
+{
+  "question": "Ce tip de proiect vrei să creezi?",
+  "header": "Tip proiect",
+  "options": [
+    {"label": "Web Application", "description": "Frontend + Backend, UI interactiv"},
+    {"label": "API / Backend", "description": "REST/GraphQL API, servicii backend"},
+    {"label": "CLI Tool", "description": "Command-line application"},
+    {"label": "Library / SDK", "description": "Cod reutilizabil pentru alți developeri"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 2** (AskUserQuestion):
+```json
+{
+  "question": "Cine sunt utilizatorii țintă?",
+  "header": "Audiență",
+  "options": [
+    {"label": "End users", "description": "Clienți finali, public larg"},
+    {"label": "Developers", "description": "API/SDK consumers, tehnici"},
+    {"label": "Admin / Staff", "description": "Utilizatori interni, back-office"},
+    {"label": "Sistem automatizat", "description": "Integrări machine-to-machine"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 3** (AskUserQuestion):
+```json
+{
+  "question": "Ce tech stack preferi?",
+  "header": "Stack",
+  "options": [
+    {"label": "Next.js + TypeScript (Recommended)", "description": "Full-stack React, App Router, API routes"},
+    {"label": "Node.js + Express", "description": "Backend flexibil, REST API"},
+    {"label": "Python + FastAPI", "description": "API modern, async, type hints"},
+    {"label": "Go", "description": "Performance, simplitate, concurrency"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 4** (AskUserQuestion):
+```json
+{
+  "question": "Ce arhitectură de date preferi?",
+  "header": "Database",
+  "options": [
+    {"label": "PostgreSQL + Prisma (Recommended)", "description": "Relațional, ORM type-safe"},
+    {"label": "MongoDB", "description": "Document store, schema flexibilă"},
+    {"label": "SQLite", "description": "Simplitate, embedded, local-first"},
+    {"label": "Fără persistență", "description": "In-memory, stateless"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 5** (AskUserQuestion):
+```json
+{
+  "question": "Cum va arăta interfața?",
+  "header": "UI/UX",
+  "options": [
+    {"label": "Dashboard / Admin Panel", "description": "Tabele, grafice, forms complexe"},
+    {"label": "Landing + App simplu", "description": "Marketing + funcționalitate core"},
+    {"label": "API only (no UI)", "description": "Doar backend, documentație API"},
+    {"label": "CLI interface", "description": "Terminal-based interaction"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 6** (AskUserQuestion):
+```json
+{
+  "question": "Ce tip de autentificare e necesar?",
+  "header": "Auth",
+  "options": [
+    {"label": "Email + Password", "description": "Classic login, JWT sessions"},
+    {"label": "OAuth / Social login", "description": "Google, GitHub, etc."},
+    {"label": "API Keys", "description": "Pentru servicii și integrări"},
+    {"label": "Fără autentificare", "description": "Public access"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 7** (AskUserQuestion):
+```json
+{
+  "question": "Ce integrări externe sunt necesare?",
+  "header": "Integrări",
+  "options": [
+    {"label": "Payment (Stripe)", "description": "Procesare plăți, subscriptions"},
+    {"label": "Email (Resend/SendGrid)", "description": "Trimitere emails tranzacționale"},
+    {"label": "Storage (S3/Cloudflare)", "description": "Upload fișiere, imagini"},
+    {"label": "Niciuna", "description": "Self-contained, fără dependențe externe"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 8** (AskUserQuestion):
+```json
+{
+  "question": "Care e prioritatea acestui proiect?",
+  "header": "Prioritate",
+  "options": [
+    {"label": "MVP rapid", "description": "Funcționalitate minimă, lansare rapidă"},
+    {"label": "Produs complet", "description": "Feature-complete, production-ready"},
+    {"label": "Proof of concept", "description": "Validare idee, poate fi refăcut"},
+    {"label": "Learning project", "description": "Experimentare, nu contează calitatea"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 9** (AskUserQuestion):
+```json
+{
+  "question": "Cum definim succesul? Ce criterii trebuie îndeplinite?",
+  "header": "Success",
+  "options": [
+    {"label": "Funcționalitate completă", "description": "Toate features funcționează conform spec"},
+    {"label": "Performance targets", "description": "Timp răspuns < X ms, throughput > Y"},
+    {"label": "User adoption", "description": "N utilizatori activi, engagement"},
+    {"label": "Code quality", "description": "Test coverage > 80%, no critical bugs"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 10** (text liber - cere descriere):
+```
+Descrie pe scurt proiectul în 2-3 propoziții:
+- Ce problemă rezolvă?
+- Care e funcționalitatea principală?
+```
+
+**Întrebarea 11 - Web Research** (AskUserQuestion):
+```json
+{
+  "question": "Vrei să cercetez best practices și patterns pentru acest stack?",
+  "header": "Research",
+  "options": [
+    {"label": "Da, cercetează", "description": "WebSearch pentru patterns și recomandări"},
+    {"label": "Nu, continuă", "description": "Am experiență cu acest stack"}
+  ],
+  "multiSelect": false
+}
+```
+
+**DACĂ utilizatorul alege "Da, cercetează":**
+- Folosește `WebSearch` pentru: "[stack] best practices 2026"
+- Integrează findings în secțiunea "Considerații Tehnice" din PRD
+
+---
+
+#### IF FEATURE_MODE:
+
+**Întrebarea 1** (text liber):
+```
+Descrie feature-ul pe care vrei să-l adaugi:
+- Ce funcționalitate nouă?
+- Care e scopul principal?
+```
+
+**Întrebarea 2** (AskUserQuestion):
+```json
+{
+  "question": "Ce tip de feature este acesta?",
+  "header": "Tip feature",
+  "options": [
+    {"label": "Funcționalitate nouă", "description": "Ceva ce nu există în app"},
+    {"label": "Îmbunătățire UX", "description": "Flow mai bun, mai intuitiv"},
+    {"label": "Performance", "description": "Optimizare viteză, eficiență"},
+    {"label": "Integrare externă", "description": "Conectare cu alt sistem/serviciu"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 3** (AskUserQuestion):
+```json
+{
+  "question": "Implică modificări de UI?",
+  "header": "UI changes",
+  "options": [
+    {"label": "Da - componente noi", "description": "Pagini sau secțiuni noi"},
+    {"label": "Da - modificări existente", "description": "Update la UI existent"},
+    {"label": "Nu - doar backend", "description": "Logic, API, fără UI"}
+  ],
+  "multiSelect": false
+}
+```
+
+**Întrebarea 4** (AskUserQuestion):
+```json
+{
+  "question": "Necesită modificări în baza de date?",
+  "header": "DB changes",
+  "options": [
+    {"label": "Da - tabele noi", "description": "Noi entități de stocat"},
+    {"label": "Da - coloane noi", "description": "Câmpuri noi pe tabele existente"},
+    {"label": "Da - relații noi", "description": "Legături între tabele"},
+    {"label": "Nu", "description": "Schema rămâne neschimbată"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 5** (AskUserQuestion):
+```json
+{
+  "question": "Sunt necesare integrări noi cu servicii externe?",
+  "header": "Integrări",
+  "options": [
+    {"label": "Da - API extern", "description": "Conectare la serviciu terț"},
+    {"label": "Da - Webhooks", "description": "Primire/trimitere events"},
+    {"label": "Nu", "description": "Self-contained în app"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 6** (AskUserQuestion):
+```json
+{
+  "question": "Există considerații speciale de security?",
+  "header": "Security",
+  "options": [
+    {"label": "Autorizare/permisiuni", "description": "Cine poate accesa ce"},
+    {"label": "Date sensibile", "description": "PII, payment, credentials"},
+    {"label": "Rate limiting", "description": "Protecție abuse"},
+    {"label": "Nu, standard", "description": "Fără cerințe speciale"}
+  ],
+  "multiSelect": true
+}
+```
+
+**Întrebarea 7** (text liber):
+```
+Cum verificăm că feature-ul funcționează corect?
+Descrie acceptance criteria (ce trebuie să se întâmple când e gata):
+```
+
+---
+
+### FAZA 3: Generează PRD-ul

 După răspunsuri, creează documentul în `/tasks/prd-[feature-name].md`:

@@ -58,49 +320,55 @@ După răspunsuri, creează documentul în `/tasks/prd-[feature-name].md`:
 # PRD: [Feature Name]

 ## 1. Introducere
-[Context și motivație pentru feature - 2-3 propoziții]
+[Context și motivație pentru feature - 2-3 propoziții bazate pe răspunsuri]

-## 2. Obiective
+## 2. Context Tehnic
+[DOAR pentru FEATURE_MODE - include stack-ul detectat]
+- **Stack**: [detectat din config]
+- **Structură**: [detectat din directoare]
+- **Comenzi disponibile**: [din package.json scripts]
+
+## 3. Obiective
 ### Obiectiv Principal
- [Ce problem rezolvă]
+- [Ce problemă rezolvă - din răspunsuri]

 ### Obiective Secundare
 - [Beneficii adiționale]

 ### Metrici de Succes
- [Cum măsurăm dacă e reușit]
+- [Din răspunsul la întrebarea despre success criteria]

-## 3. User Stories
+## 4. User Stories

 ### US-001: [Titlu Descriptiv]
-**Ca** [tip utilizator]
+**Ca** [tip utilizator - din răspunsuri]
 **Vreau** [funcționalitate]
 **Pentru că** [beneficiu]

 **Acceptance Criteria:**
 - [ ] Criteriu 1 specific și testabil
 - [ ] Criteriu 2 specific și testabil
- [ ] npm run typecheck passes
- [ ] [Pentru UI] Verify in browser that [comportament specific]
+- [ ] {TYPECHECK_COMMAND} passes
+- [ ] [Pentru UI] Verificare vizuală cu browser: [comportament specific]

 ### US-002: [Titlu]
 ...

-## 4. Cerințe Funcționale
+## 5. Cerințe Funcționale
 1. [REQ-001] Sistemul trebuie să...
 2. [REQ-002] Utilizatorul poate să...
 3. [REQ-003] Când X se întâmplă, Y trebuie să...

-## 5. Non-Goals (Ce NU facem)
+## 6. Non-Goals (Ce NU facem)
 - [Explicit ce nu e în scope pentru a evita scope creep]
 - [Funcționalități similare care NU sunt incluse]

-## 6. Considerații Tehnice
+## 7. Considerații Tehnice
 ### Stack/Tehnologii
- [Ce framework/librării se folosesc]
+- [Din detecție sau răspunsuri]

 ### Patterns de Urmat
- [Patterns existente în codebase]
+- [Patterns existente în codebase - din analiză]

 ### Dependențe
 - [De ce depinde acest feature]
@@ -108,47 +376,43 @@ După răspunsuri, creează documentul în `/tasks/prd-[feature-name].md`:
 ### Riscuri Tehnice
 - [Potențiale probleme]

-## 7. Considerații UI/UX
-[Dacă e relevant]
+### Best Practices
+[Dacă s-a făcut WebSearch, include findings aici]
+
+## 8. Considerații UI/UX
+[Dacă UI changes != "Nu - doar backend"]
 - Layout și flow
 - Stări (loading, error, empty, success)
 - Accesibilitate

-## 8. Success Metrics
- [KPI 1]: [target]
- [KPI 2]: [target]
+## 9. Considerații Security
+[Din răspunsul la întrebarea despre security]

-## 9. Open Questions
+## 10. Open Questions
 - [ ] [Întrebări nerezolvate care necesită clarificare]
 ```

-### Pas 3: Validare cu utilizatorul
+---

-După generare, întreabă:
- "PRD-ul acoperă tot ce ai în minte?"
- "Vrei să adaugi sau să modifici ceva?"
- "Stories-urile sunt de mărime potrivită pentru implementare incrementală?"
+### FAZA 4: Validare și salvare

-### Pas 4: Salvare
+1. **Afișează preview** al PRD-ului generat
+2. **Întreabă** utilizatorul:
+   - "PRD-ul acoperă tot ce ai în minte?"
+   - "Vrei să adaugi sau să modifici ceva?"
+   - "Stories-urile sunt de mărime potrivită pentru implementare incrementală?"
+3. **Salvează** în `/tasks/prd-[feature-name].md`
+4. **Sugerează următorul pas**:
+   ```
+   PRD salvat în tasks/prd-[feature-name].md

-```bash
-# Crează directorul tasks dacă nu există
-mkdir -p tasks
+   **Următorii pași:**
+   1. Revizuiește PRD-ul și adaugă detalii dacă e nevoie
+   2. Când ești gata, folosește `/ralph:convert` pentru a converti în prd.json
+   3. Apoi rulează `./scripts/ralph/ralph.sh` pentru implementare autonomă
+   ```

-# Salvează PRD-ul
-# Folosește kebab-case pentru nume
-```
-
-### Pas 5: Sugerează următorul pas
-
-```markdown
-PRD salvat în tasks/prd-[feature-name].md
-
-**Următorii pași:**
-1. Revizuiește PRD-ul și adaugă detalii dacă e nevoie
-2. Când ești gata, folosește `/ralph:convert` pentru a converti în prd.json
-3. Apoi rulează `./scripts/ralph/ralph.sh` pentru implementare autonomă
-```
+---

 ## Reguli pentru User Stories bune

@@ -176,19 +440,23 @@ PRD salvat în tasks/prd-[feature-name].md
 - Verificabile: "După submit, redirect la /dashboard"
 - NU subiective: "UX plăcut"

- Include ÎNTOTDEAUNA: "npm run typecheck passes"
- Pentru UI: "Verify in browser that [behavior]"
+- Include ÎNTOTDEAUNA comanda de typecheck din proiect
+- Pentru UI: "Verificare vizuală cu browser că [behavior]"
+
+---

 ## Output așteptat

 - Fișier `/tasks/prd-[feature-name].md` cu documentație completă
 - User stories clare, atomice, cu acceptance criteria verificabile
 - Non-goals explicit definite
+- Context tehnic detectat (pentru FEATURE_MODE)

 ## Important

 1. **NU începe implementarea** - acest skill doar generează documentație
-2. **Întreabă clarificări** înainte de a genera
-3. **Stories atomice** - fiecare trebuie să fie independent completabil
-4. **Acceptance criteria verificabile** - nu vagi
-5. **Kebab-case** pentru nume fișiere
+2. **Folosește AskUserQuestion** pentru întrebări interactive
+3. **Detectează contextul** înainte de a pune întrebări
+4. **Stories atomice** - fiecare trebuie să fie independent completabil
+5. **Acceptance criteria verificabile** - nu vagi
+6. **Kebab-case** pentru nume fișiere