الانتقال إلى OPSX

يساعدك هذا الدليل على التحول من سير عمل OpenSpec القديم إلى OPSX. تم تصميم عملية الانتقال لتكون سلسة — يتم الحفاظ على عملك الحالي، ويقدم النظام الجديد مرونة أكبر.

ما الذي يتغير؟

يستبدل OPSX سير عمل القفل الطوري القديم بنهج سلس قائم على الإجراءات. إليك التحول الرئيسي:

الجوانب	النظام القديم	OPSX
الأوامر	/openspec:proposal، /openspec:apply، /openspec:archive	الافتراضي: /opsx:propose، /opsx:apply، /opsx:sync، /opsx:archive (أوامر سير عمل موسعة اختيارية)
سير العمل	إنشاء جميع المخرجات دفعة واحدة	إنشاء تدريجي أو دفعة واحدة — خيارك
العودة للخلف	بوابات طورية غير ملائمة	طبيعي — تحديث أي مخرج في أي وقت
التخصيص	هيكل ثابت	مدفوع بالمخطط، قابل للتعديل بالكامل
التكوين	CLAUDE.md مع علامات + project.md	تكوين نظيف في openspec/config.yaml

التغيير الفلسفي: العمل ليس خطيًا. يتوقف OPSX عن التظاهر بأنه كذلك.

---

قبل أن تبدأ

عملك الحالي آمن

تم تصميم عملية الترحيل مع الحفاظ على المحتوى في الاعتبار:

• التغييرات النشطة في openspec/changes/ — محفوظة بالكامل. يمكنك متابعتها باستخدام أوامر OPSX.
• التغييرات المؤرشفة — لم يتم لمسها. يبقى تاريخك سليمًا.
• المواصفات الرئيسية في openspec/specs/ — لم يتم لمسها. هذه هي مصدر الحقيقة الخاص بك.
• محتواك في CLAUDE.md، AGENTS.md، إلخ. — محفوظ. تتم إزالة كتل علامات OpenSpec فقط؛ كل ما كتبته يبقى.

ما يتم إزالته

فقط الملفات التي تديرها OpenSpec والتي يتم استبدالها:

ماذا	لماذا
أدلة/ملفات أوامر الشرطة المائلة القديمة	تم استبدالها بنظام المهارات الجديد
openspec/AGENTS.md	محفز سير عمل قديم
علامات OpenSpec في CLAUDE.md، AGENTS.md، إلخ.	لم تعد مطلوبة

مواقع الأوامر القديمة حسب الأداة (أمثلة - قد تختلف أداتك):

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (إضافات IDE فقط؛ غير مدعومة في Copilot CLI)
• وغيرها (Augment، Continue، Amazon Q، إلخ.)

يكتشف الترحيل الأدوات التي قمت بتكوينها وينظف ملفاتها القديمة.

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

ما يحتاج انتباهك

يحتاج ملف واحد إلى ترحيل يدوي:

openspec/project.md — لا يتم حذف هذا الملف تلقائيًا لأنه قد يحتوي على سياق مشروع كتبته. ستحتاج إلى:

1. مراجعة محتوياته
2. نقل السياق المفيد إلى openspec/config.yaml (انظر الإرشادات أدناه)
3. حذف الملف عندما تكون جاهزًا

لماذا أجرينا هذا التغيير:

كان ملف project.md القديم سلبيًا - قد تقرأه الوكلاء، وقد لا تقرأه، وقد تنسى ما قرأوه. وجدنا أن الموثوقية كانت غير متسقة.

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

المقايضة:

بما أن السياق يتم حقنه في كل طلب، سترغب في الإيجاز. ركز على ما يهم حقًا:

• مكدس التكنولوجيا والاتفاقيات الرئيسية
• القيود غير الواضحة التي يحتاج الذكاء الاصطناعي لمعرفتها
• القواعد التي تم تجاهلها في كثير من الأحيان من قبل

