المخازن: التخطيط في مستودع خاص به

نسخة تجريبية. المخازن والمراجع وسياق العمل ومجموعات العمل هي ميزات جديدة. قد تتغير أشكال أسماء الأوامر والأعلام وتنسيقات الملفات والمخرجات بصيغة JSON بين الإصدارات. تم تشغيل كل شرح أدناه ضد الإصدار الحالي، لكن أعد قراءة هذا الدليل بعد الترقية.

المشكلة التي يحلها هذا

يعيش OpenSpec عادةً داخل مستودع كود واحد: مجلد openspec/ بجانب كودك، يحتوي على المواصفات والتغييرات لذلك المستودع.

تتوقف هذه الطريقة عن الملاءمة في اللحظة التي يصبح فيها تخطيطك أكبر من مستودع واحد:

• عملك يمتد عبر عدة مستودعات — ميزة واحدة تلامس خادم الـ API وتطبيق الويب ومكتبة مشتركة. في أي مجلد openspec/ تعيش الخطة؟
• فريقك يخطط قبل وجود الكود، أو يخطط أشياء لن تتحول إلى كود في هذا المستودع.
• المتطلبات يملكها فريق واحد ويستهلكها آخرون. نسخة الويكي تتغير، ووكيل البرمجة الخاص بك لا يستطيع قراءتها على أي حال.

المخزن هو الحل: مستودع مستقل وظيفته الوحيدة هي التخطيط. لديه نفس شكل openspec/ الذي تعرفه بالفعل — مواصفات وتغييرات — إضافةً إلى ملف هوية صغير. تسجله على جهازك مرة واحدة بالاسم، ثم كل أمر OpenSpec عادي يمكنه العمل فيه من أي مكان.

الشكل

            team-plans  (مخزن: التخطيط في مستودع خاص به)
            ├── .openspec-store/store.yaml     الهوية: "أنا team-plans"
            └── openspec/
                ├── specs/      ما هو صحيح
                └── changes/    ما هو قيد التنفيذ
                      ▲
                      │ مسجل على كل جهاز بالاسم؛
                      │ مشترك عبر الدفع/السحب مثل أي مستودع
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (مستودع كود)   (مستودع كود)   (مستودع كود)

قاعدتان تحافظان على البساطة:

1. المخزن هو مجرد مستودع Git. تقوم بالالتزام والدفع والسحب والمراجعة بنفسك. لا يقوم OpenSpec بالاستنساخ أو المزامنة أو الدفع بمفرده أبدًا.
2. تصريحات، وليس آليات. يمكن للمستودعات التصريح بكيفية ارتباطها بالمخازن (موضح أدناه). التصريحات تغير ما يمكن أن يخبرك به OpenSpec — وليس أين تنفذ أوامرك.

خمس دقائق حتى أول مخزن

أمران يأخذانك من لا شيء إلى تغيير عامل ومحدود بنطاق المخزن:

openspec store setup team-plans --path ~/openspec/team-plans

المخزن جاهز: team-plans
الموقع: /Users/you/openspec/team-plans
جذر OpenSpec: جاهز
السجل: مسجل

التالي: قم بتشغيل أوامر OpenSpec العادية على هذا المخزن، على سبيل المثال:
  openspec new change <change-id> --store team-plans
شارك هذا المخزن عن طريق الالتزام والدفع مثل أي مستودع Git.

openspec new change add-login --store team-plans

استخدام جذر OpenSpec: team-plans (/Users/you/openspec/team-plans)
تم إنشاء التغيير 'add-login' في /Users/you/openspec/team-plans/openspec/changes/add-login/
المخطط: مدفوع بالملخصات
التالي: openspec status --change add-login --store team-plans

هذا هو النموذج بأكمله. من هنا، دورة الحياة هي بالضبط ما تعرفه — status وinstructions وvalidate وarchive — مع --store team-plans في كل أمر، وكل تلميح مطبوع يحمل العلامة لك. سطر Using OpenSpec root: يخبرك دائمًا أين يعمل الأمر.

قصة: فريق واحد، مستودع تخطيط واحد

