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/templates/prompt.md
+++ b/plugins/ralph/templates/prompt.md
@@ -8,6 +8,7 @@ Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta es
 - PRD-ul și progress.txt sunt furnizate în context
 - Înțelege ce stories sunt deja complete (`passes: true`)
 - Identifică următorul story de implementat (prioritate cea mai mică dintre cele incomplete)
+- Notează `techStack.commands` din PRD pentru comenzile corecte

 ### 2. Management branch
 - Verifică dacă ești pe branch-ul corect (specificat în `branchName` din PRD)
@@ -23,6 +24,7 @@ Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta es
 ### 3. Selectează story-ul
 - Alege story-ul cu cea mai mică prioritate care are `passes: false`
 - Citește atent acceptance criteria
+- Verifică câmpul `requiresBrowserCheck` - dacă e `true`, trebuie verificare vizuală

 ### 4. Implementare
 - Implementează DOAR acest story
@@ -30,34 +32,114 @@ Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta es
 - Fii minimal și focusat - nu adăuga funcționalități extra

 ### 5. Quality Checks
-Rulează TOATE verificările înainte de commit:
+Rulează TOATE verificările înainte de commit. Folosește comenzile din `techStack.commands`:
+
 ```bash
-npm run typecheck    # sau echivalentul proiectului
-npm run lint         # dacă există
-npm run test         # dacă există
+# Folosește comenzile din prd.json techStack.commands:
+{techStack.commands.typecheck}   # Type checking
+{techStack.commands.lint}        # Linting
+{techStack.commands.test}        # Tests (dacă există)
 ```

+**Comenzi standard per stack:**
+
+| Stack | Typecheck | Lint | Test |
+|-------|-----------|------|------|
+| Next.js/TS | npm run typecheck | npm run lint | npm test |
+| Node.js | npm run typecheck | npm run lint | npm test |
+| Python | mypy . | ruff check . | python -m pytest |
+| Go | - | golangci-lint run | go test ./... |
+
 **IMPORTANT**: Nu face commit dacă verificările eșuează. Repară mai întâi.

-### 6. Documentare (dacă ai descoperit ceva util)
+### 6. Verificare Browser (pentru UI stories)
+
+**DACĂ story-ul are `requiresBrowserCheck: true` sau implică UI:**
+
+Folosește **agent-browser CLI** pentru verificare vizuală. Agent-browser e optimizat pentru agenți AI cu referințe compacte (@e1, @e2) care consumă minim tokeni.
+
+#### 6.1 Pornește dev server-ul
+```bash
+# Folosește comanda din techStack.commands.start
+{techStack.commands.start}
+# Exemplu: npm run dev
+```
+
+Așteaptă să pornească (verifică output-ul pentru "ready" sau similar).
+
+#### 6.2 Navighează la pagină
+```bash
+agent-browser navigate "http://localhost:{techStack.port}"
+# Exemplu: agent-browser navigate "http://localhost:3000"
+```
+
+#### 6.3 Ia snapshot pentru verificare
+```bash
+agent-browser snapshot
+```
+
+Snapshot-ul returnează o listă de elemente cu referințe compacte:
+```
+@e1: heading "Welcome"
+@e2: button "Login"
+@e3: textbox "Email"
+@e4: textbox "Password"
+@e5: button "Submit"
+```
+
+**Verifică în snapshot:**
+- Elementele cheie din acceptance criteria există
+- Textul e corect
+- Structura paginii e corectă
+
+#### 6.4 Testează interacțiunile (dacă e cazul)
+```bash
+# Click pe un element
+agent-browser click @e2
+
+# Fill un input
+agent-browser fill @e3 "test@example.com"
+
+# Așteaptă o schimbare
+agent-browser snapshot  # verifică noua stare
+```
+
+#### 6.5 Salvează screenshot ca dovadă
+```bash
+agent-browser screenshot ./scripts/ralph/screenshots/US-{id}-$(date +%Y%m%d-%H%M%S).png
+# Exemplu: agent-browser screenshot ./scripts/ralph/screenshots/US-001-20240115-143022.png
+```
+
+#### 6.6 Verifică erori
+```bash
+# Verifică console pentru erori
+agent-browser console
+```
+
+**IMPORTANT**:
+- NU marca story-ul complete dacă verificarea vizuală eșuează!
+- Dacă găsești erori în browser, repară-le înainte de commit
+- Screenshots sunt salvate în `scripts/ralph/screenshots/` pentru referință
+
+### 7. Documentare (dacă ai descoperit ceva util)
 Dacă ai descoperit patterns sau gotchas, actualizează `AGENTS.md` în directorul relevant:
 - API patterns
 - Dependențe non-evidente
 - Convenții de cod
 - Cum să testezi anumite funcționalități

