المساهمة في Apothem — دليل المطوّر

يساعد هذا الدليل المطوّرين على صون منظومة Apothem وتوسيعها وفق معايير جودة SOTA.

مرجع سريع: أنواع المُنتَجاتCopy Anchor Link

يغطّي هذا الدليل خمسة أنواع من المُنتَجات، لكلٍّ منها غرض محدّد. تحمل القواعد والأوامر والمساعِدات والمهارات بيانات أمامية بصيغة YAML؛ أمّا الخطّافات فتُسجَّل في hooks.json وsettings.json ولا تحمل بيانات أمامية. وأنماط الإخراج صنف إضافي من المُنتَجات، له مفتاحان إلزاميان في البيانات الأمامية هما name وdescription؛ راجع مخطط البيانات الأمامية.

عقد محوّل إطار العملCopy Anchor Link

تقيم حقائق هوية إطار العمل وقدراته في src/apothem/lib/harness_registry.py. ولا يكتمل تغيير إطار العمل إلا عندما تتوافق هذه الأسطح:

يجب على المحوّلات ذات نطاق المشروع أن تضبط requires_project = True، وأن تقبل project: Path | None في توابع دورة الحياة، وأن ترفض جذور المشاريع المفقودة أو غير الآمنة قبل أيّ كتابة. ويجب على المحوّلات ذات نطاق المستخدم أن تُبقي المسارات تحت جذر إعداد المستخدم الموثَّق لإطار العمل.

سياسة التجهيزة الذهبيةCopy Anchor Link

يسجّل tests/fixtures/harness-golden-plans.json الشكل العام لخطة التثبيت لأُطُر العمل السبعة عشر المُسجَّلة في السجلّ جميعها: المُعرِّف العام، ونمط التجسيد، ومسار الحزمة/القالب المصدر، والمسار الهدف المُطبَّع تحت <ROOT>. وعندما يتغيّر سلوك السجلّ أو البيان أو أهداف القوالب عمدًا، حدّث التجهيزة الذهبية في الكوميت نفسه الذي يحمل تغيير المصدر، كي يُظهر الفرق التغيّر في السلوك.

التحقّق قبل الكتابةCopy Anchor Link

يتحقّق برنامج تشغيل التثبيت المشترك من كل مصدر وكل هدف قبل أول كتابة. ويرفض مصادر البيان المفقودة، واجتياز مسار الهدف، ومسارات الهدف الواقعة خارج الجذر المختار، وعبور الروابط الرمزية. وتُنفِّذ عمليات التشغيل التجريبي التحقّق نفسه وتُعيد نتائج مُهيكَلة skipped أو unchanged دون إنشاء ملفات.

التنقيح وبيانات الأمثلةCopy Anchor Link

تُنقِّح تشخيصات الملف التعريفي الحقول التي تأخذ شكل الرمز المميّز، أو السرّ، أو كلمة المرور، أو بيانات الاعتماد، أو مفتاح API، أو المفتاح الخاص، أو التخويل، أو المصادقة، أو الترويسة. وتستخدم الوثائق والتجهيزات والأمثلة ومقتطفات JSON القيم example.invalid وExample User وexample-user وعناصر نائبة واضحة بدلًا من أسرار أو حسابات شخصية تبدو حقيقية.

قبل الكتابة: المخطط المرجعيCopy Anchor Link