يحتفظ الفريق بمواصفاته وتغييراته في team-plans بدلاً من نشرها عبر مستودعات الكود.

اليوم الأول (من يقوم بالإعداد):

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

تمرير --remote يسجل عنوان URL للاستنساخ داخل ملف هوية المخزن نفسه (.openspec-store/store.yaml)، في الالتزام الأول. كل استنساخ مستقبلي يُولد وهو يعرف مصدره، بحيث يمكن لفحوصات الصحة ورسائل الأخطاء طباعة إصلاح كامل وقابل للصق لزملاء الفريق الذين لا يملكونه بعد.

كل عضو في الفريق (مرة واحدة لكل جهاز):

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

منذ ذلك الحين، يعمل الجميع في نفس مستودع التخطيط بالاسم:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

مشاركة العمل هي Git، عن قصد. التغيير الذي تنشئه موجود فقط في نسختك المحلية حتى تلتزم وتدفعه — تمامًا مثل الكود. تحصل الخطط على فروع وطلبات سحب ومراجعة مجانًا، لأن المخزن هو مستودع عادي.

ربط مستودعات كود الفريق. مستودع الكود الذي يتم تخطيطه خارجيًا بالكامل يحتاج سطرًا واحدًا بالضبط، في openspec/config.yaml:

# web-app/openspec/config.yaml
store: team-plans

الآن كل أمر OpenSpec يُنفذ داخل web-app يعمل على team-plans بدون أي علامات إضافية:

cd ~/src/web-app
openspec status --change add-login

استخدام جذر OpenSpec: team-plans (/Users/you/openspec/team-plans)
...

المؤشر هو ارتداد، وليس تجاوزًا أبدًا: --store الصريح يفوز دائمًا، وإذا كان المستودع يحتوي على مجلدات تخطيط فعلية خاصة به، فهذه تفوز (مع تحذير لإزالة المؤشر القديم).

افتراضي واحد لكل مستودع على جهازك. إذا كنت تعمل عبر العديد من مستودعات الكود التي تخطط جميعها في نفس المخزن، قم بضبطه مرة واحدة، بشكل عام، بدلاً من إضافة سطر store: إلى كل مستودع:

openspec config set defaultStore team-plans

الآن أي أمر يُنفذ خارج جذر تخطيط — بدون --store وبدون مؤشر مشروع — سيحل إلى team-plans. يقع في أسفل قائمة الأولوية، لذا --store والجذر المحلي ومؤشر store: للمشروع كلها لا تزال تفوز. يعرض لافتة الجذر وكتلة JSON root تقرير source: "global_default" مع معرف المخزن، بحيث يمكنك دائمًا تمييز افتراضي على مستوى الجهاز عن مؤشر المستودع الخاص. قم بمسحه باستخدام openspec config unset defaultStore. إذا لم يكن المعرف مسجلاً، تُظهر الأوامر خطأ وتطلب منك تسجيله أو مسح الافتراضي القديم.

مثال: ميزة واحدة، مستودعان مكونان

لنفترض أن add-checkout-promo يغير كلاً من checkout-api وcheckout-web. يريد الفريق عقد منتج مشترك واحد، بينما لا يزال كل مستودع كود يحتاج إلى مهام التنفيذ الخاصة به، وفرعه، ومراجعته.

استخدم طبقتين:

1. احتفظ بالسلوك المشترك في team-plans.
2. احتفظ بخطط التنفيذ في كل مستودع مكون وأشر إلى المخزن كسياق علوي للقراءة فقط.

أولاً، خطط للعقد المشترك في المخزن:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

يجب أن يصف الاقتراح والمواصفات السلوك عند الحدود بين المكونات — على سبيل المثال، حقول الترويج التي يعيدها الخدمة وكيف يعالج الواجهة الأمامية عملية دفع غير مؤهلة. راجع هذا التغيير في مستودع المخزن مثل أي فرع وطلب سحب آخر.

ما السياق الذي يراه التخطيط؟

