@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title Evolucija sesija — od sesije 1 do 150+
legend top
    |= Couleur |= Projet |
    | <#4CAF50> | cheroliv.com |
    | <#2196F3> | plantuml-plugin |
    | <#FF9800> | bakery-plugin |
    | <#9C27B0> | magic-stick |
endlegend

concise "Активне Сесије" as S

@S
0 is ".md bruta"
1 is "Миграција\nAsciiDoc"
10 is "Eager/Lazy
formalizovan"
62 is "Правило сигурност\n(site.yml)"
87 is "krakiranje
kontekst"
109 is "Оптимизација
-60% токени"
133 is "133 сесија
240 тестова прошли"

S@0 -> S@1 : Session 1\n(cheroliv.com)
S@1 -> S@10
S@10 -> S@62 : Session 62\n(plantuml-plugin)
S@62 -> S@87 : Session 87\n(Cry 4 help)
S@87 -> S@109 : Session 109\n(API Key Pool)
S@109 -> S@133 : Session 133\n(Aujourd'hui)

@enduml

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "Корен пројекта (Eager - аутоматски учитаван)" {
    component "<b>AGENT.adoc</b>
Апсолутна правила
Структура и конвенције" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>\nМиссија сесије N\nСажетак N-1" as PROMPT
    component "<b>INDEX.adoc</b>
тачка улаза
Правила + Сесије" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nPoslovni kontekst\nkritičan" as ESS
}

package ".agents/ (Lazy - Učitan na zahtev)" {
    component "<b>sessions/N-*.adoc</b>
Detaljni arhivi
Odluke & Output" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nТабела сажетака\nДатум/Тип/Поен" as HIST
    component "<b>PROCEDURES.adoc</b>
Шаблони за крај сесије
6 корака" as PROC
    component "<b>*_REFERENCE.adoc</b>\nПуна архитектура\nТехничке референце" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nZavršeni zadaci\nPo mesecima" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>
Документација стратегије
Методологија" as MOD
    component "<b>*_REFERENCE.adoc</b>
Boot testovi, particija A/B
Specifični konteksti" as SPEC
}

AGENT --> PROMPT : "Reference"
AGENT --> INDEX : "Reference"
INDEX --> SESS : "indeksira"
INDEX --> HIST : "indeksira"
INDEX --> PROC : "Референца"
INDEX --> ARCH : "Референца"
INDEX --> REF : "Референца"
PROMPT --> SESS : "Arhiva N-1"
PROMPT --> ESS : "Poslovni kontekst N"

@enduml

----
----
| magic-stick    | Session 23 | SCRIPT_VERIFICATION.adoc | 2026-04-27 |
| bakery-gradle  | Session 11 | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| cheroliv.com   | Session 9  | TEST_COVERAGE_ANALYSIS   | 2026-04-27 |
| plantuml-gradle| Session 133| TEST_COVERAGE_ANALYSIS   | 2026-04-23 |
| jhipster-gradle-plugins | Session 1 | TEST_COVERAGE_ANALYSIS | 2026-04-28 |
----

**`*_ESSENTIALS.adoc`** -- Novi dodatak (Sessija 109, plantuml-plugin) za dodatnu optimizaciju Eager konteksta. Umesto da učitam 200 linija poslovnog konteksta na pulu ključeva API, učitam 50 linija osnovnog sadržaja, a ostalih 150 linija ostaje LAZY u`*_REFERENCE.adoc`.

Izmeren rezultat : prelazak od**~25k tokeni EAGER do ~10k tokeni**(poboljšanje od 60%). Agentu više nisu potrebni energetski zahtevni podsetnici.

==== Nedostajuća veza : `opencode.json

Moram vam priznati nešto što sam skoro zaboravio da dokumentiram. Iznad svih ovih .adoc fajlova, postoji mali JSON fajl bez kojega ništa ne radi. Zove se`opencode.json`i on pravi šest linija. Doslovno šest linija.

[source,json]
----
{
  "$schema": "https://opencode.ai/config.json",
  "instructions": [
    "AGENT.adoc"
  ]
}
----

Ovaj fajl kaže Opencodu : « Pri pokretanju, učitaj`AGENT.adoc`automatski. » Bez njega, agent je prazna stranica tako sam ga opisivao na početku članka. Sa njim, agent već ima u rukama apsolutna pravila, arhitekturu projekta, i osnovne komande — pre nego što sam izreo zdravo.

Slučajno sam otkrio važnost ovog fajla. Na`bakery-plugin`, ne postojalo. Srdžalo mi se zašto je agent sistematički više « gubljen » na ovom projektu nego na drugima. Apsolutna pravila bila su dobro u`AGENT.adoc`— ali`AGENT.adoc`Није био укључен. Агент је читао само што сам му рекао да чита, ручно, на svakoj сессии. Била је сесија 11 де`bakery-plugin`када сам уочио отсутство`opencode.json`. Ja sam ga stvorio — i sesija 12 je pošla kao ostale.

Ovaj fajl je baš očigodan za mene sada da nisam više mislio na nj. Klasična greška razvojača koji previše poznaje svoj alat. Danas ga kreiram sistematski *unapred*.`AGENT.adoc`. Ово је прва стена.

==== Dualnost `INDEX.adoc

Još jedna тонкост која заслујује да буде изглашена:`INDEX.adoc`živi u`.agents/`— fajl koji sam predstavio kao LAZY. Umeđeno, ga listam kao EAGER u svim mojim tabelama. Ovo je vidljiva napetost ovde.

Stvarnost na terenu : fajlovi`.agents/INDEX.adoc`su automatski dobro učitani na početku sesije, jednako kao`AGENT.adoc` et `PROMPT_REPRISE.adoc`. Oni su u`.agents/`za organizacione razloge — ne uđi u koren — ali njihovo ponašanje je EAGER.

na`plantuml-plugin`, `INDEX.adoc`ima 200 linija i sadrži apsolutna pravila *kompletna* sa njihovom istorijom (lekcije iz prošlih sesija), EPIC-ovi sa skorovima i portfelj projekata. To je dokument koji agent konsultuje da zna « gde smo ». Na`bakery-plugin`, on je 150 linija sa roadmapom i recentnim sesijama.

Dobrovoljna redundantnost između`AGENT.adoc` et `INDEX.adoc`Може да збуњи. Апсолутна правила присутна су у обоји. Зашто ? Пошто испиђују две различите улоге: у`AGENT.adoc`, one su *objasnjujuće* (pričanje o pravilu, naučena lekcija) ; u`INDEX.adoc`, one su *izvršne* (prazno pravilo, bez giustifikacije, za brzu konsultaciju). Agent čita`AGENT.adoc`jednom za *comprendre* ; ponovo čita`INDEX.adoc`на свакој сессии за *примењу*. Два употреба, два формата.

[plantuml, format=svg, id=diag-dualite-agent-index, alt="Comparaison entre AGENT.adoc (narratif) et INDEX.adoc (exécutif)"]
----
@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center

title Dualitet AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc
(Корен — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **Narativni format**\nPričanje o pravilu\nNaučena lekcija, kontekst" as NARR
  rectangle "🏗️ **Kompletna arhitektura**
Struktura projekta, komponente
Detaljani backlog US" as ARCHI
  rectangle "📋 **Објаснива правила**
Zašto pravilo postoji
Istorija incidenta" as EXPL
}

rectangle "INDEX.adoc
(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **Извршни формат**
Наго правило, без обосновања
Брза консултација" as EXEC
  rectangle "📊 **Roadmap & EPICs**
Саžетна табела
Прогрес, Скор, Приоритет" as ROAD
  rectangle "**Portfelj projekata**
Prečnji pogled
5 sinkronizovanih projekata" as PORT
}

AGENT --> INDEX : "Agent čita AGENT.adoc\njednom za **razumevanje**"
INDEX --> AGENT : "Agent čita INDEX.adoc
svaka sesija za **primeniti**"

note bottom of AGENT
  Taille max : 200 lignes
end note

note bottom of INDEX
  Taille max : 200 lignes
  Source de vérité en cas de divergence
end note

@enduml
----

Ova pretpostavljena redundantnost je izbor dizajna. Ona potrošuje ~50 dodatnih linija tokena EAGER — ali osigurava da agent uvek ima pravila pred sobom, uključujući i koncizni format koji olakšava odmah poslušanje.

=== LAZY fajlovi: Uputstvo za vlasnika

Ovi fajlovi žive u`.agents/`Oni čine istinsko bogatstvo metode, jer nahromadjuju znanje o projektu bez zagađavanja trenutnog konteksta.

[plantuml, format=svg, id=diag-agents-tree, alt="Arborescence complète du dossier .agents/"]
----
@startuml
skinparam folderBackgroundColor #E3F2FD
skinparam folderBorderColor #1565C0
skinparam fileBackgroundColor #FFF3E0
skinparam fileBorderColor #EF6C00

folder ".agents/" as ROOT {
  file "INDEX.adoc
(EAGER -- 200 linija)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc
(Šablon sesije)" as ASM
  file "SESSION_CHECKLIST.adoc
(Кда променити)" as CHK
  file "PROCEDURES.adoc\n(6 koraci + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(Све сесии)" as HIS

  folder "сесии/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-формализација-лењи.adoc" as S109 #FFECB3
    file "133-epic11-article.adoc" as S133
    file "... +130 ostalih" as SMORE
  }

  folder "архиве/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "sesije_sazimci/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "arhiva_prompta/" as PARCH {
      file "PROMPT_REPRISE_S65.adoc" as PR65
      file "PROMPT_REPRISE_S75.adoc" as PR75
      file "..." as PMORE
    }
  }
}

