التخصيص

يوفر OpenSpec ثلاثة مستويات من التخصيص:

المستوى	ما يفعله	الأفضل لـ
إعدادات المشروع	تعيين القيم الافتراضية، حقن السياق/القواعد	معظم الفرق
المخططات المخصصة	تحديد مصنوعات سير العمل الخاصة بك	الفرق ذات العمليات الفريدة
التجاوزات العامة	مشاركة المخططات عبر جميع المشاريع	المستخدمون المتقدمون

---

إعدادات المشروع

ملف openspec/config.yaml هو أسهل طريقة لتخصيص OpenSpec لفريقك. يتيح لك ما يلي:

• تعيين مخطط افتراضي - تخطي --schema في كل أمر
• حقن سياق المشروع - يرى الذكاء الاصطناعي حزمة التقنية الخاصة بك، والاصطلاحات، إلخ.
• إضافة قواعد لكل مصنوع - قواعد مخصصة لمصنوعات محددة
• إضافة إرشادات لكل عملية - تفضيلات استشارية لعمل التطبيق والأرشفة
• تذكر خيارات التكامل - مثل الاشتراك في وكيل ترميز GitHub Copilot السحابي

الإعداد السريع

openspec init

يأخذك هذا خلال إنشاء إعداد بشكل تفاعلي. أو يمكنك إنشاء واحد يدويًا:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# Set by `openspec init` when you choose (or decline) the GitHub Copilot
# cloud coding agent; controls whether `init`/`update` generate its files.
githubCopilot:
  cloudAgent: false

كيف يعمل

المخطط الافتراضي:

# بدون إعداد
openspec new change my-feature --schema spec-driven

# مع الإعداد - المخطط تلقائي
openspec new change my-feature

حقن السياق والقواعد:

عند إنشاء أي مصنوع، يتم حقن سياقك وقواعدك في موجه الذكاء الاصطناعي:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• السياق يظهر في جميع المصنوعات
• القواعد تظهر فقط للمصنوع المطابق

إرشادات العمليات:

operations.apply.guidance و operations.archive.guidance هما مصفوفتان اختياريتان من التعليمات الاستشارية لكيفية إجراء الوكيل لتلك العمليات. وهما منفصلتان عن rules: إرشادات العمليات لا تقيّد محتوى المصنوع، وقواعد المصنوع لا يُعاد تسميتها أبدًا كإرشادات عمليات.

يجلب التطبيق والأرشفة هذه المدخلات في وقت التنفيذ:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

يعيد كلا السطحين سياق المشروع الحالي و operationGuidance المطابق كحقلين اختياريين منفصلين. كل استدعاء يقرأ لقطة جديدة من الجذر المُحل. عند تحديد --store <id>، يأتي التغيير والسياق والإرشادات جميعها من ذلك المخزن بدلاً من المستودع الحالي. أمر تعليمات الأرشفة للقراءة فقط: فهو لا يفحص أو يدمج مواصفات الدلتا، ولا يكتب المواصفات الرئيسية، ولا ينقل التغيير، ولا يشغّل سير عمل الأرشفة الثابت.

سياق المشروع هو مدخل إلزامي على مستوى الموجه. تقرأ سير العمل المُنشأة منه وتطبق حقائق المشروع ذات الصلة والاصطلاحات والقيود. إرشادات العمليات هي نصيحة إضافية اختيارية: تنظر سير العمل في كل إدخال وتتبع الإدخالات القابلة للتطبيق والمتوافقة مع سير العمل المدمج.

يبقى كلا الحقلين منفصلين عن الحالة المُتحكم بها عبر CLI، والمسارات المُحلّة، والخطوات المدمجة، وخيارات المستخدم الصريحة، وقواعد المصنوع. يبلغ سير العمل عن تعارضات السياق مع الحفاظ على القيمة المُتحكمة. لا يتبع إرشادات غير قابلة للتطبيق أو متعارضة ويشرح السبب. لا يُعد أي من الحقلين فحصًا قابلًا للتنفيذ، ولا تنسخ سير العمل نصّهما في ملفات التنفيذ أو المواصفات أو مصنوعات التغيير أو الملخصات ما لم يطلب المستخدم ذلك بشكل منفصل.

سلامة مدخلات الأرشفة ومزامنة المواصفات:

تستخدم الأرشفة والأرشفة المجمّعة والمزامنة المستقلة artifactPaths.specs.existingOutputPaths من openspec status --json كمصدر وحيد لمواصفات الدلتا. المخطط الذي لا يحتوي على مصنوع specs، أو تغيير قائمة مخرجاته الفعلية فارغة، ليس لديه ما تتم مزامنته؛ لا تُستخدم المصنوعات الأخرى لاستنتاج مواصفات الدلتا.

