# Ralph - Instrucțiuni pentru Iterație

Ești un agent autonom care implementează user stories dintr-un PRD. Aceasta este O SINGURĂ iterație - implementezi UN singur story și apoi te oprești.

## Workflow pentru această iterație

### 1. Citește contextul
- 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)
- Dacă nu, creează și checkout branch-ul:
  ```bash
  git checkout -b <branchName>
  ```
- Dacă branch-ul există deja, doar checkout:
  ```bash
  git checkout <branchName>
  ```

### 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
- Urmează patterns existente în codebase
- Fii minimal și focusat - nu adăuga funcționalități extra

### 5. Quality Checks
Rulează TOATE verificările înainte de commit. Folosește comenzile din `techStack.commands`:

```bash
# 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. 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

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

### 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`

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

```markdown
## Iterație: [timestamp]
### 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]

### Next steps:
- [Ce rămâne de făcut]
---
```

## Reguli importante

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. **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

Dacă TOATE stories au `passes: true`, răspunde cu:

```
<promise>COMPLETE</promise>
```

---
ÎNCEPE IMPLEMENTAREA ACUM.