IDX --> SESS : "indeksiraj"
IDX --> HIS : "indeksiraj"
IDX --> ARCH : "референца"

note right of S109
  Session 109 =
  Formalisation stratégie
  LAZY/EAGER
  Token : ~25k → ~10k
end note

@enduml
----

Gornje stablo prikazuje stvarnu strukturu direktorijuma.`.agents/`na`plantuml-plugin`, najzrelji projekat. Obratite pažnju na dubinu u tri sloja: korenske datoteke (metapodaci), direktorijum`sessions/`(arhivske beleške), i dossier`archives/`(agregacije i sažeci). To je ta dubina koja pretvara upravljanje jedne jednostavne TODO datoteke u**puna organizaciona memorija**.

**.agents/sessions/{N}-{titre}.adoc**-- Detaljni arhivi svake sesije. Trenutno :

* `plantuml-plugin`:**133 arhiviranih sesija**(od sesije 1 do 133)
* `bakery-plugin`:**11 sesija**
* `magic-stick`[Translation not possible as no text was provided for translation]**23 sesija**
* `cheroliv.com`:**9 формалне сесије**+ 7 pre-sistemski sesiji reconstruisane retroaktivno

Svaki arhiv sadrži potpun kontekst sesije, donete odluke, naiđene probleme i njihovo rešenje, izvršene komande i njihovu izlaz.