تغيير المخزن يغير جذر OpenSpec؛ لا يكتشف أو يقرأ كل مستودع كود يستخدم ذلك المخزن. تعليمات المخزن ترى القطع الأثرية والسياق المكوّن في المخزن. ترى كود المكونات فقط عندما تكون تلك المجلدات متاحة أيضًا للوكيل أو المحرر ويقرأها الوكيل.

مجموعة العمل هي طريقة ملائمة لفتح مخزن التخطيط ومستودعي الكود معًا:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

هذا يجعل المجلدات مرئية في مساحة عمل IDE واحدة. لا ينسخ سياق المصدر إلى المخزن، ولا يحدد المستودعات المتأثرة، ولا يمنح الوكيل إذنًا لتحريرها. ضع الحقائق الدائمة عبر المكونات في المواصفات المشتركة؛ لا تعتمد على أن المخطط يتذكر المصدر الذي صادفه بالصدفة.

كيف يبدأ التنفيذ في كل مستودع؟

عند عدم وجود --store صريح أو جذر openspec/ أقرب، يقوم مؤشر store: team-plans بتوجيه الأوامر إلى ذلك المخزن. لا يقسم قائمة مهام المخزن الواحد حسب الدليل الذي تم استدعاء apply منه. لا يقوم OpenSpec حاليًا بتوجيه المهام إلى المستودعات.

عندما يحتاج كل مكون إلى دورة تطبيق/مراجعة مستقلة، امنحه جذر OpenSpec محليًا وأشر إلى المخزن المركزي بدلاً من الإشارة إليه:

# checkout-api/openspec/config.yaml (وكذلك في checkout-web)
schema: spec-driven
references:
  - team-plans

بعد الموافقة على العقد المشترك وتوفره في المواصفات الرئيسية للمخزن، أنشئ تغييرًا محليًا صغيرًا للجزء الخاص بالمكون:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

فهرس المرجع في تعليمات كل مستودع يوفر ملخص مواصفة المخزن وأمر الجلب الدقيق openspec show ... --store team-plans. كل اقتراح محلي يستشهد بذلك العقد المشترك، ومهامه تصف فقط العمل في ذلك المكون. ثم قم بتشغيل /opsx:apply في كل مستودع بشكل منفصل؛ يبقي دقة الجذر القطع الأثرية وتعديلات التنفيذ مقتصرة على ذلك المستودع. يمكن الآن اختبار تغييرات الخدمة والواجهة الأمامية ومراجعتها ودمجها وأرشفتها بشكل مستقل.

إذا كان يجب أن يبدأ التنفيذ بينما التغيير المشترك في المخزن لا يزال نشطًا، قم بجلبه صراحةً باستخدام openspec show add-checkout-promo --store team-plans؛ فهارس المراجع تسرد مواصفات المخزن الأساسية، وليس التغييرات النشطة في المخزن. اربط فرع المخزن وفروع المكونات في أوصاف طلبات السحب الخاصة بها بحيث يمكن للمراجعين رؤية إصدار العقد الذي يتبعه كل تنفيذ.

قصة: متطلبات تتجاوز حدود الفريق

فريق المنصة يملك المتطلبات. فرق المنتج تبني وفقًا لها، في مستودعاتها الخاصة، بتصاميمها الخاصة. يصف المرجع تلك العلاقة دون نقل عمل أي شخص.

   platform-reqs (مخزن)                 api-server (مستودع كود)
   مملوك لفريق المنصة                    مملوك لفريق المنتج
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ يقرأ     │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (تصاميمهم الخاصة)      │
   │   عمل المنصة             │          │ openspec/changes/        │
   │                          │          │   (عملهم الخاص)         │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

فريق المنتج يصرح بما يعتمد عليه في openspec/config.yaml لمستودعه:

references:
  - platform-reqs

