المخططات

غيّر ما ينتجه OpenSpec: المخرجات، ترتيبها، وقوالبها.

يُعرِّف المخطط ما ينتجه اقتراح التغيير: أي المخرجات، وبأي ترتيب، ومن أي قوالب. على سبيل المثال، spec-driven، المخطط الافتراضي المضمَّن، ينتج هذه المخرجات الأربع بهذا الترتيب تقريبًا، حيث يبني كل منها على ما سبقه:

proposal → specs → design → tasks

قم باستنساخ المخطط عندما تريد أن تكون هذه مستندات مختلفة، سواء كان ذلك يعني أقل عدد منها، أو أسماء مختلفة، أو هيكل مختلف.

أين تعيش المخططات

يبحث OpenSpec عن المخطط في ثلاثة أماكن، بالترتيب، ويستخدم أول ما يجده:

1. مشروعك: openspec/schemas/، مُلتزَم مع المستودع بحيث يحصل عليه فريقك بأكمله.
2. جهازك: ~/.local/share/openspec/schemas على macOS و Linux (أو تحت $XDG_DATA_HOME إذا قمت بتعيينه)، أو %LOCALAPPDATA%\openspec\schemas على Windows. المخططات هنا متاحة في كل مشروع تعمل فيه.
3. الحزمة: المخططات المضمَّنة، مثل spec-driven، تأتي داخل openspec نفسه.

يمكن أن يوجد نفس الاسم في أكثر من مكان، والموقع الأكثر تحديدًا هو الذي يفوز. يُظهر openspec schema which أي نسخة قيد الاستخدام:

$ openspec schema which spec-driven
Schema: spec-driven
Source: project
Path: /your-project/openspec/schemas/spec-driven

Shadows:
  package: .../openspec/schemas/spec-driven

ما الذي يحتويه المخطط

يُعرَّف المخطط بمجلد من الملفات العادية: ملف schema.yaml واحد يُصرِّح بالمخرجات، وقالب لكل منها. إليك المخطط المضمَّن spec-driven:

spec-driven/
├── schema.yaml
└── templates/
    ├── proposal.md
    ├── spec.md
    ├── design.md
    └── tasks.md

• schema.yaml: يُصرِّح بكل مخرَج، والملف الذي يولّده، والقالب الذي يبدأ منه، وما يتطلبه أولاً، والتعليمات التي يتلقاها الوكيل عند إنشائه. عقد كل حقل موجود في schema.yaml.
• templates/: هيكل markdown واحد لكل مخرَج، يملؤه الوكيل.

إليك إدخال مخرَج tasks في schema.yaml، بشكل مختصر:

artifacts:
  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    instruction: |
      ...what the agent is told when creating tasks.md...
    requires:
      - specs
      - design

المخططات المضمَّنة تأتي داخل حزمة openspec، لذلك لا تعدّلها أبدًا في مكانها. تحصل على نسختك الخاصة عن طريق الاستنساخ.

إنشاء مخطط مخصص خاص بك

هناك طريقتان للحصول على مخططك الخاص:

1. استنساخ مخطط موجود وتعديل نسختك. ابدأ هنا عندما يكون مخطط موجود قريبًا مما تريد، لأن كل شيء فيه يعمل بالفعل.
2. البدء من الصفر عندما لا يناسبك أي منها، بإنشاء مخطط فارغ عبر openspec schema init.

استنساخ مخطط موجود

1. استنسخ المخطط الذي تريد البدء منه، بتشغيل الأمر من جذر مشروعك:

   $ openspec schema fork spec-driven
   
   Note: Schema commands are experimental and may change.
   ✔ Forked 'spec-driven' to 'spec-driven-custom'
   
   Source: .../openspec/schemas/spec-driven (package)
   Destination: /your-project/openspec/schemas/spec-driven-custom

   مرّر وسيطًا ثانيًا لاختيار الاسم (openspec schema fork spec-driven team-flow). الأسماء بصيغة kebab-case.