لا تقلق بشأن جعله مثاليًا. نحن لا نزال نتعلم ما يعمل بشكل أفضل هنا، وسنقوم بتحسين كيفية عمل حقن السياق بينما نجرب.

---

تشغيل الترحيل

يكتشف كلا من openspec init و openspec update الملفات القديمة ويرشدك خلال نفس عملية التنظيف. استخدم أيهما يناسب وضعك:

• التثبيتات الجديدة تستخدم الملف التعريفي core (propose، explore، apply، sync، archive) كافتراضي.
• التثبيتات المُرحَّلة تحافظ على سير العمل الذي قمت بتثبيته مسبقًا عن طريق كتابة ملف تعريفي custom عند الحاجة.

استخدام openspec init

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

openspec init

يكتشف أمر init الملفات القديمة ويرشدك خلال التنظيف:

الترقية إلى OpenSpec الجديد

OpenSpec الآن يستخدم مهارات الوكيل، المعيار الناشئ عبر وكلاء
البرمجة. هذا يبسط إعدادك مع إبقاء كل شيء يعمل
كما كان من قبل.

الملفات المراد إزالتها
لا يوجد محتوى مستخدم للحفظ:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

الملفات المراد تحديثها
سيتم إزالة علامات OpenSpec، محتواك محفوظ:
  • CLAUDE.md
  • AGENTS.md

يحتاج انتباهك
  • openspec/project.md
    لن نحذف هذا الملف. قد يحتوي على سياق مشروع مفيد.

    يحتوي openspec/config.yaml الجديد على قسم "context:" لسياق
    التخطيط. يتم تضمين هذا في كل طلب OpenSpec ويعمل بشكل أكثر
    موثوقية من نهج project.md القديم.

    راجع project.md، وانقل أي محتوى مفيد إلى قسم context في config.yaml،
    ثم احذف الملف عندما تكون جاهزًا.

? الترقية وتنظيف الملفات القديمة؟ (Y/n)

ما يحدث عندما تقول نعم:

1. تتم إزالة أدلة أوامر الشرطة المائلة القديمة
2. تتم إزالة علامات OpenSpec من CLAUDE.md، AGENTS.md، إلخ. (محتواك يبقى)
3. يتم حذف openspec/AGENTS.md
4. يتم تثبيت المهارات الجديدة في .claude/skills/
5. يتم إنشاء openspec/config.yaml مع مخطط افتراضي

استخدام openspec update

قم بتشغيل هذا إذا كنت تريد فقط الترحيل وتحديث أدواتك الحالية إلى أحدث إصدار:

openspec update

يكتشف أمر التحديث أيضًا وينظف الأصناف القديمة، ثم يحدّث المهارات/الأوامر المولدة لتتطابق مع ملفك التعريفي وإعدادات التسليم الحالية.

بيئات غير تفاعلية / CI

للترحيل المبرمج:

openspec init --force --tools claude

يتجاوز علامة --force المطالبات ويقبل التنظيف تلقائيًا.

---

ترحيل project.md إلى config.yaml

كان ملف openspec/project.md القديم ملف ماركداون حرًا لسياق المشروع. openspec/config.yaml الجديد منظم و - بشكل حاسم - يتم حقنه في كل طلب تخطيط حتى تكون اتفاقياتك موجودة دائمًا عندما يعمل الذكاء الاصطناعي.

قبل (project.md)

# سياق المشروع

هذا مستودع أحادي TypeScript يستخدم React و Node.js.
نحن نستخدم Jest للاختبار ونتبع قواعد ESLint الصارمة.
واجهة برمجة تطبيقاتنا هي RESTful وموثقة في docs/api.md.

## الاتفاقيات

- يجب أن تحافظ جميع واجهات برمجة التطبيقات العامة على التوافق مع الإصدارات السابقة
- يجب أن تتضمن الميزات الجديدة اختبارات
- استخدم تنسيق Given/When/Then للمواصفات