المراجع هي سياق للقراءة فقط. يحتفظ المستودع بجذر openspec/ الخاص به؛ يبقى العمل هناك. ما يتغير: openspec instructions في ذلك المستودع يتضمن الآن فهرسًا لمواصفات المخزن المُشار إليه — كل منها بملخص من سطر واحد وأمر الجلب الدقيق (openspec show <spec-id> --type spec --store platform-reqs). الوكيل الذي يعمل في api-server يمكنه العثور على متطلبات الدفع العلوية، والاستشهاد بها، وكتابة تصميمه منخفض المستوى في جذر المستودع الخاص به — دون أي شخص يلصق السياق حوله.

يمكن أن يحمل المرجع مصدر استنساخه، بحيث يحصل زملاء الفريق الذين لا يملكون المخزن بعد على إصلاح كامل بدلاً من طريق مسدود:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

عندما تريد فتح الخطة والكود معًا، أنشئ مجموعة عمل. هذا شخصي وصريح: كل شخص يختار المجلدات التي يعمل بها فعليًا على جهازه. لا يتم الالتزام بأي شيء من مسارات السحب المحلية هذه في مستودع التخطيط المشترك.

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

سؤالان يمكنك طرحهما دائمًا

"هل إعدادي سليم؟" — openspec doctor يفحص الجذر الحالي والمخازن المُشار إليها، للقراءة فقط، مع إصلاح قابل للصق لكل نتيجة:

الطبيب

الجذر
  الموقع: /Users/you/src/api-server
  جذر OpenSpec: جيد

المراجع
  - platform-reqs: جيد (/Users/you/openspec/platform-reqs)
  - design-system: المخزن المُشار إليه 'design-system' غير مسجل على هذا الجهاز.
    الإصلاح: git clone -- git@github.com:acme/design-system.git '/Users/you/openspec/design-system' && openspec store register '/Users/you/openspec/design-system' --id design-system

"بماذا أعمل؟" — openspec context يجمع مجموعة العمل من تصريحات OpenSpec: الجذر والمخازن التي يشير إليها.

سياق العمل لـ api-server (/Users/you/src/api-server)

جذر OpenSpec
  api-server  /Users/you/src/api-server

المخازن المُشار إليها
  platform-reqs  /Users/you/openspec/platform-reqs
    الجلب: openspec show <spec-id> --type spec --store platform-reqs

كلاهما يدعم --json للوكلاء. openspec context --code-workspace <path> يكتب أيضًا ملف مساحة عمل VS Code يحتوي المجموعة بأكملها — وهي الكتابة الوحيدة التي ينفذها هذا الأمر.

مجموعات العمل: إعادة فتح المجلدات التي تعمل عليها معاً

مستقلة عن كل ما سبق: يفتح معظم الأشخاص نفس عدد قليل من المجلدات معاً في كل جلسة — مستودع التخطيط بالإضافة إلى مستودعين أو ثلاثة للملفات البرمجية. مجموعة العمل (Workset) هي عرض شخصي ومسمى لهذا بالضبط، يتم إعادة فتحه بأمر واحد في الأداة التي تختارها.

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       جميعها مفتوحة في أداتك

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (يفتح في VS Code)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

ثم يقوم openspec workset open platform بتشغيل الأداة المحفوظة: تفتح محررات النصوص (مثل VS Code و Cursor) نافذة واحدة تحتوي على جميع الأعضاء ثم تعود. يعتبر العضو الأول هو الأساسي. يمكنك تجاوز الأداة في أي وقت باستخدام --tool <id>.

مجموعات العمل مصممة عمداً لتكون حالة غير مشتركة. فهي تعيش على جهازك، ولا يتم الالتزام بها أبداً، ولا تقدم أي ادعاءات حول العمل — بل تسجل فقط ما تفضله أن يكون مفتوحاً معاً. إزالة عضو لا يؤثر أبداً على مجلدات الأعضاء الأخرى. الأدوات الجديدة هي إعدادات وليست كوداً: يمكن إضافة أي شيء يتم تشغيله عبر ملف مساحة عمل أو أعلام إرفاق لكل مجلد تحت المفتاح openers في التكوين العالمي (openspec config edit).

كيف تقرر الأوامر أين تعمل

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

1. --store <id>          لقد قلت ذلك صراحة        → ذلك المستودع
2. nearest openspec/     جذر تخطيط حقيقي هنا     → هذا المستودع
   (بالصعود من cwd)
