المفاهيم

يشرح هذا الدليل الأفكار الأساسية وراء OpenSpec وكيف تتناسب معًا. للاستخدام العملي، انظر البدء وسير العمل.

فلسفة التصميم

بُني OpenSpec حول أربعة مبادئ:

fluid not rigid         — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex        — lightweight setup, minimal ceremony
brownfield-first        — works with existing codebases, not just greenfield

لماذا هذه المبادئ مهمة

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

تكراري وليس شلالي. المتطلبات تتغير. يتعمق الفهم. ما بدا كأفضل مسار في البداية قد لا يثبت بعد رؤية قاعدة الكود. OpenSpec يحتضن هذه الحقيقة.

سهل وليس معقدًا. تتطلب بعض أطر المواصفات إعدادًا مكثفًا، أو صيغًا صارمة، أو عمليات مكثفة. OpenSpec يبقى خارج طريقك. قم بالتهيئة في ثوانٍ، ابدأ العمل فورًا، والتخصيص فقط عند الحاجة.

الأولوية للمشاريع الحالية (Brownfield-first). معظم أعمال البرمجيات ليست بناءً من الصفر — بل تعديل أنظمة موجودة. يجعل نهج OpenSpec القائم على الدلتا (التغييرات) من السهل تحديد التغييرات على السلوك الحالي، وليس فقط وصف أنظمة جديدة.

الصورة الكبيرة

ينظم OpenSpec عملك في مجالين رئيسيين:

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  مصدر الحقيقة       │◄─────│  التعديلات المقترحة           │   │
│   │  كيف يعمل نظامك     │ دمج   │  كل تغيير = مجلد واحد        │   │
│   │  حاليًا             │      │  يحتوي على عناصر + deltas     │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

المواصفات (Specs) هي مصدر الحقيقة — تصف كيفية سلوك نظامك حاليًا.

التغييرات (Changes) هي تعديلات مقترحة — توجد في مجلدات منفصلة حتى تكون جاهزًا لدمجها.

هذا الفصل أمر أساسي. يمكنك العمل على عدة تغييرات بالتوازي دون تعارضات. يمكنك مراجعة التغيير قبل أن يؤثر على المواصفات الرئيسية. وعندما تُؤرشف التغيير، تندمج deltas بسلاسة في مصدر الحقيقة.

مساحات عمل التنسيق

دعم مساحات العمل في مرحلة بيتا. نموذج العرض المحلي أدناه هو الاتجاه الحالي، لكن الأتمتة الخارجية، والتكامل، وسير العمل طويل الأمد يجب أن تستمر في التعامل مع سلوك الأوامر، وملفات الحالة، وناتج JSON باعتبارها في طور التطور.

توفر الأوامر أدناه تدفق الإعداد الأولي لفتح عروض محلية عبر مستودعات أو مجلدات مرتبطة.

مشاريع OpenSpec المحلية في المستودع هي الخيار الافتراضي الصحيح عندما يمتلك مستودع واحد تدفق التخطيط والتنفيذ والأرشفة. يمتد بعض العمل عبر عدة مستودعات أو مجلدات. لهذه الحالة، مساحة عمل تنسيق OpenSpec هي عرض محلي على الآجة تُبقي المسارات المرتبطة، وحالة الفاتح، وإعداد الوكيل معًا.

النموذج الذهبي لمساحة العمل هو:

workspace     = عرض محلي خاص عبر مستودعات السياق، والمبادرات، والمستودعات، والمجلدات
context store = حاوية سياق مشتركة ودائمة
initiative    = سياق تنسيق دائم داخل مستودع سياق
link          = اسم مستقر لمستودع أو مجلد تستطيع مساحة العمل حله محليًا
change        = قطعة مخططة واحدة من العمل؛ التنفيذ ينتمي إلى المستودع المالك

مساحة العمل لها شكل مختلف عن المشروع المحلي في المستودع:

getGlobalDataDir()/workspaces/<workspace-name>/
├── workspace.yaml                 # سجل العرض المحلي الخاص
├── AGENTS.md                      # إرشادات التشغيل المولدة
└── <workspace-name>.code-workspace # ملف مساحة عمل المحرر المولّد

حالة OpenSpec المحلية في المستودع تحتفظ بالشكل الحالي:

repo-root/
└── openspec/
    ├── specs/
    └── changes/

هذا التمييز مهم. مجلد مساحة العمل هو سطح تنسيق محلي لفتح وفحص المستودعات أو المجلدات المرتبطة. يظل دليل openspec/ لكل مستودع هو الموطن للمواصفات التي يمتلكها المستودع، والتغييرات المحلية للمستودع، وتخطيط التنفيذ. لا يحتاج المستخدمون إلى تشغيل openspec init المحلي للمستودع داخل مجلد مساحة العمل.

أسماء الروابط المستقرة هي الطريقة التي تشير بها مساحة العمل إلى المستودعات والمجلدات. يحتفظ سجل مساحة العمل الخاص بأسماء مثل api أو web أو checkout ويعيدها إلى مسارات محلية في وقت التشغيل هذا.

# workspace.yaml
version: 1
name: platform
context: null
links:
  api: /repos/api
  web: /repos/web

عندما تفتح مساحة العمل مبادرة، يسجل context ربط مستودع السياق المحدد ومعرف المبادرة. تبقى المستودعات المحددة من السجل محمولة حسب المعرف؛ بينما تحافظ المستودعات المحددة بالمسار على مسار وقت التشغيل المحلي عمدًا لأن workspace.yaml هو حالة محلية خاصة.

context:
  kind: initiative
  store:
    id: platform
    selector:
      kind: registry
      id: platform
  initiative:
    id: billing-launch

يمكن أن تكون المسارات المرتبطة مستودعات كاملة، أو مجلدات داخل مستودع ضخم (monorepo)، أو مجلدات أخرى موجودة. لا تحتاج إلى حالة openspec/ محلية في المستودع قبل أن تتمكن من المشاركة في تخطيط مساحة العمل. قد تتطلب سير عمل التنفيلمصادقة أو الأرشفة اللاحقة جاهزية أكبر للمستودع، لكن مرئية التخطيط تبدأ بالرابط.

multi-repo:
  api      -> /repos/api
  web      -> /repos/web

large monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

مساحات العمل المُدارة تقع تحت دليل بيانات OpenSpec القياسي:

getGlobalDataDir()/workspaces

وهذا يعني $XDG_DATA_HOME/openspec/workspaces عند ضبط XDG_DATA_HOME، و~/.local/share/openspec/workspaces في نظام Unix كبديل، و%LOCALAPPDATA%\openspec\workspaces في نظام Windows الأصلي كبديل. تحتفظ كل من أجهزة تشغيل Windows الأصلية، وPowerShell، وWSL2 بنصوص المسار للوقت التشغيل الذي يُشغّل OpenSpec. لا يقوم هذا الأساس بالترجمة بين D:\repo و/mnt/d/repo ومسارات UNC لـ WSL.

لا يزال بإمكان OpenSpec قراءة جذور مساحات عمل بيتا القديمة كمدخلات توافقية، لكن مساحات العمل المُدارة تستخدم الآن سجل الجذر workspace.yaml أعلاه. يظل مجلد مساحة العمل موثوقًا لعرضه المحلي الخاص.

رؤية مساحة العمل ليست الالتزام بالتغيير. قم بإعداد مساحة عمل عندما يجب أن يعرف OpenSpec أي مستودعات أو مجلدات ذات صلة؛ أنشئ تغييرًا لاحقًا عندما تكون جاهزًا لتخطيط ميزة، أو إصلاح، أو مشروع، أو أي قطعة عمل أخرى.

أوامر مفيدة:

# الإعداد الموجه
openspec workspace setup

# الإعداد الصديق للأتمتة
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex-cli