بعد (config.yaml)

schema: spec-driven

context: |
  مكدس التكنولوجيا: TypeScript، React، Node.js
  الاختبار: Jest مع React Testing Library
  واجهة برمجة التطبيقات: RESTful، موثقة في docs/api.md
  نحافظ على التوافق مع الإصدارات السابقة لجميع واجهات برمجة التطبيقات العامة

rules:
  proposal:
    - قم بتضمين خطة التراجع للتغييرات المحفوفة بالمخاطر
  specs:
    - استخدم تنسيق Given/When/Then للسيناريوهات
    - اذكر الأنماط الحالية قبل اختراع أنماط جديدة
  design:
    - قم بتضمين مخططات التسلسل للتدفقات المعقدة

الاختلافات الرئيسية

project.md	config.yaml
ماركداون حر	YAML منظم
كتلة واحدة من النص	سياق منفصل وقواعد لكل صنف
غير واضح متى يتم استخدامه	يظهر السياق في جميع الأصناف؛ تظهر القواعد فقط في الأصناف المطابقة
لا يوجد اختيار مخطط	حقل schema: الصريح يحدد سير العمل الافتراضي

ما يجب الاحتفاظ به، وما يجب إسقاطه

عند الترحيل، كن انتقائيًا. اسأل نفسك: "هل يحتاج الذكاء الاصطناعي لهذا في كل طلب تخطيط؟"

مرشحون جيدون لـ context:

• مكدس التكنولوجيا (اللغات، الأطر، قواعد البيانات)
• الأنماط المعمارية الرئيسية (مستودع أحادي، خدمات مصغرة، إلخ.)
• القيود غير الواضحة ("لا يمكننا استخدام المكتبة X لأن...")
• الاتفاقيات الحاسمة التي يتم تجاهلها في كثير من الأحيان

انقل إلى rules: بدلاً من ذلك

• التنسيق الخاص بالصنف ("استخدم Given/When/Then في المواصفات")
• معايير المراجعة ("يجب أن تتضمن المقترحات خطط تراجع")
• تظهر هذه فقط للصنف المطابق، مما يجعل الطلبات الأخرى أخف

اتركها تمامًا

• أفضل الممارسات العامة التي يعرفها الذكاء الاصطناعي بالفعل
• التفسيرات المطولة التي يمكن تلخيصها
• السياق التاريخي الذي لا يؤثر على العمل الحالي

خطوات الترحيل

1. أنشئ config.yaml (إذا لم يتم إنشاؤه بالفعل بواسطة init):

   schema: spec-driven

2. أضف سياقك (كن موجزًا - هذا يذهب في كل طلب):

   context: |
     خلفية مشروعك تذهب هنا.
     ركز على ما يحتاجه الذكاء الاصطناعي لمعرفته حقًا.

3. أضف قواعد لكل صنف (اختياري):

   rules:
     proposal:
       - إرشاداتك الخاصة بالمقترح
     specs:
       - قواعد كتابة المواصفات الخاصة بك

4. احذف project.md بمجرد نقل كل شيء مفيد.

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

تحتاج مساعدة؟ استخدم هذا التوجيه

إذا لم تكن متأكدًا كيفية تقطير project.md، اطلب من مساعد الذكاء الاصطناعي:

أنا أنتقل من project.md القديم في OpenSpec إلى تنسيق config.yaml الجديد.

إليك project.md الحالي:
[الصق محتوى project.md الخاص بك]

ساعدني في إنشاء config.yaml مع:
1. قسم `context:` موجز (يتم حقنه في كل طلب تخطيط، لذا اجعله مختصرًا - ركز على مكدس التكنولوجيا، القيود الرئيسية، والاتفاقيات التي يتم تجاهلها في كثير من الأحيان)
2. `rules:` لأصناف محددة إذا كان أي محتوى خاصًا بالصنف (مثل "استخدم Given/When/Then" ينتمي إلى قواعد المواصفات، وليس السياق العام)

