# نظرة عامة على المشروع

## ما هو OSpec

حزمة CLI الرسمية لـ OSpec هي `@clawplays/ospec-cli`، والأمر الرسمي هو `ospec`. يدعم OSpec أسلوب التطوير المعتمد على المواصفات (SDD) والتطوير المعتمد على الوثائق لوكلاء البرمجة بالذكاء الاصطناعي وتدفقات العمل المعتمدة على CLI.

يعامل الوثائق كمصدر وحيد للحقيقة للمتطلبات والتغييرات. تقوم التهيئة بإعداد قواعد التعاون ومعرفة المشروع الأساسية أولاً، ثم تسمح للذكاء الاصطناعي بدفع التنفيذ من خلال حاويات تغيير صريحة.

## المبادئ الأساسية

- يجب أن يترك `ospec init` المستودع في حالة جاهزة للتغيير (change-ready).
- يمكن للتهيئة المدعومة بالذكاء الاصطناعي طلب متابعة موجزة واحدة لملخص المشروع أو مكدس التقنيات عند فقدان سياق المستودع.
- تبقى التهيئة البسيطة عبر واجهة سطر الأوامر غير تفاعلية وترجع إلى وثائق المشروع المؤقتة عند عدم توفر السياق.
- `ospec docs generate` هو أمر صيانة لاحق لتحديث أو إصلاح أو ملء وثائق معرفة المشروع.
- التغيير الأول لا يزال صريحاً. التهيئة لا تنشئ عمل تنفيذ تلقائياً.
- المسار الموصى به للمستخدم هو `init -> execute -> deploy/validate -> archive`.
- يظل تنفيذ الطابور أمرا صريحا. استخدمه فقط عندما يريد المستخدم فعلا تنسيق عدة تغييرات.

## حالات الاستخدام النموذجية

- المستودعات التي تريد سلوكاً متسقاً للذكاء الاصطناعي
- الفرق التي تريد أن يكون تنفيذ التغيير مرئياً وقابلاً للمراجعة
- المشاريع التي قد تصبح مستودعات ويب أو واجهة سطر أوامر أو Unity أو Godot أو خلفية أو بروتوكول فقط
- البيئات التي تحتاج إلى نفس سير العمل عبر Codex و Claude Code

## كيف يقارن OSpec

مقارنة مع [Spec Kit](https://github.github.com/spec-kit/) — يركز Spec Kit على المواصفات القابلة للتنفيذ ومراحل التخطيط الأعمق والتنقيح متعدد الخطوات. أما OSpec فيحافظ على حاوية change أنحف ومسار افتراضي أقصر حتى التسليم والأرشفة.

مقارنة مع [Kiro](https://kiro.dev/docs/specs/) — يجمع Kiro بين specs و steering و hooks و MCP و powers داخل منصة أوسع. يركز OSpec على طبقة workflow أصلية للمستودع وتبقى قابلة للنقل عبر المساعدات التي تستخدمها بالفعل.

## القدرات الحالية

- تهيئة جاهزة للتغيير
- صيانة معرفة المشروع
- إدارة سير عمل التغيير النشط
- مسار إغلاق قياسي `finalize -> archive -> commit-ready`
- حالة تغيير مجمعة `PASS / WARN / FAIL`
- فرض خطافات Git للتغييرات النشطة
- تثبيت ومزامنة مهارات Codex و Claude Code

## نموذج الأوامر

لدليل جديد، الترتيب المعتاد هو:

```bash
ospec init [path]
ospec new <change-name> [path]
ospec verify [changes/active/<change>]
ospec finalize [changes/active/<change>]
```

عندما تحتاج فقط إلى صيانة الوثائق لاحقاً، استخدم:

```bash
ospec docs generate [path]
```

استخدم `ospec status [path]` بشكل منفصل عندما تريد لقطة استكشاف أعطال بدلاً من مسار التسليم الافتراضي.