المهارات
كل مهارة من مهارات OpenSpec: الوسائط، وما تُنشئه، وما تستجيب به.
تأتي المهارات في مجموعتين:
- الأساسية: تُثبَّت افتراضيًا، وهي حلقة التخطيط الرئيسية.
- الاختيارية: تُثبَّت فقط عندما تضيفها، عبر الملفات التعريفية.
تتوقع كل مهارة مشروعًا يستخدم OpenSpec بالفعل. قبل أول خطوة تكتب فيها أي شيء، تتحقق المهارة من وجود جذر مُحلَّل. ويعتمد ما يحدث عند عدم وجوده على الطريقة التي وُصلت بها إلى المهارة:
- اختيار تلقائي: يختار وكيلك المهارة بنفسه، دون أن تذكر OpenSpec. يتخلى عن OpenSpec ويجيب على طلبك بشكل طبيعي، تمامًا كما لو لم يكن OpenSpec مثبتًا.
- طلب OpenSpec صريح: إذا ذكرت OpenSpec، أو ذكرت المهارة، أو شغّلت أمرها. يتوقف قبل الكتابة ويسأل عن كيفية المتابعة: تشغيل
openspec initهنا، أو استهداف مخزن باستخدام--store <id>، أو المتابعة بدون OpenSpec. وينتظر إجابتك.
الأوامر تمثل دائمًا الحالة الثانية. المشروع الذي يشير فيه openspec/config.yaml إلى مخزن لا تستطيع هذه الآلة حلّه (غير مسجل، أو سطر store: مشوّه) لا يُعامل بوصفه غير مُهيّأ: فتتوقف المهارة وتعرض خطأ المخزن مع كيفية إصلاحه. لا تنشئ أي مهارة دليل openspec/ بمفردها في أي من الحالتين. تصف الإدخالات أدناه ما تفعله كل مهارة بمجرد أن يصبح الجذر موجودًا.
| المهارة | المهمة | النوع |
|---|---|---|
| openspec-explore | التفكير في فكرة قبل أن تصبح مقترح تغيير | أساسية |
| openspec-propose | إنشاء مقترح تغيير مع جميع مخرجات التخطيط الخاصة به في خطوة واحدة | أساسية |
| openspec-apply-change | تنفيذ مهام مقترح التغيير | أساسية |
| openspec-update-change | مراجعة خطة مقترح التغيير | أساسية |
| openspec-sync-specs | دمج تحديثات مواصفات مقترح التغيير في specs/ | أساسية |
| openspec-archive-change | نقل مقترح تغيير مكتمل إلى الأرشيف | أساسية |
| openspec-new-change | بدء مقترح تغيير كهيكل مبدئي فارغ | اختيارية |
| openspec-continue-change | إنشاء مخرج التخطيط التالي، واحدًا في كل مرة | اختيارية |
| openspec-ff-change | إنشاء مقترح تغيير مع كل مخرج يحتاجه التنفيذ، في تمريرة واحدة | اختيارية |
| openspec-verify-change | التحقق من أن التنفيذ يطابق الخطة | اختيارية |
| openspec-bulk-archive-change | أرشفة عدة مقترحات تغيير دفعة واحدة | اختيارية |
| openspec-onboard | تعلّم سير العمل من خلال تنفيذ مقترح تغيير حقيقي من البداية إلى النهاية | اختيارية |
يذكر كل إدخال أدناه المهارة التي تمتلك الخطوة التالية. عندما يغفل ملفك التعريفي تلك المهارة، لا تذكر الملفات المثبتة اسمها أبدًا: ويصبح التسليم أمر openspec المكافئ، أو طلبًا مباشرًا إليك، أما السطر الذي لا وجود له إلا للإشارة إلى مهارة مفقودة فلا يُكتب على الإطلاق. وبذلك، فإن المهارات التي تملكها تسلم دائمًا إلى مهارات تملكها. والمجموعة التي تحصل عليها تُحدد عبر الملفات التعريفية.
openspec-explore
فكّر في فكرة قبل أن تصبح اقتراح تغيير.
| Contract | Description |
|---|---|
| Arguments | موضوع: فكرة، مشكلة، مقارنة، أو اسم اقتراح تغيير موجود لاستكشافه في سياقه. عند عدم تقديم أي شيء يدخل وضع الاستكشاف. |
| Creates | لا شيء افتراضيًا. يقرأ ويتقصى فقط. عند الطلب يلتقط الرؤى: اقتراح تغيير جديد تحت openspec/changes/<name>/، أو تحديثات لاقتراح أو تصميم أو مواصفات أو مهام موجودة. لا كود أبدًا. |
| Response | محادثة مفتوحة بدون مخرجات مطلوبة. عندما يتبلور التفكير يلخص المشكلة والنهج والأسئلة المفتوحة والخطوات التالية، ويعرض التقاطها. أنت تقرر. التنفيذ لا يبدأ هنا أبدًا. |
openspec-propose
أنشئ اقتراح تغيير وولّد جميع مخرجات التخطيط الخاصة به في خطوة واحدة.
| Contract | Description |
|---|---|
| Arguments | اسم بصيغة kebab-case (add-dark-mode) أو وصف عادي. يسأل إذا لم تقدم أيًا منهما. |
| Creates | openspec/changes/<name>/ مع كل مخرج يحدده المخطط، بترتيب التبعية (موجه بالمواصفات: الاقتراح، فروق المواصفات، التصميم، المهام). لا كود أبدًا. |
| Response | المخرجات التي تم إنشاؤها، جاهزة للمراجعة، والخطوة التالية. يتوقف عند ذلك؛ التنفيذ ينتظر openspec-apply-change. |
openspec-apply-change
نفّذ مهام اقتراح التغيير، مع العمل عبر القائمة حتى الانتهاء أو الحظر.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير (add-auth)، اختياري. إذا كان الهدف غامضًا يسرد اقتراحات التغيير النشطة ويطلب منك الاختيار. |
| Creates | كود: التغييرات الدنيا التي تتطلبها كل مهمة، في ملفات مشروعك. في اقتراح التغيير يضع علامة على كل مهمة مكتملة (- [ ] إلى - [x]) في الملف المتتبع المحدد بواسطة sourcePath وline المرقم بدءًا من واحد. قد يتتبع المخطط المهام عبر ملفات متعددة. |
| Response | التقدم لكل مهمة، ثم عدد إجمالي (N/M مهمة مكتملة). عند الانتهاء من الكل: يقترح openspec-archive-change. عند الحظر بسبب مخرجات مفقودة: يشير إلى openspec-continue-change، أو إلى openspec status وopenspec instructions عندما لا تكون تلك المهارة مثبتة (الملف الأساسي يستثنيها). المهام غير الواضحة أو الأخطاء: يتوقف ويسأل. |
openspec-update-change
راجع مخرجات التخطيط الحالية لاقتراح التغيير وأبقِها متسقة مع بعضها البعض.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير، اختياري، بالإضافة إلى المراجعة التي تريدها. عند عدم ذكر مراجعة يجري فحص اتساق: المخرجات مفحوصة مقابل بعضها البعض بحثًا عن تناقضات وفجوات وازدواجية. |
| Creates | يعدّل ملفات المخرجات الموجودة بالفعل. استثناء واحد: لمخرج مكتوب بصيغة glob، مثل specs/**/*.md، لديه ملف واحد على الأقل بالفعل، يمكنه إضافة ملف مصاحب مفقود بمجرد تأكيد المسار. المخرج الذي لا يحتوي ملفات بعد من مسؤولية openspec-continue-change. بدون تلك المهارة (الملف الأساسي يستثنيها)، يشير إلى openspec status وopenspec instructions بدلًا من ذلك. لا كود أبدًا. |
| Response | يعرض كل مراجعة مقترحة ويكتبها فقط بعد تأكيدك، مخرج واحد في كل مرة. ينتهي بما تمت مراجعته والخطوة التالية؛ التنفيذ ينتظر openspec-apply-change. |
openspec-sync-specs
ادمج تحديثات مواصفات اقتراح التغيير في specs/ دون أرشفته.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير، اختياري. يمكنك أيضًا تسمية مجموعة فرعية من مواصفات الفروق الخاصة به، وتتم مزامنة تلك فقط. |
| Creates | يعدّل أو ينشئ openspec/specs/<capability-path>/spec.md لكل مواصفة فروق، مدمجًا المتطلبات المضافة والمعدلة والمحذوفة والتي أعيدت تسميتها في المواصفة الرئيسية. لا كود أبدًا. |
| Response | ملخص لكل قدرة من المتطلبات المضافة والمعدلة والمحذوفة أو التي أعيدت تسميتها، بعد التحقق من صحة المواصفات المحدثة. يبقى اقتراح التغيير نشطًا؛ الأرشفة تنتظر openspec-archive-change. |
openspec-archive-change
انقل اقتراح تغيير مكتمل إلى الأرشيف.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير، اختياري. |
| Creates | ينقل مجلد اقتراح التغيير إلى openspec/changes/archive/YYYY-MM-DD-<name>/ (لا يضاف تاريخ إذا كان الاسم يبدأ بتاريخ بالفعل). بموافقتك يزامن أولاً مواصفات الفروق المعلقة. عندما يكون openspec-sync-specs مثبتًا، يشغل سير العمل ذلك. وإلا، يدمج مواصفات الفروق في المواصفات الرئيسية بنفسه. لا كود أبدًا. |
| Response | يحذر ويسأل قبل الأرشفة مع مخرجات أو مهام غير مكتملة، ويسأل عما إذا كان ينبغي المزامنة عند وجود مواصفات فروق. ينتهي بملخص: الاسم والمخطط وموقع الأرشيف وحالة مزامنة المواصفات وأي تحذيرات. |
openspec-new-change
ابدأ اقتراح تغيير كهيكل فارغ.
| Contract | Description |
|---|---|
| Arguments | اسم بصيغة kebab-case (add-user-auth) أو وصف عادي، بالإضافة إلى اسم مخطط فقط لسير عمل غير افتراضي. يسأل عما تريد بناءه إذا لم تقدم أيًا منهما. |
| Creates | openspec/changes/<name>/ كهيكل فارغ: لا مخرجات بعد، لا كود أبدًا. |
| Response | اسم الهيكل وموقعه، تسلسل مخرجات سير العمل، الحالة (0/N مكتمل)، وقالب المخرج الأول. صياغة المخرجات تنتظر openspec-continue-change. |
openspec-continue-change
أنشئ مخرج التخطيط التالي في اقتراح التغيير، واحدًا في كل مرة.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير، اختياري. إذا كان لا يزال غامضًا يطلب منك الاختيار من الأكثر تعديلًا حديثًا. |
| Creates | المخرج التالي الجاهز الوحيد في تسلسل المخطط، مكتوبًا في مجلد اقتراح التغيير. مخرج واحد لكل تشغيل، لا كود أبدًا. |
| Response | المخرج الذي تم إنشاؤه، التقدم (N من M مكتمل)، والمخرجات التي تم فتحها. عند اكتمال التخطيط يذكر ذلك؛ التنفيذ ينتقل إلى openspec-apply-change. |
openspec-ff-change
أنشئ اقتراح تغيير وكل مخرجات التخطيط التي يحتاجها التنفيذ، في تمريرة واحدة.
| Contract | Description |
|---|---|
| Arguments | اسم بصيغة kebab-case أو وصف عادي. يسأل إذا لم تقدم أيًا منهما. إذا كان اقتراح التغيير المسمى موجودًا بالفعل يقترح استكماله بدلًا من ذلك. |
| Creates | openspec/changes/<name>/ وكل مخرج تخطيط يتطلبه التنفيذ، بترتيب التبعية (موجه بالمواصفات: الاقتراح، المواصفات، التصميم، المهام)، مستثنيًا فقط المخرجات المعلمة كمتخطاة أو مشروطة. لا كود أبدًا. |
| Response | اسم اقتراح التغيير وموقعه، كل مخرج تم إنشاؤه، وأي مخرج مشروط تم تخطيه ولماذا. يتوقف عند ذلك؛ التنفيذ ينتظر openspec-apply-change. |
openspec-verify-change
تحقق من أن التنفيذ يطابق مخرجات اقتراح التغيير.
| Contract | Description |
|---|---|
| Arguments | اسم اقتراح تغيير، اختياري. عند الغموض يسأل، مسردًا اقتراحات التغيير التي لديها مخرج مهام. |
| Creates | لا شيء. يقرأ مخرجات اقتراح التغيير وقاعدة الكود. التحقق هو تقرير فقط. |
| Response | تقرير: بطاقة أداء للاكتمال والصحة والاتساق، ثم مشكلات CRITICAL وWARNING وSUGGESTION مع توصيات، وتقييم نهائي للجاهزية للأرشفة. لا يغير شيئًا ولا يؤرشف. |
openspec-bulk-archive-change
أرشف عدة اقتراحات تغيير دفعة واحدة.
| Contract | Description |
|---|---|
| Arguments | لا شيء. يسرد اقتراحات التغيير النشطة ويطلب منك تحديد أي عدد، مع خيار للكل. إذا لم يكن هناك أي نشط يذكر ذلك ويتوقف. |
| Creates | openspec/changes/archive/YYYY-MM-DD-<name>/ لكل اقتراح تغيير مؤرشف (الأسماء المؤرخة مسبقًا تحتفظ ببادئتها). مزامنة فروق مواصفات كل منها أولاً عبر openspec-sync-specs. لا كود أبدًا. |
| Response | جدول حالة لكل اقتراح تغيير وتأكيد واحد للدفعة بأكملها، ثم ملخص بما تم أرشفته وتخطيه وفشله، بالإضافة إلى نتائج مزامنة المواصفات. عندما يمس اقتراحا تغيير نفس المواصفة يتحقق من قاعدة الكود ويزامن الفروق المنفذة من الأقدم أولاً. |
openspec-onboard
تعلم سير العمل عن طريق إنجاز اقتراح تغيير حقيقي من البداية إلى النهاية.
| Contract | Description |
|---|---|
| Arguments | لا شيء. يفحص قاعدة الكود الخاصة بك بحثًا عن مهام بداية صغيرة ويطلب منك اختيار واحدة أو وصف مهمة خاصة بك. |
| Creates | اقتراح تغيير حقيقي للمهمة المختارة، مخرج واحد في كل مرة، ثم كود حقيقي بمجرد تأكيدك للتنفيذ. يؤرشف اقتراح التغيير في النهاية. |
| Response | جولة مشروحة للدورة الكاملة مع توقفات لمدخلاتك: استكشاف، إنشاء، بناء كل مخرج، تنفيذ، أرشفة. ينتهي بملخص وإشارة إلى openspec-propose. يستغرق حوالي 15 إلى 20 دقيقة. |