اترك أي شيء عام يعرفه نماذج الذكاء الاصطناعي بالفعل. كن صارمًا بشأن الإيجاز.

سيساعدك الذكاء الاصطناعي في تحديد ما هو جوهري مقابل ما يمكن تقليصه.

---

الأوامر الجديدة

توفر الأوامر يعتمد على الملف التعريفي:

الافتراضي (ملف تعريفي core):

الأمر	الغرض
/opsx:propose	إنشاء تغيير وتوليد أصناف التخطيط في خطوة واحدة
/opsx:explore	التفكير في الأفكار بدون هيكل
/opsx:apply	تنفيذ المهام من tasks.md
/opsx:archive	الانتهاء وأرشفة التغيير

سير عمل موسع (اختيار مخصص):

الأمر	الغرض
/opsx:new	بدء هيكل تغيير جديد
/opsx:continue	إنشاء الصنف التالي (واحد في كل مرة)
/opsx:ff	تقديم سريع - إنشاء أصناف التخطيط دفعة واحدة
/opsx:verify	التحقق من تطابق التنفيذ مع المواصفات
/opsx:sync	دمج مواصفات الدلتا في المواصفات الرئيسية
/opsx:bulk-archive	أرشفة عدة تغييرات دفعة واحدة
/opsx:onboard	سير عمل إرشادي شامل من البداية إلى النهاية

قم بتمكين الأوامر الموسعة باستخدام openspec config profile، ثم قم بتشغيل openspec update.

تعيين الأوامر من النظام القديم

القديم	OPSX المكافئ
/openspec:proposal	/opsx:propose (افتراضي) أو /opsx:new ثم /opsx:ff (موسّع)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

القدرات الجديدة

هذه القدرات جزء من مجموعة أوامر سير العمل الموسعة.

إنشاء أصناف متدرجة:

/opsx:continue

ينشئ صنفًا واحدًا في كل مرة بناءً على التبعيات. استخدم هذا عندما تريد مراجعة كل خطوة.

وضع الاستكشاف:

/opsx:explore

فكر في الأفكار مع شريك قبل الالتزام بتغيير.

---

فهم البنية الجديدة

من المقفل إلى المائع

فرض سير العمل القديم تقدمًا خطيًا:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

إذا كنت في مرحلة التنفيذ وأدركت أن التصميم خاطئ؟
سيئ. البوابات بين المراحل لا تسمح بالعودة بسهولة.

يستخدم OPSX إجراءات، وليس مراحل:

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

مخطط الاعتماديات

تشكل المخرجات مخططًا موجهًا. الاعتماديات هي مُمكِّنات، وليست بوابات:

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

عند تشغيل /opsx:continue، يتحقق مما هو جاهز ويعرض المخرج التالي. يمكنك أيضًا إنشاء عدة مخرجات جاهزة بأي ترتيب.

المهارات مقابل الأوامر

استخدم النظام القديم ملفات أوامر خاصة بالأدوات:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

يستخدم OPSX معيار المهارات الناشئ:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

تُعترف المهارات عبر أدوات ترميز متعددة للذكاء الاصطناعي وتوفر بيانات وصفية أغنى.

---

متابعة التغييرات الحالية

تعمل تغييراتك قيد التقدم بسلاسة مع أوامر OPSX.

هل لديك تغيير نشط من سير العمل القديم؟

/opsx:apply add-my-feature

يقرأ OPSX المخرجات الموجودة ويستمر من حيث توقفت.

هل تريد إضافة المزيد من المخرجات إلى تغيير موجود؟

/opsx:continue add-my-feature

يعرض ما هو جاهز للإنشاء بناءً على ما هو موجود بالفعل.

هل تحتاج إلى رؤية الحالة؟

openspec status --change add-my-feature

---

نظام التكوين الجديد

هيكل config.yaml

# Required: Default schema for new changes
schema: spec-driven

