clawd/memory/kb/tools/antfarm-flux-complet.md

# Antfarm - Flux Complet cu Discovery & PRD

**Data:** 2026-02-10  
**Inspirat din:** ralph skill /prd command

---

## Problema cu Fluxul Vechi

❌ **Ce nu a funcționat:**
- Am lansat direct `antfarm workflow run` cu prompt vag
- Planner (Sonnet) a interpretat minimal → feature incomplet
- Test files în dashboard/ → aglomerare
- Fără întrebări UX → implementare basic fără customizare

---

## Fluxul NOU (80/20)

### FAZA 1: Discovery cu Întrebări (Echo, Opus)

**Când primesc request pentru feature nou:**

1. **Detectez context** (proiect existent vs nou)
   - Citesc ~/clawd/dashboard/ pentru stack actual
   - Identific patterns existente (common.css, api.py, etc.)

2. **Pun întrebări adaptive** (ca ralph /prd):

**Pentru FEATURE în proiect existent (dashboard):**

```
Întrebarea 1: Ce funcționalitate nouă vrei?
- Descrie în 2-3 propoziții

Întrebarea 2: Ce tip de feature?
- Funcționalitate nouă
- Îmbunătățire UX
- Integrare externă

Întrebarea 3: Implică UI?
- Da - componente noi (pagină separată)
- Da - secțiune în index.html
- Nu - doar backend

Întrebarea 4: Modificări DB?
- Da - fișier JSON nou
- Da - câmpuri noi în JSON existent
- Nu

Întrebarea 5 (CRITICĂ pentru UX): Cum arată UI-ul?
- Layout: listă simplă / cards / table / kanban
- Features: create, edit, delete, filter, sort, export
- Customizare: frecvență, categorii, culori, icoane
- Mobile responsive: da/nu

Întrebarea 6: Acceptance criteria?
- Ce trebuie să funcționeze exact?
- Cum testăm că e gata?

Întrebarea 7: Structură fișiere?
- Tests în dashboard/tests/ sau tests/
- Assets separate? (imagini, icons)
```

---

### FAZA 2: Generez PRD Complet (Echo, Opus)

Bazat pe răspunsuri, creez:

**`~/clawd/tasks/prd-FEATURE-NAME.md`**