العقد المقروء آليًا الذي تفرضه البوابة هو مخططات JSON Schema لكل صنف تحت src/apothem/schemas/*.schema.json — إذ يرفض additionalProperties المفاتيح غير المعروفة، فتكون الكلمة الفصل لبوابة المطابقة. ويتتبّعها إسقاطان مقروءان للبشر: site/content/docs/reference/frontmatter-schema.mdx (فهرس المفاتيح المطلوبة) وsite/content/docs/reference/artifact-schema.mdx (قوالب لكل صنف وأمثلة محلولة). وحيثما تخالف صفحةٌ مخططاتِ JSON Schema، تكون الغلبة للمخططات.

• اقرأ مخطط JSON Schema الخاص بنوع مُنتَجك تحت src/apothem/schemas/
• اقرأ site/content/docs/reference/artifact-schema.mdx § «Schema» للاطّلاع على القالب ومثال محلول
• انسخ الحقول المطلوبة، واملأ القيم الإلزامية، وأضف الحقول الاختيارية حسب الحاجة

فحص سريع للبيانات الأماميةCopy Anchor Link

يجب أن تجتاز البيانات الأمامية لكل مُنتَج هذه الفحوص. طبّق فحوص version وupdated وportability على الصنف الذي يحمل المفتاح فقط: فالقواعد لا تحمل أيًّا منها، والمهارات لا تحمل portability.

✓ Valid YAML syntax (use tools: `yamllint` or PowerShell `ConvertFrom-Yaml` where available)
✓ All mandatory fields present (per schema for artifact type)
✓ name: uses kebab-case
✓ version: semantic MAJOR.MINOR.PATCH
✓ updated: ISO 8601 date (YYYY-MM-DD)
✓ description: single-line, non-empty
✓ scope fields valid per artifact type (rules: pathFilter + alwaysApply; CLAUDE.md root: scope)
✓ portability: string, for example `universal` (the schemas do not enumerate its values)
✓ No typos in field names — must match canonical schema exactly
✓ Optional fields use correct enum values

اصطلاحات التسميةCopy Anchor Link

أسماء المُنتَجات (kebab-case)Copy Anchor Link

• القواعد: operational-mandates، clean-room-generation، context-management
• الأوامر: plan-execute، plan-spec، plan-generate
• المساعِدات: codebase-explorer، convention-auditor، quality-gate
• المهارات: plan-suite، ecosystem-audit

النمط: أحرف صغيرة، وشرطات بين الكلمات، دون مسافات أو شرطات سفلية.

تسمية الملفاتCopy Anchor Link

• القواعد: {name}.md
• الأوامر: {name}.md
• المساعِدات: {name}.md
• المهارات: داخل المجلّد src/apothem/skills/{name}/SKILL.md (بحالة الأحرف نفسها تمامًا: SKILL.md)
• الخطّافات: داخل المجلّد src/apothem/hooks/. جميع معالجات الأحداث مكتوبة بلغة Python. يستخدم كل أمر خطّاف في قالب settings.json الخاص بـ Claude Code صيغة exec: إذ إن command هو العنصر النائب للمفسِّر ${PYTHON_BIN}، ويُحلّ وقت التثبيت، وargs يحمل مسار النص البرمجي ووسائطه. ويشغّل ذلك القالب الأمرين ${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py <event> [<message-name>] و${HARNESS_ROOT}/.apothem/support/conformity/gate.py --hook بالمسار المطلق، فلا تحتاج النسخة المثبّتة إلى حزمة apothem قابلة للاستيراد. أمّا إضافة Claude Code فتسجّل الخطّافات بدلًا من ذلك في src/apothem/hooks/hooks.json، بوصفها أوامر صدفة تشغّل hooks/lib/bootstrap.sh عبر bash؛ ويحدّد ذلك الملف الهيكلي موضع Python ويشغّل dispatch.py، فتبقى المعالجات بلغة Python. سجّل أي خطّاف جديد في hooks.json وفي قالب settings.json الخاص بـ Claude Code. ويوجّه dispatch.py الحدث SessionStart إلى session_start_bootstrap.main()، وكل حدث آخر مُدرَج في القائمة البيضاء إلى emit_hook_context.main(). وملفات الصدفة الهيكلية الوحيدة المسموح بها تحت src/apothem/hooks/ أو scripts/ هي الملفات الستة لتحديد الموقع والتمهيد (find-python.{ps1,sh}، وfind-pwsh.{ps1,sh}، وbootstrap.{ps1,sh})؛ وأي ملف .ps1 / .sh آخر يُخفق في فحص النظافة scripts/dev/validate_hooks.py.

الإحالات المتبادلةCopy Anchor Link

عند الإحالة إلى مُنتَجات أخرى، استخدم الأسماء الدقيقة:

• القواعد: "operational-mandates" (قيمة حقل الاسم)
• الأوامر: /plan-execute (بالشرطة المائلة في الوثائق الموجّهة للبشر؛ ومن دونها في الشيفرة)
• المساعِدات: codebase-explorer (قيمة حقل الاسم)
• المهارات: plan-suite (قيمة حقل الاسم)

لا تستخدم أبدًا مسارات الملفات أو الأسماء المبتورة في النصّ النثري.

قابلية النقل: Windows مقابل UnixCopy Anchor Link

يجب على كل أمر أن يُعلن صراحةً حالة قابليته للنقل في الحقل portability. ويجوز للمساعِد أن يُعلنها. ولا تحمل المهارات والقواعد وأنماط الإخراج حقل portability.

عامّCopy Anchor Link

• يعمل بالطريقة نفسها على Windows وmacOS وLinux
• لا افتراضات بشأن الصدفة
• تستخدم المسارات الشرطات المائلة الأمامية (/)
• لا مسارات مطلقة ثابتة مُضمَّنة
• لا صيغة PowerShell خاصة بـ Windows

portability: "universal"

عامّ مع تحفّظات على WindowsCopy Anchor Link

• عامّ عبر مضيفات POSIX؛ وينطبق التحفّظ المُسمّى على متغيّر منصّة Windows المُعلَن في المحتوى
• وثّق التحفّظ صراحةً في المحتوى
• مثال: «الروابط الرمزية غير مدعومة على Windows قبل Win 10»

portability: "universal-with-windows-caveats"

وثّق التحفّظ في ملاحظة تلي العنوان مباشرةً.

مقتصر على Unix / مقتصر على WindowsCopy Anchor Link

• مقيَّد صراحةً بمنصّة واحدة
• نادر في Apothem — ينبغي أن تكون معظم المُنتَجات عامّة
• لا تستخدمه إلا إذا كانت الميزات الخاصة بالمنصّة أساسية

portability: "unix-only"

وثّق السبب في القسم الأول من المُنتَج.

النطاق: فعّال دائمًا مقابل مُرشَّح بالمسارCopy Anchor Link

فعّال دائمًاCopy Anchor Link

تنطبق القاعدة في كل مكان. خمس قواعد فعّالة دائمًا: agnostic-posture، وauthority-inquiry، وsession-closure، وcontext-management، وفهرس القواعد (apothem-rule-index). والمجموعة صغيرة لأن كل قاعدة فعّالة دائمًا تستهلك من السياق في كل جلسة.

pathFilter: ""
alwaysApply: true

مُرشَّح بالمسارCopy Anchor Link

تنطبق القاعدة شرطيًا بحسب مسار الملف.

pathFilter: "**/*.py, **/*.toml"
alwaysApply: false

يستخدم pathFilter أنماط glob (بالصيغة نفسها المستخدمة في .gitignore). وعندما يطابق ملفٌّ المرشِّح، تُفعَّل القاعدة.

دلالات النسخCopy Anchor Link

يحمل كل مُنتَج ذي نسخة نسخته الدلالية الخاصة (MAJOR.MINOR.PATCH). تتطلّبها الأوامر والمهارات، ويجوز أن تحملها المساعِدات وأنماط الإخراج، ولا تحمل القواعد أيَّ نسخة:

• PATCH — تغيير سلوكي يُصحّح توجيهًا قائمًا دون كسر العقد.
• MINOR — تغييرات إضافية غير كاسرة: أقسام اختيارية جديدة، وحقول اختيارية جديدة في البيانات الأمامية، وأمثلة جديدة. ويواصل المستهلكون الحاليون العمل دون أي تغيير.
• MAJOR — تغييرات كاسرة في المخطط أو العقد: أقسام محذوفة، وحقول مُعاد تسميتها، وتغيير سلوك توجيه قائم، وتغييرات تتطلّب أن تتكيّف المُنتَجات التابعة.

لا تُغيّر إصلاحات الأخطاء المطبعية، وإصلاحات الروابط، والتنسيق، والتعديلات المقتصرة على التعليقات أو على الوثائق رقمَ الإصدار. ولا يرفعه إلا تغيير سلوكي. ومع ذلك يُحدِّث مثل هذا التعديل تاريخ updated الخاص بالمُنتَج.

أمثلة:

• vX.Y.Z → vX.Y.(Z+1) (PATCH: توجيه مُصحَّح يغيّر السلوك)
• vX.Y.Z → vX.Y.Z (بلا رفع: إصلاح خطأ مطبعي أو رابط؛ يتغيّر updated)
• vX.Y.Z → vX.(Y+1).0 (MINOR: إضافة قسم اختياري جديد)
• v0.Y.Z → v(0+1).0.0 (MAJOR: إعلان استقرار العقد؛ وتبدأ المُنتَجات الجديدة عند v0.Y.Z)
• vX.Y.Z → v(X+1).0.0 (MAJOR: حذف حقل إلزامي من البيانات الأمامية)

ارفع version وupdated معًا في كل تعديل يغيّر السلوك في مُنتَج يحمل هذين الحقلين. وألحِق صفًّا مطابقًا بملف CHANGELOG.md على مستوى المنظومة للإصدارات التي تجمع تغييرات في المُنتَجات.

مراجعات حزمة الخطّةCopy Anchor Link

لا تنطبق القاعدة الخاصة بالقِطَع أعلاه على حزم الخطط. إصدار حزمة الخطّة هو قيمة vX.Y.Z المسجّلة في ترويسة MASTER-PLAN.md وفي جدول سجلّ المراجعات. وتصحيح خطأ مطبعي في حزمة خطّة يُعدّ مراجعة ترفع رقم PATCH. تحدّد الخطوة 10.2 من /plan-review التصنيف، وتُلحِق صفّ سجلّ المراجعات.

• vX.Y.Z → vX.Y.(Z+1) (حزمة خطّة، تصحيح مطبعي: PATCH)
• vX.Y.Z → vX.Y.Z (قِطعة، تصحيح مطبعي: بلا رفع للإصدار؛ قاعدة القِطَع أعلاه)

متى تُعدِّل مُنتَجًاCopy Anchor Link

القواعدCopy Anchor Link

• عامِل بنية الإلزامي/الاختياري على أنها حاملة للحِمل — فإعادة هيكلتها تمتدّ آثارها إلى كل مُنتَج تابع.
• نقّح الأنماط المضادة وأمثلة تدرّج الجدّية والاستشهادات كلّما تعمّق الفهم.
• دوّن مبرّر أيّ تغيير بنيوي في ملف موضوع الذاكرة ذي الصلة.

الأوامرCopy Anchor Link

• شكل الوسائط جزء من العقد العام — لا تكسره إلا بنيّة صريحة، وانشر التغيير إلى كل مستدعٍ (رفع MAJOR).
• أبقِ خطوات سير العمل وعقود الإرجاع مُحكمة وحديثة.
• وثّق تسلسل الخطوات غير البديهي في موضعه.

المساعِداتCopy Anchor Link

• أبقِ disallowedTools في حدّه الأدنى الكافي؛ ووثّق المبرّر عندما يتغيّر.
• نقّح مبادئ التشغيل وعقود الإرجاع كلّما نضج دور المساعِد (رفع MINOR).
• تتبّع تحوّلات القدرات في موضعها كي يتمكّن المستدعون من إعادة ضبط توقّعاتهم.

المهاراتCopy Anchor Link

• أبقِ خطوات الإجراء والأمثلة متزامنة مع الواقع.
• يجب أن تعكس إشارات الكشف صياغة المستخدمين الفعلية في الاستخدام الحالي.
• قسّم المهارة متى تجاوزت ~150 سطرًا (راجع auto-memory.md § Topic File Management).

خطوة بخطوة: إضافة قاعدة جديدةCopy Anchor Link

1. قيّم التعامدCopy Anchor Link

هل تتداخل هذه القاعدة مع قواعد قائمة؟ ابحث في src/apothem/rules/ عن محتوى ذي صلة.

إذا تجاوز التداخل 50%، ففكّر في توسيع قاعدة قائمة بدلًا من ذلك. راجع persistent-conventions-vigilance.md § Artifact Evolution.

2. اكتب المحتوىCopy Anchor Link

اتّبع البنية التالية:

• العنوان: # Rule: {Title}
• قسم الغرض
• الالتزامات / التوجيهات الأساسية (مرقّمة ومزوّدة بروابط)
• جدول تدرّج الجدّية (مطلوب دائمًا)
• قسم الأنماط المضادة
• قسم الإنفاذ

3. أنشئ البيانات الأماميةCopy Anchor Link

استخدم المخطط من site/content/docs/reference/artifact-schema.mdx § Schema: Rules. واضبط:

• name: مُعرِّفًا بصيغة kebab-case
• description: ملخّصًا من سطر واحد للسجلّات
• pathFilter: قائمة glob للقواعد المُرشَّحة بالمسار؛ والسلسلة الفارغة ("") للقواعد الفعّالة دائمًا
• alwaysApply: true للقواعد الفعّالة دائمًا، وfalse للقواعد المُرشَّحة بالمسار

لا تحمل القواعد إلا هذه الحقول الأربعة — بلا version / updated / scope / portability / implements.

القاعدة الجديدة مُرشَّحة بالمسار. وتحتاج القاعدة الجديدة الفعّالة دائمًا إلى رفع القائمة الأساسية وسقوف البايتات في التغيير نفسه: القائمة في tests/unit/test_always_on_core.py والسقوف في conformity/always_on_budget_grep.py. وتأخذ القاعدة المرافقة (<parent>-<aspect>) قيمة pathFilter الخاصة بقاعدتها الأم، أو قيمة أضيق منها.

مثال:

---
name: "my-new-rule"
description: "Brief one-liner"
pathFilter: "**/*.py"
alwaysApply: false
---

