الترحيل إلى 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 والتي يتم استبدالها:

ما	لماذا
أدلة/ملفات أوامر slash القديمة	يتم استبدالها بنظام المهارات الجديد
openspec/AGENTS.md	مشغل سير عمل قديم
علامات OpenSpec في ملفات CLAUDE.md و AGENTS.md وما إلى ذلك	لم تعد هناك حاجة إليها

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

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .cinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (امتدادات IDE فقط؛ غير مدعومة في Copilot CLI)
• Codex: تستخدم OpenSpec الآن .codex/skills/openspec-*؛ يستهدف التنظيف القديم فقط أسماء ملفات الأوامر المدرجة في القائمة المسموح بها لـ OpenSpec في $CODEX_HOME/prompts أو ~/.codex/prompts، ويزيلها فقط بعد وجود مهارات بديلة.
• وآخرون (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

يكشف أمر التهيئة عن الملفات القديمة ويوجهك خلال عملية التنظيف:

الترقية إلى الإصدار الجديد من 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، وانقل أي محتوى مفيد إلى قسم السياق في config.yaml، ثم احذف الملف عندما تكون مستعداً لذلك.

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

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

1. تتم إزالة أدلة الأوامر slash القديمة
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 إلى تخطي المطالبات وقبول التنظيف تلقائياً.

يتضمن هذا تنظيف ملفات أوامر Codex التي تديرها OpenSpec في دليل أوامر Codex العام. يستهدف التنظيف فقط أسماء ملفات أوامر Codex القديمة المدرجة في القائمة المسموح بها لـ OpenSpec، ويزيلها فقط بعد وجود مهارات .codex/skills/openspec-* بديلة، ويحافظ على جميع الملفات الأخرى.

---

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

كان ملف openspec/project.md القديم ملف ماركداون حر لسياق المشروع. أما ملف 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
ماركداون حر	YAML منظم
كتلة نصية واحدة	سياق منفصل وقواعد خاصة بكل عنصر فني
غير واضح متى يتم استخدامه	يظهر السياق في جميع العناصر الفنية؛ تظهر القواعد فقط في العناصر الفنية المطابقة
لا يوجد اختيار للمخطط	حقل schema: الصريح يحدد سير العمل الافتراضي

ما تحتفظ به، وما تتخلى عنه

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

المرشحون الجيدون لقسم context:

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

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

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

اتركها خارجاً تماماً

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

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

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

   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	دمج مواصفات Delta في المواصفات الرئيسية
/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 إجراءات، وليس مراحل:

         ┌───────────────────────────────────────────────┐
         │           إجراءات (ليس مراحل)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    أي ترتيب                  │
         └───────────────────────────────────────────────┘

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

تشكل العناصر الفنية رسماً بيانياً موجهًا. التبعيات هي عوامل تمكين، وليست بوابات:

                        proposal
                       (العقدة الجذرية)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (يتطلب:                  (يتطلب:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (يتطلب:
                     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
└── ...

يتم التعرف على المهارات عبر أدوات برمجة الذكاء الاصطناعي المتعددة وتوفر بيانات وصفية أكثر ثراءً.

يدعم Codex المهارات فقط في OPSX. لم تعد OpenSpec تنشئ ملفات أوامر مخصصة لـ Codex؛ استخدم أدلة .codex/skills/openspec-* المُنشأة بدلاً من ذلك.

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

تعمل تغييراتك الجارية بسلاسة مع أوامر 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	proposal → specs → design → tasks	معظم المشاريع

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

openspec schemas

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

إنشاء سير العمل الخاص بك:

openspec schema init my-workflow

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

openspec schema fork spec-driven my-workflow

راجع التخصيص للتفاصيل.

---

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

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

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

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/
│       ├── openspec-sync-specs/
│       └── ...                   # الملف الموسع يضيف new/continue/ff/etc.
├── 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 الكامل