DEV-PLAYBOOK — Instrucțiune globală de dezvoltare GStack

Acest conținut nu este încă disponibil în limba selectată.

Sursa unică de adevăr pentru dezvoltarea (Bloc C) a TUTUROR aplicațiilor din grupul govtech/gstack. Acest playbook e comun tuturor subproiectelor. O aplicație nouă nu-și inventează propriul proces — reutilizează pașii de aici. Constituția (CLAUDE.md) obligă orchestratorul să respecte acest fișier pentru orice task de cod.

GitLab: https://git.esempla.systems/govtech/gstack (grup). Fiecare aplicație = un proiect în grup: govtech/gstack/<app> (ex. govtech/gstack/glog, govtech/gstack/gsso, govtech/gstack/gstorage).

0. Principii nenegociabile (se aplică la fiecare aplicație)

JDL = sursa de adevăr a modelului. Backend-ul se generează cu JHipster din <app>.jdl. Nu se scrie manual cod de entitate/repository/DTO care poate fi regenerat.
Spec-first pentru orice schimbare. Un change request se aplică ÎNTÂI în specificație (Spec - <app>, <app>.jdl, ADR) și DOAR APOI în cod. Vezi §5 și skill spec-first-change.
Fiecare decizie de arhitectură = ADR, generat, verificat și aprobat înainte de cod. Vezi §4.
„Done” = testat, dovedit. Nimic nu e done fără: teste verzi rulate real (unit + integrare pe docker-compose ridicat de agent), lint curat, build OK, review APPROVE, MR legat de issue, scenarii de test documentate. Cuvintele „should / probably / ar trebui” sunt interzise ca dovadă.
Reluabil. Starea se documentează după fiecare task (checkpoint + task-ledger + GitLab issue), ca munca să poată reporni după orice restart. Vezi §7.
Comun, nu per-om. Aceleași skill-uri, aceleași agenți, aceeași DoD pentru toate aplicațiile.

1. Precondiții per aplicație (ce trebuie să existe înainte de cod)

Artefact	Unde	Rol
Caiet de sarcini	`Spec - <app>.docx` / `.pdf` + `vault/`	businessul: procese, roluri, forme, criterii de acceptanță
Design	`<app>.dc.html` (+ `screenshots/`)	UI-ul dorit pe care îl aplicăm pe frontend
JDL	`03-development/<app>/<app>.jdl`	modelul de date + relații → intrarea JHipster
ADR-uri	`vault/` (din `templates/adr.md`)	deciziile de arhitectură aprobate
Issue GitLab	`govtech/gstack/<app>`	urmărirea livrabilului

Dacă lipsește JDL sau caietul de sarcini → NU începe codul; creează un item în .workplace/questions/inbox.md (batch) și, dacă e cazul, întoarce-te pe fluxul Bloc B (spec).

2. Stack standard (aliniat cu exemplul `glog` / eIntegritate)

JHipster 9.1.0, applicationType: microservice, authenticationType: oauth2 (Keycloak).
Maven, Java Spring Boot, packageName: systems.esempla.<app>.
PostgreSQL (dev+prod), Kafka message broker, limbi ro,ru,en (nativă ro).
skipClient: true — frontend separat (Angular), stilizat după <app>.dc.html.
API conform Standardului API GovStack (CU-API-003..006): api/v{N} + zone public/citizen/staff/admin/app, operaționale /health/live, /health/ready, /metrics, /info, /api/v1/openapi.json, erori RFC 7807. Auditat de api-governor (/api-audit) în CI.

3. Bucla globală per aplicație (rezumat)

/dev-app <app>
  1. PREGĂTIRE  → verifică precondiții (§1), citește caiet+design+JDL, deschide/creează issue-uri
  2. ADR        → generează/actualizează ADR-urile necesare; reviewer verifică; aprobare teamlead (gate)
  3. GENERARE   → JHipster din <app>.jdl  (skill jhipster-app-loop)
  4. FRONTEND   → aplică design-ul <app>.dc.html pe Angular (GLM)
  5. TDD        → run-until-green: RED→GREEN→REFACTOR, unit + integrare (docker-compose up→test→down)
  6. REVIEW     → reviewer gate (spec+cod+API standard). CRITICAL → înapoi la 5.
  7. DOCUMENT   → checkpoint + task-ledger + GitLab issue comentat + wiki actualizat
  8. LIVRARE    → MR `Closes #issue` pe branch, NICIODATĂ push în main
  repetă pe următorul task/feature până când toată aplicația e verde & testată