**.agents/SESSIONS_HISTORY.adoc**Табела сажетак свих сесија са поенима. Пример на`cheroliv.com`:

----

| -6 | 2025-05 | chore | Initialisation projet Gradle/JBake | 7/10 |  1 | 2026-04-25 | chore | Migration gouvernance agent | 8/10 |  7 | 2026-04-27 | debug/fix | Correction publishSite | 9/10 |  8 | 2026-04-27 | analyse | Analyse article 0108 | 7/10

**.agents/COMPLETED_TASKS_ARCHIVE_{mois}.adoc**-- Završeni zadaci arhivirani po mesecima, da ne bi se preopteregao aktivni backlog. Kada se user story završi, premješta se ovde. Backlog ostaje čitljiv: maksimalno 10 aktivnih stavki.

**.agents/PROCEDURES.adoc**-- Detaljni predlošci postupka završetka sesije. Dug, ali pročitan samo jednom od agenta kada uči metod. Zatim postepanje postaje mehaničko.

**.agents/AGENT_MODUS_OPERANDI.adoc**-- Пуна стратегијска документација. На`plantuml-plugin`, ovaj fajl čini**900+ linije**и у ствари се зове`AGENT_METHODOLOGIES.adoc`— promenio sam ime između pisanja ovog članka i njegove efektivne implementacije. Ovaj tip razlike u imenovanju je neizbežan u ručnom sistemu koji se razvija. Važna je konvencija imenovanja: ako fajl dokumentuje *metodu*, počinje sa`AGENT_`ili eksplicitni prefiks. Dokumentuje metodologiju Eager/Lazy, obrasce koje treba slediti, i anti-obrasce koje treba izbegnuti. On je LAZY jer agentu ne mora da ponovo pročita celu strategiju na svakoj sesiji, već samo kada postoji nejednoznačnost.

