مواصفة مخطط المُنتَجات

قوالب البيانات الأمامية بصيغة YAML لكل صنف والحقول المطلوبة لكل مُنتَجات منظومة Apothem.

مصدر الحقيقة. العقد المقروء آليًا الذي تفرضه البوابة هو مخططات JSON Schema لكل صنف تحت src/apothem/schemas/ (agent.schema.json، وcommand.schema.json، وskill.schema.json، …). ويُعلِن مخطّطا المهارات والأوامر additionalProperties: false، فيرفضان المفاتيح غير المعروفة؛ أما مخططات العوامل ونمط الإخراج والخطة فتُعلِن additionalProperties: true. هذه الصفحة وfrontmatter-schema.mdx هما الإسقاطان المقروءان للبشر لتلك المخططات — تحمل هذه الصفحة القوالب والأمثلة المحلولة لكل صنف، ويحمل frontmatter-schema فهرس المفاتيح المطلوبة المُوجَز. وحيثما تخالف صفحةٌ مخططاتِ JSON Schema، تكون الغلبة للمخططات.

نظرة عامةCopy Anchor Link

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

القواعد العامة:

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

اصطلاح ترقيم النسخ (أصناف المُنتَجات ذات النسخ — الأوامر، والمساعِدات، والمهارات، وCLAUDE.md):

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

المخطط: القواعدCopy Anchor Link

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

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

الحقول الإلزاميةCopy Anchor Link

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

الحقول الاختياريةCopy Anchor Link

لا تحمل القواعد أيّ حقول اختيارية في البيانات الأمامية، ولا تحمل كذلك — خلافًا لأصناف المُنتَجات الأخرى — حقول version / updated / scope / portability. الحقول الإلزامية الأربعة أعلاه هي عقد البيانات الأمامية الكامل للقاعدة الذي يفرضه frontmatter_grep.

المثالCopy Anchor Link

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

# Rule: Operational Mandates
...

المخطط: الأوامرCopy Anchor Link

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

الغرض: تعريفات أوامر الشرطة المائلة (/plan-execute، و/freshify، وغيرها).

الحقول الإلزاميةCopy Anchor Link

---
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: "Read, Glob, Grep"
---

الحقول الاختياريةCopy Anchor Link

لا تحمل الأوامر أيّ حقول اختيارية في البيانات الأمامية — الحقول الإلزامية الثمانية أعلاه هي عقد البيانات الأمامية الكامل للأمر الذي يفرضه command.schema.json (additionalProperties: false).

المثالCopy Anchor Link

---
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: "Read, Glob, Grep"
---

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

المخطط: المساعِداتCopy Anchor Link

نمط المسار:

src/apothem/agents/*.md

الغرض: تعريفات دائمة للمساعِدات (وتُسمّى أيضًا العاملين المُفوَّض إليهم) من أجل الاستكشاف المتوازي، والتدقيق، وبوابات الجودة.

الحقول الإلزاميةCopy Anchor Link

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

الحقول الاختياريةCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

المثالCopy Anchor Link

---
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"
portability: "universal"
---

You are a codebase exploration specialist...

المخطط: المهاراتCopy Anchor Link

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

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

الحقول الإلزاميةCopy Anchor Link

---
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, Glob, Grep"
---

الحقول الاختياريةCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

المثالCopy Anchor Link

---
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: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

المخطط: الخطّافاتCopy Anchor Link

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

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

مخطط ملف الإعداداتCopy Anchor Link

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

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

الصيغة -m apothem.hooks.dispatch مخصّصة للتطوير من نسخة مسحوبة من المصدر مع PYTHONPATH=src.

الأحداث المطلوبةCopy Anchor Link

يُسجِّل قالب Claude Code أربعة أحداث: SessionStart وPreToolUse وPostToolUse وStop. ويتحقّق scripts/dev/validate_hooks.py في settings.json من وجود الأحداث الخمسة الواردة في الجدول أدناه، وهي مجموعة مختلفة، ويُبلغ عن كل حدث لا يجده بوصفه تحذيرًا لا إخفاقًا. وPostToolUse مُسجَّل لكنه ليس من الأحداث الخمسة. أما PreCompact وPostCompact فمن الأحداث الخمسة لكنهما غير مُسجَّلين في Claude Code (مرجع الخطّافات)، ولذلك تُصدر أداة الفحص تحذيرًا بشأن كليهما هناك.

تعكس قيم المهلة ميزانيات أحداث الخطّافات المرجعية — يُعيد الجدول أدناه إيرادها تيسيرًا على القارئ؛ والمصدر المرجعي هو الحاكم.

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

طبقة PythonCopy Anchor Link

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

التحقّقCopy Anchor Link

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

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

المخطط: CLAUDE.mdCopy Anchor Link

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

الغرض: تعليمات Claude Code بنطاق المشروع.

البيانات الأمامية الإلزامية بصيغة YAMLCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

الأقسامCopy Anchor Link

يُؤلَّف CLAUDE.md في أقسام نثرية، موصوفة في CLAUDE.md. لا يشترط أي مدقّق قائمة أقسام ثابتة: يفحص scripts/dev/validate_ecosystem.py مفاتيح البيانات الأمامية أعلاه.

قائمة فحص التحقّقCopy Anchor Link

يجب أن يستوفي كل مُنتَج هذه الفحوص:

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

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

التحقّق من المحتوىCopy Anchor Link

• يبدأ المحتوى في سطر جديد بعد --- الختامي؛ وفي ملفات عائلة Markdown يكون سطر ترويسة SPDX المرجعي هو أول محتوى بعده
• لا إشارات داخلية للخطط (امتثالًا لـ CM-7)
• تُحَلّ الإحالات المتقاطعة (إن كان المُنتَج يسرد مُنتَجات أخرى)
• تستخدم الروابط مسارات نسبية بشرطات مائلة أمامية

التحقّق من قابلية النقلCopy Anchor Link

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

ملاحظاتCopy Anchor Link

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