4. حدّث ملف README الخاص بالقواعدCopy Anchor Link

أضف صفًّا إلى جدول عائلة القاعدة في قسم «Rule families» من src/apothem/rules/README.md:

| `my-new-rule.md` | One-line concern of the new rule. |

اختر جدول العائلة الذي يتّفق مجال اهتمامه مع القاعدة. وسمِّ القاعدة أيضًا في سطر src/apothem/rules/apothem-rule-index.md الخاص بالموقف الذي يستدعيها؛ إذ يفشل tests/unit/test_always_on_core.py عندما تغيب قاعدة عن الفهرس.

5. ألحِق بملف CHANGELOG.mdCopy Anchor Link

أضف صفًّا تحت قسم ### Added الخاص بالإصدار التالي يصف القاعدة الجديدة.

6. شغّل التحقّقCopy Anchor Link

استدعِ مهارة ecosystem-audit للتحقّق من القاعدة الجديدة، مع التركيز على منطقة القواعد:

Invoke the ecosystem-audit skill with --focus rules --fix

تحقّق من عدم الإبلاغ عن أيّ أخطاء في قاعدتك الجديدة.

خطوة بخطوة: إضافة أمر جديدCopy Anchor Link

الأوامر هي أوامر بشرطة مائلة مثل /plan-spec و/plan-execute و/security-audit وغيرها.

