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/convert.md
+++ b/plugins/ralph/commands/convert.md
@@ -29,13 +29,145 @@ Citește fișierul PRD și identifică:
 - User stories cu acceptance criteria
 - Dependențe între stories

-### Pas 3: Creează structura Ralph
+### Pas 3: Detectează Tech Stack

-```bash
-mkdir -p scripts/ralph/logs scripts/ralph/archive
+**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
 ```

-### Pas 4: Generează prd.json
+**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ă:

@@ -44,6 +176,17 @@ 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",
@@ -54,6 +197,7 @@ Convertește user stories în format JSON cu următoarea structură:
        "Criteriu specific și verificabil",
        "npm run typecheck passes"
      ],
+      "requiresBrowserCheck": true,
      "passes": false,
      "notes": ""
    }
@@ -61,7 +205,13 @@ Convertește user stories în format JSON cu următoarea structură:
 }
 ```

-### Pas 5: Validează mărimea stories
+**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.

@@ -78,7 +228,7 @@ Convertește user stories în format JSON cu următoarea structură:

 Dacă găsești stories prea mari, sparge-le în sub-stories mai mici.

-### Pas 6: Setează prioritățile
+### Pas 8: Setează prioritățile

 Ordinea recomandată:
 1. Schema/Database changes (priority: 1-10)
@@ -89,35 +239,92 @@ Ordinea recomandată:

 Stories care depind de altele trebuie să aibă prioritate mai mare (număr mai mare).

-### Pas 7: Verifică acceptance criteria
+### Pas 9: Verifică acceptance criteria

 Fiecare story TREBUIE să aibă:
 - Criterii specifice și verificabile (NU vagi ca "funcționează bine")
- `npm run typecheck passes` (sau echivalent)
- Pentru UI: `Verify in browser that [specific behavior]`
+- Comanda reală de typecheck: `{TYPECHECK_COMMAND} passes`
+- Pentru UI: `Verificare vizuală browser: [specific behavior]`

-### Pas 8: Copiază fișierele Ralph
+### Pas 10: Copiază și actualizează fișierele Ralph

-Dacă nu există deja, copiază template-urile din plugin:
+**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)

-### Pas 9: Inițializează progress.txt
+**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 10: Instrucțiuni finale
+### 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]
@@ -125,18 +332,29 @@ Pentru a rula Ralph:
 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
+- `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. **Validează mărimea stories** - sparge-le dacă sunt prea mari
-3. **Prioritizează corect** - dependențele trebuie respectate
-4. **Criterii verificabile** - nu vagi, ci specifice
-5. **Inițializează `passes: false`** pentru toate stories
+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