@startuml
skinparam backgroundColor #FEFEFE
skinparam handwritten false

title تطور الجلسات — من الجلسة 1 إلى 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 خام"
1 is "الهجرة\nAsciiDoc"
10 is "Eager/Lazy\nformalisé"
62 is "قاعدة أمان\n(site.yml)"
87 is "الاختراق\nالسياق"
109 is "التحسين\n-60% رموز"
133 is "133 جلسات\n240 اختبارات PASS"

S@0 -> S@1 : الجلسة 1\n(cheroliv.com)
S@1 -> S@10
S@10 -> S@62 : جلسة 62\n(إضافة PlantUML)
S@62 -> S@87 : جلسة 87\n(صرخة طلب المساعدة)
S@87 -> S@109 : جلسة 109\n(API مجمع المفاتيح)
S@109 -> S@133 : جلسة 133\n(اليوم)

@enduml

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "جذر المشروع (متحمس - يُحمَّل تلقائيًا)" {
    component "<b>AGENT.adoc</b>\nقواعد مطلقة\nهيكل & الاتفاقيات" as AGENT
    component "<b>PROMPT_REPRISE.adoc</b>\nمهمة الجلسة N\nملخص N-1" as PROMPT
    component "<b>INDEX.adoc</b>\nنقطة الدخول\nقواعد + جلسات" as INDEX
    component "<b>*_ESSENTIALS.adoc</b>\nسياق العمل\nحرجة" as ESS
}

package ".agents/ (كسل - يتم تحميله عند الطلب)" {
    component "<b>sessions/N-*.adoc</b>\nملفات تفصيلية\nقرارات & المخرجات" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nجدول ملخص\nالتاريخ/Type/Score" as HIST
    component "<b>PROCEDURES.adoc</b>\nقوالب نهاية الجلسة\n6 مراحل\n" as PROC
    component "<b>*_REFERENCE.adoc</b>\nالبنية الكاملة\nالمراجع التقنية" as REF
    component "<b>COMPLETED_TASKS_ARCHIVE</b>\nالمهام المكتملة\nلكل شهر" as ARCH
    component "<b>AGENT_MODUS_OPERANDI.adoc</b>\nتوثيق الإستراتيجية\nالمنهجية" as MOD
    component "<b>*_REFERENCE.adoc</b>\nBoot tests, A/B partition\nسياقات محددة" as SPEC
}

AGENT --> PROMPT : "المراجع"
AGENT --> INDEX : "المراجع"
INDEX --> SESS : "الفهرس"
INDEX --> HIST : "الفهرس"
INDEX --> PROC : "المرجع"
INDEX --> ARCH : "المرجع"
INDEX --> REF : "المرجع"
PROMPT --> SESS : "الأرشيف N-1"
PROMPT --> ESS : "سياق العمل 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 |
----

[No output]`*_ESSENTIALS.adoc`** -- إضافة حديثة (الجلسة 109، ملحق PlantUML) لتحسين السياق المتعطش أكثر. بدلاً من تحميل 200 سطرًا من سياق العمل على حوض مفاتيح API، أقوم بتحميل 50 سطرًا من الأساسيات، وتبقى الـ 150 سطرًا الأخرى في وضع LAZY داخل`*_REFERENCE.adoc`.

النتيجة المقاسة : مرور من**~25k tokens EAGER إلى ~10k tokens**(ربح 60٪). الوكيل لم يعد بحاجة إلى التذكيرات التي تستهلك الطاقة

