مواصفة مخطّط الأداة (Artifact Schema)

فرونت-ماتر YAML كنسي وحقول مطلوبة لكل أدوات منظومة Apothem.

نظرة عامة

يجب أن تتضمّن كل الأدوات في شجرة مصدر Apothem (تحت src/apothem/ وسطح الإعداد الجذري) كتلة فرونت-ماتر YAML (بين فاصلَي ---) بحقول إلزامية واختيارية خاصّة بنوع الأداة. يعرّف هذا المستند المخطّط الكنسي لكل نوع.

قواعد كونية:

• الفرونت-ماتر متوافق مع YAML 1.2
• كل القيم النصّية تستخدم علامات اقتباس مزدوجة ما لم تكن فارغة
• ترتيب الحقول: الحقول الإلزامية أولًا، والحقول الاختيارية مجمَّعة حسب الصلة
• التعليقات في الفرونت-ماتر تستخدم # مع مسافة: # comment
• قيم المسارات يجب أن تكون نسبية (بلا / في البداية) وتستخدم الشرطة المائلة الأمامية (/) من أجل التوافق عبر المنصّات

اصطلاح ترقيم الإصدارات (كوني عبر أنواع الأدوات):

• version دلالي (MAJOR.MINOR.PATCH). ارفع MAJOR لتغييرات المخطّط أو العقد الكاسرة؛ وMINOR للتغييرات الإضافية غير الكاسرة (حقول اختيارية جديدة، أقسام إضافية، أنماط مضادّة إضافية)؛ وPATCH للتوضيحات أو إصلاحات التنسيق أو التحريرات الخاصّة بالوثائق فقط دون تغيير في السلوك.
• updated هو تاريخ ISO 8601 (YYYY-MM-DD) لأحدث تحرير. يجب أن يتغيّر مع كل رفع لِـ version ويمكن تحديثه باستقلال من أجل تحديثات الروابط دون رفع للإصدار.
• تُبذَر الأدوات الجديدة عند v0.Y.Z. الترقية إلى vX.Y.Z تشير إلى أن عقد الأداة مستقرّ بما يكفي ليكون التزامًا عموميًّا.

المخطّط: القواعد

نمط المسار: src/apothem/rules/*.md

الغرض: تفويضات سلوكية وتوجيهات تشغيلية.

الحقول الإلزامية

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

الحقول الاختيارية (إن انطبقت)

Rules carry no optional frontmatter fields, and — unlike other artifact classes — no version / updated / scope / portability fields either. The four mandatory fields above are the complete rule frontmatter contract enforced by frontmatter_grep.

المثال

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

المخطّط: الأوامر

نمط المسار: src/apothem/commands/*.md

الغرض: تعريفات أوامر السلاش (/plan-execute، /freshify، إلخ).

الحقول الإلزامية

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "*"
---

الحقول الاختيارية

Commands carry no optional frontmatter fields — the eight mandatory fields above are the complete command frontmatter contract enforced by command.schema.json (additionalProperties: false).

المثال

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "*"
---

# /plan-execute — Execute a Specific Phase
...

المخطّط: العاملون المساعِدون

نمط المسار:

src/apothem/agents/*.md

الغرض: تعريفات العاملين المساعِدين الدائمة من أجل الاستكشاف المتوازي والتدقيق وبوّابات الجودة.

الحقول الإلزامية

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

الحقول الاختيارية

permissionMode: "default"       # Permission handling
memory: true | false                    # If true, agent retains memory across sessions
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

المثال

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
memory: false
portability: "universal"
---

You are a codebase exploration specialist...

المخطّط: المهارات

نمط المسار: src/apothem/skills/*/SKILL.md

الغرض: تعريفات تقنيات قابلة لإعادة الاستخدام مع إشارات اكتشاف وإجراءات تنفيذ.

الحقول الإلزامية

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Write, Glob"
---

الحقول الاختيارية

argument-hint: "[args...]"                           # Usage pattern if userInvocable
effort: "low" | "medium" | "high" | "xhigh" | "max" # Optional effort level

المثال

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: true
allowed-tools: "Read, Write, Edit, Glob, Grep, Bash"
argument-hint: "[--focus area] [--fix]"
effort: "max"
---

## Purpose
...

المخطّط: الخطّافات

نمط المسار: كتلة hooks في settings.json إضافةً إلى تطبيقات Python تحت src/apothem/hooks/.

الغرض: إعلان مدقّقات مُشغَّلة بالأحداث ومعالِجات إدارة-الحالة التي يستدعيها المضيف عند نقاط دورة-حياة محدّدة جيّدًا.

مخطّط ملف الإعدادات