# رؤية مساحات العمل المعروفة من السجل المحلي
openspec workspace list
openspec workspace ls

# إضافة أو إصلاح الروابط لمساحة العمل المحددة
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api

# التحقق مما يمكن لهذه الآجة حله
openspec workspace doctor
openspec workspace doctor --workspace platform

# تحديث إرشادات مساحة العمل المحلية ومهارات الوكيل
openspec workspace update
openspec workspace update --workspace platform --tools codex,claude

# فتح مجموعة العمل المرتبطة
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

# فتح مبادرة كعرض لمساحة عمل محلية
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative billing-launch --store-path /repos/platform-context

workspace setup يُنشئ دائمًا مساحة العمل في موقع مساحة العمل القياسي، يسجلها في السجل المحلي، يُظهر موقع مساحة العمل، ويتطلب مستودعًا أو مجلدًا واحدًا على الأقل مرتبطًا. يطلب الإعداد التفاعلي فاتحًا مفضلًا ويمكنه تثبيت مهارات OpenSpec للوكلاء المحددين. يخزن الإعداد غير التفاعلي فاتحًا واحدًا فقط عند توفير --opener codex-cli أو --opener claude أو --opener github-copilot أو --opener editor.

تتُثبَّت مهارات مساحة العمل فقط في جذر مساحة العمل. يحدد الملف الشخصي العام النشط أي مهارات سير العمل يتم إنشاؤها؛ يحدد --tools أي وكلاء يتلقونها. لا يُنشئ إعداد مساحة العمل وتحديثها ملفات أوامر مائلة حتى عندما يتضمن التسليم العام أوامرًا. قم بتشغيل openspec workspace update لتحديث إرشادات مساحة العمل المحلية وإضافة أو تحديث أو إزالة دليلات مهارات مساحة العمل المحلية المُدارة دون تعديل المستودعات أو المجلدات المرتبطة.

يحافظ OpenSpec أيضًا على ملفات فتح مساحة العمل الجذر: كتلة إرشادية يديرها OpenSpec في AGENTS.md وملف <workspace-name>.code-workspace محلي على الآلة لـ VS Code وفتح GitHub Copilot-in-VS-Code. مساحة العمل المُدارة ليست مستودعًا، لذلك لا يُنشئ OpenSpec ملف .gitignore افتراضي لمساحة العمل أو دليل changes/ افتراضي على مستوى مساحة العمل.

تُسرد مساحة عمل VS Code المُدارة أولاً المستودعات أو المجلدات المرتبطة الصالحة، ثم سياق المبادرة عند إرفاقه، ثم ملفات مساحة عمل OpenSpec. يعرض VS Code تلك الإدخالات كمساحة عمل متعددة الجذور.

workspace open تفتح مجموعة العمل المرتبطة بالفاتح المفضل المخزن ما لم يتم تمرير --agent <tool> أو --editor لتلك الجلسة المحددة. تمرير كلا تجاوزات الفاتح هو خطأ. يُتيح فتح مساحة العمل الجذر المستودعات والمجلدات المرتبطة مرئية للاستكشاف والسياق؛ يبدأ التنفيذ بعد أن يطلب المستخدم صراحةً عمل التنفيذ.

workspace link وworkspace relink تسجل المجلدات الموجودة فقط؛ لا تُنشئ أو تنسخ أو تنقل أو تُهيئ أو تعدل المستودع أو المجلد المرتبط. بعد الارتباط أو إعادة الارتباط الناجح، يقوم OpenSpec بتحديث الإرشادات المُدارة وملف مساحة عمل VS Code.

أوامر مساحة العمل التي تحتاج مساحة عمل واحدة يمكن تشغيلها من أي مكان باستخدام --workspace <name>. إذا قمت بتشغيلها داخل مجلد مساحة العمل أو دليل فرعي، يستخدم OpenSpec مساحة العمل الحالية تلك. إذا كانت عدة مساحات عمل معروفة متاحة ولم تمرر --workspace <name>، تُظهر الأوامر البشرية منتقي؛ --json و--no-interactive يفشلان مع خطأ حالة منظمة بدلاً من المطالبة.

