schema.yaml

كل حقل في تعريف المخطط، لقراءته أو كتابته.

يسرد schema.yaml ملفات التخطيط التي ينشئها سير العمل. كما يحدد ترتيبها ونقل المهام إلى التنفيذ.

الموقع

يقع مخطط المشروع تحت openspec/schemas/<name>/:

openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

يتحقق OpenSpec من ثلاثة أماكن لهذا المجلد. يُستخدم أول تطابق.

النسخة	المجلد
1. المشروع	<project>/openspec/schemas/<name>/
2. المستخدم، macOS و Linux	~/.local/share/openspec/schemas/<name>/
2. المستخدم، Windows	%LOCALAPPDATA%\openspec\schemas\<name>\
3. الحزمة	المخططات المثبتة مع CLI

إذا تم تعيين XDG_DATA_HOME، ينتقل مجلد المستخدم إلى $XDG_DATA_HOME/openspec/schemas/<name>/ على كل منصة.

اسم المجلد هو مفتاح البحث المستخدم بواسطة --schema و config.yaml و .openspec.yaml. إذا اختلف حقل name عن اسم المجلد، لا يزال OpenSpec يستخدم اسم المجلد للبحث.

openspec schema which <name> يطبع المجلد النشط وأي نسخ أدنى أولوية يخفيها.

الحقول الرئيسية

الحقل	العقد
name	مطلوب. سلسلة نصية غير فارغة تُخزن كاسم المخطط. البحث لا يزال يستخدم اسم المجلد.
version	مطلوب. عدد صحيح موجب يُخزن كإصدار المخطط. القيمة لا تغير سلوك OpenSpec.
description	سلسلة نصية اختيارية تطبعها openspec schemas. بدون قيمة، لا يحتوي المخطط على وصف.
artifacts	مطلوب. قائمة غير فارغة من إدخالات المخرجات.
apply	إعدادات التطبيق اختيارية. بدون كتلة، يستخدم OpenSpec إعدادات التطبيق الافتراضية.

حقول المخرجات

كل إدخال تحت artifacts يحدد ملف تخطيط واحد أو مجموعة ملفات.

الحقل	العقد
id	مطلوب. سلسلة نصية فريدة وغير فارغة تُستخدم في التبعيات وقواعد المشروع والأوامر وإعدادات التطبيق.
generates	مطلوب. مسار نسبي أو نمط glob يخبر الوكيل أين يكتب المخرج داخل مجلد التغيير.
description	مطلوب. سلسلة نصية تصف المخرج في التعليمات المرسلة إلى الوكيل.
template	مطلوب. مسار نسبي لتنسيق المخرج في مجلد templates/ الخاص بالمخطط.
instruction	توجيه اختياري يخبر الوكيل بالمحتوى المطلوب إنتاجه.
requires	قائمة بمعرفات المخرجات التي يجب أن تكتمل أولاً. الافتراضي: [].

generates

يبدأ المسار من مجلد التغيير. لتغيير اسمه add-auth:

generates: proposal.md

يذهب المخرج هنا:

openspec/changes/add-auth/proposal.md

يمكن لنمط glob أن يطابق عدة ملفات:

generates: specs/**/*.md

هذا يطابق ملفات Markdown تحت openspec/changes/add-auth/specs/.

يتعرف OpenSpec على أشكال glob التالية في generates:

• أحرف البدل وفئات الأحرف: قيم تحتوي على * أو ? أو [، مثل specs/**/*.md و review-[ab].md.
• توسيعات الأقواس: بدائل مثل review-{api,ui}.md ونطاقات مثل file-{1..3}.md.
• Extglobs: أنماط مثل @(proposal|design).md و +(proposal|design).md و !(proposal|design).md.

أسماء الملفات الحرفية: لا تجعل ! في البداية وحدها نمط glob. استخدم generates: '!review.md' لتسمية ذلك الملف. الأقواس العادية مثل (proposal|design).md والأقواس المفردة مثل review-{api}.md تبقى حرفية أيضاً.

يرفض OpenSpec المسارات المطلقة والمسارات التي تحتوي على جزء .. وأنماط glob التي تضم أقواساً أو أقواساً متداخلة أكثر من 16 مستوى، مثل {a,{b,{c,...}}}. الأنماط الحقيقية تحتاج إلى مستوى أو مستويين. كما يرفض نمط glob الذي تتوسع أقواسه إلى أكثر من 1,024 نمط، مثل {a,b} مكرر إحدى عشرة مرة أو نطاق مثل file-{1..5000}.md. يقول الخطأ Artifact output pattern expands to more than 1024 patterns. الأنماط الحقيقية تتوسع إلى عدد قليل.

الإكمال

يتحقق OpenSpec مما إذا كان المخرج موجوداً. لا يقرأ الملف لتحديد ما إذا كان المخرج مكتملاً.

قيمة generates	يكتمل عندما
proposal.md	يكون ذلك الملف موجوداً.
specs/**/*.md	يطابق نمط glob ملفاً واحداً على الأقل.

template

يبدأ المسار من مجلد templates/ الخاص بالمخطط. في مخطط review-first:

template: proposal.md

يقرأ OpenSpec هذا الملف:

openspec/schemas/review-first/templates/proposal.md

يوفر OpenSpec محتويات القالب للوكيل كتنسيق المخرج. لا ينسخ القالب إلى مجلد التغيير.

يرفض OpenSpec المسارات المطلقة والمسارات التي تحتوي على جزء ...

requires

• التبعيات: يجب أن يحدد كل معرف في requires مخرجاً آخر في نفس المخطط.
• حالة الجاهزية: يصبح المخرج جاهزاً بعد اكتمال جميع تبعياته.
• الرسوم البيانية غير الصالحة: تفشل عملية التحقق في حالة معرفات مفقودة أو معرفات مكررة أو دورات تبعية.
• التعادل: عندما تكون عدة مخرجات جاهزة، يحدد ترتيبها في artifacts أي منها يعيده OpenSpec أولاً.

حقول التطبيق

يحدد apply ما يجب أن يكون موجوداً قبل بدء التنفيذ.

الحقل	العقد
requires	مطلوب. قائمة غير فارغة من المخرجات التي يجب أن تكون موجودة قبل أن تصبح تعليمات التطبيق جاهزة.
tracks	مسار نسبي أو نمط glob اختياري لملفات مهام Markdown في مجلد التغيير. الافتراضي: null.
instruction	توجيه اختياري يُرسل إلى الوكيل عندما يصبح التطبيق جاهزاً. يستخدم OpenSpec توجيهات مدمجة افتراضياً.

يتحكم requires الخاص بالمخرجات في ترتيب التخطيط. يتحكم apply.requires في متى تصبح تعليمات التطبيق جاهزة.

tracks

يبدأ المسار من مجلد التغيير. لتغيير اسمه add-auth، tracks: tasks.md يقرأ:

openspec/changes/add-auth/tasks.md

نمط glob مثل tracks: "**/tasks.md" يقرأ كل ملف مطابق، مثل backend/tasks.md و frontend/tasks.md. يجمع OpenSpec مهامهم وتقدمهم. استخدم نفس القيمة لحقل generates الخاص بالمخرج لتتبع الحالة والقائمة لنفس الملفات. تنطبق حدود الأقواس من generates (16 مستوى، 1,024 نمط موسع) هنا أيضاً.

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

- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

أي علامة قائمة Markdown تعمل: - أو * أو + أو رقم يتكون من تسعة أرقام على الأكثر متبوعاً بـ . أو ). المسافات البادئة مسموح بها. قسم tasks.md في صفحة التطوير بالمخطط يحدد التنسيق الأكثر صرامة الذي ينتجه المخطط الافتراضي.

الملفات المتتبعة تقود حالة التطبيق:

• blocked: لا يوجد ملف متطابق، أو لا يوجد ملف قابل للقراءة يحتوي على مربع اختيار مع نص مهمة.
• ready: مهمة واحدة على الأقل معلقة، أو تعذرت قراءة ملف متطابق بينما يوفر آخر مهاماً.
• all_done: كل مهمة متتبعة محددة وكل ملف متطابق تمت قراءته.

إذا تعذرت قراءة ملف متطابق، يحتفظ التطبيق بالمهام والتقدم من الملفات القابلة للقراءة ولكنه لا يضع علامة all_done على التغيير. مخرجات JSON للتطبيق تحدد كل ملف غير متاح والسبب.

يرفض OpenSpec المسارات المطلقة والمسارات التي تحتوي على جزء ...

إعدادات التطبيق الافتراضية

السلوك	الافتراضي
المخرجات المطلوبة	كل مخرج في المخطط
تتبع التقدم	لا يوجد ملف متتبع
توجيه الوكيل	توجيه التطبيق المدمج

مثال كامل

name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

التحقق

openspec schema validate <name> يتحقق من:

• أنواع الحقول والحقول المطلوبة
• المسارات النسبية
• معرفات المخرجات والتبعيات والدورات
• معرفات apply.requires: يجب أن يكون كل منها مخرجاً في المخطط
• ملفات القوالب

المخطط الذي يحتوي على معرف apply.requires غير معروف لا يتم تحميله، لذا تُبلغ كل أمر يستخدمه عن الخطأ.

يصدر التحقق تحذيراً، دون فشل، عندما لا يكون apply.tracks مساوياً تماماً لقيمة generates لأحد المخرجات. يجد OpenSpec المخرج المتتبع بمقارنة هاتين السلسلتين، لذا فإن أي شيء آخر يتركه غير قادر على تحديد تقدم أي مخرج ينتمي إليه الملف. وهذا يشمل خطأ إملائياً مثل task.md، وأيضاً tracks: tasks/main.md مقابل generates: tasks/*.md، حيث ينتج نمط glob الملف لكن السلسلتين لا تزالان مختلفتين. يستمر التطبيق في قراءة الملف على أي حال، لكن openspec list و openspec status يحسبان tasks.md بدلاً من ذلك.

لا يكتشف التحقق هذه الأخطاء:

الخطأ	ما يحدث
حقل به خطأ إملائي، مثل instrution	يتجاهله OpenSpec. لا يُبلغ التحقق عن الخطأ الإملائي.
يختلف name عن مجلد المخطط	ينجح التحقق. لا يزال OpenSpec يستخدم اسم المجلد للبحث.