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

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

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

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:

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:

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.