OpenSpec

schema.yaml ​

किसी स्कीमा परिभाषा का हर फ़ील्ड—चाहे उसे पढ़ा जा रहा हो या लिखा जा रहा हो।

schema.yaml उन योजना फ़ाइलों को सूचीबद्ध करता है जिन्हें कोई वर्कफ़्लो बनाता है। यह उनका क्रम और कार्यान्वयन को हैंडऑफ़ भी परिभाषित करता है।

स्थान ​

कोई प्रोजेक्ट स्कीमा openspec/schemas/<name>/ के अंतर्गत रहता है:

text
openspec/schemas/review-first/
├── schema.yaml
└── templates/
    ├── proposal.md
    └── tasks.md

OpenSpec उस निर्देशिका के लिए तीन स्थानों की जाँच करता है। पहला मिलान चुना जाता है।

प्रतिनिर्देशिका
1. प्रोजेक्ट<project>/openspec/schemas/<name>/
2. उपयोगकर्ता, macOS और Linux~/.local/share/openspec/schemas/<name>/
2. उपयोगकर्ता, Windows%LOCALAPPDATA%\openspec\schemas\<name>\
3. पैकेजCLI के साथ इंस्टॉल किए गए स्कीमा

यदि XDG_DATA_HOME सेट है, तो हर प्लेटफ़ॉर्म पर उपयोगकर्ता निर्देशिका $XDG_DATA_HOME/openspec/schemas/<name>/ पर चली जाती है।

निर्देशिका का नाम वह लुकअप कुंजी है जिसका उपयोग --schema, config.yaml, और .openspec.yaml करते हैं। यदि name फ़ील्ड निर्देशिका के नाम से भिन्न है, तो भी OpenSpec लुकअप के लिए निर्देशिका का नाम ही उपयोग करता है।

openspec schema which <name> सक्रिय निर्देशिका और उन कम-प्राथमिकता वाली प्रतियों को प्रिंट करता है जिन्हें वह छिपाता है।

शीर्ष-स्तरीय फ़ील्ड ​

फ़ील्डकॉन्ट्रैक्ट
nameआवश्यक। स्कीमा नाम के रूप में संग्रहीत एक गैर-खाली स्ट्रिंग। लुकअप अभी भी निर्देशिका का नाम उपयोग करता है।
versionआवश्यक। स्कीमा रिवीज़न के रूप में संग्रहीत एक धनात्मक पूर्णांक। यह मान OpenSpec के व्यवहार को नहीं बदलता।
descriptionopenspec schemas द्वारा प्रिंट की जाने वाली एक वैकल्पिक स्ट्रिंग। कोई मान न होने पर स्कीमा में कोई विवरण नहीं होता।
artifactsआवश्यक। आर्टिफ़ैक्ट प्रविष्टियों की एक गैर-खाली सूची।
applyवैकल्पिक apply सेटिंग्स। कोई ब्लॉक न होने पर, OpenSpec apply डिफ़ॉल्ट का उपयोग करता है।

आर्टिफ़ैक्ट फ़ील्ड ​

artifacts के अंतर्गत प्रत्येक प्रविष्टि एक योजना फ़ाइल या फ़ाइलों के समूह को परिभाषित करती है।

फ़ील्डकॉन्ट्रैक्ट
idआवश्यक। निर्भरताओं, प्रोजेक्ट नियमों, कमांडों और apply सेटिंग्स में उपयोग की जाने वाली एक अद्वितीय, गैर-खाली स्ट्रिंग।
generatesआवश्यक। एक सापेक्ष पथ या ग्लोब जो एजेंट को बताता है कि चेंज फ़ोल्डर के अंदर आर्टिफ़ैक्ट कहाँ लिखना है।
descriptionआवश्यक। एक स्ट्रिंग जो एजेंट को भेजे गए निर्देशों में आर्टिफ़ैक्ट को लेबल करती है।
templateआवश्यक। स्कीमा के templates/ फ़ोल्डर में आर्टिफ़ैक्ट के प्रारूप का सापेक्ष पथ।
instructionवैकल्पिक मार्गदर्शन जो एजेंट को बताता है कि कौन-सी सामग्री तैयार करनी है।
requiresउन आर्टिफ़ैक्ट ID की सूची जो पहले पूर्ण होनी चाहिए। डिफ़ॉल्ट: []।

generates ​

पथ चेंज फ़ोल्डर से शुरू होता है। add-auth नामक चेंज के लिए:

yaml
generates: proposal.md

आर्टिफ़ैक्ट यहाँ जाता है:

text
openspec/changes/add-auth/proposal.md

एक ग्लोब कई फ़ाइलों से मेल खा सकता है:

yaml
generates: specs/**/*.md

यह openspec/changes/add-auth/specs/ के नीचे के Markdown फ़ाइलों से मेल खाता है।

