स्टोर्स (बीटा)

कई रिपॉजिटरी में फैले चेंजेस की योजना बनाएँ: एक स्टोर, कई रिपॉजिटरी।

OpenSpec सामान्यतः एक ही रिपॉजिटरी के अंदर रहता है: जिस कोड के लिए वह योजना बनाता है, उसके बगल में एक openspec/ फ़ोल्डर। एक स्टोर उस फ़ोल्डर को उसकी अपनी रिपॉजिटरी में ले जाता है, और कई कोड रिपॉजिटरी उसे साझा कर सकती हैं।

हर मशीन पर एक बार सेटअप करने के बाद, status, new change, और archive जैसे कमांड किसी भी डायरेक्टरी से स्टोर में काम कर सकते हैं।

         team-plans  (a store: OpenSpec in its own repo)
         ├── .openspec-store/store.yaml   the store's name
         └── openspec/
             ├── specs/
             └── changes/
                   ▲
                   │ set up once on each machine,
                   │ shared by pushing and cloning like any repo
     ┌─────────────┼─────────────┐
     │             │             │
 web-app       api-server     mobile-app
(code repo)   (code repo)    (code repo)

आप किसी स्टोर को git के साथ उसी तरह साझा करते हैं जैसे कोड साझा करते हैं: उसे स्वयं commit, push, pull और review करें। स्पेक्स और चेंजेस को ब्रांच और pull request उसी तरह मिलते हैं जैसे कोड को मिलते हैं।

स्टोर की आवश्यकता कब होती है

स्टोर का उपयोग करने के दो सामान्य कारण हैं:

• फ्रंटएंड और बैकएंड अलग-अलग रिपॉजिटरी में: एक फ़ीचर दोनों को प्रभावित करता है, और योजना को दो अलग हिस्सों के बजाय एक ही स्थान चाहिए।

        shop-plans  (store)
        └── openspec/changes/add-discounts/    one plan for the feature
                  ▲
        ┌─────────┴─────────┐
        │                   │
    storefront             api
  (frontend repo)     (backend repo)

• एक उत्पाद, कई क्लाइंट रिपॉजिटरी: Android, iOS और web अपनी-अपनी रिपॉजिटरी से रिलीज़ होते हैं, लेकिन एक ही अपेक्षित व्यवहार साझा करते हैं। एक स्पेक व्यवहार का वर्णन करता है, कार्यान्वयन का नहीं, इसलिए एक ही स्पेक तीनों के लिए पर्याप्त होता है।

          product-specs  (store)
          └── openspec/specs/checkout/spec.md    the expected behavior
                    ▲
      ┌─────────────┼─────────────┐
      │             │             │
  android-app    ios-app       web-app
  (code repo)   (code repo)   (code repo)

आपके पास एक से अधिक स्टोर हो सकते हैं, हालाँकि हम संख्या कम रखने की सलाह देते हैं।

स्टोर सेट करें

एक व्यक्ति स्टोर बनाता है, फिर बाकी सभी उसमें शामिल होते हैं।

1. स्टोर बनाएं (एक व्यक्ति, टीम के लिए एक बार)। openspec store setup चलाएं और प्रॉम्प्ट के उत्तर दें:

   # कहीं भी से चलाएं; यह पूछता है कि क्या बनाना है और कहाँ
   openspec store setup

   यह तीन सवाल पूछता है:

   • स्टोर का नाम: team-plans
   • यह स्टोर कहाँ रहेगा?: पहले से ~/openspec/<name> भरा हुआ है, इसे स्वीकार करने के लिए Enter दबाएं या कोई और पथ टाइप करें
   • यह स्टोर बनाएं?: दिखाता है कि इसे क्या बनाने वाला है, उत्तर दें Yes

   फिर यह बताता है कि इसने क्या बनाया:

   Store ready: team-plans
   Location: ~/openspec/team-plans
   OpenSpec root: ready
   Registry: registered
   
   Next: run normal OpenSpec commands against this store, for example:
     openspec new change <change-id> --store team-plans
   Share this store by committing and pushing it like any Git repo.

