स्कीमा

OpenSpec जो उत्पन्न करता है उसे बदलें: आर्टिफ़ैक्ट, उनका क्रम और उनके टेम्पलेट।

एक स्कीमा परिभाषित करता है कि कोई परिवर्तन प्रस्ताव क्या उत्पन्न करता है: कौन से आर्टिफ़ैक्ट, किस क्रम में, किन टेम्पलेट से। उदाहरण के लिए, spec-driven, डिफ़ॉल्ट रूप से बंडल किया गया स्कीमा, इन चारों को मोटे तौर पर इसी क्रम में उत्पन्न करता है, और हर एक पिछले आर्टिफ़ैक्ट पर आधारित होता है:

proposal → specs → design → tasks

जब आप चाहते हैं कि ये अलग दस्तावेज़ हों—चाहे उनकी संख्या कम हो, नाम अलग हों या संरचना अलग हो—तब स्कीमा फ़ोर्क करें।

स्कीमा कहाँ रहते हैं

OpenSpec एक स्कीमा को तीन स्थानों पर, क्रम से खोजता है और जो पहले मिलता है उसी का उपयोग करता है:

1. आपका प्रोजेक्ट: openspec/schemas/, रिपॉज़िटरी के साथ कमिट किया गया ताकि आपकी पूरी टीम को यह मिले।
2. आपकी मशीन: macOS और Linux पर ~/.local/share/openspec/schemas (या $XDG_DATA_HOME के अंतर्गत, यदि आपने इसे सेट किया है), या Windows पर %LOCALAPPDATA%\openspec\schemas। यहाँ के स्कीमा आपके द्वारा काम किए जाने वाले हर प्रोजेक्ट में उपलब्ध होते हैं।
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 खाका, जिसे एजेंट भरता है।

यहाँ schema.yaml में tasks आर्टिफ़ैक्ट की प्रविष्टि है, संक्षिप्त रूप में:

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 में अपने प्रोजेक्ट को इस पर इंगित करें। यह कदम आपको स्वयं करना है क्योंकि फ़ोर्क 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

ढाँचा न्यूनतम है। आर्टिफ़ैक्ट केवल बिल्ट-इन चार ids से आते हैं, और उत्पन्न टेम्पलेट में कोई निर्देश नहीं होते, इसलिए जब तक आप अपने स्वयं के निर्देश नहीं लिखते, एजेंट को कम मार्गदर्शन मिलता है। वहाँ से फ़ोर्क के चरण बिना बदलाव के लागू होते हैं: इसे मान्य करें, फिर config.yaml को इस पर इंगित करें।

अपना फ़ोर्क संपादित करना

फ़ोर्क में दो तरह की फ़ाइलें संपादित करनी होती हैं:

• templates/ हर दस्तावेज़ का खाका बदलते हैं। tasks टेम्पलेट में एक सेक्शन जोड़ें और हर नया tasks.md उसी के साथ शुरू होगा। पहली पंक्ति पर # शीर्षक रखें: आर्टिफ़ैक्ट इसे विरासत में लेता है, इसलिए हर उत्पन्न फ़ाइल एक शीर्षक वाले दस्तावेज़ के रूप में खुलती है।
• schema.yaml वर्कफ़्लो को ही बदलता है: कौन से आर्टिफ़ैक्ट मौजूद हैं, हर एक को पहले किन चीज़ों की आवश्यकता होती है, और निर्माण के समय एजेंट को मिलने वाला निर्देश।

उदाहरण के लिए, अधिक सरल वर्कफ़्लो के लिए design दस्तावेज़ हटाने हेतु:

1. schema.yaml से design प्रविष्टि हटाएँ।

2. tasks की requires सूची से design निकालें।

3. मान्य करें:

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

चरण 2 छोड़ें और validate इसे पकड़ लेगा:

✗ 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 एक्ज़िक्यूशन स्किल्स से जोड़ता है। इसे अपने प्रोजेक्ट में कॉपी करने से पहले bridge के इंस्टॉलेशन और संगतता नोट्स का पालन करें।

Bridge को OpenSpec के बाहर रिलीज़ किया जाता है। OpenSpec इसके Superpowers इंटीग्रेशन का परीक्षण या संस्करण-प्रबंधन नहीं करता।