2. عدّل النسخة: schema.yaml والقوالب. تحرير الاستنساخ يغطي ما يجب تغييره.

3. تحقق من صحته:

   openspec schema validate spec-driven-custom

   هذا هو الأمر الوحيد الذي يكتشف المخطط المكسور (قوالب مفقودة، YAML غير صالح، دورات تبعية) قبل أن تكون في منتصف تغيير.

4. وجّه مشروعك إليه في openspec/config.yaml. هذه الخطوة متروكة لك لأن fork لا يلمس config.yaml:

   schema: spec-driven-custom

5. اقتراحات التغيير الجديدة تتبع الآن مخططك. التغييرات التي أُنشئت سابقًا تحتفظ بالمخطط الذي بدأت به.

لاستبدال المخطط الافتراضي في كل مكان دون لمس config.yaml، استنسخ بنفس الاسم: openspec schema fork spec-driven spec-driven. نسخة مشروعك عندئذٍ تُحجب أمام المضمَّن، كما يوضح أين تعيش المخططات.

البدء من الصفر

يُنشئ openspec schema init مخططًا جديدًا بدلاً من نسخ واحد:

$ openspec schema init lite --description "Lite flow" --artifacts proposal,tasks

✔ Created schema 'lite'
Schema created at: /your-project/openspec/schemas/lite
Artifacts: proposal, tasks

الهيكل الجديد عارٍ. المخرجات تأتي من المعرفات الأربع المضمَّنة فقط، والقوالب المولّدة لا تحمل أي تعليمات، لذلك يحصل الوكيل على إرشاد أقل حتى تكتب تعليماتك الخاصة. من هناك تنطبق خطوات الاستنساخ دون تغيير: تحقق من صحته، ثم وجّه config.yaml إليه.

تحرير الاستنساخ

يحتوي الاستنساخ على نوعين من الملفات لتعديلها:

• templates/ تغيّر هيكل كل مستند. أضف قسمًا إلى قالب tasks وسيبدأ كل tasks.md جديد به. أبقِ عنوان # في السطر الأول: المخرَج يرثه، لذلك يُفتح كل ملف مُولَّد كمستند بعنوان.
• schema.yaml يغيّر سير العمل نفسه: أي المخرجات موجودة، وما يتطلبه كل منها أولاً، والتعليمات التي يتلقاها الوكيل عند إنشائه.

على سبيل المثال، لإسقاط مستند design لسير عمل أكثر نحافة:

1. احذف إدخال design من schema.yaml.

2. أزل design من قائمة requires الخاصة بـ tasks.

3. تحقق من الصحة:

   $ openspec schema validate spec-driven-custom
   
   ✓ Schema 'spec-driven-custom' is valid

تجاوز الخطوة 2 ويكتشفها التحقق:

✗ Schema 'spec-driven-custom' has errors:
  error: Invalid dependency reference in artifact 'tasks': 'design' does not exist

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

الاستنساخ هو لقطة

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

مشاركة المخططات

مشاركة المخطط تعني نسخ مجلده.

• مع فريقك: التزم openspec/schemas/ ويستخدمه الجميع في المستودع.
• عبر مشاريعك: ضع المجلد في دليل مستوى المستخدم من أين تعيش المخططات.
• من المجتمع: فهرس المجتمع يسرد المخططات المشتركة. انسخ واحدًا إلى openspec/schemas/<name> ويعمل مثل مخططك الخاص.

نعمل على سجل مخططات، عام وخاص، بحيث يمكن تثبيت المخططات بالاسم بدلاً من نسخها يدويًا.

استخدم OpenSpec مع Superpowers

مخطط superpowers-bridge الذي يحافظ عليه المجتمع يربط مخرجات OpenSpec بمهارات تنفيذ Superpowers. اتبع ملاحظات تثبيت الجسر والتوافق قبل نسخه إلى مشروعك.

الجسر مُصدَر خارج OpenSpec. OpenSpec لا يختبر تكامله مع Superpowers ولا يدير إصداراته.