تدعم أوامر مساحة العمل المباشرة ناتج JSON للنصوص البرمجية. تحتفظ استجابات JSON بالبيانات الأساسية في كائنات workspace أو workspaces أو link وتُبلغ عن التحذيرات أو الأخطاء في مصفوفات status. تستخدم الكائنات السليمة status: [].

المواصفات

تصف المواصفات سلوك نظامك باستخدام متطلبات وسيناريوهات منظمة.

البنية

openspec/specs/
├── auth/
│   └── spec.md           # سلوك المصادقة
├── payments/
│   └── spec.md           # معالجة المدفوعات
├── notifications/
│   └── spec.md           # نظام الإشعارات
└── ui/
    └── spec.md           # سلوك وسمات واجهة المستخدم

نظم المواصفات حسب المجال — تجميعات منطقية منطقية بالنسبة لنظامك. الأنماط الشائعة:

• حسب مجال الميزة: auth/، payments/، search/
• حسب المكون: api/، frontend/، workers/
• حسب السياق المحدود: ordering/، fulfillment/، inventory/

صيغة المواصفة

تحتوي المواصفة على متطلبات، ولكل متطلب سيناريوهات:

# مواصفة المصادقة

## الغرض
المصادقة وإدارة الجلسات للتطبيق.

## المتطلبات

### متطلب: مصادقة المستخدم
يجب أن يُصدر النظام رمز JWT عند تسجيل الدخول الناجح.

#### سيناريو: بيانات اعتماد صالحة
- بافتراض مستخدم لديه بيانات اعتماد صالحة
- عندما يقدم المستخدم استمارة تسجيل الدخول
- ثم يتم إرجاع رمز JWT
- ويتم إعادة توجيه المستخدم إلى لوحة التحكم

#### سيناريو: بيانات اعتماد غير صالحة
- بافتراض بيانات اعتماد غير صالحة
- عندما يقدم المستخدم استمارة تسجيل الدخول
- ثم يُعرض رسالة خطأ
- ولا يتم إصدار أي رمز

### متطلب: انتهاء صلاحية الجلسة
يجب أن تُنهي الجلسات بعد 30 دقيقة من عدم النشاط.

#### سيناريو: مهلة الخمول
- بافتراض جلسة مصادقة
- عندما تمر 30 دقيقة دون نشاط
- ثم تُبطل الجلسة
- ويجب على المستخدم إعادة المصادقة

العناصر الرئيسية:

العنصر	الغرض
## الغرض	وصف عام لمجال هذه المواصفة
### متطلب:	سلوك محدد يجب أن يكون للنظام
#### سيناريو:	مثال ملموس على المتطلب أثناء التنفيذ
SHALL/MUST/SHOULD	كلمات مفتاحية من RFC 2119 تُشير إلى قوة المتطلب

لماذا هيكلة المواصفات بهذه الطريقة

المتطلبات هي "ماذا" — تُحدد ما ينبغي أن يفعله النظام دون تحديد التنفيذ.

السيناريوهات هي "متى" — توفر أمثلة ملموسية يمكن التحقق منها. السيناريوهات الجيدة:

• قابلة للاختبار (يمكنك كتابة اختبار آلي لها)
• تغطي المسار السعيد وحالات الحافة
• تستخدم صيغة Given/When/Then أو تنظيم منظم مشابه

كلمات RFC 2119 المفتاحية (SHALL، MUST، SHOULD، MAY) تنقل القصد:

• MUST/SHALL — متطلب مطلق
• SHOULD — مُوصى به، لكن توجد استثناءات
• MAY — اختياري

ما هي المواصفة (وما ليست)

المواصفة هي عقد سلوك، وليس خطة تنفيذ.

محتوى المواصفة الجيد:

• السلوك الملحوظ الذي يعتمد عليه المستخدمون أو الأنظمة اللاحقة
• المدخلات والمخرجات وحالات الخطأ
• القيود الخارجية (الأمان، الخصوصية، الموثوقية، التوافق)
• سيناريوهات يمكن اختبارها أو التحقق منها صراحةً

تجنّب في المواصفات:

• أسماء الفئات/الدوال الداخلية
• اختيارات المكتبة أو الإطار
• تفاصيل التنفيذ خطوة بخطوة
• خطط التنفيذ التفصيلية (تلك تنتمي إلى design.md أو tasks.md)

اختبار سريع:

• إذا كان التنفيذ يمكن أن يتغير دون تغيير السلوك المرئي خارجيًا، فعلى الأرجح لا ينتمي إلى المواصفة.

اجعلها خفيفة: التدريج في الصارمة

يهدف OpenSpec إلى تجنب البيروقراطية. استخدم أخف مستوى لا يزال يجعل التغيير قابلًا للتحقق.

مواصفة خفيفة (الافتراضية):

• متطلبات قصيرة تركز على السلوك أولاً
• نطاق واضح وأهداف غير مرغوبة
• عدد قليل من عمليات القبول الملموسة

مواصفة كاملة (للمخاطر الأعلى):

• التغييرات عبر الفرق أو عبر المستودعات
• تغييرات API/العقود، الترحيل، المخاوف الأمنية/الخصوصية
• التغييرات حيث من المحتمل أن يسبب الغموض إعادة عمل مكلفة

معظم التغييرات يجب أن تبقى في الوضع الخفيف.

التعاون بين البشر والوكلاء

في العديد من الفرق، يستكشف البشر ويصيغ الوكلاء العناصر. الحلقة المقصودة هي:

1. يُقدم البشر القصد والسياق والقيود.
2. يُحوّل الوكيل هذا إلى متطلبات وسيناريوهات تركز على السلوك أولاً.
3. يُبقي الوكيل تفاصيل التنفيذ في design.md وtasks.md، وليس في spec.md.
4. يؤكد التحقق على البنية والوضوح قبل التنفيذ.

هذا يُبقي المواصفات مقروءة للبشر ومتسقة للوكلاء.

التغييرات

التغيير هو تعديل مقترح على نظامك، مُجمَّع كمجلد يحتوي على كل ما هو مطلوب لفهمه وتنفيذه.

هيكل التغيير

openspec/changes/add-dark-mode/
├── proposal.md           # لماذا وماذا
├── design.md             # كيف (النهج التقني)
├── tasks.md              # قائمة التنفيذ
├── .openspec.yaml        # بيانات التعريف للتغيير (اختياري)
└── specs/                # المواصفات الت增量ية
    └── ui/
        └── spec.md       # ما يتغير في ui/spec.md

كل تغيير مكتفٍ ذاتيًا. يحتوي على:

• الأُدوات — مستندات تلتقط النية والتصميم والمهام
• المواصفات الت增量ية — مواصفات لما يُضاف أو يُعدَّل أو يُزال
• البيانات الوصفية — تكوين اختياري لهذا التغيير المحدد

لماذا التغييرات هي مجلدات

تُجمَّع التغييرات كمجلدات لعدة فوائد:

1. كل شيء معًا. الاقتراح والتصميم والمهام والمواصفات توجد في مكان واحد. لا حاجة للبحث في مواقع مختلفة.

2. العمل المتوازي. يمكن أن توجد عدة تغييرات في وقت واحد دون تعارض. العمل على add-dark-mode بينما fix-auth-bug قيد التنفيذ أيضًا.

3. تاريخ نظيف. عند الأرشفة، تنتقل التغييرات إلى changes/archive/ مع الحفاظ على سياقها الكامل. يمكنك العودة للخلف وفهم ليس فقط ما تغير، بل لماذا.

