From 5f3e9b5c47ade348ef2e4c8967d71e99225a9092 Mon Sep 17 00:00:00 2001 From: Claude Agent Date: Mon, 31 Aug 2026 17:56:51 +0000 Subject: [PATCH] docs: TODO.md ca registru viu + flux plan-pe-Opus / executie-pe-Sonnet Firele Discord sunt independente: un fir nou nu vede conversatia din alt fir. Fara un loc scris, progresul unei functionalitati se pierde intre runde. TODO.md e acel loc, iar CLAUDE.md il face parte din procedura, nu optional. - TODO.md: intrari grupate pe stare (in lucru / blocate / planificate / gata), fiecare cu unde, ce face, ce s-a verificat si data absoluta, plus un Jurnal append-only. Populat cu starea reala de azi. - docs/flux-dezvoltare.md: pentru orice cerere de dezvoltare -- citeste TODO.md, planifica delegand `Agent(subagent_type: "Plan", model: "opus")`, posteaza planul in fir, executa tu (firul e pe Sonnet), actualizeaza TODO.md. Delegarea catre subagent obtine "plan pe Opus, executie pe Sonnet" fara `/model` si fara repornirea sesiunii, ceea ce un fir nu poate face oricum. Excepii: intrebarile si diagnosticele fara modificare. Marimea sarcinii NU e criteriu -- prima versiune a documentului lasa asta ambiguu si agentul a sarit peste plan la un script de 20 de linii; acum e spus explicit in ambele locuri. - CLAUDE.md: sectiunea "Cum lucrezi" in cap, cei 4 pasi, plus TODO.md si documentul de flux in tabelul de documentatie. - CLAUDE.md: nota despre atasamente actualizata -- imaginile si fisierele text ajung acum la agent (implementat azi in discord-bridge). - README.md: tabel de fisiere; `!cd`/`!status` -> `/cd`/`/status`. Verificat pe o sesiune reala pe Sonnet in acest director, cu aceeasi cerere inainte si dupa intarire: prima data a sarit peste plan, a doua oara a chemat subagentul Plan pe Opus si a actualizat TODO.md in formatul cerut. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01Q4uzvgm7AyJch5WH8QHRhY --- CLAUDE.md | 26 +++++++++++- README.md | 18 ++++++++- TODO.md | 81 +++++++++++++++++++++++++++++++++++++ docs/flux-dezvoltare.md | 90 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 211 insertions(+), 4 deletions(-) create mode 100644 TODO.md create mode 100644 docs/flux-dezvoltare.md diff --git a/CLAUDE.md b/CLAUDE.md index e6a1037..0d9bb53 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,6 +2,25 @@ Vezi `README.md` pentru context general. +## Cum lucrezi (OBLIGATORIU pentru orice cerere de dezvoltare) + +1. **Citește [`TODO.md`](TODO.md)** — registrul viu al funcționalităților. Poate lucrul e + deja început, blocat sau abandonat deliberat. +2. **Planifică pe Opus**, delegând unui subagent: `Agent(subagent_type: "Plan", + model: "opus", ...)`. Firul rulează pe Sonnet; nu schimba modelul firului. + **Pasul ăsta nu se sare pentru că sarcina pare mică.** Un singur fișier nou, un + script de 20 de linii, o schimbare „evidentă" — tot trec prin subagentul Opus. + Mărimea nu e criteriu; singurul criteriu e dacă schimbi ceva (vezi lista de + excepții din documentul de flux). +3. **Postează planul în fir**, apoi **execută tu, pe Sonnet**. +4. **Actualizează [`TODO.md`](TODO.md)** la final — mută intrarea, scrie data absolută, + adaugă o linie în `Jurnal`. Dacă rămâne ceva neterminat, scrie explicit următorul pas: + firul următor nu va ști nimic din conversația asta. + +Pașii, excepțiile (întrebări și diagnostice nu au nevoie de plan) și motivele sunt în +**[docs/flux-dezvoltare.md](docs/flux-dezvoltare.md)** — citește-l înainte de prima +cerere de dezvoltare din fir. + ## Unde ești Rulezi pe **LXC 171 (`claude-agent`, 10.0.20.171, nod pvemini)**, în ecosistemul Romfast: @@ -42,13 +61,16 @@ supraviețuiască între fire se scrie în memorie sau în documentație, nu se Utilizatorul comunică cu acest agent în principal prin **Discord**, prin puntea Discord → Claude Code (vezi și `docs/echo-roa2web.md` pentru diferența față de Echo/MoltBot). Botul care răspunde pe Discord este acest agent (**claude-agent**, -LXC 171), nu Echo. Atașamentele (imagini, fișiere) trimise pe Discord nu sunt încă -citite automat de punte — doar textul mesajului ajunge la Claude. +LXC 171), nu Echo. Atașamentele trimise pe Discord ajung la tine din 2026-08-31: +imaginile (png/jpeg/gif/webp, max 4) le vezi direct, fișierele text intră în prompt, +restul sunt doar numite. Mesajele vocale, nu — vezi `TODO.md`. ## Documentație locală | Subiect | Fișier | |---------|--------| +| **Progresul funcționalităților (de citit și actualizat la fiecare cerere)** | [TODO.md](TODO.md) | +| **Fluxul de lucru: plan pe Opus → execuție pe Sonnet → TODO.md** | [docs/flux-dezvoltare.md](docs/flux-dezvoltare.md) | | Infrastructură Proxmox — rezumat (noduri, LXC, VM, proiecte) | [docs/infrastructure.md](docs/infrastructure.md) | | Echo (LXC 110 moltbot) — acces și comenzi pentru roa2web | [docs/echo-roa2web.md](docs/echo-roa2web.md) | | Punte Discord → Claude Code — context | [docs/discord-bridge-context.md](docs/discord-bridge-context.md) | diff --git a/README.md b/README.md index 66c0ced..10c094c 100644 --- a/README.md +++ b/README.md @@ -7,5 +7,19 @@ Repo propriu, ca lucrurile facute din Discord sa aiba istoric separat de proiect reale si sa se poata da inapoi fara sa atinga altceva. - Codul puntii NU e aici: e in `romfastsql/proxmox/lxc171-claude-agent/discord-bridge/`. -- Pentru a lucra pe alt proiect dintr-un fir: `!cd /workspace/`. -- Fiecare fir Discord isi tine propriul director; `!status` il arata. +- Pentru a lucra pe alt proiect dintr-un fir: `/cd cale:/workspace/`. +- Fiecare fir Discord isi tine propriul director; `/status` il arata. + (Prefixul `!` nu mai executa nimic — comenzile sunt `/`.) + +## Fisiere + +| Fisier | Ce e | +|--------|------| +| `CLAUDE.md` | Regulile agentului: cum lucreaza, unde e documentatia, granita Maria | +| `TODO.md` | Registrul viu al functionalitatilor — agentul il citeste si il actualizeaza | +| `docs/flux-dezvoltare.md` | Plan pe Opus -> executie pe Sonnet -> TODO.md | +| `docs/infrastructure.md` | Rezumat noduri/LXC/VM, cu trimiteri la romfastsql | +| `docs/echo-roa2web.md` | Echo (LXC 110) — acces si comenzi pentru roa2web | +| `docs/discord-bridge-context.md` | Context despre puntea Discord | +| `docs/maria-whatsapp-rag-prototype.md` | Maria — punte WhatsApp + RAG | +| `tools/` | Scripturi reutilizabile pentru sarcini care revin | diff --git a/TODO.md b/TODO.md new file mode 100644 index 0000000..1b4061b --- /dev/null +++ b/TODO.md @@ -0,0 +1,81 @@ +# TODO — progresul funcționalităților + +Registrul viu al lucrului cerut prin puntea Discord. **Botul îl citește la începutul +oricărei cereri de dezvoltare și îl actualizează la final** — vezi +[docs/flux-dezvoltare.md](docs/flux-dezvoltare.md). + +Stări: `🔵 planificat` · `🟡 în lucru` · `⛔ blocat` · `✅ gata` · `❌ abandonat` + +--- + +## 🟡 În lucru + +*(nimic în acest moment)* + +--- + +## ⛔ Blocate + +### Maria — sincronizare cu Google Drive +- **Unde:** `romfastsql/proxmox/lxc171-claude-agent/maria-whatsapp-bridge/rag/sync.py` +- **Blocat pe:** un cont de serviciu Google pe care trebuie să-l creeze utilizatorul + (containerul e headless, OAuth interactiv nu merge). `rclone` e deja instalat. +- **Până atunci:** `DRIVE_REMOTE` gol = sincronizare oprită, documentele se pun manual + din dashboard. Indexarea end-to-end a fost testată cu 6 documente reale. +- **Actualizat:** 2026-08-31 + +--- + +## 🔵 Planificate + +### Mesaje vocale din Discord +- **Unde:** `romfastsql/proxmox/lxc171-claude-agent/discord-bridge/bot.py` +- **Ce ar însemna:** atașamentele audio (`audio/ogg`, mesajele vocale Discord) transcrise + local înainte de a intra în prompt. Whisper rulează pe CPU pe LXC 171, deci trebuie + măsurat întâi costul în timp per mesaj. +- **De ce nu acum:** nu a fost cerut; e singura limitare rămasă după atașamente. +- **Actualizat:** 2026-08-31 + +--- + +## ✅ Gata + +### Atașamente Discord → Claude (imagini + fișiere text) +- **Unde:** `romfastsql/proxmox/lxc171-claude-agent/discord-bridge/bot.py` + (`build_user_content`), `runner.py` (`user_message`), `tests/test_attachments.py` +- **Ce face:** imaginile png/jpeg/gif/webp ajung ca blocuri `image` (max 4, max 3,5 MB), + fișierele text intră în prompt (max 4, trunchiate la 100 KB), restul sunt doar numite. + Merge și mid-tur, ca steering. Un mesaj doar cu poză nu mai e respins ca gol. +- **Verificat:** 31 de teste noi, suita 426 pass; blocurile de imagine testate pe CLI-ul + real (`--input-format stream-json`), Claude descrie corect imaginea. +- **Terminat:** 2026-08-31 + +### Plan cu Opus, execuție cu Sonnet +- **Unde:** [docs/flux-dezvoltare.md](docs/flux-dezvoltare.md), referit din `CLAUDE.md` +- **Ce face:** orice cerere de dezvoltare trece întâi printr-un subagent `Plan` pe Opus; + planul se postează în fir, apoi execuția merge pe Sonnet, în sesiunea firului. +- **Terminat:** 2026-08-31 + +### Memorie comună claude-agent ↔ romfastsql +- **Ce face:** `~/.claude/projects/-workspace-claude-agent/memory` e symlink către memoria + proiectului `romfastsql`, deci firele Discord nu mai pornesc fără context. +- **Terminat:** 2026-08-31 + +### Repo propriu pentru claude-agent + reparare Gitea +- **Ce face:** `/workspace/claude-agent` e repo separat + (`git@gitea.romfast.ro:romfast/claude-agent.git`), scos din `romfast/workspace`. + Gitlink-urile fără `.gitmodules` care dădeau 500 pe pagina repo-ului `workspace` au + fost scoase din index. +- **Terminat:** 2026-08-31 + +--- + +## Jurnal + +Cea mai recentă intrare prima. O linie per schimbare de stare. + +- 2026-08-31 — ✅ Atașamente Discord → Claude (imagini + fișiere text) +- 2026-08-31 — ✅ Plan cu Opus, execuție cu Sonnet +- 2026-08-31 — ✅ Memorie comună claude-agent ↔ romfastsql +- 2026-08-31 — ✅ Repo propriu pentru claude-agent + reparare Gitea +- 2026-08-31 — ⛔ Maria — sincronizare Drive, blocată pe cont de serviciu Google diff --git a/docs/flux-dezvoltare.md b/docs/flux-dezvoltare.md new file mode 100644 index 0000000..409c96a --- /dev/null +++ b/docs/flux-dezvoltare.md @@ -0,0 +1,90 @@ +# Fluxul de lucru pentru cereri de dezvoltare + +Regula, pe scurt: **planifici cu Opus, execuți cu Sonnet, actualizezi +[`TODO.md`](../TODO.md).** Se aplică oricărei cereri de dezvoltare venite prin puntea +Discord, indiferent de proiectul atins. + +## Ce e „cerere de dezvoltare" + +Orice ți se cere să **schimbi**: funcționalitate nouă, refactorizare, reparare de bug, +schimbare de configurație sau de infrastructură, script nou, migrare. + +**Nu** intră aici, și nu au nevoie de plan: întrebări („cum merge X?", „ce e în fișierul +Y?"), diagnostice fără modificare, citit loguri, verificat starea unui serviciu, +o corectură de o linie pe care utilizatorul a formulat-o deja exact. + +**Mărimea sarcinii nu e un criteriu.** „E doar un script", „e o singură funcție", „știu +deja exact ce am de făcut" — nu sunt motive să sari peste plan. Criteriul e unul singur: +*schimbi ceva?* Dacă da, planul se face. Dacă ești în dubiu, planifică. Un plan în plus +costă câteva secunde; o execuție greșită pe infrastructura de producție costă mult mai +mult. + +Singurul caz în care poți sări peste plan la o schimbare este când utilizatorul spune +explicit să nu planifici („fă direct", „fără plan"). + +## Pasul 1 — Planifică, pe Opus + +Firele Discord rulează pe **Sonnet** (`MODEL_DEFAULT`). Nu schimba modelul firului ca să +planifici — nu poți, și oricum ar reporni procesul. În loc de asta, **delegă planificarea +unui subagent pe Opus**, din sesiunea curentă: + +``` +Agent( + subagent_type: "Plan", + model: "opus", + description: "Planifică ", + prompt: "" +) +``` + +Așa obții exact ce a cerut utilizatorul — gândirea pe Opus, execuția pe Sonnet — fără +niciun `/model` și fără repornirea sesiunii. + +Înainte de a chema subagentul, **citește [`TODO.md`](../TODO.md)**: poate lucrul e deja +început, blocat, sau abandonat deliberat, iar planul trebuie să pornească de acolo. +Dă-i subagentului contextul pe care îl ai deja — el pornește fără istoricul firului. + +## Pasul 2 — Postează planul în fir + +Rezumă planul în fir **înainte** de a atinge ceva: pașii, fișierele, ce verifici la final. +Scurt — pașii, nu eseul. + +Apoi execută. Nu aștepta aprobare pentru pași obișnuiți; utilizatorul poate interveni +oricând, un mesaj trimis în timpul turului ajunge la tine ca steering. Cere confirmare +explicită doar pentru ce e ireversibil sau are efect în afară: ștergere de date, restart +de servicii cu clienți live, `pct/qm/zfs destroy`, orice ajunge la un client. + +## Pasul 3 — Execută, pe Sonnet + +Execuția o faci tu, în sesiunea firului, care e deja pe Sonnet. Nu delega execuția înapoi +unui subagent Opus — ăsta e exact lucrul pe care regula vrea să-l evite. + +Termină toată cerința, nu doar partea ușoară. Rulează testele proiectului dacă există +(`python3 -m pytest -q` pentru puntea Discord) și spune rezultatul real, inclusiv când +pică. + +## Pasul 4 — Actualizează `TODO.md` + +La finalul oricărei cereri de dezvoltare, actualizează [`TODO.md`](../TODO.md): + +1. **Mută intrarea** în secțiunea potrivită (`🟡 În lucru` → `✅ Gata`, sau `⛔ Blocate` + dacă te-ai oprit în ceva ce depinde de altcineva). +2. **Completează câmpurile:** `Unde` (căi de fișiere), ce face, ce ai verificat, + `Actualizat`/`Terminat` cu data absolută (nu „azi", nu „ieri"). +3. **Adaugă o linie în `Jurnal`**, prima, în formatul `AAAA-LL-ZZ — `. +4. Dacă lucrul e nou și nu era în listă, **creează intrarea** — inclusiv când îl termini + într-un singur tur; registrul e util doar dacă e complet. +5. Dacă rămâne ceva neterminat, lasă intrarea în `🟡 În lucru` cu **următorul pas scris + explicit** — firul următor pornește fără conversația asta și ăla e tot ce va ști. + +`TODO.md` e în repo-ul `claude-agent`; comite-l odată cu restul lucrului. + +## De ce așa + +- **Opus planifică mai bine, Sonnet execută mai ieftin.** Un plan prost costă mai mult + decât diferența de model. +- **Sesiunile Discord sunt per fir.** Un fir nou nu vede conversația din alt fir, deci + ce nu e scris în `TODO.md`, în memorie sau în documentație e pierdut. +- **Planul postat în fir e singurul moment ieftin de intervenție.** După ce ai scris în + `/workspace/romfastsql` sau ai atins un container, corectura e mai scumpă.