```markdown
# PRD: [Feature Name]

## 1. Context Tehnic
- **Proiect:** Echo Dashboard
- **Stack:** Python (api.py), HTML+Vanilla JS, common.css
- **Storage:** JSON files (tasks.json, todos.json, etc.)
- **Patterns existente:** 
  - API endpoints în api.py (handle_X_get, handle_X_post)
  - Frontend: fetch('/echo/api/X'), common.css pentru styling
  - Mobile: swipe-nav.js pentru navigare touch

## 2. Obiective
### Obiectiv Principal
[Din răspunsul utilizatorului]

### Metrici Succes
[Din acceptance criteria]

## 3. User Stories (Ordonate Dependencies-First)

### US-001: Schema și Storage
**Ca** developer
**Vreau** să definesc structura de date
**Pentru că** backend și frontend depind de ea

**Acceptance Criteria:**
- [ ] Fișier FEATURE.json cu schema corectă
- [ ] Funcții helper pentru streak/calculation logic
- [ ] Documentație format data în cod

### US-002: Backend API - GET
**Ca** frontend
**Vreau** să pot citi datele
**Pentru că** trebuie să afișez lista

**Acceptance Criteria:**
- [ ] Endpoint GET /api/FEATURE în api.py
- [ ] Returnează JSON cu toate intrările
- [ ] Tests pentru GET în dashboard/tests/test_FEATURE_api.py

### US-003: Backend API - POST Create
...

### US-004: Backend API - PUT Edit
...

### US-005: Backend API - DELETE
...

### US-006: Frontend - Structure
**Ca** user
**Vreau** o pagină dedicată pentru FEATURE
**Pentru că** vreau acces rapid

**Acceptance Criteria:**
- [ ] FEATURE.html creat în dashboard/
- [ ] Link în index.html navigation
- [ ] Layout responsive (mobile + desktop)
- [ ] Tests în dashboard/tests/test_FEATURE_ui.py

### US-007: Frontend - Create Form
...

### US-008: Frontend - Edit Modal
...

### US-009: Frontend - Delete cu Confirmare
...

### US-010: Frontend - Customizare (frecvență, zile, categorii, etc.)
...

### US-011: Integration Tests
...

## 4. Structură Fișiere

```
~/clawd/dashboard/
├── FEATURE.html              # UI principal
├── FEATURE.json              # Data storage
├── api.py                    # Backend (modificat)
├── tests/                    # Tests separate (NU în root dashboard/)
│   ├── test_FEATURE_api.py
│   ├── test_FEATURE_ui.py
│   └── test_FEATURE_integration.py
└── index.html                # Link adăugat în nav
```

## 5. UX Detalii

[Din răspunsul la întrebarea 5]

**Layout:**
- Cards cu shadow și hover effects (ca în common.css pattern)

**Create/Edit:**
- Modal pentru create (buton fix bottom-right)
- Inline edit sau modal pentru modificare
- Fields: nume, frecvență dropdown, zile săptămână checkboxes, etc.

**Customizare:**
- Frecvență: zilnic / săptămânal / lunar / custom (X zile)
- Zile săptămână: checkboxes pentru weekly habits
- Categorii: work, health, growth, etc.
- Culori: picker pentru identificare vizuală
- Icoane: librarie icons (lucide) pentru personalizare

**Mobile:**
- Swipe pentru delete/edit
- Touch-friendly buttons (min 44px)

## 6. Non-Goals

❌ NU facem:
- Sincronizare cloud / multi-device
- Gamification advanced (badges, levels)
- Social features (share, leaderboard)
- Export/import (poate în viitor)

## 7. Considerații Tehnice

### Backend (api.py)
- Pattern existent: `handle_X_get`, `handle_X_post`, etc.
- Storage în JSON cu `lastUpdated` timestamp
- Validare input (max lengths, format checks)

### Frontend
- common.css pentru styling consistent
- Lucide icons pentru UI
- Fetch API cu error handling
- Toast notifications pentru success/error

### Tests
- **Locație:** `dashboard/tests/` (NU în root dashboard/)
- **Coverage:** API endpoints + UI behaviors + integration
- **Run:** pytest pentru Python, manual pentru UI (sau Playwright dacă disponibil)

## 8. Acceptance Criteria Finale

- [ ] Toate user stories implementate
- [ ] Tests pass (pytest dashboard/tests/)
- [ ] UI responsive (mobile + desktop)
- [ ] No console errors
- [ ] Git commits clean cu mesaje descriptive
- [ ] PR creat pentru review
```

---

### FAZA 3: Configurez Opus pentru Planner

**Înainte de a lansa workflow-ul, configurez Opus pentru planner:**

```bash
# Găsesc job ID pentru planner
cron action=list | grep "antfarm/feature-dev/planner"

# Actualizez cu model Opus
cron action=update jobId="<PLANNER_JOB_ID>" patch='{"payload": {"model": "opus"}}'
```

**Verificare:**
```bash
cron action=list | grep -A 5 "antfarm/feature-dev/planner"
# Ar trebui să văd "model": "opus" în payload
```

---

### FAZA 4: Lansez Workflow cu PRD ca Input

**Task string pentru antfarm include PRD-ul complet:**