==== الحلقة المفقودة : `opencode.json

عليّ أن أقول لكم شيئًا كدت أن أنسى توثيقه. في أعلى كل هذه الملفات .adoc، يوجد ملف JSON صغير جدًا لا يعمل أي شيء بدونه. اسمه`opencode.json`وهو يشكل ستة أسطر. حرفيًا ستة أسطر.

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

هذا هو الملف الذي يقول إلى Opencode : « عند بدء التشغيل، تحميل`AGENT.adoc`أوما تلقائيًا." دونه، الوكيل صفحة بيضاء تمامًا كما وصفته في بداية المقالة. معه، يكون لدى الوكيل بالفعل القواعد المطلقة، وهندسة المشروع، والأوامر الأساسية في يده — قبل أن أقول حتى مرحباً.

اكتشفتُ أهمية هذا الملف بالصدفة. على`bakery-plugin`, لم يكن موجودًا. كنت أتساءل لماذا كان الوكيل بشكل منتظم أكثر «ضائع» في هذا المشروع مقارنة بالآخرين. كانت القواعد المطلقة جيدًا في`AGENT.adoc`— لكن`AGENT.adoc`لم يكن مشحونًا قط. كان الوكيل يقرأ فقط ما طلبت منه أن يقرأه، يدويًا، في كل جلسة. كانت الجلسة رقم 11 من`bakery-plugin`عندما أدركت غياب ال`opencode.json`. لقد أنشأته — وبدأت الجلسة 12 مثل باقي الجلسات.

هذا الملف أصبح واضحًا جدًا بالنسبة لي الآن إلى درجة أنني لم أعد أفكر به إطلاقًا. خطأ كلاسيكي للمطور الذي يعرف أداته أكثر من اللازم. اليوم، أقوم بإنشائه بشكلٍ منهجي *avant*`AGENT.adoc`. هذا هو الحجر الأول

==== ثنائية `INDEX.adoc

نقطة دقيقة أخرى تستحق أن تُوضَّح :`INDEX.adoc`يعيش في`.agents/`— ملف قدمته على أنه LAZY. ومع ذلك، أدرجته كـ EAGER في جميع جدولي. هناك توتر واضح هنا.

واقع الميدان : الملفات`.agents/INDEX.adoc`يتم تحميلها تلقائيًا في بداية الجلسة، على قدم المساواة مع`AGENT.adoc` et `PROMPT_REPRISE.adoc`. هم في`.agents/`لأسباب تنظيمية — لا تغزو الجذر — لكن سلوكهم EAGER

على`plantuml-plugin`, `INDEX.adoc`يحتوي على 200 سطرًا ويحتوي على القواعد المطلقة *المكتملة* مع تاريخها (دروس الجلسات الماضية)، وإيبيكس مع الدرجات، ومحفظة المشاريع. إنه المستند الذي يستشيره الوكيل لمعرفة « أين نحن الآن ». Sur`bakery-plugin`، يحتوي على 150 سطرًا مع خريطة الطريق والجلسات الأخيرة.