4. سهل للمراجعة. مجلد التغيير سهل المراجعة — افتحه، اقرأ الاقتراح، افحص التصميم، وشاهد deltas المواصفات.

الأُدوات

الأُدوات هي المستندات داخل التغيير التي توجه العمل.

تدفق الأُدوات

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   why            what           how          steps
 + scope        changes       approach      to take

الأُدوات تبني بعضها البعض. كل أداة توفر السياق للتي تليها.

أنواع الأُدوات

الاقتراح (proposal.md)

الاقتراح يلتقط النية، النطاق، والنهج على مستوى عالٍ.

# Proposal: Add Dark Mode

النية

طلب المستخدمون خيار الوضع المظلم لتقليل إجهاد العينين أثناء الاستخدام الليلي لمطابقة تفضيلات النظام.

النطاق

ضمن النطاق:

• مفتاح تبديل السمة في الإعدادات
• كشف تفضيلات النظام
• حفظ التفضيل في localStorage

خارج النطاق:

• سمات مخصصة (عمل مستقبلي)
• تجاوزات السمة حسب الصفحة

النهج

استخدام خصائص CSS المخصصة للسمات مع سياق React لإدارة الحالة. كشف تفضيلات النظام عند التحميل الأول، السماح بالتجاوز اليدوي.

**متى يتم تحديث الاقتراح:**
- تغييرات النطاق (تضييق أو توسيع)
- توضيح النية (فهم أفضل للمشكلة)
- تغيير جوهري في النهج

#### المواصفات (مواصفات دلتا في `specs/`)

تصف مواصفات دلتا **ما يتغير** بالنسبة للمواصفات الحالية. انظر [مواصفات دلتا](#delta-specs) أدناه.

#### التصميم (`design.md`)

يحتوي التصميم على **النهج التقني** و**قرارات الهيكل**.

````markdown
# التصميم: إضافة الوضع المظلم

## النهج التقني
حالة السمة تُدار عبر React Context لتجنب تمرير الخصائص.
خصائص CSS المخصصة تتيح التبديل في وقت التشغيل بدون تبديل الفئات.

## قرارات الهيكل

### القرار: السياق بدلاً من Redux
استخدام React Context لحالة السمة لأن:
- حالة ثنائية بسيطة (فاتح/مظلم)
- لا توجد تحولات حالة معقدة
- تجنب إضافة تبعية Redux

### القرار: خصائص CSS المخصصة
استخدام متغيرات CSS بدلاً من CSS-in-JS لأن:
- تعمل مع ورقة الأنماط الحالية
- لا توجد أعباء تشغيلية
- حل أصلي للمتصفح

## تدفق البيانات

ThemeProvider (context) │ ▼ ThemeToggle ◄──► localStorage │ ▼ CSS Variables (applied to :root)

## تغييرات الملفات
- `src/contexts/ThemeContext.tsx` (جديد)
- `src/components/ThemeToggle.tsx` (جديد)
- `src/styles/globals.css` (معدل)

متى يتم تحديث التصميم:

• كشف التنفيذ أن النهج لن يعمل
• اكتشاف حل أفضل
• تغيير التبعيات أو القيود

المهام (tasks.md)

المهام هي قائمة التنفيذ — خطوات ملموسة بمربعات اختيار.

# المهام

## 1. البنية التحتية للسمة
- [ ] 1.1 إنشاء ThemeContext مع حالة فاتح/مظلم
- [ ] 1.2 إضافة خصائص CSS مخصصة للألوان
- [ ] 1.3 تنفيذ الاستمرارية في localStorage
- [ ] 1.4 إضافة كشف تفضيلات النظام

## 2. واجهة المستخدم
- [ ] 2.1 إنشاء مكون ThemeToggle
- [ ] 2.2 إضافة المفتاح لصفحة الإعدادات
- [ ] 2.3 تحديث الرأس لتضمين المفتاح السريع

## 3. التنسيق
- [ ] 3.1 تحديد لوحة ألوان السمة المظلمة
- [ ] 3.2 تحديث المكونات لاستخدام متغيرات CSS
- [ ] 3.3 اختبار نسب التباين لسهولة الوصول

أفضل ممارسات المهام:

• تجميع المهام ذات الصلة تحت عناوين
• استخدام الترقيم الهرمي (1.1، 1.2، إلخ.)
• إبقاء المهام صغيرة بما يكفي لإكمالها في جلسة واحدة
• تعليم المهام كمكتملة عند إنجازها

مواصفات دلتا

مواصفات دلتا هي المفهوم الرئيسي الذي يجعل OpenSpec يعمل للتطوير البراوني. تصف ما يتغير بدلاً من إعادة صياغة المواصفات بالكامل.

الصيغة

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 15 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)