Detalii mecanice: skill jhipster-app-loop. Bucla de cod: skill run-until-green. Rulare continuă, fără check-in între taskuri — vezi §8.

4. ADR — planificarea dezvoltării (obligatoriu înainte de cod)

Dezvoltarea se planifică pe bază de ADR. Regula:

Orice decizie cu impact (alegere de tehnologie, model de date semnificativ, integrare cu blocuri MPass/MPay/MConnect, strategie de securitate, breaking change de API) → ADR din vault/templates/adr.md, numerotat ADR-NNN.
ADR-ul e generat (draft de orchestrator/govstack-architect), verificat de reviewer (context complet? alternative reale? consecințe? aliniat la cerinte-universale.md și Standard API?), apoi aprobat de teamlead (poartă de aprobare — batch).
Doar ADR cu status Acceptat deblochează codul aferent. Un ADR Propus nu se implementează.
ADR-ul se leagă de issue-ul GitLab și se publică pe wiki (§6).

Change request pe o decizie deja acceptată → ADR nou care înlocuiește (status Înlocuit pe cel vechi), apoi fluxul spec-first (§5).

5. Change requests — SPEC-FIRST (întâi specificația, apoi codul)

Orice cerere de modificare (cerință nouă, câmp nou, regulă schimbată, endpoint nou) urmează ordinea:

1. SPEC   → actualizează caietul de sarcini `Spec - <app>` (+ nota din vault/) — ce & de ce
2. MODEL  → actualizează <app>.jdl dacă se schimbă modelul de date/relații
3. ADR    → dacă e decizie de arhitectură: ADR nou/înlocuitor, verificat + aprobat
4. TEST   → actualizează scenariile de test (§9) ÎNAINTE de cod (TDD: testul pică întâi)
5. COD    → abia acum: regenerează JHipster (merge peste custom code) + implementează diferența
6. TRACE  → issue GitLab „CR: <titlu>" (label change-request) + wiki + checkpoint

Regulă dură: niciun commit de cod pentru un CR fără ca pașii 1–4 să fie deja făcuți și comise. Skill: spec-first-change. Reviewer respinge (CRITICAL) orice cod care divergă de spec/JDL/ADR.

6. GitLab — issues + wiki (trasabilitate completă)

Grup: govtech/gstack. Proiect per aplicație: govtech/gstack/<app>.

Issues (skill gitlab-issues, agent gitlab-sync):

Un issue per livrabil/feature/CR. Labels: block:C, type:dev|adr|change-request|review-followup, app:<app>. Titlu = numele livrabilului; descriere = scop + link fișier repo + link notă vault/.
Branch feat/<task-id> → MR cu Closes #<issue>. Follow-up din review → label review-followup.
Idempotent: verifică list-open după titlu înainte de a crea (la resume după restart).

Wiki (documentarea deciziilor & stării — pagini durabile, nu efemere):

Home → index aplicații + starea curentă (link către task-ledger).
<app>/Arhitectura → ADR-urile acceptate ale aplicației (copie sincronizată din vault/).
<app>/Scenarii-de-test → scenariile de test documentate (§9).
<app>/Stare → unde ne aflăm (bloc/task curent, ce urmează) — actualizat la checkpoint.
Proces/DEV-PLAYBOOK → acest playbook (sursa comună). Sincronizarea o face gitlab-sync prin API-ul de wiki; conținutul „viu” rămâne în vault/, wiki e oglinda publicabilă pentru echipă.

7. Documentarea taskurilor & reluare (checkpoint / resume)

Mecanismul e skill-ul checkpoint-and-resume. Pentru dezvoltare, la fiecare task:

task-ledger.md — o linie: [DONE|WIP|TODO] <task-id> <descriere> | reviewer:… | mr:!.. | ckpt:…
.workplace/checkpoints/<task>.md — rezumat, fișiere atinse, comenzile de verificare rulate + rezultatul lor (inclusiv rularea docker-compose), NEXT STEP.
state.json — current_block=C, current_task, last_checkpoint.
Commit local pe branch (nu main) + comentariu pe issue-ul GitLab + wiki <app>/Stare.

La pornire (/resume): citește state.json + task-ledger.md + checkpoint-ul WIP + inbox.md, anunță în 3 rânduri unde suntem, apoi continuă de la NEXT STEP. Nu reface ce e DONE. Dacă un task era WIP fără checkpoint coerent → re-rulează testele înainte de a-l declara done.

8. Rulare cu Claude Code CLI (bucla autonomă „până la verde”)

Bucla lungă, autonomă, se rulează în Claude Code CLI (headless). Claude Desktop rămâne pentru orchestrare/planificare/review interactiv, dar execuția dev continuă e în CLI.

Împărțirea rolurilor (model routing — config/models.json):

Claude — orchestrator + reviewer + ADR (decizii, gate-uri).
Kimi — implementer / qa-runner: rulări lungi autonome (bucla run-until-green ore întregi).
GLM — frontend Angular + volum de conținut.

Pornire (în directorul scaffold-ului):

# o singură aplicație, autonom până la verde:
claude
> /dev-app glog

# sau tot Blocul C:
> /run-block C

Reguli de rulare continuă (din CLAUDE.md §1 + skill run-until-green):

Nu se oprește pentru check-in între taskuri. Întrebările se acumulează în inbox.md (batch de 5).
Presupuneri rezonabile marcate ASSUMPTION: în loc de blocaj.
Se oprește doar la: ≥5 întrebări, blocaj total pe drumul critic, sau decizie ireversibilă (push în main, ștergere date, cost real, schimbare de arhitectură neaprobată).
Plafon MAX_GREEN_ITERATIONS (config .env, default 25) → dacă nu ajunge verde, scrie raport de blocaj OPEN! în inbox și trece la următorul task independent.

Cadența teamlead-ului (Desktop sau CLI): /status pentru poziție, citește batch-ul de întrebări, aprobă ADR-uri/planuri, dă direcție. Între intervenții sistemul avansează singur.

9. Testare — „done = testat” cu docker-compose ridicat de agent

Agentul își ridică singur mediul, testează, apoi îl oprește. Nimic nu rămâne pornit.

Niveluri de test (toate rulate real înainte de done):

Unit — logica de business/domeniu. mvn -B test (back) / npm test (front).
Integrare — repository/endpoint pe PostgreSQL + Kafka reale din docker-compose (Testcontainers unde e disponibil; altfel compose explicit).
API-conformitate — api_audit.py (Standard API, RFC 7807, endpoint-uri operaționale).
E2E frontend (când există) — Playwright pe frontend + backend pornit.

Ciclul de mediu (obligatoriu, îl face agentul — vezi skill run-until-green §docker-compose):

docker compose -f 03-development/<app>/docker-compose.test.yml up -d --wait   # ridică postgres+kafka(+keycloak)
mvn -B verify                                                                  # unit + integrare
python 03-development/ci-templates/api_audit.py --base http://localhost:<port> # API standard
docker compose -f 03-development/<app>/docker-compose.test.yml down -v         # oprește ȘI curăță (mereu, chiar și la eșec)

down -v rulează în trap/finally — mediul se oprește chiar dacă testele pică.

Scenariile de test se documentează (nu doar codul lor):

Fișier 03-development/<app>/test-scenarios.md — per scenariu: ID (TS-<app>-NN), precondiții, pași, rezultat așteptat, mapare la cerință (CU-* / criteriu din caiet) și la testul automat.
Reutilizează biblioteca comună 02-specifications/_comune/biblioteca-cazuri-test-comune.md (TC-COM-*).
Se oglindește pe wiki <app>/Scenarii-de-test. Un feature nu e done dacă scenariul lui nu e documentat.

10. Definition of Done — aplicație / feature (checklist dur)

Un feature/CR e done doar dacă TOATE sunt bifate:

Vezi și CLAUDE.md §3–§4 și docs/WORKFLOW.md (Bloc C).