Governing an AI Agent with AsciiDoc: My Eager/Lazy Strategy for Context-Leak-Free Opencode Sessions

----
| 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`** -- A recent addition (Session 109, plantuml-plugin) to further optimize Eager context. Instead of loading 200 lines of business context on the API key pool, I load 50 lines of essentials, and the other 150 lines remain LAZY in`*_REFERENCE.adoc`.

Measured result: move from**~25k EAGER tokens to ~10k tokens**(60% gain). The agent no longer needs energy-consuming reminders.

==== The Missing Link: `opencode.json`

I must confess something I almost forgot to document. Above all these .adoc files, there is a tiny JSON file without which nothing works. It's called`opencode.json`and it is six lines long. Literally six lines.

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

This file tells Opencode: "At startup, load`AGENT.adoc`automatically." Without it, the agent is a blank page, exactly as I described at the beginning of the article. With it, the agent already has the absolute rules, the project architecture, and the essential commands in hand — before I even say hello.

I discovered the importance of this file by chance. On`bakery-plugin`, it didn't exist. I wondered why the agent was consistently more "lost" on this project than on others. The absolute rules were indeed in`AGENT.adoc`— but`AGENT.adoc`was never loaded. The agent only read what I told it to read, manually, every session. It was session 11 of`bakery-plugin`when I realized the`opencode.json`was missing. I created it — and session 12 started like the others.

This file is so obvious to me now that I didn't even think of it. A classic developer's error of knowing the tool too well. Today, I systematically create it *before*`AGENT.adoc`. It is the first stone.

==== The Duality of `INDEX.adoc`

Another subtlety that deserves explanation:`INDEX.adoc`lives in`.agents/`— a folder I presented as LAZY. Yet, I list it as EAGER in all my tables. There is an apparent tension here.

Field reality:`.agents/INDEX.adoc`files are indeed loaded automatically at the start of the session, just like`AGENT.adoc` et `PROMPT_REPRISE.adoc`. They are in`.agents/`for organizational reasons — not to clutter the root — but their behavior is EAGER.

On`plantuml-plugin`, `INDEX.adoc`is 200 lines and contains *complete* absolute rules with their history (lessons from past sessions), EPICs with scores, and the project portfolio. It is the document the agent consults to know "where we stand." On`bakery-plugin`, it is 150 lines with the roadmap and recent sessions.

The intentional redundancy between`AGENT.adoc` et `INDEX.adoc`might be surprising. Absolute rules are present in both. Why? Because they fulfill two different roles: in`AGENT.adoc`, they are *explanatory* (the storytelling of the rule, the lesson learned); in`INDEX.adoc`, they are *executive* (the bare rule, without justification, for quick consultation). The agent reads`AGENT.adoc`once to *understand*; it re-reads`INDEX.adoc`every session to *apply*. Two uses, two formats.

[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 Dualité AGENT.adoc ←→ INDEX.adoc

left to right direction

rectangle "AGENT.adoc\n(Racine — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **Format Narratif**\nLe storytelling de la règle\nla leçon apprise, le contexte" as NARR
  rectangle "🏗️ **Architecture Complète**\nStructure projet, composants\nBacklog détaillé US" as ARCHI
  rectangle "📋 **Règles Explicatives**\nPourquoi la règle existe\nHistorique de l'incident" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **Format Exécutif**\nLa règle nue, sans justification\nConsultation rapide" as EXEC
  rectangle "📊 **Roadmap & EPICs**\nTableau récapitulatif\nProgression, Score, Priorité" as ROAD
  rectangle "🌐 **Portefeuille Projets**\nVue transverse\n5 projets synchronisés" as PORT
}

AGENT --> INDEX : "Agent lit AGENT.adoc\n1 fois pour **comprendre**"
INDEX --> AGENT : "Agent relit INDEX.adoc\nchaque session pour **appliquer**"

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
----

This assumed redundancy is a design choice. It consumes ~50 additional lines of EAGER tokens — but it guarantees the agent always has the rules before its eyes, including in the concise format that facilitates immediate obedience.

=== LAZY Files: The Owner's Manual

These files live in`.agents/`and are only read when the agent needs them. They constitute the true wealth of the method, as they accumulate project knowledge without polluting the current context.

[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\n(EAGER -- 200 lignes)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc\n(Template session)" as ASM
  file "SESSION_CHECKLIST.adoc\n(Quand changer)" as CHK
  file "PROCEDURES.adoc\n(6 étapes + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(Toutes sessions)" as HIS

  folder "sessions/" as SESS {
    file "1-chore-migration.adoc" as S1
    file "109-formalisation-lazy.adoc" as S109 #FFECB3
    file "133-epic11-article.adoc" as S133
    file "... +130 autres" as SMORE
  }

  folder "archives/" as ARCH {
    file "COMPLETED_TASKS_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "sessions_summaries/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "prompts_archive/" as PARCH {
      file "PROMPT_REPRISE_S65.adoc" as PR65
      file "PROMPT_REPRISE_S75.adoc" as PR75
      file "..." as PMORE
    }
  }
}

IDX --> SESS : "Indexe"
IDX --> HIS : "Indexe"
IDX --> ARCH : "Référence"

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

@enduml
----

The tree above shows the actual structure of the`.agents/`folder on`plantuml-plugin`, the most mature project. Note the three-layer depth: root files (metadata),`sessions/`folder (chronological archives), and`archives/`folder (aggregations and summaries). This depth transforms governance from a simple TODO file into a**complete organizational memory**.

**`.agents/sessions/{N}-{title}.adoc`**-- Detailed archives of each session. Currently:

* `plantuml-plugin`:**133 archived sessions**(from session 1 to 133)
* `bakery-plugin`:**11 sessions**
* `magic-stick`:**23 sessions**
* `cheroliv.com`:**9 formal sessions**+ 7 pre-system sessions retroactively reconstructed

Each archive contains the full context of the session, decisions made, problems encountered and their resolution, commands executed and their output.

**`.agents/SESSIONS_HISTORY.adoc`**-- A summary table of all sessions with a score. Example on`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