1. حدّد الدورCopy Anchor Link

الأوامر سيرورات عمل يُطلقها المستخدم. ولا يشغّل النموذج أمرًا منها من تلقاء نفسه إلا عندما يكون إعداد disable-model-invocation الخاص به false (الخطوة 2). اسأل:

• هل هذا سير عمل يكتب فيه المستخدم /command-name؟
• هل يُنسِّق خطوات متعدّدة؟
• هل يمكن أن تنتهي مهلته أو أن يتطلّب إدخالًا من المستخدم في منتصف التنفيذ؟

إذا كانت الإجابة «لا» عن أيٍّ من هذه الأسئلة، فهو على الأرجح مهارة لا أمر.

2. أنشئ الملفCopy Anchor Link

المسار: src/apothem/commands/{name}.md

البيانات الأمامية (من site/content/docs/reference/artifact-schema.mdx § Schema: Commands):

---
name: "my-command"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this command does"
argument-hint: "[path/to/input] [--flag VALUE]"
disable-model-invocation: false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

يجعل disable-model-invocation: true الأمرَ لا يُستدعى إلا من المُشغِّل؛ ومع false يجوز للنموذج تشغيله عندما يطابق طلبٌ وصفَه. والقيمة الافتراضية false للأوامر التي للقراءة فقط وللأوامر الاستشارية، مع وصف يبدأ بحالة الاستخدام؛ ويستخدمها 35 أمرًا من أصل 45. ويبقى الأمر true عندما يُغيّر الحالة خارج شجرة العمل أو يعتمد على اختيار المُشغِّل للّحظة المناسبة (10 أوامر). ويسرد جدول الاستدعاء في src/apothem/commands/README.md إعداد كل أمر؛ أضف صفًّا للأمر الجديد. وأبقِ allowed-tools للقراءة فقط: فإطار العمل الذي يلتزم به يُشغِّل تلك الأدوات دون أن يسأل. لا تمنح أداةً ذات آثار جانبية إلا بوصفها قاعدة محدودة النطاق، مثل Bash(git log *)؛ إذ يرفض المخطط "*" وأيًّا من Bash أو PowerShell أو Write أو Edit أو NotebookEdit أو WebFetch إذا كُتب دون نطاق.