OpenSpec generates में इन ग्लोब रूपों को पहचानता है:

  • वाइल्डकार्ड और कैरेक्टर क्लासेस: *, ?, या [ वाले मान, जैसे specs/**/*.md और review-[ab].md।
  • ब्रेस एक्सपैन्शन: विकल्प जैसे review-{api,ui}.md और रेंज जैसे file-{1..3}.md।
  • एक्स्टग्लोब्स: पैटर्न जैसे @(proposal|design).md, +(proposal|design).md, और !(proposal|design).md।

शाब्दिक फ़ाइलनाम: केवल अग्रणी ! किसी मान को ग्लोब नहीं बनाता। उस फ़ाइल का नाम देने के लिए generates: '!review.md' का उपयोग करें। सामान्य कोष्ठक जैसे (proposal|design).md और एकल-तत्व ब्रेस जैसे review-{api}.md भी शाब्दिक ही रहते हैं।

OpenSpec निरपेक्ष पथों, .. खंड वाले पथों, और उन ग्लोब्स को अस्वीकार करता है जो ब्रेस या कोष्ठकों को 16 से अधिक स्तरों की गहराई तक नेस्ट करते हैं, जैसे {a,{b,{c,...}}}। वास्तविक पैटर्नों में एक या दो स्तर ही चाहिए। यह ऐसे ग्लोब को भी अस्वीकार करता है जिसके ब्रेस 1,024 से अधिक पैटर्नों तक विस्तारित होते हैं, जैसे ग्यारह बार दोहराया गया {a,b} या file-{1..5000}.md जैसी रेंज। त्रुटि में लिखा होता है Artifact output pattern expands to more than 1024 patterns। वास्तविक पैटर्न मुट्ठी भर पैटर्नों तक ही विस्तारित होते हैं।

पूर्णता ​

OpenSpec जाँचता है कि आउटपुट मौजूद है या नहीं। यह तय करने के लिए कि आर्टिफ़ैक्ट पूर्ण है या नहीं, फ़ाइल को पढ़ता नहीं है।

generates मानपूर्ण होता है जब
proposal.mdवह फ़ाइल मौजूद है।
specs/**/*.mdग्लोब कम से कम एक फ़ाइल से मेल खाता है।

template ​

पथ स्कीमा के templates/ फ़ोल्डर से शुरू होता है। review-first स्कीमा में:

yaml
template: proposal.md

OpenSpec इस फ़ाइल को पढ़ता है:

text
openspec/schemas/review-first/templates/proposal.md

OpenSpec टेम्पलेट की सामग्री को आउटपुट प्रारूप के रूप में एजेंट को देता है। यह टेम्पलेट को चेंज फ़ोल्डर में कॉपी नहीं करता।

OpenSpec निरपेक्ष पथों और .. खंड वाले पथों को अस्वीकार करता है।

requires ​

  • निर्भरताएँ: requires में प्रत्येक ID को उसी स्कीमा में किसी अन्य आर्टिफ़ैक्ट का नाम देना चाहिए।
  • तैयार स्थिति: कोई आर्टिफ़ैक्ट अपनी सभी निर्भरताओं के पूर्ण होने के बाद तैयार होता है।
  • अमान्य ग्राफ़: अनुपस्थित ID, डुप्लिकेट ID, और निर्भरता चक्र सत्यापन में विफल होते हैं।
  • बराबरी की स्थिति: जब कई आर्टिफ़ैक्ट तैयार हों, तो artifacts में उनका क्रम तय करता है कि OpenSpec पहले किसे लौटाता है।

Apply फ़ील्ड ​

apply परिभाषित करता है कि कार्यान्वयन शुरू होने से पहले क्या मौजूद होना चाहिए।

फ़ील्डकॉन्ट्रैक्ट
requiresआवश्यक। उन आर्टिफ़ैक्ट की गैर-खाली सूची जो apply निर्देशों के तैयार होने से पहले मौजूद होने चाहिए।
tracksचेंज फ़ोल्डर में Markdown कार्य फ़ाइलों के लिए एक वैकल्पिक सापेक्ष पथ या ग्लोब। डिफ़ॉल्ट: null।
instructionजब apply तैयार होता है तो एजेंट को भेजा जाने वाला वैकल्पिक मार्गदर्शन। OpenSpec डिफ़ॉल्ट रूप से अंतर्निहित मार्गदर्शन का उपयोग करता है।

आर्टिफ़ैक्ट का requires योजना क्रम को नियंत्रित करता है। apply.requires नियंत्रित करता है कि apply निर्देश कब तैयार होते हैं।

tracks ​

पथ चेंज फ़ोल्डर से शुरू होता है। add-auth नामक चेंज के लिए, tracks: tasks.md यह पढ़ता है:

text
openspec/changes/add-auth/tasks.md

tracks: "**/tasks.md" जैसा ग्लोब हर मेल खाने वाली फ़ाइल को पढ़ता है, जैसे backend/tasks.md और frontend/tasks.md। OpenSpec उनके कार्यों और प्रगति को जोड़ता है। किसी आर्टिफ़ैक्ट के generates फ़ील्ड के लिए वही मान उपयोग करें ताकि status और list उन्हीं फ़ाइलों को ट्रैक करें। generates की ब्रेस सीमाएँ (16 स्तर गहरी, 1,024 विस्तारित पैटर्न) यहाँ भी लागू होती हैं।

यदि कोई फ़ाइल मेल नहीं खाती या मेल खाने वाली फ़ाइलों में कार्य पाठ वाला कोई चेकबॉक्स नहीं है, तो apply ब्लॉक रहता है। OpenSpec इन चेकबॉक्स रूपों को गिनता है:

markdown
- [ ] Pending task
- [x] Completed task
* [X] Completed task
+ [ ] Pending task
1. [ ] Pending task
2) [x] Completed task