Please provide the French text you would like translated.`*_REFERENCE.adoc`** -- Tehničke reference specifične za projekat. Na`magic-stick`, dva gaustog LAZY fajla:

* `AB_PARTITION_REFERENCE.adoc`(147 linija) -- Arhitektura particija A/B GPT, skripte`update-system.sh`, procijenjene veličine, mehanizam vraćanja
* `BOOT_TEST_REFERENCE.adoc`(144 linija) -- Procedura QEMU + VNC za testiranje boot-a ISO bez fizičkog hardvera, lista provere BIOS/UEFI, ograničenja CI/CD

na`plantuml-plugin` :

* `ARCHITECTURE.adoc`(134 линија) -- Структура 11 класа података, тачке на пажњи (избегљиви погрешци), оптимизоване тест команде
* `API_KEY_POOL_REFERENCE.adoc`-- Пуне детаљи о пулу кључева (LAZY dok`ESSENTIALS`je EAGER)

== Specijalizirani agenti : virtualni tim

Uprava se ne ograničava na pasivne datoteke. Formalisao sam**uloge specijalizovanih agenta**u posebnima LAZY fajlovima, koji definišu očekivan radni tok prema tipu zadatka.

|===
|agent |Fajl |улага |projekat |**CODER** |`CODER.adoc` |Implementacija FTL/CSS/JS, semantičke oznake, kriteriji pristupačnosti |cheroliv.com |**Scrum master** |`SCRUM_MASTER.adoc` |US planiranje, razlaganje na podzadatke, otkrivanje zavisnosti |cheroliv.com |**PlantUML dizajner** |`PLANTUML_DESIGNER.adoc` |Kreiranje dijagrama, sintaksa PUML, integracija JBake |cheroliv.com
|===

Fajl`CODER.adoc`na`cheroliv.com`sadrži konkretna pravila : _jedno`<h1>`po stranica_, _Dodaj putanje sa`${content.rootpath}`_, _Навести језик`<html lang="${content.lang!"fr"}">`_. Ove konvencije, napisane jednom, automatski se poštuju agentom od sesije 1.

Datoteka`SCRUM_MASTER.adoc`postavlja strukturu izlagaja :**Cilj**, **Zadaci**(koordinate sa dodelom),**Прихватљиви критеријуми**, **Rizici**. Kada tražim plan akcije, agent proizvodi ovu strukturu bez da sam je zatražila. Uprava**програм**агент.

==== Када специјализовани агенти постају неопходни

Kreiranje specijaliziranih agenta slijedi prirodnu krivulju. Na početku projekta, ne trebate ih —`AGENT.adoc`Dovoljno je. Ali kada se projekat povećava (recimo, iznad 20 sesija), dva signala moraju da vas upozore:

1. Agent miješa konvencije dva različita domena (npr. sintaksa PlantUML i pravila CSS)
2. Vi provodite više vremena ispravljajući agenta po konvencijama koje ste mu već pet puta objasnili.

На`cheroliv.com`, se dogodilo na sesiji... 1. Da, odmah sa početka. Jer je ovaj projekat veb sajt sa tri jezika (FTL, CSS, JS), sadržaj AsciiDoc i dijagrami PlantUML — tri oblasti koje nemaju ništa zajedničkog. Agentu CODER treba znati veličine fontova i medijske upite; agentu PLANTUML_DESIGNER treba znati sintaksu`@startuml`. Bez razdvajanja, agent CODER mi je ponudivao dijagrame, i obrnuto. Haos.

на`jhipster-gradle-plugins`, sam kreirao dva specijalizovana agenta prilagođena za razvoj Gradle pluginova :`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. Prvi kodira sve konvencije Kotlin/Gradle (ne`!!`, klase podataka za modele,`@TaskAction`за задацима). Други зна da`persistence`mora biti stabilan pre nego što`assistant`не покреће свој развој — критична зависимост у мон-репо.

Greška koju ne treba napraviti: kreirati previše agenata previše rano.`plantuml-plugin`Čekao je sesiju 108 pre nego što je formalizovao specijalizovanog agenta za pool ključeva API. Pre toga, poslovni kontekst je bio u`AGENT.adoc`. Empiričko pravilo: specijalizovan agent se justifikuje kada njegov poslovni domen pređe 100 linija dokumentacije.

==== Конвенција о наименовању сесија

Detalj koji izgleda beznačajan, ali postaje kritičan kada se dosegne 100 sesija. Kako da imenujemo datoteke arhive?

Naukio sam na svojoj koži da je konvencija neophodna — četiri projekta, četiri različita formata na početku, i više sam se ne mogao orijentirati. Danas, konvencija koju sam uspostavio je :

Конкретни примери :

* `1-chore-migration-gouvernance-agent.adoc`— сесија 1, тип задатка
* `10-solidification-tests.adoc`— sesija 10, bez eksplicitnog tipa (subjekat je dosta)
* `036-debug-graphify-symlink-epic9.adoc`— сесија 36 са трицифрен бројем за сортирање

Broj sesije je glavni kriterijum za sortiranje. Projekti koji koriste trocifrene brojeve (001, 036, 133) izbegavaju probleme leksikografskog sortiranja kada se prelazi 99. To je šta sada koristim na`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

Tip je opcioni i izveden iz ključnih reči sesije (debug, feature, refactor, docs, chore, test). Naslov u kebab-case-u je najvažniji deo: mora da omogući pronalaženje sesije bez otvaranja fajla. Ako se pitate « Koja je bila sesija u kojoj smo ispravili timeout testova integracije? », odgovor je`124-fix-timeout-integration-test.adoc`.

Za reconstruisane istorijske sesije (projekti koji su nastali pre upravljanja), koristim negativne brojeve. Na`cheroliv.com`, sesije od -6 do 0 pokrivaju celokupnu pre-vladavinu istoriju projekta. I za sesije « ne dokumentovane » ili izgubljene, napravim unos u`SESSIONS_HISTORY.adoc`без одговарајућег архива, са једним скором`?`. To je poštenije nego da se pretvaramo.

[plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]

==== TEST_COVERAGE_ANALYSIS.adoc` — Корак 5 разложен

Peti korak postupka završetka sesije je najtajniji. Ona kaže « Ažuriraj`TEST_COVERAGE_ANALYSIS.adoc`ako su testovi dodati ili izmenjeni » Ali kako izgleda ovaj fajl?

Na`plantuml-plugin`, je se razvijao od nekoliko linija do kompletne strukture. Ovde je njegov stabilizovani oblik :

[source]