أقسام دلتا

القسم	المعنى	ما يحدث عند الأرشفة
## ADDED Requirements	سلوك جديد	مُلحق بالمواصفات الرئيسية
## MODIFIED Requirements	سلوك متغير	يحل محل المتطلب الحالي
## REMOVED Requirements	سلوك مُلغى	مُحذف من المواصفات الرئيسية

لماذا الدلتا بدلاً من المواصفات الكاملة

الوضوح. تُظهر الدلتا بالضبط ما يتغير. عند قراءة مواصفات كاملة، سيتعين عليك مقارنتها ذهنيًا مع الإصدار الحالي.

تجنب التعارض. يمكن لتغييرين أن يلمسا نفس ملف المواصفات دون تعارض، طالما أنهما يعدلان متطلبات مختلفة.

كفاءة المراجعة. يرى المراجعون التغيير، وليس السياق غير المتغير. التركيز على ما يهم.

ملاءمة البراوني. يُعد معظم العمل تعديلًا لسلوك حالي. تجعل الدلتا التعديلات من الدرجة الأولى، وليس أمرًا ثانويًا.

المخططات

تحدد المخططات أنواع الأدوات وتبعياتها لسير العمل.

كيف تعمل المخططات

# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # لا توجد تبعيات، يمكن إنشاؤها أولاً

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # تحتاج الاقتراح قبل الإنشاء

  - id: design
    generates: design.md
    requires: [proposal]      # يمكن إنشاؤها بالتوازي مع المواصفات

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # تحتاج كلاً من المواصفات والتصميم أولاً