3. اكتب المحتوىCopy Anchor Link

البنية:

• العنوان: # /{name} — Human-Readable Title
• قسم الدور (مَن يُنفِّذ هذا)
• تعليمات عالية المستوى
• قسم سير العمل مع الخطوات
• عقد الإرجاع / صيغة المُخرَج

يُقسِّم إصدار المهارات لدى أحد أُطر العمل كل أمر إلى ملف SKILL.md مختصر وملفات references/ بحسب أقسام H2. امنح الأمر قسم ## Workflow واحدًا، وأغلِق كل سياج شيفرة، وصنِّف أي نوع جديد من أقسام H2 في src/apothem/lib/claude_skill_split.py؛ إذ يفشل tests/unit/test_claude_skill_split.py عند وجود نوع غير مُصنَّف. والقواعد موجودة في عقد تقسيم إصدار المهارات (Skill-emission split contract) ضمن src/apothem/commands/README.md.

4. حدّث ملف README وملف CHANGELOG.mdCopy Anchor Link

أضف صفًّا إلى جدول قسم الأمر في src/apothem/commands/README.md، إضافةً إلى صفّ جدول الاستدعاء من الخطوة 2؛ وأضف صفًّا في CHANGELOG تحت قسم ### Added الخاص بالإصدار التالي.

5. تحقّقCopy Anchor Link

استدعِ مهارة ecosystem-audit، مع التركيز على الأوامر:

Invoke the ecosystem-audit skill with --focus commands --fix

خطوة بخطوة: إضافة مساعِد جديدCopy Anchor Link

المساعِدات تعريفات دائمة لعمّال مُفوَّضين للعمل المتوازي.

1. حدّد النمطCopy Anchor Link

هل يندرج هذا المساعِد ضمن أحد أنماط الفرق المُدرَجة أدناه؟

• فريق البحث: للقراءة فقط، وجمع المعلومات
• فريق التدقيق: التحقّق، وفحوص الاتساق
• فريق التنفيذ: تغييرات متوازية في الشيفرة
• فريق الجودة: الفحص الساكن، والاختبار، وفحص الأنواع، والأمان
• فريق التوثيق: تحديثات الوثائق
• أخرى: مهمة متخصّصة

2. أنشئ الملفCopy Anchor Link

المسار:

src/apothem/agents/{name}.md

البيانات الأمامية:

---
name: "my-helper"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this helper specializes in"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit"
maxTurns: 15
portability: "universal"
---

أغفِل model وeffort وpermissionMode كي يرث المساعِد اختيارات الجلسة (الوضعية المحايدة)، وأغفِل memory ما لم يحتج المساعِد إلى نطاق ذاكرة دائمة (user أو project أو local).

3. اكتب المحتوىCopy Anchor Link

الأقسام:

• مبادئ التشغيل (للقراءة فقط، قائمة على الأدلّة، أحكام ثنائية، شاملة)
• سير العمل (خطوات مرقّمة)
• عقد الإرجاع (الحدّ الأقصى للرموز، والبنية، والحقول المطلوبة)

4. حدّث ملف README وملف CHANGELOG.mdCopy Anchor Link

أضف صفًّا إلى جدول الفهرس في src/apothem/agents/README.md؛ وأضف صفًّا في CHANGELOG تحت قسم ### Added الخاص بالإصدار التالي.

5. اختبرCopy Anchor Link

انشر المساعِد في سيناريو حقيقي وتحقّق من أنه يعمل كما هو موثَّق.

خطوة بخطوة: إضافة مهارة جديدةCopy Anchor Link

المهارات تقنيات قابلة لإعادة الاستخدام والكشف.

1. حدّد قابلية إعادة الاستخدامCopy Anchor Link

قبل كتابة مهارة:

• هل صادفت هذه المشكلة/التقنية 3 مرات فأكثر؟
• هل يمكن كشفها؟ (هل يشير إليها نمطٌ في طلبات المستخدم؟)
• هل يمكنك تدوينها بطريقة قابلة لإعادة الإنتاج؟