2. इसे अपने git host पर push करें। पहले अपने host पर एक खाली team-plans रिपो बनाएं। Setup git remote नहीं जोड़ता है, इसलिए स्टोर को उस रिपो से जोड़ें, फिर push करें:

   # स्टोर को अपने git host पर खाली रिपो से जोड़ें
   cd ~/openspec/team-plans
   git remote add origin git@github.com:acme/team-plans.git
   
   # इसे प्रकाशित करें
   git push -u origin main

3. स्टोर में शामिल हों (हर साथी, हर मशीन पर एक बार):

   # स्टोर को अपनी मशीन पर लाएं
   git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
   
   # OpenSpec को बताएं कि यह कहाँ रहता है
   openspec store register ~/openspec/team-plans

   Store registered: team-plans
   Location: /Users/you/openspec/team-plans
   OpenSpec root: ready
   Registry: registered

   रजिस्टर करने से आपकी मशीन को पता चलता है कि यह स्टोर कहाँ रहता है। स्टोर का नाम पहले से ही उसके अंदर .openspec-store/store.yaml में कमिट है। Setup ने निर्माता की कॉपी रजिस्टर कर दी, इसलिए केवल क्लोन की गई कॉपियों को यह कदम चाहिए।

4. पुष्टि करें कि यह काम कर गया, किसी भी डायरेक्टरी से:

   # कोई भी OpenSpec कमांड स्टोर तक नाम से पहुंचता है
   openspec status --store team-plans

   Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
   No active changes. Create one with: openspec new change <name> --store team-plans

सेटअप के प्रकार

OpenSpec में तीन सेटअप हैं। इस पेज का बाकी हिस्सा इन नामों का उपयोग करता है:

• repo-local: आपकी रिपो के अंदर OpenSpec, बिना स्टोर के। डिफ़ॉल्ट।
• store-only: आपकी रिपो के पास अपने कोई specs या changes नहीं होते। सब कुछ स्टोर में रहता है।
• store-optional: आपके प्रोजेक्ट का अपना openspec/ फ़ोल्डर है और आपके कहने पर एक स्टोर तक भी पहुंच है।

डिफ़ॉल्ट: आपकी रिपो के अंदर OpenSpec (repo-local)

openspec init आपके कोड के साथ एक openspec/ फ़ोल्डर रखता है, और उस रिपो के specs और changes वहीं रहते हैं। कोई स्टोर शामिल नहीं होता। यह वही सेटअप है जो अपना प्रोजेक्ट सेट करें सिखाता है, और ज़्यादातर प्रोजेक्ट को कभी किसी और की ज़रूरत नहीं होती।

web-app  (code repo)
└── openspec/
    ├── specs/
    └── changes/

आपकी रिपो के बाहर, स्टोर में OpenSpec (store-only)

रिपो के पास अपने कोई specs या changes नहीं होते। इसकी सारी योजनाएं स्टोर में रहती हैं, और रिपो की config में एक पंक्ति दोनों को जोड़ती है।

आम तौर पर तब जब एक टीम सभी रिपो और योजनाएं एक जगह बनाती है। ऊपर के उदाहरण सभी में यही आकार है।

team-plans  (store)
└── openspec/
    ├── specs/       रिपो के specs यहाँ रहते हैं
    └── changes/     इसके changes भी
          ▲
          │ store: team-plans   (जोड़ने वाली पंक्ति)
web-app  (code repo)
└── openspec/
    └── config.yaml    कुछ और नहीं

आपकी रिपो में और स्टोर में OpenSpec (store-optional)

रिपो अपने काम के लिए repo-local रहती है, जबकि स्टोर साझा specs और changes रखता है। रिपो के अंदर, OpenSpec आपके प्रोजेक्ट के openspec/ फ़ोल्डर का उपयोग करता है, और केवल तब स्टोर तक पहुंचता है जब आप --store देते हैं।

