Failed to generate image: PlantUML preprocessing failed: [From <input> (line 18) ]

@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 "الهجرة
^^^^^
 Syntax Error? (Assumed diagram type: timing)

@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 "الهجرة
AsciiDoc"
10 is "متحمس/كسول\nرسمي"
62 is "قاعدة أمان
(site.yml)"
87 is "الاختراق
السياق"
109 is "التحسين
-60% الرموز"
133 is "133 جلسات\n240 اختبارًا نجح"

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

Failed to generate image: PlantUML preprocessing failed: [From <input> (line 6) ]

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "جذر المشروع (متحمّس - تم تحميله تلقائيًا)" {
    component "<b>AGENT.adoc</b>
^^^^^
 Syntax Error? (Assumed diagram type: class)

@startuml
skinparam defaultTextAlignment center
skinparam wrapWidth 200

package "جذر المشروع (متحمّس - تم تحميله تلقائيًا)" {
    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>\nالسياق المهني الحرج" as ESS
}

package ".agents/ (Lazy - تم التحميل عند الطلب)" {
    component "<b>sessions/N-*.adoc</b>\nالأرشيفات المفصلة\nالقرارات & المخرجات" as SESS
    component "<b>SESSIONS_HISTORY.adoc</b>\nجدول ملخص\ntاريخ/النوع/النتيجة" as HIST
    component "<b>PROCEDURES.adoc</b>
قالب إنهاء الجلسة
6 خطوات" as PROC
    component "<b>*_REFERENCE.adoc</b>
الهندسة المعمارية الكاملة
المراجع التقنية" 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>\nاختبارات التشغيل، تقسيم A/B\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 |
----

**`*_ESSENTIALS.adoc`** -- إضافة حديثة (جلسة 109، البرنامج المساعد plantuml-plugin) لتحسين السياق المتحمس بشكل أكبر. بدلاً من تحميل 200 سطر من سياق الأعمال على مجموعة مفاتيح واجهة برمجة التطبيقات، أتحمل 50 سطرًا من الأساسيات، وتظل 150 سطرًا أخرى في وضع التحميل المتكاسل في`*_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/`لأسباب تنظيمية — لا تغزو الجذر — لكن سلوكهم متحمس.

على`plantuml-plugin`, `INDEX.adoc`يبلغ 200 سطرًا ويحتوي على القواعد المطلقة *الكاملة* مع تاريخها (دروس الجلسات السابقة)، وEPICs مع الدرجات، ومحفظه المشاريع. هذا المستند هو الذي يرجعه الوكيل لمعرفة « حيث نحن ». على`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 "📖 **الصيغة السردية**
القصّة الخاصة بالقاعدة
الدّرس المستفاد، السياق" as NARR
  rectangle "�🏗️ **العمارة الكاملة**
هيكل المشروع، المكونات
Backlog التفصيلي US" as ARCHI
  rectangle "📋 **القواعد التوضيحية**
لماذا توجد القاعدة
تاريخ الحادث" as EXPL
}

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

AGENT --> INDEX : "الوكيل يقرأ AGENT.adoc\nمرة واحدة **لفهم**"
INDEX --> AGENT : "Agent relit INDEX.adoc
كل جلسة لـ **تطبيق**"

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

هذه التكرار المتقصد هو خيار تصميم. إنه يستهلك حوالي 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
(EAGER -- 200 أسطر)" as IDX #E8F5E9
  file "AGENT_SESSION_MANAGER.adoc
(جلسة قالب)" as ASM
  file "SESSION_CHECKLIST.adoc\n(متى التغيير)" as CHK
  file "PROCEDURES.adoc
(6 مراحل + LAZY/EAGER)" as PRO
  file "SESSIONS_HISTORY.adoc
(كل الجلسات)" 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 آخرين" as SMORE
  }

  folder "الأرشيف/" as ARCH {
    file "المهام_المكتملة_2026-04.adoc" as CTA
    file "SESSIONS_HISTORY_83-95.adoc" as SHIST
    folder "جلسات_ملخصات/" as SUM {
      file "SESSION_64_SUMMARY.adoc" as SU64
      file "SESSION_73_SUMMARY.adoc" as SU73
      file "..." as SUMORE
    }
    folder "prompts_أرشيف/" 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
  Session 109 =
  Formalisation stratégie
  LAZY/EAGER
  Token : ~25k → ~10k
end note

@enduml
----

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

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

* `plantuml-plugin` : **133 جلسة مؤرشفة**(من الجلسة 1 إلى الجلسة 133)
* `bakery-plugin` : **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_{شهر}.adoc**المهام المكتملة المؤرشفة شهريًا، لتجنب إرهاق الباك-لوج النشط. عندما تُنهي قصة المستخدم، يتم نقلها إلى هنا. يبقى الباك-لوج قابلاً للقراءة: الحد الأقصى 10 عناصر نشطة.

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

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

**`*_REFERENCE.adoc`** -- المراجع التقنية الخاصة بالمشروع. على`magic-stick`, ملفين LAZY كثيفين:

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

على`plantuml-plugin`(Empty)

* `ARCHITECTURE.adoc`(134 سطرًا) -- الهيكل 11 فئة بيانات، نقاط انتباه (مخاطر يجب تجنبها)، أوامر اختبار محسّنة
* `API_KEY_POOL_REFERENCE.adoc`-- تفاصيل كاملة لمجمع المفاتيح (LAZY أثناء`ESSENTIALS`هو EAGER)

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

لا تقتصر الحوكمة على ملفات سلبية. لقد قمت بصياغة بعض**أدوار الوكلاء المتخصصين**في ملفات 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 قبل تحديد وكيل متخصص لمجموعة مفاتيح API. قبل ذلك، كان السياق التجاري محتوى في`AGENT.adoc`. القاعدة التجريبية: يُبرر وكيل متخصص عندما يتجاوز مجال عمله 100 سطر من التوثيق.

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

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

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

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

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

رقم الجلسة هو معيار الفرز الرئيسي. المشاريع التي تستخدم أرقامًا مكونة من ثلاثة أرقام (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

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

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

[source]