3. store: pointer        يعلن config.yaml عن مستودع → ذلك المستودع
4. defaultStore          يضبط التكوين العالمي آلة  → ذلك المستودع
                         الافتراضية
5. none of the above     هل هناك مستودعات مسجلة على هذه → خطأ مع
                         الآلة؟                      تلميح اختيار
                         لا توجد مستودعات مسجلة؟    → الدليل الحالي
                                                          (السلوك الكلاسيكي)

سطر Using OpenSpec root: (ومكتبة root في مخرجات --json) يخبرك بأي حالة أنت.

القيود المعروفة

• شكل تجريبي. قد يتغير كل شيء في هذه الصفحة بين الإصدارات — الأسماء، العلامات، تنسيقات الملفات، مفاتيح JSON.
• فحص واحد لكل معرف مستودع لكل آلة. فشل تسجيل فحص ثانٍ تحت نفس المعرف مع تلميح لاستخدام store unregister أولاً.
• لا مزامنة، أبداً — بتصميم. لا يقوم OpenSpec بالنسخ المتماثل أو السحب أو الدفع. يعرض الفحص القديم مواصفات قديمة حتى تقوم أنت بالسحب؛ يتم فهرسة المراجع مباشرة مما هو موجود على القرص.
• يمكن أن تكون مجلدات التخطيط الفارغة غائبة. قد لا يحتوي مستودع جديد على openspec/changes/ أو openspec/specs/ أو openspec/changes/archive/ في Git بعد. هذا مقبول خلال الفترة التجريبية؛ تظهر تلك المجلدات بمجرد إنشاء الأوامر العادية الملفات لها.
• تبقى مستودعات المؤشرات مؤشرات. يُعامل المستودع الذي يعتمد على التكوين فقط والذي يعلن openspec/config.yaml عن store: <id> كتخطيط خارجي، وليس كفحص مستودع لتسجيله. قم بإزالة سطر store: أولاً إذا كنت تريد عمداً تحويل ذلك المستودع إلى جذر مستودع محلي.
• بعض الأوامر تبقى حيث هي. تعمل templates والأسماء الاسمية القديمة (openspec change show، ...) على الدليل الحالي فقط — بدون --store. تتبع schemas أولوية تحديد الجذر القياسية وتقبل --store <id> مع الحفاظ على شكل مصفوفة JSON الناجحة دون تغيير.
• الحالة الخاصة بالآلة خاصة بالآلة. سجل المستودعات ومجموعات العمل هي إعدادات محلية. لا يتم الالتزام بأي شيء يتعلق بترتيب جهازك في التخطيط المشترك أبداً.
• أسلوبان للإطلاق لمجموعات العمل. لا يمكن إضافة أداة لا يمكن تشغيلها بملف مساحة عمل أو أعلام إرفاق لكل مجلد كمفتّح.
• للـ Agent JSON تقسيم معروف لحالة الأحرف (مفاتيح عائلة المستودع snake_case، وعائلة سير العمل camelCase). موثق في عقد الوكيل; تم تأجيل توحيده إلى إصدار مجدول.

أين توجد الأشياء

ماذا	أين	مشترك؟
تخطيط المستودع	<store>/openspec/ (المواصفات، التغييرات)	نعم — التزم به ودفعه
هوية المستودع	<store>/.openspec-store/store.yaml	نعم — ملتزم مع المستودع
سجل المستودعات	<data dir>/openspec/stores/registry.yaml	لا — هذه الآلة فقط
مجموعات العمل	<data dir>/openspec/worksets/	لا — هذه الآلة فقط

<data dir> هو ~/.local/share/openspec على macOS و Linux (أو $XDG_DATA_HOME/openspec عند تعيينه)، و %LOCALAPPDATA%\openspec على Windows.

المرجع

العلامات الدقيقة وأشكال JSON لكل أمر في هذه الصفحة: مرجع CLI (المستودعات، الطبيب، سياق العمل، مجموعات العمل الشخصية) و عقد الوكيل.