-### 7. Commit
+### 8. Commit
 Format commit message:
 ```
 feat: [Story ID] - [Story Title]
 ```

-### 8. Marchează story-ul ca complet
+### 9. Marchează story-ul ca complet
 **CRITIC**: Actualizează `scripts/ralph/prd.json`:
 - Setează `passes: true` pentru story-ul implementat
 - Adaugă note relevante în câmpul `notes`

-### 9. Actualizează progress.txt
+### 10. Actualizează progress.txt
 Adaugă la sfârșitul fișierului `scripts/ralph/progress.txt`:

 ```markdown
@@ -65,6 +147,12 @@ Adaugă la sfârșitul fișierului `scripts/ralph/progress.txt`:
 ### Story implementat: [ID] - [Title]
 ### Status: Complete

+### Verificări:
+- Typecheck: PASS
+- Lint: PASS
+- Tests: PASS/SKIP
+- Browser check: PASS/N/A
+
 ### Learnings:
 - [Ce ai învățat]
 - [Patterns descoperite]
@@ -78,8 +166,34 @@ Adaugă la sfârșitul fișierului `scripts/ralph/progress.txt`:

 1. **UN SINGUR STORY PE ITERAȚIE** - Nu implementa mai mult de un story
 2. **TOATE CHECKS TREBUIE SĂ TREACĂ** - Nu face commit cu erori
-3. **ACTUALIZEAZĂ prd.json** - Altfel iterația următoare va repeta munca
-4. **FII CONCIS** - Nu over-engineer
+3. **VERIFICARE BROWSER PENTRU UI** - Obligatorie dacă `requiresBrowserCheck: true`
+4. **ACTUALIZEAZĂ prd.json** - Altfel iterația următoare va repeta munca
+5. **FII CONCIS** - Nu over-engineer
+
+## Comenzi agent-browser (referință rapidă)
+
+```bash
+# Navigare
+agent-browser navigate "http://localhost:3000/page"
+
+# Snapshot (vedere compactă a paginii)
+agent-browser snapshot
+
+# Click pe element (folosind ref din snapshot)
+agent-browser click @e5
+
+# Fill input
+agent-browser fill @e3 "value"
+
+# Screenshot
+agent-browser screenshot ./path/to/file.png
+
+# Console logs
+agent-browser console
+
+# Așteaptă text
+agent-browser wait-for "Loading complete"
+```

 ## Condiție de terminare

--- a/plugins/ralph/templates/ralph.sh
+++ b/plugins/ralph/templates/ralph.sh
@@ -11,6 +11,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PRD_FILE="$SCRIPT_DIR/prd.json"
 PROGRESS_FILE="$SCRIPT_DIR/progress.txt"
 ARCHIVE_DIR="$SCRIPT_DIR/archive"
+SCREENSHOTS_DIR="$SCRIPT_DIR/screenshots"
 LAST_BRANCH_FILE="$SCRIPT_DIR/.last-branch"
 PROMPT_FILE="$SCRIPT_DIR/prompt.md"

@@ -27,6 +28,14 @@ if ! command -v claude &> /dev/null; then
    exit 1
 fi

+# Verifică agent-browser (opțional, pentru verificări UI)
+if ! command -v agent-browser &> /dev/null; then
+    echo "Notă: agent-browser nu este instalat."
+    echo "Pentru verificări vizuale UI, instalează cu: npm install -g agent-browser && agent-browser install"
+    echo "Continuăm fără verificări browser..."
+    echo ""
+fi
+
 # Verifică existența fișierelor necesare
 if [ ! -f "$PRD_FILE" ]; then
    echo "Eroare: prd.json nu există în $SCRIPT_DIR"
@@ -71,6 +80,9 @@ if [ -f "$PRD_FILE" ]; then
  fi
 fi

+# Creează directoare necesare
+mkdir -p "$SCRIPT_DIR/logs" "$SCRIPT_DIR/archive" "$SCRIPT_DIR/screenshots"
+
 # Inițializare progress file dacă nu există
 if [ ! -f "$PROGRESS_FILE" ]; then
  echo "# Ralph Progress Log" > "$PROGRESS_FILE"
@@ -97,6 +109,7 @@ echo "  Proiect: $PROJECT_NAME"
 echo "  Branch: $BRANCH_NAME"
 echo "  Stories: $COMPLETE_STORIES / $TOTAL_STORIES complete"
 echo "  Max iterații: $MAX_ITERATIONS"
+echo "  Screenshots: $SCREENSHOTS_DIR"
 echo "======================================================================="
 echo ""