आम तौर पर तब जब कोई रिपो स्टोर के अस्तित्व में आने से पहले OpenSpec का उपयोग करती थी, या जब एक ज़्यादातर स्वतंत्र रिपो कभी-कभार साझा काम को छूती है।

team-plans  (store)
└── openspec/          साझा specs और changes
          ▲
          │ केवल तब जब आप --store team-plans देते हैं
web-app  (code repo)
└── openspec/          इस रिपो का अपना
    ├── config.yaml
    ├── specs/
    └── changes/

कोई रिपो repo-local से शुरू हो सकती है और बाद में अपने specs और changes को स्टोर में ले जा सकती है। रिपो के specs और changes को स्टोर में ले जाएं दिखाता है कि कैसे।

जहाँ artifacts बनते हैं जब स्टोर का उपयोग करते हैं

जब आप स्टोर का उपयोग करते हैं, तो OpenSpec को यह भी तय करना पड़ता है कि artifacts कहाँ बनेंगे। यह आपके सेटअप पर निर्भर करता है:

• store-only (आपका प्रोजेक्ट केवल स्टोर में लिखता है): हर artifact स्टोर में बनता है। नीचे दी गई store: पंक्ति इसे दर्ज करती है।
• store-optional (आपके प्रोजेक्ट का अपना openspec/ फ़ोल्डर है और स्टोर भी उपयोग करता है): artifacts आपके प्रोजेक्ट में बनते हैं, जब तक कि आप अपने अनुरोध में स्टोर का नाम न बताएं या उस change के लिए --store न दें। फिर आपका एजेंट उस फ़्लैग को पूरे वर्कफ़्लो में लेकर चलता है।

OpenSpec artifacts को दो जगहों में से एक पर लिखता है: आपके प्रोजेक्ट के openspec/ फ़ोल्डर में, या स्टोर में। यह इस क्रम में चुनता है, और पहला विकल्प जो लागू होता है जीत जाता है:

1. कमांड पर --store <id>। हमेशा जीतता है, किसी भी डायरेक्टरी से।
2. आपके प्रोजेक्ट का openspec/ फ़ोल्डर। अगर आपके प्रोजेक्ट में अपने specs/ या changes/ फ़ोल्डर हैं, तो OpenSpec उनका उपयोग करता है।
3. आपके प्रोजेक्ट में store: पंक्ति। store-only प्रोजेक्ट अपना स्टोर इस तरह दर्ज करते हैं।
4. आपकी मशीन पर defaultStore। तब का फ़ॉलबैक जब उपरोक्त में से कुछ भी लागू न हो।

अगर इनमें से कुछ भी लागू न हो और आपने स्टोर रजिस्टर किए हुए हैं, तो कमांड विफल होता है और उन्हें सूचीबद्ध करता है। जब किसी स्टोर की id आपकी रिपो के origin remote में उसके नाम से मेल खाती है, तो त्रुटि उस स्टोर और उस store: पंक्ति का नाम बताती है जो उसे चुनती है। OpenSpec कभी भी अपने-आप नाम से स्टोर नहीं चुनता, क्योंकि अलग-अलग संगठनों की रिपो एक ही नाम से हो सकती हैं।

जब OpenSpec कोई स्टोर चुनता है, तो यह कमांड आउटपुट से पहले Using OpenSpec root: ... प्रिंट करता है।

store: पंक्ति (store-only प्रोजेक्ट)

अपने प्रोजेक्ट की openspec/config.yaml में एक पंक्ति जोड़ें:

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

अब आप या आपका एजेंट आपके प्रोजेक्ट के अंदर जो भी चलाते हैं वह स्टोर का उपयोग करता है, बिना कोई फ़्लैग टाइप किए:

# web-app के अंदर, जुड़ा हुआ
openspec status

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
No active changes. Create one with: openspec new change <name> --store team-plans