يربط المفتاح ذو المستوى الأعلى hooks أسماء الأحداث بمصفوفات من كتل المطابِق:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "python",
          "args": ["-m", "apothem.hooks.dispatch", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

الأحداث المطلوبة

تسجّل القوالب المُسلَّمة الأحداث التالية. الخمسة جميعها مطلوبة لكي تبلّغ المدقّقات عن PASS:

قيم المهلة تعكس الكتلة الكنسية في CLAUDE.md §٧.٤ — الجدول أدناه يعيد إنتاجها لراحة القارئ؛ والعمود الكنسي هو الحاكم.

يقبل dispatch.py أيضًا UserPromptSubmit وNotification في قائمته البيضاء للأحداث من أجل التوافق المستقبلي؛ وليس أيّ منهما موصولًا في القوالب المُسلَّمة. أضِف كتلة مطابِق بنفس نمط صيغة-exec للتفعيل.

طبقة Python

تمرّ كل أوامر الخطّافات عبر موزِّع Python نفسه:

التحقّق

يفرض scripts/dev/validate_hooks.py عقد الخطّافات:

• يُحلَّل settings.json كـ JSON ويعلن كل حدث مطلوب.
• توجد سكربتات Python الثلاثة جميعها وتُحلَّل كـ Python صحيح.
• توجد كل ملفات الرسائل التي تشير إليها وسائط --context-file.
• لا تظهر مسارات مستخدِم مطلقة مُضمَّنة (C:\Users\... إلخ) في src/apothem/hooks/**.py.
• تقتصر أدوات الصدفة (shell) تحت src/apothem/hooks/ وscripts/ على كعوب المحدِّد / الإقلاع المعتمدة.

المخطّط: CLAUDE.md

المسار: CLAUDE.md (الجذر)

الغرض: فهرس الإعداد العمومي للمنظومة.

الفرونت-ماتر YAML الإلزامي

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Global Claude Code ecosystem configuration and mandate index"
scope: "always-on"
portability: "universal"
---

الأقسام المطلوبة (بالترتيب)

١. §١ حزمة الخطّة — إشارة إلى موقع القالب ٢. §٢ الهوية الإدراكية — تفويض المعمارية الإبداعية ٣. §٣ أدلّة الأدوات — جدول المسارات والأغراض ٤. §٤ الحوكمة المتدرّجة-بالجدّية — تعريف المستويات الأربعة ٥. §٥ التوجيهات التشغيلية — مبادئ حلّ-المشكلات والتواصل ٦. §٦ التفويضات الشاملة — نظرة عامة على CM-1–28 ٧. §٧ السجلّات — جداول الأدوات:

• ٧.١ الأوامر
• ٧.٢ القواعد
• ٧.٣ العاملون المساعِدون
• ٧.٤ الخطّافات
• ٧.٥ المهارات
• ٧.٦ تطوّر الأدوات

قائمة تحقّق التحقيق

يجب أن تستوفي كل أداة هذه الفحوص:

تحقّق الفرونت-ماتر

• الـ YAML صحيح نحويًّا (بلا أخطاء تحليل)
• كل الحقول الإلزامية حاضرة لنوع الأداة
• يتّبع name اصطلاح kebab-case
• version دلالي (MAJOR.MINOR.PATCH)
• updated بصيغة تاريخ ISO 8601 (YYYY-MM-DD)
• description سلسلة غير فارغة من سطر واحد
• الحقول الاختيارية تطابق قيم enum المتوقّعة (إن انطبق)
• لا أخطاء إملائية في أسماء الحقول (استخدم الأسماء الكنسية من المخطّط)
• لا مسافات بيضاء زائدة ولا مشكلات تنسيق

تحقّق المحتوى

• يبدأ المحتوى مباشرةً بعد --- الإغلاق على سطر جديد
• لا إشارات داخلية-للخطّة (امتثال CM-7)
• تُحَلّ الإشارات المتقاطعة (إن عُدِّدت أدوات أخرى)
• تستخدم الروابط مسارات نسبية بشرطات مائلة أمامية

تحقّق قابلية النقل

• لا مسارات مطلقة مُضمَّنة (استخدم النسبية)
• لا صياغة خاصّة بـ Windows في الأدوات ذات النطاق universal
• تستخدم فواصل المسارات الشرطات المائلة الأمامية
• تستخدم متغيّرات البيئة صيغة محايدة-للمنصّة (${VAR} أو الأصيلة-للأداة)

ملاحظات

• الاتساق كأمن: يمكّن الفرونت-ماتر الكنسي من التحقّق الآلي والأدوات والتحقيق عبر-الأدوات. تتراكم الانحرافات بسرعة.
• إعلان قابلية النقل: ليست كل الأدوات قادرة على أن تكون universal. أعلِن القيود صراحةً — توثيق تنبيه أفضل من شحن خلل صامت.
• kebab-case للأسماء: سهل الاستخدام في الروابط والسكربتات وسياقات سطر-الأوامر. تجنّب المسافات والشرطات السفلية وcamelCase في الأسماء.
• نظافة رفع الإصدار: كل تحرير يغيّر السلوك يجب أن يرفع version وupdated معًا. إصلاحات التنسيق أو الأخطاء الإملائية الصِّرفة ترفع PATCH؛ والأقسام الاختيارية أو الأنماط المضادّة الجديدة ترفع MINOR؛ وإعادة التنظيم الهيكلية أو تغييرات العقد ترفع MAJOR.