----
{N}-{type}-{sujet-kebab-case}.adoc
----

Concrete examples:

* `1-chore-migration-gouvernance-agent.adoc`— session 1, type chore
* `10-solidification-tests.adoc`— session 10, without explicit type (subject suffices)
* `036-debug-graphify-symlink-epic9.adoc`— session 36 with 3-digit number for sorting

The session number is the primary sorting criterion. Projects using 3-digit numbers (001, 036, 133) avoid lexicographical sorting issues when exceeding 99. This is what I now use on`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

The type is optional and derived from session keywords (debug, feature, refactor, docs, chore, test). The subject in kebab-case is the most important part: it must allow finding a session without opening the file. If you wonder "which session was it where we fixed the integration test timeout?", the answer is`124-fix-timeout-integration-test.adoc`.

For reconstructed historical sessions (projects born before governance), I use negative numbers. On`cheroliv.com`, sessions -6 to 0 cover the entire pre-governance history of the project. And for "undocumented" or lost sessions, I create an entry in`SESSIONS_HISTORY.adoc`without a corresponding archive, with a score`?`. It's more honest than pretending.

[plantuml, format=svg, id=diag-naming-convention, alt="Arbre de décision pour le nommage des fichiers de session"]
----
@startuml
skinparam backgroundColor #FEFEFE
skinparam defaultTextAlignment center
skinparam wrapWidth 200

title Convention de Nommage des Sessions

start

:Une session se termine;
note right: Trigger "fin de session"

if (Session antérieure\nà la gouvernance ?) then (oui)
  :Numéro **NÉGATIF**\n-6, -5 ... 0;
  note right: Historique\nreconstitué
  :Suffixe : reconstitution;
else (non)
  :Numéro **POSITIF**\nsur 3 chiffres si > 99;
  note right: 001, 036, 133\npour le tri lexicographique

  :Détecter le **TYPE**;
  if (Mots-clés trouvés ?) then (oui)
    :debug / feature / refactor\ndocs / chore / test;
  else (non)
    :Omettre le type\n(le sujet suffit);
  endif

  :Formuler le **SUJET** en kebab-case;
  note right
    Ex: fix-timeout-integration-test
    Doit permettre de retrouver
    sans ouvrir le fichier
  end note
endif

:Nom final : {N}-{type}-{sujet}.adoc;
note right
  • 1-chore-migration-gouvernance.adoc
  • 036-debug-graphify-symlink.adoc
  • 124-fix-timeout-integration-test.adoc
  • 133-epic11-article-blog-kg.adoc
end note

if (Session documentée ?) then (oui)
  :Créer archive dans sessions/;
  :Ajouter ligne SESSIONS_HISTORY\navec score X/10;
else (non)
  :Ajouter ligne SESSIONS_HISTORY\navec score **?**\n**sans archive**;
  note right: L'honnêteté\nplutôt que le vide
endif

stop
@enduml
----

==== `TEST_COVERAGE_ANALYSIS.adoc` — Step 5 Dissected

Step 5 of the end-of-session procedure is the most mysterious. It says "Update`TEST_COVERAGE_ANALYSIS.adoc`if tests were added or modified." But what does this file look like?

On`plantuml-plugin`, it evolved from a few lines to a complete structure. Here is its stabilized form:

[source]
----
= Analyse de Couverture de Tests

== Suivi des Tests
|===
| Classe de test | Type | Tests | Statut | Dernière MAJ
| PlantumlServiceTest | unit | 45/45 | ✅ PASS | 2026-04-23
| ApiKeyPoolTest | integration | 15/15 | ✅ PASS | 2026-04-20
|===

== Historique par Session
| Session | Tests ajoutés | Tests modifiés | Couverture
| 133     | 0             | 2              | 100%
| 132     | 5             | 0              | 100%
|===
----

The value is not in the file itself — it's the obligation to *note* what changed. Without this step, after 50 sessions, you no longer know which tests cover what. Neither does the agent. The file becomes the single source of truth for the project's test coverage.

For projects without traditional tests (like`magic-stick`which tests bash scripts), step 5 is replaced by`SCRIPT_VERIFICATION.adoc`. The mechanism is the same: a file that tracks the validation state of scripts. Adapt step 5 to your project, but never skip it. It is the safety net that prevents silent regression.

If your project has *no* tests — neither unit, nor functional, nor script — create the empty file anyway with a section "To do: define a test strategy." It's a bookmark that will remind your future self that this subject hasn't been addressed.

[plantuml, format=svg, id=diag-session-flow, alt="Flux d'une session type avec Eager/Lazy et agents"]
----
@startuml
skinparam backgroundColor #FEFEFE

start

:Début session;
note right: L'agent est une page blanche

:Chargement EAGER auto;
note right
  * AGENT.adoc (règles absolues)
  * PROMPT_REPRISE.adoc (mission N)
  * INDEX.adoc (état projet)
end note

if (Mission claire ?) then (oui)
  :Exécution directe;
else (non)
  :Charge LAZY sur demande;
  note right
    * SESSIONS_HISTORY.adoc (contexte passé)
    * sessions/{N-1}-*.adoc (décisions)
    * *_REFERENCE.adoc (architechture)
  end note
endif

:Délégation agent spécialisé ?;

if (CODER ?) then (oui)
  :Lit CODER.adoc;
  :Suit conventions FTL/CSS;
elseif (SCRUM Master ?) then (oui)
  :Lit SCRUM_MASTER.adoc;
  :Structure livrable imposée;
elseif (PlantUML ?) then (oui)
  :Lit PLANTUML_DESIGNER.adoc;
  :Syntaxe PUML + intégration;
else (non)
endif

:Travail de la session;

:Fin de session (trigger utilisateur);

:Procédure 6 étapes;
note right
  1. Archive sessions/N-*.adoc
  2. Maj PROMPT_REPRISE.adoc (N+1)
  3. Maj SESSIONS_HISTORY.adoc
  4. Maj INDEX.adoc
  5. Maj TEST_COVERAGE (si applicable)
  6. Maj COMPLETED_TASKS_ARCHIVE.adoc
end note

:Checklist [✅] x 6;

stop
@enduml
----

The diagram above shows the complete life cycle of a session. The key point is the bifurcation after EAGER loading: either the mission is clear enough to execute directly (80% of cases), or the agent loads LAZY data to resolve an ambiguity (20% of cases). This discrimination is what saves tokens.

== End-of-Session Procedure: The Golden Rule

=== Why It Is Essential

Without this procedure, the Eager/Lazy strategy is useless. This is what transforms the session's work into persistent information. It is executed**upon the user's explicit request**(keywords: "end of session", "I'm leaving", etc.), and it is**mandatory**-- no exceptions, no omissions.

The file`SESSION_CHECKLIST.adoc`defines metrics for an ideal session:

* Duration: 15-30 minutes
* Modified files: 1-3 maximum
* LLM exchanges: 5-10 messages
* Context tokens: < 50k

And signs that it's time to change sessions: _The LLM repeats errors already corrected_, _More than 3 files modified in parallel_, _Conversation > 50 messages_. The golden rule:**Better 5 sessions of 20 minutes than one session of 2 hours with debugging chaos.**

=== The 6-Step Flow (Silently)

[plantuml, format=svg, id=diag-end-session-flow, alt="Flux de la procédure de fin de session"]
----
@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200
skinparam activityBackgroundColor #E3F2FD

start
:L'utilisateur dit "fin de session";
note right: Mots-clés déclencheurs

:Agent détecte le trigger;

:Étape 1\nCréer archive\n`.agents/sessions/N-*.adoc`;
note right: Tout le contexte de la session

:Étape 2\nMettre à jour\n`PROMPT_REPRISE.adoc`;
note right: Mission N + critères d'acceptation N+1

:Étape 3\nMettre à jour\n`SESSIONS_HISTORY.adoc`;
note right: Ligne récap : # / Date / Type / Sujet / Score

:Étape 4\nMettre à jour\n`INDEX.adoc`;
note right: État courant, roadmap, fichiers modifiés

:Étape 5\nMettre à jour\n`TEST_COVERAGE_ANALYSIS.adoc`;
note right: Si tests ajoutés ou modifiés

:Étape 6\nMettre à jour\n`COMPLETED_TASKS_ARCHIVE.adoc`;
note right: Archiver tâches terminées

:Afficher la checklist de confirmation;
note right: Vérifier que chaque [✅] est mérité

stop
@enduml
----

=== Results of 150+ Sessions

Here is what this procedure, applied systematically across my four projects, yielded:

**plantuml-plugin**:

* **133 sessions**since the project start
* **240/240 tests PASS**(100% coverage) -- EPICs 1-7 completed
* **57 Cucumber BDD scenarios**validated
* Safety rule on config files born from a real error (Session 2 bakery-plugin)

**bakery-plugin**:

* **11 sessions**in two weeks
* Supabase → Firebase migration completed (9 tests corrected)
* EPIC 6 (publishProfile) functional in production
* Rule 0 created:`publishToMavenLocal`mandatory after each mod

**magic-stick**:

* **23 sessions**to build a live Xubuntu system with A/B partition
* First ISO generated at session 10
* QEMU + VNC boot tests formalized (144-line LAZY documentation)
* SourceForge CI/CD functional

**cheroliv.com**:

* **9 formal sessions**+ reconstruction of 7 pre-system sessions
* Article 0101 (OpenCode PATH) published
* Article 0108 (this one) rewritten after analyzing its gaps
* Complete governance migrated from Markdown to AsciiDoc

=== The Final Checklist

After silent execution of the 6 steps, the agent must display a confirmation checklist:

✅ Procédure de fin de session exécutée
📋 Checklist :
[✅] 1. Archive session N créée
[✅] 2. PROMPT_REPRISE.adoc mis à jour pour session N+1
[✅] 3. SESSIONS_HISTORY.adoc mis à jour
[✅] 4. INDEX.adoc mis à jour
[✅] 5. TEST_COVERAGE_ANALYSIS.adoc mis à jour (si applicable)
[✅] 6. COMPLETED_TASKS_ARCHIVE.adoc mis à jour

mkdir -p .agents/sessions .agents/archives

= {NOM_PROJET} — Directives Agent

[CAUTION]