romfast/claude-plugins
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
Claude Agent
2026-01-22 13:15:43 +00:00
parent 3d52ac696c
commit 0050fc66ef
7 changed files with 906 additions and 150 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
plugins/ralph/README.md
View File

@@ -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