• पंक्ति के बिना: store-only प्रोजेक्ट में एक साधारण कमांड चलाएं और OpenSpec त्रुटि के साथ रुक जाता है जो आपके रजिस्टर किए गए स्टोर सूचीबद्ध करती है।
• इसे कमिट करें: जो साथी आपका प्रोजेक्ट क्लोन करते हैं उन्हें यह पंक्ति भी मिलती है। उन्हें अभी भी अपनी मशीन पर स्टोर रजिस्टर करने की ज़रूरत है (स्टोर सेट करें का कदम 3), नहीं तो OpenSpec त्रुटि देता है और उन्हें रजिस्टर करने के लिए कहता है।
• असली फ़ोल्डरों के साथ: अगर आपके प्रोजेक्ट में specs/ या changes/ फ़ोलडर भी हैं, तो OpenSpec उनका उपयोग करता है और पंक्ति को चेतावनी के साथ अनदेखा करता है।

store-only रिपो में इंटीग्रेशन इंस्टॉल करें

कोड रिपो की जड़ से init चलाएं ताकि AI टूल इंटीग्रेशन फ़ाइलें उस रिपो में वापस योजना न डाले बगैर इंस्टॉल हो सकें:

# web-app के अंदर, रिपॉजिटरी की जड़ पर
openspec init --tools claude

• इंटीग्रेशन फ़ाइलें: कोड रिपो में लिखी जाती हैं।
• openspec/config.yaml: बाइट-दर-बाइट संरक्षित, store: पंक्ति सहित।
• openspec/specs/ और openspec/changes/: कोड रिपो में नहीं बनते।

OpenSpec कोड रिपो की किसी उप-डायरेक्टरी से यह कमांड करने से मना करता है। इसे रिपॉजिटरी की जड़ से चलाएं।

OpenSpec यहाँ --language को भी अस्वीकार करता है क्योंकि भाषा बाहरी स्टोर की config में होनी चाहिए। स्टोर की जड़ में init चलाएं या उस config को सीधे संपादित करें।

आपकी मशीन पर defaultStore

अगर आप जितने भी प्रोजेक्ट में काम करते हैं वे सब एक ही स्टोर का उपयोग करते हैं तो इसे एक बार सेट करें। जब OpenSpec कोई फ़्लैग नहीं, कोई स्थानीय openspec/ फ़ोल्डर नहीं, और कोई store: पंक्ति नहीं पाता, तो यह इस पर फ़ॉलबैक करता है:

# जब कुछ और स्टोर का नाम न बताए तब team-plans का उपयोग करें
openspec config set defaultStore team-plans

# इसे पूर्ववत करें
openspec config unset defaultStore

जो कमांड स्थानीय रहते हैं। init, update, templates, schemas, और openspec schema उप-कमांड केवल वर्तमान डायरेक्टरी पर काम करते हैं और --store नहीं लेते।

रिपो के specs और changes को स्टोर में ले जाएं

किसी रिपो को repo-local से store-only में ले जाने के लिए:

1. रिपो के openspec/specs/ और openspec/changes/ में जो कुछ है उसे स्टोर में उन्हीं फ़ोल्डरों में ले जाएं।
2. अब खाली फ़ोल्डरों को हटा दें, ताकि रिपो के openspec/ फ़ोल्डर में केवल config.yaml रहे।
3. उस config.yaml में store: पंक्ति जोड़ें।

अब रिपो के अंदर openspec status शुरू होगा Using OpenSpec root: team-plans से।

स्टोर में काम करें

वर्कफ़्लो नहीं बदलते, आपके लिए या आपके एजेंट के लिए। प्रस्ताव करना, लागू करना और संग्रह करना हमेशा की तरह चलता है। एकमात्र अंतर यह है कि artifacts कहाँ बनते हैं, और ऊपर वाला खंड उसे कवर करता है।

store-only रिपो के अंदर कोई change बनाएं और वह स्टोर में जाता है:

# web-app के अंदर; store: पंक्ति इसे team-plans तक भेजती है
openspec new change add-login

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
Created change 'add-login' at /Users/you/openspec/team-plans/openspec/changes/add-login/
Schema: spec-driven
Next: openspec status --change add-login --store team-plans