قبل كتابة دمج دلالي لمواصفة رئيسية، يستهلك سير العمل مخرجات openspec instructions specs --change <name> --json الحالية. قواعد specs المُعادة تقيّد فقط المواصفات الرئيسية الناتجة عن ذلك الدمج. تمرر الأرشفة المفردة تلك اللقطة إلى المزامنة المضمنة، وتجلب المزامنة المستقلة مباشرة، وتحصل الأرشفة المجمّعة على كل لقطة مطلوبة قبل أول كتابة مواصفة لها. استجابة تعليمات أرشفة/مواصفات غير صفرية أو غير صالحة JSON هي فشل بحث، وليست مدخلًا فارغًا: يتوقف سير العمل قبل كتابة المواصفة المتأثرة أو نقل التغيير (بالنسبة للأرشفة المجمّعة، قبل أي كتابة أو نقل دفعة).

لا يغير هذا الإعداد مراحل تنفيذ الأرشفة، أو مطالبات المستخدم، أو عمليات نظام الملفات، أو ملكية الدمج الدلالي، أو أمر openspec archive المباشر، أو بنية ومخرجات قواعد المصنوع.

ترتيب حل المخطط

عندما يحتاج OpenSpec إلى مخطط، فإنه يتحقق بالترتيب التالي:

1. علامة CLI: --schema <name>
2. بيانات التغيير الوصفية (.openspec.yaml في مجلد التغيير)
3. إعداد المشروع (openspec/config.yaml)
4. الافتراضي (spec-driven)

---

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

عندما لا يكون تكوين المشروع كافياً، أنشئ مخططك الخاص مع تدفق عمل مخصص بالكامل. تعيش المخططات المخصصة في مجلد openspec/schemas/ الخاص بمشروعك وتُدار مع أكوادك عبر نظام التحكم بالإصدارات.

your-project/
├── openspec/
│   ├── config.yaml        # تكوين المشروع
│   ├── schemas/           # المخططات المخصصة تعيش هنا
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # تغييراتك
└── src/

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

أسرع طريقة للتخصيص هي استنساخ مخطط مدمج:

openspec schema fork spec-driven my-workflow

ينسخ هذا المخطط spec-driven بالكامل إلى openspec/schemas/my-workflow/ حيث يمكنك تحريره بحرية.

ما تحصل عليه:

openspec/schemas/my-workflow/
├── schema.yaml           # تعريف تدفق العمل
└── templates/
    ├── proposal.md       # قالب لوثيقة الاقتراح
    ├── spec.md           # قالب للمواصفات
    ├── design.md         # قالب للتصميم
    └── tasks.md          # قالب للمهام

الآن عدّل schema.yaml لتغيير تدفق العمل، أو عدّل القوالب لتغيير ما يولّده الذكاء الاصطناعي.

إنشاء مخطط من الصفر

لتدفق عمل جديد بالكامل:

# تفاعلي
openspec schema init research-first

# غير تفاعلي
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

بنية المخطط

يحدد المخطط المخرجات في تدفق عملك وكيف تعتمد على بعضها البعض:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

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

الحقل	الغرض
id	معرّف فريد، يُستخدم في الأوامر والقواعد
generates	اسم الملف الناتج (يدعم الأنماط مثل specs/**/*.md)
template	ملف القالب في مجلد templates/
instruction	تعليمات الذكاء الاصطناعي لإنشاء هذا المخرج
requires	الاعتماديات - أي المخرجات يجب أن توجد أولاً

رتّب المخرجات بالترتيب الذي تريد كتابتها به. يحدد requires ما هو ممكن؛ أما ترتيب قائمة artifacts: فيحدد ما يأتي أولاً عندما تكون عدة مخرجات جاهزة في نفس الوقت.

القوالب

القوالب هي ملفات Markdown توجه الذكاء الاصطناعي. تُحقن في الأمر عند إنشاء المخرج المعني.

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

يمكن أن تتضمن القوالب:

• عناوين أقسام يجب على الذكاء الاصطناعي ملؤها
• تعليقات HTML بتوجيهات للذكاء الاصطناعي
• أمثلة على الصيغ تُظهر البنية المتوقعة

التحقق من مخططك

قبل استخدام مخطط مخصص، تحقّق منه:

openspec schema validate my-workflow

يتحقق هذا من:

• صحة صياغة schema.yaml
• وجود جميع القوالب المُشار إليها
• عدم وجود اعتماديات دائرية
• صلاحية معرفات المخرجات

استخدام مخططك المخصص

بعد الإنشاء، استخدم مخططك مع:

# حدد في الأمر
openspec new change feature --schema my-workflow