कोई भी Markdown सूची मार्कर काम करता है: -, *, +, या . या ) के बाद अधिकतम नौ अंकों तक की संख्या। अग्रणी स्पेस की अनुमति है। spec-driven पेज का tasks.md अनुभाग डिफ़ॉल्ट स्कीमा द्वारा उत्पादित सख्त प्रारूप को परिभाषित करता है।

ट्रैक की गई फ़ाइलें apply स्थिति को निर्धारित करती हैं:

  • blocked: कोई फ़ाइल मेल नहीं खाती, या किसी पठनीय फ़ाइल में कार्य पाठ वाला चेकबॉक्स नहीं है।
  • ready: कम से कम एक कार्य लंबित है, या कोई मेल खाने वाली फ़ाइल पढ़ी नहीं जा सकी, जबकि कोई अन्य फ़ाइल कार्य प्रदान करती हो।
  • all_done: हर ट्रैक किया गया कार्य चेक किया गया है और हर मेल खाने वाली फ़ाइल पढ़ी गई है।

यदि कोई मेल खाने वाली फ़ाइल पढ़ी नहीं जा सकती, तो apply पठनीय फ़ाइलों के कार्यों और प्रगति को बनाए रखता है, लेकिन चेंज को all_done चिह्नित नहीं करता। Apply JSON आउटपुट प्रत्येक अनुपलब्ध फ़ाइल और कारण की पहचान करता है।

OpenSpec निरपेक्ष पथों और .. खंड वाले पथों को अस्वीकार करता है।

Apply डिफ़ॉल्ट ​

व्यवहारडिफ़ॉल्ट
आवश्यक आर्टिफ़ैक्टस्कीमा का हर आर्टिफ़ैक्ट
प्रगति ट्रैकिंगकोई ट्रैक की गई फ़ाइल नहीं
एजेंट मार्गदर्शनअंतर्निहित apply मार्गदर्शन

पूर्ण उदाहरण ​

yaml
name: review-first
version: 1
description: Proposal and implementation checklist

artifacts:
  - id: proposal
    generates: proposal.md
    description: Why the change is needed and what it affects
    template: proposal.md
    instruction: |
      Explain the problem, the proposed change, and its impact.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Trackable implementation checklist
    template: tasks.md
    instruction: |
      Break the approved proposal into ordered implementation tasks.
    requires:
      - proposal

apply:
  requires:
    - tasks
  tracks: tasks.md
  instruction: |
    Work through the pending tasks and mark each one complete.

सत्यापन ​

openspec schema validate <name> इनकी जाँच करता है:

  • फ़ील्ड प्रकार और आवश्यक फ़ील्ड
  • सापेक्ष पथ
  • आर्टिफ़ैक्ट ID, निर्भरताएँ, और चक्र
  • apply.requires ID: प्रत्येक को स्कीमा में एक आर्टिफ़ैक्ट होना चाहिए
  • टेम्पलेट फ़ाइलें

अज्ञात apply.requires ID वाला स्कीमा लोड नहीं होता, इसलिए इसका उपयोग करने वाला प्रत्येक कमांड उस त्रुटि की रिपोर्ट करता है।

जब apply.tracks किसी आर्टिफ़ैक्ट के generates मान के बिल्कुल बराबर नहीं होता, तो सत्यापन विफल हुए बिना चेतावनी देता है। OpenSpec उन दो स्ट्रिंग्स की तुलना करके ट्रैक किए गए आर्टिफ़ैक्ट को ढूँढता है, इसलिए कोई भी अन्य अंतर उसे यह बताने में असमर्थ छोड़ देता है कि फ़ाइल किस आर्टिफ़ैक्ट की प्रगति से संबंधित है। इसमें task.md जैसा टाइपो शामिल है, और tracks: tasks/main.md बनाम generates: tasks/*.md भी, जहाँ ग्लोब फ़ाइल को उत्पन्न तो करता है, लेकिन स्ट्रिंग्स फिर भी भिन्न रहती हैं। apply किसी भी स्थिति में फ़ाइल पढ़ता रहता है, लेकिन openspec list और openspec status इसके बजाय tasks.md को गिनते हैं।

सत्यापन इन गलतियों को नहीं पकड़ता:

गलतीक्या होता है
किसी फ़ील्ड की वर्तनी गलत है, जैसे instrutionOpenSpec इसे अनदेखा करता है। सत्यापन टाइपो की रिपोर्ट नहीं करता।
name स्कीमा निर्देशिका से भिन्न हैसत्यापन पास हो जाता है। OpenSpec फिर भी लुकअप के लिए निर्देशिका का नाम उपयोग करता है।