comun/docs/orchestrare-subagenti.md

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.

REGULA ZERO: predarea contextului e OBLIGATORIE, nu optionala

Se aplica identic sesiunii principale si oricarui subagent. Nu e o recomandare de eficienta, e o conditie de corectitudine: un context supraincarcat pierde tacut decizii deja luate si reia investigatii deja platite.

Declansatoare — la oricare dintre ele, predarea porneste imediat:

1. contextul propriu a trecut de ~50% din fereastra (orchestrator) sau de ~200-250k tokens (subagent);
2. harness-ul anunta compactare automata (PreCompact) — prea tarziu ca sa mai amani, dar nu prea tarziu ca sa scrii fisierul; scrie handoff-ul inainte sa raspunzi orice altceva;
3. utilizatorul semnaleaza ca s-a atins limita;
4. s-a terminat un bloc de lucru — indiferent cat context a mai ramas.

Procedura, in ordine, fara exceptii:

1. Opreste lucrul. Nu incepe o sarcina noua, nu porni o rulare noua. Daca esti in mijlocul unei editari, du-o pana la o stare consistenta pe disc (text si binare sincronizate) si atat.
2. Scrie handoff-ul pe disc (docs\handoff_<subiect>.md). Nu in mesaj, nu in raport — pe disc. Un mesaj catre orchestrator se pierde; fisierul nu.
3. Confirma in doua randuri ce ai lasat in urma si daca ceva e intr-o stare periculoasa (fisier editat fara write-back, tranzactie deschisa, proces ramas viu, date de test consumate).
4. Opreste-te. Blocul urmator il ia un agent proaspat. "Mai am putin" nu e motiv de amanare — exact acolo se pierd lucrurile.

Obligatia e a fiecaruia, nu doar a orchestratorului. Un subagent care simte ca se apropie de prag anunta singur si cere predarea; nu asteapta sa fie oprit. Un orchestrator care se apropie de prag isi scrie propriul handoff si preda orchestrarea unei sesiuni noi — regula nu are portita pentru "eu doar coordonez".

Ce intra obligatoriu in handoff: inventarul livrabilelor cu fisier:linie; ce e terminat si ce nu; daca write-back-ul e facut pentru fiecare fisier atins; comanda exacta de rulare a testelor si unde scriu logurile; ce s-a stabilit deja (ca sa nu se reia); ce e interzis; starea datelor de test consumate; capcanele de mediu platite. Fara analize noi — doar stare.

Doua lectii platite scump, amandoua din aceeasi cauza — un agent tinut peste prag (s5-nivel2 533k, s2d-modifica-gestiuni 434k). Predarea e aproape gratuita: raportul e oricum deja scris.

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. Vezi Regula zero de la inceputul fisierului: obligatia e aceeasi ca pentru subagenti, fara portita pentru "eu doar coordonez".

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.