إذا كانت الإجابة نعم عن الثلاثة جميعًا، فاكتب مهارة.

2. أنشئ البنيةCopy Anchor Link

%%{ init: { "theme": "neutral" } }%%
%% verified: 2026-04-27 %%
%% provenance: site/content/docs/reference/artifact-schema.mdx (skill artifact schema) %%
%% cross-reference: src/apothem/skills/plan-suite/SKILL.md (canonical example) %%
flowchart TD
    accTitle: New skill directory structure
    accDescr: Top-down flowchart of the directory structure for a new skill under src/apothem/skills: a {skill-name} folder holding the required SKILL.md plus optional examples and templates subfolders.
    SKILLS["src/apothem/skills/"]
    SKILLS --> NAME["{skill-name}/"]
    NAME --> SKILLMD["SKILL.md<br/>(main definition · required)"]
    NAME --> EX["examples/<br/>(optional · example workflows)"]
    NAME --> TPL["templates/<br/>(optional · reusable templates)"]

3. اكتب SKILL.mdCopy Anchor Link

البيانات الأمامية:

---
name: "skill-name"
version: "X.Y.Z"
updated: "2026-04-20"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
argument-hint: "[args]"               # optional; if userInvocable
---

بنية المحتوى:

• الغرض
• متى تُستخدم هذه المهارة
• المتطلّبات المسبقة
• الإجراء خطوة بخطوة
• الأخطاء الشائعة
• الأمثلة

4. حدّث ملف README وملف CHANGELOG.mdCopy Anchor Link

أضف صفًّا إلى جدول الفهرس، وصفًّا لكل ملف من ملفات المهارة إلى جدول محتويات المجلّد، في src/apothem/skills/README.md؛ وأضف صفًّا في CHANGELOG تحت قسم ### Added الخاص بالإصدار التالي.

5. تحقّقCopy Anchor Link

استدعِ مهارة ecosystem-audit، مع التركيز على المهارات:

Invoke the ecosystem-audit skill with --focus skills --fix

قائمة فحوص التحقّق قبل إنشاء الكوميتCopy Anchor Link

• تجتاز البيانات الأمامية فحص صيغة YAML
• جميع الحقول الإلزامية موجودة وفق المخطط
• يستخدم الحقل name صيغة kebab-case
• version (للأصناف ذات النسخ فقط؛ فالقواعد لا تحمل نسخة) دلالي (MAJOR.MINOR.PATCH) ورُفِع إن تغيّر السلوك
• updated يطابق تاريخ اليوم لأيّ مُنتَج عدّلته يحمل هذا الحقل
• الحقل portability مضبوط وصالح (إلزامي في الأوامر، واختياري في المساعِدات)
• يحمل CHANGELOG.md التغيير في الفئة المناسبة تحت قسم الإصدار التالي
• لا إحالات داخلية خاصة بالخطط (امتثالًا لـ CM-7)
• الإحالات المتبادلة متّسقة مع المُنتَجات الأخرى
• المُنتَج الجديد مُسجَّل في فهرس README الخاص بمجلّده
• المُنتَج مُختبَر (إن انطبق ذلك)
• تعمل مهارة ecosystem-audit دون أخطاء
• يتّبع المحتوى الاصطلاحات البنيوية (صيغة العنوان، والأقسام، وما إلى ذلك)

الإحالة إلى مُنتَجات أخرىCopy Anchor Link

استخدم هذه الاصطلاحات بدقّة:

الإحالة إلى قاعدةCopy Anchor Link

See `src/apothem/rules/operational-mandates.md` or shorthand: the Operational Mandates rule.
In prose: ... per CM-1–10 (Operational Mandates rule) ...

الإحالة إلى أمرCopy Anchor Link

See `/plan-execute` command. Or: Run `/plan-execute`.
In prose: The `/plan-execute` command handles phase execution.

الإحالة إلى مساعِدCopy Anchor Link

Deploy the `codebase-explorer` delegated worker.
In prose: The codebase-explorer worker finds patterns.

الإحالة إلى مهارةCopy Anchor Link

Use the `plan-suite` skill.
In prose: The plan-suite skill provides the Master Plan Suite template.

الإحالة إلى أقسام CLAUDE.mdCopy Anchor Link

See CLAUDE.md § Harness Adapter Pattern.
Or: § Plans Discipline.

الفحص الساكن والتنسيقCopy Anchor Link

تستخدم جميع المُنتَجات:

• Markdown: GFM (GitHub Flavored Markdown)
• YAML: متوافق مع YAML 1.2
• نهايات الأسطر: LF (نمط Unix)
• الترميز: UTF-8
• عرض السطر: التفاف مرن عند 100 حرف للمحتوى (دون فواصل أسطر ثابتة)

استخدم المُنسِّق / المدقّق Ruff لملفات Python. ولملفات Markdown، استخدم prettier أو ما يعادله.

الاختبار والقياسCopy Anchor Link

تشغيل مجموعة الاختباراتCopy Anchor Link