• कहाँ गया: आपके कोड के साथ नहीं, बल्कि स्टोर रिपो में।
• इसे साझा करना: जब तक आप स्टोर रिपो को कमिट और push नहीं करते, change केवल आपके चेकआउट में मौजूद रहता है। साथी इसे pull करने पर देखते हैं। वर्कफ़्लो जितने भी artifacts लिखते हैं उनके बारे में भी यही बात है।
• दस्तावेज़ों में पथ: जहाँ भी दस्तावेज़ openspec/ पथ दिखाते हैं, स्टोर सेटअप में वह फ़ोल्डर स्टोर का होता है।

जब artifacts किसी ऐसी जगह बनते हैं जहाँ आपको उम्मीद नहीं थी, तो openspec doctor बिना कुछ बदले आपका सेटअप जांचता है और हर निष्कर्ष के लिए सुधार प्रिंट करता है:

# वर्तमान जड़ और उसके स्टोर जांचें
openspec doctor

Doctor

Root
  Location: /Users/you/openspec/team-plans
  OpenSpec root: ok
  Store: team-plans (metadata ok)

References
  (none declared)

जब आपको वही चित्र जांच के बिना चाहिए हो, तो openspec context आपकी वर्तमान डायरेक्टरी के साथ काम करने वाली जड़ और स्टोर सूचीबद्ध करता है।

एक एडिटर विंडो में स्टोर और रिपो दोनों को खोलने के लिए, ताकि आपका एजेंट दोनों पढ़ सके, देखें वर्कसेट (बीटा)।

दूसरे स्टोर से स्पेक्स पढ़ें

आपका repo अपना openspec/ फ़ोल्डर रख सकता है और फिर भी अपने एजेंट को दूसरे स्टोर के स्पेक्स पढ़ने दे सकता है। उस स्टोर को repo की openspec/config.yaml में references: के अंतर्गत घोषित करें:

# api-server/openspec/config.yaml
references:
  - team-plans

रेफ़रेंस केवल पढ़ने के लिए (read-only) होते हैं। आपका काम आपके repo में ही रहता है, और रेफ़रेंस केवल यह बदलता है कि आपके एजेंट को क्या बताया जाता है।

जब कोई वर्कफ़्लो कोई आर्टिफ़ैक्ट बनाता है, तो उसके निर्देशों में रेफ़र किए गए स्टोर के स्पेक्स का एक इंडेक्स जुड़ जाता है — प्रत्येक के साथ एक-पंक्ति का सारांश और उसे fetch करने का सटीक कमांड:

<referenced_stores>
<!-- केवल पढ़ने योग्य upstream संदर्भ। जो आवश्यक हो उसे fetch करें; जो उपयोग करें उसका हवाला दें। -->
Store team-plans (/Users/you/openspec/team-plans):
  - payments: Rules for charging and refunding customers.
  Fetch: openspec show <spec-id> --type spec --store team-plans
</referenced_stores>

एक रेफ़रेंस में स्टोर का clone URL भी हो सकता है, उन मशीनों के लिए जिनके पास वह स्टोर अभी तक नहीं है:

references:
  - team-plans
  - { id: design-system, remote: "git@github.com:acme/design-system.git" }

URL घोषित होने पर, openspec doctor एक अनुपलब्ध (missing) स्टोर को पेस्ट करने योग्य समाधान में बदल देता है:

# आउटपुट को फ़िट करने के लिए रैप किया गया
References
  - team-plans: ok (/Users/you/openspec/team-plans)
  - design-system: Referenced store 'design-system' is not registered on this machine.
    Fix: 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 कभी clone, pull या push नहीं करता। जब तक आप pull न करें, एक पुराना (stale) चेकआउट पुराने स्पेक्स दिखाता रहेगा, और रेफ़रेंस डिस्क पर जो कुछ भी मौजूद है, उसी से पढ़े जाते हैं।
• प्रति स्टोर नाम केवल एक चेकआउट: पहले से पंजीकृत किसी नाम के अंतर्गत दूसरा फ़ोल्डर रजिस्टर करना विफल हो जाता है, और पहले openspec store unregister चलाने का संकेत दिया जाता है।