OpenSpec

الترحيل إلى OPSX ​

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

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

يستبدل OPSX سير العمل المقفل بالمرحلة (phase-locked) القديم بنهج مرن قائم على الإجراءات. إليك التغيير الجوهري:

الجانبالقديم (Legacy)OPSX
الأوامر/openspec:proposal، /openspec:apply، /openspec:archiveالافتراضي: /opsx:propose، /opsx:explore، /opsx:apply، /opsx:update، /opsx:sync، /opsx:archive (أوامر سير العمل الموسعة اختيارية)
سير العملإنشاء جميع العناصر دفعة واحدةالإنشاء تدريجياً أو دفعة واحدة—حسب اختيارك
العودة للخلفحواجز مراحل غير مريحةطبيعي—يمكنك تحديث أي عنصر في أي وقت
التخصيصهيكل ثابتقائم على المخطط (Schema-driven)، وقابل للتعديل بالكامل
التكوين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
  • Devin Desktop، سابقاً 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)
  • Codex: يستخدم OpenSpec الآن المسار القياسي .agents/skills/openspec-*. ملفات SKILL.md المُدارة من OpenSpec تحت المسار السابق .codex/skills تُسوّى فقط بعد وجود البدائل؛ الملفات المخصصة والنسخ المختلفة تبقى في مكانها. إذا كان شجرة .agents غير مُعلَّمة تحتوي بالفعل على مهارات OpenSpec، يحافظ OpenSpec على العرض الحالي لـ Codex ($openspec-*) أو العام (/openspec-*) بدلاً من التخمين من المجلد القديم. اختر codex صراحةً باستخدام openspec init لتبديل الملكية. تنظيف الأوامر القديمة يستهدف فقط أسماء ملفات 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، update، sync، archive).
  • التثبيتات المُرحَّلة تحافظ على سير عملك المثبّت سابقاً عن طريق كتابة ملف custom عند الحاجة.

استخدام openspec init ​

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

bash
openspec init

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

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

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

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

استخدام openspec update ​

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

bash
openspec update

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

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

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

bash
openspec init --force --tools claude

العلم --force يتخطى الاستفسارات ويقبل التنظيف تلقائياً.

يشمل هذا تنظيف ملفات أوامر Codex المُدارة من OpenSpec في مجلد أوامر Codex العام. التنظيف يستهدف فقط أسماء ملفات أوامر Codex القديمة المُصرَّح بها من OpenSpec، ويحذفها فقط بعد وجود بدائل .agents/skills/openspec-*، ويحافظ على جميع الملفات الأخرى.

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

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

قبل (project.md) ​

markdown
# 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) ​

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.mdconfig.yaml
نص markdown حرYAML مُنظَّم
كتلة نص واحدةسياق منفصل وقواعد لكل مخرج
غير واضح متى يُستخدمالسياق يظهر في جميع المخرجات؛ القواعد تظهر فقط في المخرجات المطابقة
لا يوجد اختيار مخططحقل schema: صريح يحدد سير العمل الافتراضي

ما الذي تُبقيه، وما الذي تتخلى عنه ​

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

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

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

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

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

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

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

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

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

    yaml
    schema: spec-driven

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

    yaml
    context: |
  Your project background goes here.
  Focus on what the AI genuinely needs to know.

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

    yaml
    rules:
  proposal:
    - Your proposal-specific guidance
  specs:
    - Your spec-writing rules

  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:updateمراجعة مخرجات تخطيط التغيير وإبقائها متماسكة
/opsx:syncدمج مواصفات الدلتا في المواصفات الرئيسية
/opsx:archiveإنهاء التغيير وأرشفته

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

الأمرالغرض
/opsx:newبدء هيكل تغيير جديد
/opsx:continueإنشاء المخرج التالي (واحد في كل مرة)
/opsx:ffتسريع—إنشاء مخرجات التخطيط دفعة واحدة
/opsx:verifyالتحقق من مطابقة التنفيذ للمواصفات
/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
└── ...

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

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

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

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

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

/opsx:apply add-my-feature

يقوم OPSX بقراءة العناصر الناتجة الموجودة ويستمر من حيث توقفت.

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

/opsx:continue add-my-feature

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

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

bash
openspec status --change add-my-feature

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

هيكل config.yaml ​

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. علم سطر الأوامر: --schema <name> (أعلى أولوية)
  2. بيانات التعريف للتغيير: .openspec.yaml في دليل التغيير
  3. تكوين المشروع: openspec/config.yaml
  4. الافتراضي: spec-driven

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

المخططالعناصر الناتجةالأنسب لـ
spec-drivenproposal → specs → design → tasksمعظم المشاريع

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

bash
openspec schemas

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

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

bash
openspec schema init my-workflow

أو استنسخ واحدًا موجودًا:

bash
openspec schema fork spec-driven my-workflow

انظر التخصيص للحصول على التفاصيل.

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

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

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

bash
openspec init --force

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

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

"معرف عنصر ناتج غير معروف في القواعد" ​

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

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

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

bash
openspec schemas --json

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

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

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

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

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

قم بتشغيل التهيئة وامتنع عن قبول طلب التنظيف—سترى ملخص الكشف الكامل دون إجراء أي تغييرات.

مرجع سريع ​

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

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-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # 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، إلخ.

ورقة غش للأوامر ​

text
/opsx:propose      Start quickly (default core profile)
/opsx:apply        Implement tasks
/opsx:archive      Finish and archive

# Expanded workflow (if enabled):
/opsx:new          Scaffold a change
/opsx:continue     Create next artifact
/opsx:ff           Create planning artifacts

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