python -m pytest                      # unit, integration, property, conformity, scripts
python -m pytest tests/property       # Hypothesis properties (profile loader, frontmatter, merge)

مجموعة الاختبارات محكمة العزل: تنجح والنسخة المسحوبة تحت $TMPDIR، ومع python على PATH يفتقر إلى المتطلّبات المسبقة لواجهة سطر الأوامر، لأن اختبارات التكامل تُشغِّل المُفسِّر نفسه الذي يُشغِّل pytest، وتستبدل برموزٍ مساراتِ المجلّدات المؤقّتة والمصدر المتداخلة بدءًا بالأطول.

التغطية لكل حزمةCopy Anchor Link

يقيس CI ثلاث حزم ويُلزِم كلًّا منها بحدّها الأدنى الخاص. ولا تُدمَج أيٌّ منها في أخرى.

الرقم هو تغطية الأسطر مع الفروع، وهو النسبة المئوية نفسها التي يُبلغ عنها coverage.py مع branch = true؛ ويسجّل مُنتَج المقاييس أيضًا رقم التغطية المقتصر على العبارات تحت coverage_lines. والحدّ الأدنى لكل حزمة هو القيمة المقيسة لتغطية الأسطر مع الفروع مُقرَّبةً إلى الأدنى. ارفع الحدّ الأدنى عندما ترتفع التغطية؛ ولا تخفضه أبدًا لتمرير تغيير. للتحقّق محليًا:

python -m pytest --cov=src/apothem --cov-report=json:coverage.json
python scripts/dev/collect_metrics.py --coverage-json coverage.json --check-floors \
  --skip-hooks --skip-coldstart --harness zed

مُنتَج المقاييسCopy Anchor Link

تُشغِّل مهمة metrics في CI النص البرمجي scripts/dev/collect_metrics.py عند كل دفع وكل طلب سحب، وترفع metrics.json (schema_version: 1). وكل قيمة تساوي null تحمل سببها تحت nulls.

تحديد الملفات التي تُعدّ مُحمَّلةً عند الإقلاع قاعدةٌ خاصة بكل إطار عمل، مأخوذة من أسطح التعليمات الموثَّقة لدى كل مورّد. ولا تُحتسَب القوائم التي لا تحمل سوى وصف (المهارات، والأوامر، والعوامل الفرعية). ويُكتَب نصّ القاعدة أيضًا في المُنتَج تحت rules.always_on_bytes:

antigravity     ~/.gemini/{GEMINI,AGENTS}.md, ~/.gemini/config/{GEMINI,AGENTS}.md,
                ~/.gemini/config/rules/*.md with trigger: always_on, project
                GEMINI.md and AGENTS.md. The plugin rules/ folder is not a
                documented launch surface.
claude-code     ~/.claude/CLAUDE.md and ~/.claude/rules/**/*.md without paths:
                frontmatter, plus the project equivalents.
codebuddy       .codebuddy/rules/**/*.md (project and home) unless
                alwaysApply: false, plus CODEBUDDY.md.
codex           ~/.codex/AGENTS.md and the project AGENTS.md.
cursor          .cursor/rules/**/*.mdc with alwaysApply: true, and AGENTS.md.
gemini-cli      ~/.gemini/GEMINI.md and the project GEMINI.md.
github-copilot  .github/copilot-instructions.md and the project AGENTS.md.
hermes          ~/.hermes/SOUL.md, project .hermes.md, AGENTS.md, CLAUDE.md.
                The support tree and apothem/rules/ are not launch surfaces.
kimi-code       ~/.kimi-code/AGENTS.md, project AGENTS.md and .kimi-code/AGENTS.md.
kiro            .kiro/steering/**/*.md with inclusion: always or no inclusion
                key, and the project AGENTS.md.
open-claw       Workspace bootstrap files ~/.openclaw/workspace/*.md.
opencode        ~/.config/opencode/AGENTS.md, the project AGENTS.md, and every
                file the instructions globs in opencode.json match.
qwen-code       The context files named by context.fileName in
                ~/.qwen/settings.json (default QWEN.md), in ~/.qwen/ and the project.
trae            .trae/rules/**/*.md with alwaysApply: true, and
                ~/.trae/user_rules/*.md.
windsurf        .devin/rules/**/*.md and .windsurf/rules/**/*.md with
                trigger: always_on, the global global_rules.md, and AGENTS.md.
zed             The first of .rules, .cursorrules, .windsurfrules, .clinerules,
                .github/copilot-instructions.md, AGENT.md, AGENTS.md, CLAUDE.md,
                GEMINI.md in the project, plus ~/.config/zed/AGENTS.md.
glm             Nothing: GLM is a model backend and loads no instruction files.

التقييمات السلوكيةCopy Anchor Link

