# Orchestrare cu subagenti: context mic, misiuni descompuse

Regula (valabila in toate proiectele ROA/VFP): un singur subagent care duce o misiune lunga
(iteratii de teste, investigatii, mai multe sarcini inlantuite) acumuleaza context urias —
calitate degradata, cost mare. Nu se lucreaza asa.

## Cum se lucreaza

- Sesiunea principala (sau un agent primar) e ORCHESTRATOR: imparte planul pe sarcini
  independente (un test, un audit, un scenariu = o sarcina), monitorizeaza, transmite
  constatarile intre agenti, verifica rezultatele.
- Fiecare sarcina merge la un SUBAGENT PROASPAT cu prompt autosuficient: context complet
  in prompt + trimitere la un fisier de handoff, nu context acumulat in conversatie.
- HANDOFF compact pe disc (docs\handoff_*.md, stil telegrafic): inventar livrabile,
  stare, ce ramane, detaliile ne-evidente pe care un agent proaspat nu le-ar putea
  reconstitui usor. Se actualizeaza la fiecare predare de stafeta.
- PRAG: maxim ~200-250k tokens per subagent. Orchestratorul urmareste dimensiunea
  contextului; la atingerea pragului: cere handoff, inchide agentul, respawneaza unul
  proaspat pe sarcina urmatoare.
- Sarcinile independente ruleaza in PARALEL (lane-uri), ex. audit read-only + editare teste.
- Orchestratorul da utilizatorului UPDATE-URI SCURTE de progres, regulat (monitor pe
  artefacte: loguri/fisiere/screenshots; o propozitie-doua la fiecare schimbare relevanta,
  fara naratiune la evenimente fara continut).
- Orchestratorul MONITORIZEAZA ACTIV subagentii sa nu se blocheze: monitor persistent pe
  artefactele lor + verificare la lipsa de progres (~10 min fara schimbare = suspect):
  procese agatate (vfp9 zombi, dialoguri modale), semafoare orfane, timeout-uri de tool
  (120s implicit) care omoara procese. La blocaj: diagnostic direct (procese, fisiere,
  loguri), mesaj de deblocare cu constatarea concreta, si abia apoi restart daca e cazul.
- Modele: subagentii care DOAR ruleaza/editeaza teste si alte sarcini de volum/rutina ->
  Sonnet; ORCHESTRATORUL subagentilor (cel care imparte, monitorizeaza, deblocheaza,
  decide) -> Opus (sau sesiunea principala). Commit doar dupa review-ul diff-ului de
  catre om (vezi reguli_lucru.md).

## Semne ca ai gresit impartirea

- Acelasi agent primeste "inca o sarcina" a treia oara -> trebuia agent nou + handoff.
- Agentul re-descopera capcane deja documentate -> handoff-ul/docs-ul e incomplet;
  completeaza-l, nu repeta investigatia.
- Orchestratorul face el insusi munca de volum -> deleaga si pastreaza-si contextul
  pentru decizii, verificari si deblocari.

## Disciplina de context a ORCHESTRATORULUI

Pragul de ~200-250k e pentru subagenti, dar orchestratorul se umple la fel de repede daca isi
lasa in sesiune munca de CITIT (masurat: o runda de implementare + 4 rulari de teste a dus
sesiunea principala la ~570k desi tot codul fusese scris de subagenti). Principalii consumatori:
citirea rezultatelor de test dupa fiecare rulare (cu tot cu liniile "OK"), citirea codului pentru
diagnostic, fixuri aplicate direct in loc de delegate.

- **Nu citi log-uri brute.** Scripturile de raportare afiseaza DOAR esecurile plus un total
  ("22 OK, 3 FAIL: <nume + linia de esec>"). Tabelul complet se citeste o singura data, la
  baseline - nu dupa fiecare rulare. Pentru suitele VFP exista deja:
  `COMUN\utile\Teste\raport_teste.ps1 -Dir <folder> [-Tot] [-Baseline <fisier>]` - fara `-Tot`
  afiseaza doar esecurile, iar cu `-Baseline` le marcheaza `[preexistent]` vs `[NOU - REGRESIE]`.
- **Nu citi cod ca sa diagnostichezi.** Deleaga cu "adu-mi dovada, nu fisierul": agentul intoarce
  cauza + linia + citatul minim. Verifici afirmatia, nu o redescoperi.
- **Verifica prin assert, nu prin citire.** Daca vrei sa stii ca ceva e adevarat, cere o comanda
  care intoarce da/nu, nu continutul din care ai deduce singur.
- **Nu aplica fixuri direct** decat sub ~5 linii si doar daca ai deja contextul in sesiune.
- **Prag si pe orchestrator**: la ~50% din fereastra, scrie handoff-ul si reia orchestrarea
  dintr-o sesiune noua. Handoff-ul e deja pe disc - exact pentru asta exista.

## Model de lucru: backlog de story-uri mici, context mic per story

Impartirea pe "lane-uri" mari (o clasa, un modul) produce subagenti cu context mare si serializare
pe fisier. Alternativa mai ieftina si mai robusta: **backlog de story-uri mici, fiecare rezolvabila
cu context mic, rulate in bucla de agenti PROASPETI.**

Doua fisiere pe disc tin toata starea:

- `docs/handoff_<subiect>.md` - **contextul stabil**: reguli de editare, cai, ancore verificate,
  capcane confirmate, decizii luate. Il citeste fiecare agent; se actualizeaza rar.
- `docs/backlog_<subiect>.md` - **starea vie**: story-uri cu ID, criteriu de acceptare
  VERIFICABIL, fisiere atinse, stare (`todo` / `in lucru` / `gata` / `blocat de #N`).

Bucla:
1. orchestratorul ia primul story `todo` neblocat;
2. spawneaza un agent proaspat cu prompt = trimitere la handoff + textul story-ului + criteriul
   de acceptare. **Nimic altceva** - fara istoric, fara rapoartele celorlalti agenti;
3. agentul modifica, ruleaza verificarea din criteriu si raporteaza **verdict + ce a schimbat +
   ce a descoperit neasteptat**, atat;
4. orchestratorul marcheaza story-ul in backlog si trece la urmatorul.

O story buna: are criteriu de acceptare care se poate RULA (un test, un grep, o comanda da/nu);
atinge un singur fisier sau o singura zona (altfel story-urile se serializeaza intre ele); incape
in 15-20 de linii de descriere; nu cere citirea intregului fisier ca sa fie inteleasa.

Sablon:

    ### S7 - garda pe randul protejat in recalcule
    Fisiere:   COMUN\clase\<x>.vc2 (do_executa, recalc_tva_document)
    Blocat de: S4
    De facut:  <2-4 propozitii>
    Acceptare: test_<y>.ps1 trece 12/12 SI `rand_protejat()` nu mai apare in nicio clauza Where
    Stare:     todo

Cand un story pica de doua ori la rand, nu-l reincerca a treia oara cu acelasi prompt: semnul e ca
descrierea sau criteriul e gresit, nu executia. Rescrie story-ul (mai mic, sau cu criteriul
corectat) inainte de a mai cheltui un agent.
