diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 01c7507..179a3bc 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -17,9 +17,9 @@ { "name": "ralph", "source": "./plugins/ralph", - "description": "Autonomous loop for PRD implementation with Claude Code", - "version": "1.0.0", - "keywords": ["ralph", "prd", "autonomous", "agent", "loop"] + "description": "Autonomous loop for PRD implementation - context detection, adaptive questions, browser verification", + "version": "1.1.0", + "keywords": ["ralph", "prd", "autonomous", "agent", "loop", "browser", "verification"] } ] } diff --git a/plugins/ralph/.claude-plugin/plugin.json b/plugins/ralph/.claude-plugin/plugin.json index d7df349..16de6d5 100644 --- a/plugins/ralph/.claude-plugin/plugin.json +++ b/plugins/ralph/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "ralph", - "description": "Autonomous loop for PRD implementation with Claude Code", - "version": "1.0.0", + "description": "Autonomous loop for PRD implementation with Claude Code - context detection, adaptive questions, browser verification", + "version": "1.1.0", "author": { "name": "Romfast Team" } diff --git a/plugins/ralph/README.md b/plugins/ralph/README.md index b46a112..303a29b 100644 --- a/plugins/ralph/README.md +++ b/plugins/ralph/README.md @@ -2,38 +2,77 @@ **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. +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 întrebări clarificatoare | -| `/ralph:convert` | Convertește PRD markdown în prd.json pentru execuție | +| `/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 ``` -1. /ralph:prd → Generează PRD markdown cu întrebări clarificatoare -2. /ralph:convert → Convertește PRD în prd.json pentru execuție -3. ./ralph.sh → Rulează loop-ul autonom +┌─────────────────────────────────────────────────────────────┐ +│ 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 │ +└─────────────────────────────────────────────────────────────┘ ``` -## Ciclul Ralph +## Cerințe -``` -┌──────────────────────────────────────────────────────────────────┐ -│ CICLUL RALPH │ -├──────────────────────────────────────────────────────────────────┤ -│ 1. Citește prd.json → selectează story cu prioritate minimă │ -│ 2. Lansează instanță fresh Claude Code (context curat) │ -│ 3. Implementează story-ul selectat │ -│ 4. Rulează quality checks (typecheck, tests, lint) │ -│ 5. Commit dacă trece → marchează story ca "passes: true" │ -│ 6. Salvează learnings în progress.txt │ -│ 7. Repetă până toate story-urile sunt complete │ -└──────────────────────────────────────────────────────────────────┘ -``` +### 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 @@ -45,7 +84,13 @@ Adaptat din [snarktank/ralph](https://github.com/snarktank/ralph) pentru Claude Vreau să adaug funcționalitate de export CSV pentru dashboard. ``` -Claude va pune întrebări clarificatoare și va genera PRD în `/tasks/prd-export-csv.md`. +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 @@ -55,7 +100,11 @@ Claude va pune întrebări clarificatoare și va genera PRD în `/tasks/prd-expo Convertește PRD-ul din tasks/prd-export-csv.md ``` -Claude va crea structura `scripts/ralph/` și genera `prd.json`. +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 @@ -66,31 +115,96 @@ Claude va crea structura `scripts/ralph/` și genera `prd.json`. ### 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 -│ ├── prd.json # Task-uri și status (generat) +│ ├── 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 +│ ├── logs/ # Logs per iterație +│ ├── archive/ # Arhive rulări anterioare +│ └── screenshots/ # Screenshots verificări UI └── tasks/ └── prd-*.md # PRD-uri markdown ``` -## Templates incluse +## Format prd.json -| Template | Descriere | -|----------|-----------| -| `ralph.sh` | Scriptul principal de loop autonom | -| `prompt.md` | Instrucțiuni pentru fiecare iterație | -| `prd-template.json` | Schema JSON pentru PRD | +```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 @@ -107,12 +221,41 @@ your-project/ 4. UI components (priority: 31-40) 5. Integration/polish (priority: 41-50) -## Cerințe +### Acceptance Criteria +- Specifice și verificabile +- Include comanda typecheck reală din proiect +- Pentru UI: "Verificare vizuală browser că [behavior]" -- Claude Code CLI instalat și autentificat -- `jq` pentru procesare JSON -- Git repository +## 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 diff --git a/plugins/ralph/commands/convert.md b/plugins/ralph/commands/convert.md index c27ec5a..95115c8 100644 --- 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 diff --git a/plugins/ralph/commands/prd.md b/plugins/ralph/commands/prd.md index 7212e17..d5f0cb7 100644 --- 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 diff --git a/plugins/ralph/templates/prompt.md b/plugins/ralph/templates/prompt.md index cb8711a..25f7f9b 100644 --- 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 diff --git a/plugins/ralph/templates/ralph.sh b/plugins/ralph/templates/ralph.sh index 859e55f..b335ea7 100755 --- 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 ""