# أو اضبطه كافتراضي في config.yaml
schema: my-workflow

تصحيح حل المخطط

غير متأكد أي مخطط يُستخدم؟ تحقّق مع:

# اعرف من أين يُحل المخطط المحدد
openspec schema which my-workflow

# اذكر جميع المخططات المتاحة
openspec schema which --all

يُظهر الإخراج ما إذا كان من مشروعك، أو من مجلد المستخدم، أو من الحزمة:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

ملاحظة: يدعم OpenSpec أيضاً مخططات على مستوى المستخدم في ~/.local/share/openspec/schemas/ للمشاركة عبر المشاريع، لكن يُوصى بالمخططات على مستوى المشروع في openspec/schemas/ لأنها مُدارة مع أكوادك عبر نظام التحكم بالإصدارات.

---

أمثلة

تدفق عمل التكرار السريع

تدفق عمل مبسّط للتكرارات السريعة:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

إضافة مخرج للمراجعة

استنسخ الافتراضي وأضف خطوة مراجعة:

openspec schema fork spec-driven with-review

ثم عدّل schema.yaml لإضافة:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

مخططات المجتمع

يدعم OpenSpec أيضاً مخططات يديرها المجتمع وتُوزّع عبر مستودعات مستقلة. توفر هذه المخططات تدفقات عمل ذات توجهات تكامل OpenSpec مع أدوات أو أنظمة أخرى، بشكل مشابه لكيفية عمل كتالوج امتدادات المجتمع في github/spec-kit لـ spec-kit.

لا تُدمج مخططات المجتمع في نواة OpenSpec — تعيش في مستودعاتها الخاصة بإيقاع إصدار خاص بها. لاستخدام أحدها، انسخ حزمة المخطط إلى مجلد openspec/schemas/<schema-name>/ في مشروعك (تتضمن صفحة README لكل مستودع تعليمات التثبيت).

المخطط	المُشرف	المستودع	الوصف
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	يلتقط نية التغيير والسلوك القابل للملاحظة والتصميم التقني والقرارات المعمارية الدائمة قبل التنفيذ. يضيف قائمة مراجعة ADR محلية للتغيير ويكتب القرارات طويلة الأمد المؤهلة كـ ADRs غير قابلة للتعديل وقابلة للاستبدال.
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	يدمج حوكمة مخرجات OpenSpec مع مهارات التنفيذ في obra/superpowers (العصف الذهني، كتابة الخطط، TDD عبر الوكلاء الفرعيين، مراجعة الكود، الإنهاء). يضيف مخرج retrospective قائم على الأدلة يملأ فجوة لا تغطيها Superpowers بشكل أصلي.
nanopm	@nmrtn	nmrtn/nanopm	تدفق عمل يركز على مدير المشروع. يشغّل خط أنابيب التخطيط في nanopm (التدقيق ← الاستراتيجية ← خارطة الطريق ← PRD) قبل التنفيذ. يربط تخطيط المنتج بتدفق هندسة المواصفات في OpenSpec. تُقرأ المخرجات من .nanopm/ إن وُجدت — الاقتراح يستمد من التدقيق، والتصميم يستمد من الاستراتيجية، والمهام تستمد من تفصيل PRD.
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	سجلات تشغيل اختبار منطقي إلى منطقي على مستوى القدرة. تحصل كل قدرة على مواصفة غير قابلة للتعديل، وقالب مهام غير قابل للتعديل، وسجل تشغيل واحد مُوسوم بالوقت لكل تنفيذ. الادعاءات هي سلوك قابل للملاحظة فقط (حالة HTTP، جسم الاستجابة، الحالة المحفوظة — وليس مقاطع السجلات أبداً)؛ يسجل كل تشغيل وقت البداية/النهاية بتوقيت UTC، والمدة، واستهلاك رموز LLM المُقدَّر.
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	تدفق عمل قائم على المواصفات مع انضباط TDD وخطوة مراجعة معادية. التدفق: proposal ← specs ← design ← review ← test-plan ← tasks ← apply ← verify. يُكتب review بواسطة مُراجع جديد السياق للقراءة فقط (نموذج ثانٍ عند توفره) ويُصدر سطر VERDICT: يخبر الوكيل بترشيح test-plan وtasks وapply؛ يتحقق OpenSpec فقط من وجود المخرجات، لذا نفّذ الترشيح عبر CI أو خطاف خاص بك. يربط test-plan كل سيناريو مواصفة باختبار مُسمّى ويعمل كدفتر أحمر/أخضر تدقّقه verify.

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

---

راجع أيضاً

• مرجع CLI: أوامر المخطط - وثائق أوامر كاملة