التحويل إلى OPSX

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

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

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

الجانب	القديم	OPSX
الأوامر	/openspec:proposal, /openspec:apply, /openspec:archive	الافتراضي: /opsx:propose, /opsx:apply, /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, 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

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

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

للترحيل عبر السكريبتات:

openspec init --force --tools claude

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

---

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

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

قبل (project.md)

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

بعد (config.yaml)

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

الفروقات الرئيسية

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

ما الذي يُحتفظ به وما الذي يُهمل

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

مرشحات جيدة لـ context:

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

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

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

اتركها بالكامل

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

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

1. إنشاء config.yaml (إذا لم يتم إنشاؤه بالفعل عبر init):

   schema: spec-driven

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

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

3. إضافة قواعد لكل مخرج (اختياري):

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

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

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

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

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

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

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

---

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

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

الافتراضي (ملف شخصي 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

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

---

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

من المرحلة المُقفلة إلى المرن

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

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   التخطيط    │ ───► │   التنفيذ    │ ───► │   الأرشفة    │
│    المرحلة    │      │    المرحلة    │      │    المرحلة    │
└──────────────┘      └──────────────┘      └──────────────┘

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

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

         ┌───────────────────────────────────────────────┐
         │           الإجراءات (وليس المراحل)            │
         │                                               │
         │     جديد ◄──► متابعة ◄──► تطبيق ◄──► أرشفة   │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    أي ترتيب                   │
         └───────────────────────────────────────────────┘

الرسم البياني للاعتماديات

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

                        اقتراح
                       (العقد الجذر)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           مواصفات                     تصميم
        (يتطلب:                    (يتطلب:
         اقتراح)                    اقتراح)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         مهام
                     (يتطلب:
                     مواصفات، تصميم)

عندما تقوم بتشغيل /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

# مطلوب: المخطط الافتراضي للتغييرات الجديدة
schema: spec-driven

# اختياري: سياق المشروع (حد أقصى 50 كيلوبايت)
# يُحقن في جميع تعليمات المخرجات
context: |
  خلفية مشروعك، حزمة التقنيات،
  الاتفاقيات، والقيود.

# اختياري: قواعد لكل مخرج
# تُحقن فقط في المخرجات المطابقة
rules:
  proposal:
    - تضمين خطة التراجع
  specs:
    - استخدام تنسيق Given/When/Then
  design:
    - توثيق استراتيجيات البدائل
  tasks:
    - تقسيم إلى أجزاء بحد أقصى ساعتين

حل المخططات

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

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

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

المخطط	المخرجات	الأفضل لـ
spec-driven	اقتراح → مواصفات → تصميم → مهام	معظم المشاريع

列出 جميع المخططات المتاحة:

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/                    # لم يتغير
│   ├── changes/                  # لم يتغير
│   │   └── archive/              # لم يتغير
│   └── config.yaml               # جديد: إعدادات المشروع
├── .claude/
│   └── skills/                   # جديد: مهارات OPSX
│       ├── openspec-propose/     # الملف الشخصي الأساسي الافتراضي
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       └── ...                   # الملف الشخصي الموسّع يضيف جديد/متابعة/مقدمة/إلخ.
├── CLAUDE.md                     # أُزيلت علامات OpenSpec، محتواك محفوظ
└── AGENTS.md                     # أُزيلت علامات OpenSpec، محتواك محفوظ

ما الذي اختفى

• .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