# Optional: Project context (max 50KB)
# Injected into ALL artifact instructions
context: |
  Your project background, tech stack,
  conventions, and constraints.

# Optional: Per-artifact rules
# Only injected into matching artifacts
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

تحليل المخطط

عند تحديد المخطط المراد استخدامه، يتحقق OPSX بالترتيب:

1. علامة CLI: --schema <name> (أولوية قصوى)
2. بيانات التغيير الوصفية: .openspec.yaml في دليل التغيير
3. تكوين المشروع: openspec/config.yaml
4. الافتراضي: spec-driven

المخططات المتاحة

المخطط	المخرجات	الأفضل لـ
spec-driven	proposal → specs → design → tasks	معظم المشاريع

سرد جميع المخططات المتاحة:

openspec schemas

المخططات المخصصة

أنشئ سير عملك الخاص:

openspec schema init my-workflow

أو انسخ مخططًا موجودًا:

openspec schema fork spec-driven my-workflow

انظر التخصيص للتفاصيل.

---

استكشاف الأخطاء وإصلاحها

"تم اكتشاف ملفات قديمة في وضع غير تفاعلي"

أنت تعمل في بيئة CI أو غير تفاعلية. استخدم:

openspec init --force

الأوامر لا تظهر بعد الترحيل

أعد تشغيل بيئة التطوير المتكاملة (IDE). يتم اكتشاف المهارات عند بدء التشغيل.

"معرّف مخرج غير معروف في القواعد"

تحقق من أن مفاتيح rules: تتطابق مع معرّفات المخرجات في مخططك:

• spec-driven: proposal, specs, design, tasks

قم بتشغيل هذا لرؤية معرّفات المخرجات الصالحة:

openspec schemas --json

لم يتم تطبيق التكوين

1. تأكد من أن الملف موجود في openspec/config.yaml (وليس .yml)
2. تحقق من صحة بنية YAML
3. تدخل تغييرات التكوين حيز التنفيذ فورًا - لا حاجة لإعادة التشغيل

لم يتم ترحيل project.md

يحافظ النظام عن عمد على project.md لأنه قد يحتوي على محتواك المخصص. راجعه يدويًا، وانقل الأجزاء المفيدة إلى config.yaml، ثم احذفه.

تريد رؤية ما سيتم تنظيفه؟

قم بتشغيل init ورفض مطالبة التنظيف - سترى ملخص الكشف الكامل دون إجراء أي تغييرات.

---

مرجع سريع

الملفات بعد الترحيل

project/
├── openspec/
│   ├── specs/                    # Unchanged
│   ├── changes/                  # Unchanged
│   │   └── archive/              # Unchanged
│   └── config.yaml               # NEW: Project configuration
├── .claude/
│   └── skills/                   # NEW: OPSX skills
│       ├── openspec-propose/     # default core profile
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-sync-specs/
│       └── ...                   # expanded profile adds new/continue/ff/etc.
├── CLAUDE.md                     # OpenSpec markers removed, your content preserved
└── AGENTS.md                     # OpenSpec markers removed, your content preserved

ما تم إزالته

• .claude/commands/openspec/ — تم استبداله بـ .claude/skills/
• openspec/AGENTS.md — قديم
• openspec/project.md — قم بالترحيل إلى config.yaml، ثم احذفه
• كتل علامات OpenSpec في CLAUDE.md، AGENTS.md، إلخ.

جدول الأوامر المختصر

/opsx:propose      ابدأ بسرعة (الملف التعريفي الأساسي الافتراضي)
/opsx:apply        تنفيذ المهام
/opsx:archive      الانتهاء والأرشفة

# سير عمل موسع (إذا كان ممكّنًا):
/opsx:new          إنشاء هيكل تغيير
/opsx:continue     إنشاء المخرج التالي
/opsx:ff           إنشاء مخرجات التخطيط

---

الحصول على المساعدة

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• التوثيق: docs/opsx.md للمرجع الكامل لـ OPSX