التكرار الطوعي بين`AGENT.adoc` et `INDEX.adoc`قد يثير الدهشة. القواعد المطلقة موجودة في كلاهما. لماذا؟ لأنها تلعب دورين مختلفين: في`AGENT.adoc`, إنها *مفسّرة* (حكاية القصة للـقاعدة، الدرس المستفاد) ; في`INDEX.adoc`, همّ *تنفيذيّات* (القاعدة العارية, بدون مبرر, لاستشارة سريعة). الوكيل يقرأ`AGENT.adoc`مرّة واحدة *للفهم* ؛ يعيد القراءة`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 الثنائية AGENT.adoc ←→ INDEX.adoc
left to right direction

rectangle "AGENT.adoc\n(الجذر — EAGER)" as AGENT #E3F2FD {
  rectangle "📖 **التنسيق السردي**\nالسرد القصصي للقاعدة\nالدرس المستفاد، السياق" as NARR
  rectangle "🏗️ **البنية الكاملة**\nالهيكل المشروع، المكونات\nBacklog مفصل US" as ARCHI
  rectangle "📋 **القواعد التوضيحية**\nلماذا توجد القاعدة\nتاريخ الحادث" as EXPL
}

rectangle "INDEX.adoc\n(.agents/ — EAGER)" as INDEX #E8F5E9 {
  rectangle "⚡ **التنسيق التنفيذي**\nالقاعدة العارية، بدون تبرير\nاستشارة سريعة" as EXEC
  rectangle "📊 **Roadmap & EPICs**\nالجدول الملخص\nProgression, Score, الأولوية" as ROAD
  rectangle "🌐 **مجموعة المشاريع**\nرؤية عرضية\n5 مشاريع متزامنة" as PORT
}

AGENT --> INDEX : "Agent lit AGENT.adoc\n1 مرة ل **لفهم**"
INDEX --> AGENT : "Agent relit INDEX.adoc\nكل session ل **لتطبيق**"

note bottom of AGENT
الحد الأقصى للحجم: 200 سطر
end note

note bottom of INDEX
الحد الأقصى للحجم: 200 سطر
  Source de vérité en cas de divergence
end note

@enduml
----

هذه الزيادة المتعمدة هي خيار تصميم. تستهلك حوالي 50 سطرًا إضافيًا من رموز EAGER المتحمسة — لكنها تضمن أن الوكيل لديه دائمًا القواعد أمامه، حتى في الشكل المختصر الذي يسهّل الامتثال الفوري.

=== ملفات LAZY : دليل المالك

هذه الملفات تعيش في`.agents/`ولا يُقرؤون إلا عندما يحتاج الوكيل إليهم. وهم يمثلون الثروة الحقيقية للطريقة، لأنهم يتراكمون معرفة المشروع دون تلويث السياق الحالي.

[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 ".وكلاء/" as ROOT {
  file "INDEX.adoc\n(EAGER -- 200 أسطر)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc\n(جلسة القالب)" as ASM
  file "SESSION_CHECKLIST.adoc\n(متى تتغير)" as CHK
  file "PROCEDURES.adoc\n(6 خطوات + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc\n(كل الجلسات)" as HIS

  folder "جلسات/" 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 الآخرين" as SMORE
  }

  folder "المحفوظات/" 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 : "فهرس"
IDX --> HIS : "فهرس"
IDX --> ARCH : "مرجع"

note right of S109
الجلسة 109 =
استراتيجية الصياغة
LAZY/EAGER
الرمز : ~25k → ~10k
end note

@enduml
----

الهيكلية أعلاه تُظهر الهيكل الحقيقي للمجلد`.agents/`علي`plantuml-plugin`، المشروع الأكثر نضجًا. لاحظ العمق في ثلاث طبقات: الملفات الجذرية (البيانات), المجلد`sessions/`(الأرشيفات الزمنية)، و ملف`archives/`(التجميعات والتلخيصات). هذا العمق هو الذي يحول حوكمة ملف TODO البسيط إلى une**ذاكرة تنظيمية كاملة**.

**.agents/sessions/{N}-{titre}.adoc**-- الأرشيفات التفصيلية لكل جلسة. حالياً :

* `plantuml-plugin`:

(Note: a single space, then a colon, then a newline.)**133 جلسة مؤرشفة**من الجلسة 1 إلى 133
* `bakery-plugin`(No output, as there is no text to translate after the colon)**11 جلسات**
* `magic-stick`:**23 جلسات**
* `cheroliv.com`:**9 جلسات رسمية**+ 7 جلسات قبل النظام مُعاد بناؤها بأثر رجعي

كل أرشيف يحتوي على السياق الكامل للجلسة، والقرارات المتخذة، والمشكلات التي واجهتها وحلّها، والأوامر التي تم تنفيذها ومخرجاتها.

**.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**-- تم أرشفة المهام المكتملة شهريًا لتجنب إفراط تحميل الباكلوج النشط. عندما تنتهي قصة المستخدم، يتم نقلها إليها. يبقى الباكلوج قابلاً للقراءة: أقصى حد هو 10 عناصر نشطة.

**.agents/PROCEDURES.adoc**-- قوالب مفصلة من الإجراء من انتهاء الجلسة. طويل، لكن قرأ مرة واحدة بواسطة الوكيل عندما يتعلم الطريقة. بعد ذلك، يصبح الإجراء آليًا.

**.agents/AGENT_MODUS_OPERANDI.adoc**الوثائق الاستراتيجية الكاملة. على`plantuml-plugin`, هذا الملف يفعل**900+ أسطر**وهو يُسمى في الواقع`AGENT_METHODOLOGIES.adoc`— غيرت الاسم بين كتابة هذا المقال وتنفيذه الفعلي. هذا النوع من اختلاف التسمية لا مفر منه في نظام صناعي يتطور.الأهم هو اتفاقية التسمية: إذا كان الملف يوثق *الطريقة*، يبدأ بـ`AGENT_`أو بادئة صريحة. هو يوثق منهجية الإيفاج/لايزي، والأنماط الواجب اتباعها، والأنماط الضارّة الواجب تجنّبها. وهو لايزي لأن الوكيل لا يحتاج إلى إعادة قراءة الاستراتيجية بأكملها في كل جلسة، فقط عندما يكون هناك غموض.

**`*_REFERENCE.adoc`المراجع الفنية المحددة للمشروع. على`magic-stick`, ملفّان LAZY كثيفان :

* `AB_PARTITION_REFERENCE.adoc`(147 أسطر) -- البنية لتقسيم أ/ب GPT، النصوص`update-system.sh`, الأحجام المقدّرة, آلية الاسترجاع
* `BOOT_TEST_REFERENCE.adoc`(144 سطر) -- إجراء QEMU + VNC لاختبار تمهيد الـ ISO دون جهاز مادي، قائمة تحقق BIOS/UEFI، قيود CI/CD

على`plantuml-plugin`:

* `ARCHITECTURE.adoc`(134 أسطر) -- هيكل فئات البيانات الـ 11, نقاط الانتباه (مصائد لتجنبها), أوامر الاختبار المحسّنة
* `API_KEY_POOL_REFERENCE.adoc`-- التفاصيل الكاملة لمجموعة المفاتيح (LAZY pendant que`ESSENTIALS`هو متحمس)

== الوكلاء المتخصصون: فريق افتراضي

الإدارة لا تقتصر على ملفات سلبية. لقد قمت بصياغة بعض**أدوار الوكلاء المتخصصين**في ملفات LAZY مخصصة، التي تحدد سير العمل المتوقع حسب نوع المهمة.

|===
|وكيل |ملف |دور |مشروع |**مبرمج** |`CODER.adoc` |تنفيذ FTL/CSS/JS، علامات دلالية، معايير إمكانية الوصول |cheroliv.com |**ماستر سكرام** |`SCRUM_MASTER.adoc` |التخطيط US، تقسيم إلى مهام فرعية، اكتشاف التبعيات |cheroliv.com |**مصمم PlantUML** |`PLANTUML_DESIGNER.adoc` |إنشاء مخططات، صيغة PUML، تكامل JBake |cheroliv.com
|===

الملف`CODER.adoc`على`cheroliv.com`يحتوي على قواعد ملموسة : _واحد`<h1>`لكل صفحة_, _أضف بادئة المسارات مع`${content.rootpath}`_, _إعلان اللغة`<html lang="${content.lang!"fr"}">`هذه الاتفاقيات، التي تُكتب مرة واحدة فقط، يتم احترامها تلقائيًا من قبل الوكيل منذ الجلسة 1.

الملف`SCRUM_MASTER.adoc`تفرض هيكلًا للتسليم:**الهدف**, **مهام**(الإحداثيات مع التعيين),**معايير القبول**, **المخاطر**. عندما أطلب خطة عمل، ينتج الوكيل هذه البنية دون أن أكون قد طلبتها. الحوكمة**البرنامج**الوكيل.

==== عندما يصبح الوكلاء المتخصصون ضروريين

يتبع إنشاء الوكلاء المتخصصين منحًى طبيعياً. في بداية مشروع، أنت لا تحتاج إليها —`AGENT.adoc`يكفي كثيرًا. لكن عندما يزداد المشروع حجمًا (لنفترض، بأكثر من 20 جلسة)، يجب أن يُنبهك إشارتان:

1. الوكيل يخلط بين اتفاقيتين من مجالين مختلفين (مثال: صياغة PlantUML وقواعد CSS)
2. أنت تقضي وقتًا أطول في تصحيح الوكيل على الاتفاقيات التي شرحت له خمس مرات

على`cheroliv.com`, وصل إلى الجلسة...

1. نعم، منذ البداية.

لأنّ هذا المشروع هو موقع ويب يحتوي على ثلاث لغات (FTL، CSS، JS)، ومحتوى AsciiDoc، ورسومات PlantUML — ثلاثة مجالات لا علاقة لها ببعضها البعض. الوكيل CODER يحتاج إلى معرفة أحجام الخطوط و استعلامات الوسائط؛ الوكيل PLANTUML_DESIGNER يحتاج إلى معرفة الصياغة`@startuml`بدون فصل، وكيل CODER كان يعطيني مخططات، والعكس صحيح. الفوضى

على`jhipster-gradle-plugins`, قمت بإنشاء اثنين من الوكلاء المتخصصين المصممين لتطوير مكونات Gradle:`PLUGIN_DEVELOPER.adoc` et `BACKLOG_MANAGER.adoc`. الأول يُرمّز جميع اتفاقيات Kotlin/Gradle (لا`!!`، فئات البيانات للنماذج،`@TaskAction`للمهام). الثاني يعرف أن`persistence`يجب أن يكون مستقرًا قبل أن`assistant`لا يبدأ تطويره — اعتماد حرج في مستودع أحادي.

الخطأ الذي لا ينبغي ارتكابه: إنشاء عدد كبير جدًا من الوكلاء في وقت مبكر.`plantuml-plugin`انتظرت الجلسة 108 قبل أن تُعطى صيغة لوكيل متخصص لمجموعة مفاتيح واجهة برمجة التطبيقات. قبل ذلك، كان سياق الأعمال يقتصر على`AGENT.adoc`. القاعدة التجريبية : الوكيل المتخصص مبرر عندما يتجاوز مجال عمله 100 سطرًا من الوثائق.

==== اتفاقية تسمية الجلسات

تفصيل يبدو تافهاً لكنه يصبح حاسماً عندما نصل إلى 100 جلسة. كيف نسمّي ملفات الأرشيف ?

تعلمت بطريقتي الصعبة أن اتفاقية ضرورية — أربعة مشاريع، أربعة تنسيقات مختلفة في البداية، ولم أعد أستطيع تتبعها. اليوم، الاتفاقية التي استقررت عليها هي:

أمثلة ملموسة :

* `1-chore-migration-gouvernance-agent.adoc`— الجلسة 1، نوع مهمة
* `10-solidification-tests.adoc`— الجلسة 10، من دون نوع صريح (الموضوع كافٍ)
* `036-debug-graphify-symlink-epic9.adoc`— الجلسة 36 مع رقم من ثلاثة أرقام للفرز

رقم الجلسة هو معيار الفرز الأساسي. المشاريع التي تستخدم أرقامًا من ثلاثة أرقام (001، 036، 133) تتجنب مشكلات الفرز اللُّغوي عندما يتجاوز العدد 99. هذا هو ما أستخدمه الآن على`magic-stick`:`001-init-projet.adoc`, `036-debug-graphify-symlink-epic9.adoc`.

النوع اختياري ومشتق من كلمات مفتاحية للجلسة (debug, feature, refactor, docs, chore, test). الموضوع في kebab-case هو الجزء الأكثر أهمية: يجب أن يسمح بالعثور على جلسة دون فتح الملف. إذا كنت تتساءل « ما هي الجلسة التي أصلحنا فيها وقت انتهاء مهلة اختبارات الدمج؟ »، الجواب هو`124-fix-timeout-integration-test.adoc`.

للجلسات التاريخية المعاد إنشاؤها (المشاريع التي وُلدت قبل الحوكمة)، أستخدم أرقامًا سالبة. على`cheroliv.com`, الجلسات من -6 إلى 0 تغطي كامل تاريخ ما قبل الحوكمة للمشروع. و بالنسبة للجلسات « غير الموثقة » أو المفقودة، أنشئ إدخالًا في`SESSIONS_HISTORY.adoc`بدون أرشيف مطابق، مع درجة`?`. إنه أكثر صدقًا من التظاهر.

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

==== TEST_COVERAGE_ANALYSIS.adoc` — الخطوة الخامسة المفصلة

الخطوة 5 من إجراء إنهاء الجلسة هي الأكثر غموضًا. تقول « تحديث`TEST_COVERAGE_ANALYSIS.adoc`إذا تم إضافة أو تعديل الاختبارات. » لكن كيف يبدو هذا الملف؟

على`plantuml-plugin`, طور من بضعة أسطر إلى هيكل كامل. هذه هي صيغته المستقرة :

[source]