تشكل الأدوات رسمًا بيانيًا للتبعيات:

                    proposal
                   (root node)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (requires:                  (requires:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (requires:
                specs, design)

التبعيات مُمكِّنة، وليس بوابات. تُظهر ما يمكن إنشاؤه، وليس ما يجب إنشاؤه بعد ذلك. يمكنك تخطي التصميم إذا لم تكن بحاجة إليه. يمكنك إنشاء المواصفات قبل التصميم أو بعده — كليهما يعتمد فقط على الاقتراح.

المخططات المدمجة

spec-driven (افتراضي)

سير العمل القياسي للتطوير المُوجَّه بالمواصفات:

proposal → specs → design → tasks → implement

الأفضل لـ: معظم عمل الميزات حيث تريد الاتفاق على المواصفات قبل التنفيذ.

مخططات مخصصة

أنشئ مخططات مخصصة لسير عمل فريقك:

# إنشاء من الصفر
openspec schema init research-first

# أو نسخ مخطط موجود
openspec schema fork spec-driven research-first

مثال على مخطط مخصص:

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # إجراء البحث أولاً

  - id: proposal
    generates: proposal.md
    requires: [research]   # اقتراح مستند إلى البحث

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # تخطي المواصفات/التصميم، الذهاب مباشرة إلى المهام

انظر التخصيص للتفاصيل الكاملة حول إنشاء واستخدام مخططات مخصصة.

الأرشفة

تكمل الأرشفة التغيير من خلال دمج مواصفات دلتا في المواصفات الرئيسية والحفاظ على التغيير للتاريخ.

ماذا يحدث عند الأرشفة

قبل الأرشفة:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ دمج
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


بعد الأرشفة:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # الآن تتضمن متطلبات المصادقة الثنائية
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # محفوظ للتاريخ
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

عملية الأرشفة

1. دمج الدلتا. يُطبَّق كل قسم مواصفات دلتا (مُضاف/مُعدَّل/مُزيل) على المواصفات الرئيسية المقابلة.

2. النقل إلى الأرشيف. يُنقل مجلد التغيير إلى changes/archive/ مع بادئة تاريخ للترتيب الزمني.

3. الحفاظ على السياق. تبقى جميع الأدوات سليمة في الأرشيف. يمكنك دائمًا العودة لفهم سبب إجراء التغيير.

لماذا الأرشفة مهمة

حالة نظيفة. تُظهر التغييرات النشطة (changes/) فقط العمل قيد التنفيذ. يُنقل العمل المكتمل بعيدًا.

سجل المراجعة. يُحافظ الأرشيف على السياق الكامل لكل تغيير — ليس فقط ما تغير، بل الاقتراح الذي يشرح السبب، والتصميم الذي يشرح الكيفية، والمهام التي تُظهر العمل المُنجز.

تطور المواصفات. تنمو المواصفات عضويًا مع أرشفة التغييرات. يدمج كل أرشيف دلتا الخاصة به، مما يبني مواصفات شاملة بمرور الوقت.

كيف يتناسب كل شيء معًا

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC FLOW                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
│   │     ARTIFACTS  │  Creates proposal → specs → design → tasks              │
│   │                │  (based on schema dependencies)                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. IMPLEMENT  │  /opsx:apply                                            │
│   │     TASKS      │  Work through tasks, checking them off                  │
│   │                │◄──── Update artifacts as you learn                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. VERIFY     │  /opsx:verify (optional)                                │
│   │     WORK       │  Check implementation matches specs                     │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. ARCHIVE    │────►│  Delta specs merge into main specs           │    │
│   │     CHANGE     │     │  Change folder moves to archive/             │    │
│   └────────────────┘     │  Specs are now the updated source of truth   │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

الدورة الفاضلة:

1. تصف المواصفات السلوك الحالي
2. تقترح التغييرات تعديلات (كنماط دلتا)
3. يجعل التنفيذ التغييرات حقيقية
4. تدمج الأرشفة الدلتا في المواصفات
5. تصف المواصفات الآن السلوك الجديد
6. يبني التغيير التالي على المواصفات المُحدَّثة

المصطلحات

المصطلح	التعريف
Artifact (مُنشَأ)	مستند داخل التغيير (اقتراح، تصميم، مهام، أو مواصفات دلتا)
Archive (أرشفة)	عملية إكمال التغيير ودمج تغييرات الدلتا في المواصفات الرئيسية
Change (تغيير)	تعديل مقترح على النظام، مُجمَّع في مجلد يحتوي على مُنشآت
Delta spec (مواصفات دلتا)	مواصفات تصف التغييرات (مُضافة/مُعدَّلة/مُزالة) مقارنة بالمواصفات الحالية
Domain (نطاق)	تجميع منطقي للمواصفات (مثلاً: auth/، payments/)
Requirement (متطلب)	سلوك محدد يجب أن يتوفر في النظام
Scenario (سيناريو)	مثال ملموس على متطلب، عادةً بتنسيق Given/When/Then
Schema (مخطط)	تعريف لأنواع المُنشآت وتوابعها
Spec (مواصفات)	وصف لسلوك النظام، يحتوي على متطلبات وسيناريوهات
Source of truth (مصدر الحقيقة)	دليل openspec/specs/، الذي يحتوي على السلوك المتفق عليه حاليًا

الخطوات التالية

• البدء - الخطوات العملية الأولى
• سير العمل - الأنماط الشائعة ومتى يتم استخدام كل منها
• الأوامر - مرجع الأوامر الكامل
• التخصيص - إنشاء مخططات مخصصة وتكوين مشروعك