تقيس المجموعة الموجودة تحت evals/ السلوكَ لا الشكل: 148 حالة إطلاق (كل أمر وكل مهارة وكل عامل فرعي يمكن للنموذج استدعاؤه ينطلق عند طلب يقع في مجاله، ويبقى صامتًا عند طلب قريب منه لا يخصّه، وستة أوامر لا يستدعيها إلا المستخدم لا تبدأ من تلقاء نفسها)، و32 حالة نتيجة (حالة واحدة لكل مرحلة تخطيط، ومرحلة بحث، وبُعد تدقيق)، و6 أزواج لأثر القواعد (نصّ قاعدة من عيّنة مختارة مُفعَّلًا ومُعطَّلًا). الحالات بيانات بسيطة يُتحقَّق منها مجانًا عبر python -m pytest tests/unit/test_eval_suite.py؛ أمّا تشغيلها فمدفوع التكلفة ويدوي. راجع تشغيل التقييمات السلوكية للاطّلاع على سير عمل Evals، والتشغيل المحلي، وكيفية إضافة حالة. وبعد تعديل قاعدة لها زوج، شغِّل python scripts/dev/sync_eval_rule_cases.py.

اختبارات الأداء المرجعيةCopy Anchor Link

يُشغِّل make benchmarks برامج التشغيل الخاصة بكل صنف تحت src/apothem/benchmarks/، باستثناء bench_agents.py. ويخرج كلٌّ من برامج التشغيل بالرمز 0 عند النجاح، أو 1 عند تجاوز الميزانية، أو 2 عند الخطأ (لم يُنفَّذ التشغيل المقيس)، أو 3 عند عدم القياس.

• يُشغِّل bench_hooks.py كل أمر shell: bash يسجّله hooks/hooks.json، كما هو مكتوب، على حمولة حقيقية لكل حدث ومُطابِق، ويُبلغ عن الزمن الإجمالي الوسيط، وأبطأ أمر (مُقارَنًا بميزانية الحدث)، وعدد الأحرف المحقونة. والأمر الذي لا يمكن تشغيله كما سُجِّل (رمز الخروج 126 عندما يفتقر نص برمجي إلى بتّ التنفيذ) يُعدّ خطأً، لا نجاحًا.
• يُبلغ bench_agents.py عن NOT MEASURED (رمز الخروج 3): فإطلاق عامل فرعي يحتاج إلى إطار عمل مضيف واستدعاء للنموذج. ولا يُشغِّله make benchmarks.

يَعُدّ فحص ميزانية القواعد الفعّالة دائمًا (always-on-budget-grep) الكلماتِ المفصولة بمسافات بيضاء، مع استبعاد قسم Bindings وأسطر الإشارة المرافقة. ويحمل تقريره بصيغة JSON أيضًا always-on-loaded: البايتات والأحرف والكلمات في المتون المجرّدة من البيانات الأمامية التي يُحمِّلها إطار العمل، مجموعةً على القواعد الفعّالة دائمًا. وعند توجيه الفحص إلى مجلد القواعد المشحونة، يفشل أيضًا عندما يتجاوز ذلك المجموع سقفًا للبايتات (يُبلَّغ عنه بوصفه always-on-ceiling-bytes) أو يتجاوز فهرس القواعد سقفه الخاص. ويُحمِّل Claude Code نسخه من القواعد دون قسم Bindings، لذا يكون حجمها المُحمَّل أصغر من الرقم الذي يُبلغ عنه هذا الفحص.

تدقيق المنظومة: تشغيل التحقّقCopy Anchor Link

يغطّي المنظومةَ سطحا تحقّق متكاملان:

قابل للفحص آليًا (مدقّقات Python) — شغِّلها قبل كل كوميت:

python scripts/dev/validate_hooks.py       # Hook structure + Python-only hygiene
python scripts/dev/validate_ecosystem.py   # Full tree + frontmatter + delegated hook checks
python scripts/dev/chaos_pass.py           # Adversarial sweep across configured hooks
pytest tests                                    # Unit tests for the hook runtime

يقوده المساعد البرمجي — لتدقيقات الإحالات المتبادلة والسرد والاصطلاحات:

/ecosystem-audit --focus all --fix

يُشغِّل هذا بالتوازي:

• تدقيق البنية: دقّة السجلّ، ووجود الملفات، وصلاحية البيانات الأمامية
• تدقيق المُنتَجات: الإحالات المتبادلة، وتغطية التفويضات، وترتيب خطّ الأنابيب
• تدقيق الذاكرة: ادّعاءات ملفات الذاكرة مقابل حالة نظام الملفات

المُخرَج المتوقّع: PASS مع صفر نتائج من كلا السطحين.

إذا أُبلِغ عن FINDINGS:

• راجع شدّة كل نتيجة (حرجة / مهمّة / استشارية)
• عالِج البنود الحرجة فورًا
• خطِّط للبنود المهمّة في الدورة التالية
• انظر في البنود الاستشارية في التكرار التالي

أسئلة؟Copy Anchor Link

ارجع إلى:

• مخطط البيانات الأمامية: site/content/docs/reference/artifact-schema.mdx
• دورة حياة المُنتَج: src/apothem/rules/persistent-conventions-vigilance.md § Artifact Evolution
• التفويضات التشغيلية: src/apothem/rules/operational-mandates.md CM-1–10
• مرجع حزمة الخطة: src/apothem/skills/plan-suite/master-template.md
• ملاحظات الإصدار: CHANGELOG.md