```bash
cd ~/clawd

antfarm workflow run feature-dev "$(cat <<'EOF'
FEATURE: Habit Tracker

PRD LOCATION: tasks/prd-habit-tracker.md

CONTEXT:
- Proiect existent: Echo Dashboard (Python backend + HTML/JS frontend)
- Storage: JSON files
- Patterns: common.css, api.py endpoints, swipe-nav.js

REQUIREMENTS (vezi PRD complet în tasks/ pentru detalii):

1. Backend API (api.py):
   - GET /api/habits - returnează toate habits
   - POST /api/habits - creează habit nou cu validare
   - PUT /api/habits/{id} - editează habit existent
   - DELETE /api/habits/{id} - șterge habit
   - Funcții: calculate_streak(completions, frequency)
   - Storage: habits.json

2. Frontend (habits.html):
   - Layout: Cards cu grid responsive
   - Create: Modal cu form (nume, frecvență, zile, categorie, culoare, icon)
   - Edit: Modal sau inline edit
   - Delete: Confirmare dialog
   - Check-in: Click pentru bifaretoday
   - Display: Streak counter, last check date, progress visualization

3. Customizare:
   - Frecvență: zilnic / săptămânal / lunar / custom (X zile)
   - Zile săptămână: checkboxes pentru weekly habits (L, Ma, Mi, J, V, S, D)
   - Categorii: work, health, growth, personal (cu culori)
   - Icoane: lucide icons picker
   - Culori: color picker pentru identificare vizuală

4. Tests:
   - Locație: dashboard/tests/ (NU în dashboard/ root!)
   - Coverage: API, UI, integration
   - Framework: pytest pentru Python

5. Integration:
   - Link în index.html navigation
   - Toast notifications (success/error)
   - Mobile responsive (swipe gestures)

ACCEPTANCE CRITERIA (COMPLETE):
- [ ] Pot crea habit cu toate detaliile (nume, frecvență custom, zile, categorie, culoare, icon)
- [ ] Pot edita habit existent (toate câmpurile)
- [ ] Pot șterge habit cu confirmare
- [ ] Pot bifa habit pentru azi (once per day max)
- [ ] Streak calculation corect (zilnic: consecutive days, săptămânal: consecutive weeks)
- [ ] UI responsive (mobile + desktop)
- [ ] Tests în dashboard/tests/ (NU în dashboard/)
- [ ] No console errors
- [ ] API paths corecte (/echo/api/habits)
- [ ] Git commits clean

STORY SIZING:
- Fiecare story trebuie să fie atomică (1 context window)
- Dependencies-first: schema → backend → frontend → integration
- Include typecheck și tests în fiecare story

NON-GOALS:
- Cloud sync / multi-device
- Advanced gamification
- Social features
- Export/import

Vezi tasks/prd-habit-tracker.md pentru detalii complete UX și tehnice.
EOF
)"
```

---

### FAZA 5: Monitor și Ajustări

**Monitor progres:**
```bash
antfarm workflow status <run-id>
antfarm logs 50
```

**Dacă planner-ul generează stories prea mari:**
- Opresc run-ul
- Editez PRD pentru a clari sizing
- Relanșez cu PRD actualizat

**Dacă developer-ul face greșeli (ex: test files în locul greșit):**
- Verifier-ul ar trebui să prindă asta (acceptance criteria specifică locația)
- Dacă nu, adaug în PRD mai explicit: "Tests MUST be in dashboard/tests/"

---

## Rezumat Flux pentru Echo

**Când primesc "Vreau să construiesc X în dashboard":**

1. ✅ **Discovery:** Pun întrebări adaptive (5-7 întrebări pentru feature în proiect existent)
2. ✅ **PRD:** Generez tasks/prd-X.md cu user stories complete, UX detaliat, acceptance criteria specifice
3. ✅ **Config Opus:** Actualizez planner job cu model="opus"
4. ✅ **Launch:** antfarm workflow run cu PRD complet ca input
5. ✅ **Monitor:** Verific progres, intervin doar dacă escalation

**NU mai fac:**
- ❌ Launch direct cu prompt vag
- ❌ Presupun ce vrea utilizatorul fără întrebări
- ❌ Las planner-ul (Sonnet) să interpreteze minimal
- ❌ Accept test files în locuri greșite

---

## Checklist pentru Mine (Echo)

**Înainte de ORICE antfarm workflow run:**

- [ ] Am pus întrebări despre UX/features? (5-7 întrebări)
- [ ] Am generat PRD complet în tasks/?
- [ ] PRD-ul include acceptance criteria specifice?
- [ ] PRD-ul specifică structură fișiere (ex: tests/ location)?
- [ ] Am configurat Opus pentru planner?
- [ ] Task string include link la PRD + detalii complete?
- [ ] Marius a aprobat PRD-ul înainte de launch?

**Dacă răspuns = NU la oricare → STOP și completez înainte de launch.**

---

**REGULA DE AUR:**

> **80% din timpul unui proiect bun e în discovery și planning.**  
> **Antfarm execută rapid doar dacă știe EXACT ce să construiască.**  
> **Prompt vag = implementare minimalistă.**  
> **PRD complet = feature complet.**