स्टोर्स: अपने स्वयं के रिपोजिटरी में योजना बनाएं

बीटा. स्टोर्स, संदर्भ, कार्य संदर्भ और वर्कसेट नए हैं। कमांड नाम, फ्लैग, फाइल फॉर्मेट और JSON आउटपुट रिलीज के बीच अभी भी बदल सकते हैं। नीचे दिए गए हर वॉकथ्रू वर्तमान बिल्ड पर चलाया गया था, लेकिन अपग्रेड करने के बाद कृपया इस गाइड को फिर से पढ़ें।

यह किन समस्याओं का समाधान करता है

ओपनस्पेक आमतौर पर एक ही कोड रिपोजिटरी के अंदर होता है: अपने कोड के पास openspec/ फोल्डर, जिसमें उस रिपोजिटरी के लिए स्पेक और बदलाव संग्रहीत होते हैं।

जैसे ही आपकी योजना एक रिपोजिटरी से बड़ी हो जाती है, यह व्यवस्था उपयुक्त नहीं रह जाती है:

• आपका कार्य कई रिपोजिटरियों में फैला हुआ है — एक ही फीचर API सर्वर, वेब ऐप और एक शेयर्ड लाइब्रेरी को प्रभावित करता है। योजना किसके openspec/ फोल्डर में स्थित होगी?
• आपकी टीम कोड मौजूद होने से पहले ही योजना बनाती है, या ऐसी चीजों की योजना बनाती है जो कभी इस रिपोजिटरी में कोड में नहीं बनतीं।
• आवश्यकताओं का स्वामित्व एक ही टीम का होता है और अन्य टीमें उनका उपयोग करती हैं। विकी का संस्करण टल जाता है, और आपका कोडिंग एजेंट इसे वैसे भी नहीं पढ़ सकता।

स्टोर्स इसका समाधान है: एक स्टैंडअलोन रिपोजिटरी जिसका पूरा काम योजना बनाना है। इसमें आपके पहले से जानी-पहचानी openspec/ संरचना होती है — स्पेक और बदलाव — साथ ही एक छोटा पहचान फाइल भी होता है। आप इसे अपने मशीन पर एक बार नाम से पंजीकृत कर लें, और फिर किसी भी जगह से हर सामान्य ओपनस्पेक कमांड इसमें काम कर सकता है।

आकार

            team-plans  (एक स्टोर: अपने रेपो में प्लानिंग)
            ├── .openspec-store/store.yaml     identity: "I am team-plans"
            └── openspec/
                ├── specs/      सत्य क्या है
                └── changes/    क्या गति में है
                      ▲
                      │ नाम द्वारा प्रत्येक मशीन पर पंजीकृत;
                      │ किसी भी रेपो की तरह पुश/क्लोन करके शेयर किया जाता है
        ┌─────────────┼─────────────┐
        │             │             │
    web-app       api-server     mobile-app
   (कोड रेपो)   (कोड रेपो)    (कोड रेपो)

दो नियम इसे सरल रखते हैं:

1. एक स्टोर बस एक गिट रेपो है। आप स्वयं इसे कमिट, पुश, पुल और रिव्यू करते हैं। ओपनस्पेक कभी भी स्वयं कुछ क्लोन, सिंक या पुश नहीं करता।
2. मशीनरी नहीं, घोषणाएँ। रेपो अपने आप को स्टोर्स के साथ कैसे संबंधित करते हैं यह घोषणा कर सकते हैं (नीचे दिखाया गया है)। घोषणाएँ ओपनस्पेक को आपको क्या बता सकता है बदलती हैं — कभी नहीं कि आपके कमांड कहां काम करते हैं।

अपने पहले स्टोर तक पाँच मिनट

दो कमांड आपको कुछ नहीं से काम करने वाले, स्टोर-स्कोप्ड चेंज तक ले जाते हैं:

openspec store setup team-plans --path ~/openspec/team-plans

स्टोर तैयार: team-plans
स्थान: /Users/you/openspec/team-plans
ओपनस्पेक रूट: तैयार
रजिस्ट्री: पंजीकृत

अगला: इस स्टोर के खिलाफ सामान्य ओपनस्पेक कमांड चलाएं, उदाहरण के लिए:
  openspec new change <change-id> --store team-plans
इस स्टोर को शेयर करने के लिए इसे किसी भी गिट रेपो की तरह कमिट और पुश करें।

openspec new change add-login --store team-plans

ओपनस्पेक रूट का उपयोग: team-plans (/Users/you/openspec/team-plans)
'add-login' चेंज बनाई गई स्थिति: /Users/you/openspec/team-plans/openspec/changes/add-login/
स्कीमा: spec-driven
अगला: openspec status --change add-login --store team-plans

यह पूरा मॉडल है। यहाँ से लाइफसाइकल बिल्कुल वही है जिसे आप जानते हैं — status, instructions, validate, archive — हर कमांड पर --store team-plans के साथ, और प्रिंट किए गए हर संकेत के पास आपके लिए फ्लैग होता है। ओपनस्पेक रूट का उपयोग: लाइन हमेशा बताती है कि कोई कमांड कहां काम कर रहा है।

कहानी: एक टीम, एक प्लानिंग रेपो

एक टीम अपने स्पेक्स और चेंजेज को team-plans में रखती है बजाय इसके कि उन्हें कोड रेपो में बिखरा देती है।

पहला दिन (जो भी इसे सेटअप करता है):

openspec store setup team-plans --path ~/openspec/team-plans \
  --remote git@github.com:acme/team-plans.git
git -C ~/openspec/team-plans push -u origin main

--remote पास करने से स्टोअर की अपनी आइडेंटिटी फाइल (.openspec-store/store.yaml) में क्लोन URL रिकॉर्ड हो जाता है, इनिशियल कमिट में। हर भविष्य के क्लोन को यह जानते हुए जन्म लेता है कि यह कहाँ से आया है, ताकि हेल्थ चेक और एरर मैसेज टीम में उन सदस्यों के लिए पूरा, पेस्ट करने योग्य फिक्स प्रिंट कर सकें जिनके पास अभी तक यह नहीं है।

हर टीम सदस्य (मशीन पर एक बार):

git clone git@github.com:acme/team-plans.git ~/openspec/team-plans
openspec store register ~/openspec/team-plans

इसके बाद, हर किसी नाम से एक ही प्लानिंग रेपो में काम करता है:

openspec status --store team-plans --change add-login
openspec show add-login --store team-plans

काम शेयर करना जानबूझकर गिट है। आपके द्वारा बनाई गई कोई चेंज तब तक केवल आपके चेकआउट में मौजूद रहती है जब तक आप इसे कमिट और पुश नहीं करते — कोड की तरह ही। प्लान्स को स्वतः ब्रांच, पुल रिक्वेस्ट और रिव्यू मिल जाते हैं, क्योंकि स्टोर एक साधारण रेपो है।

टीम के कोड रेपो को कनेक्ट करना। जिस कोड रेपो की पूरी प्लानिंग बाहरी की गई है, उसमें openspec/config.yaml में केवल एक लाइन की जरूरत होती है:

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

अब web-app के अंदर चलाए गए हर ओपनस्पेक कमांड बिना किसी फ्लैग के team-plans पर काम करेंगे:

cd ~/src/web-app
openspec status --change add-login

ओपनस्पेक रूट का उपयोग: team-plans (/Users/you/openspec/team-plans)
...

पॉइंटर एक फॉलबैक है, कभी ओवरराइड नहीं: कोई स्पष्ट --store हमेशा जीतता है, और यदि रेपो अपने आप को प्लानिंग फोल्डर बनाता है तो वे जीतते हैं (पुराने पॉइंटर को हटाने के लिए चेतावनी के साथ)।

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

openspec config set defaultStore team-plans

अब बिना प्लानिंग रूट के बाहर चलाए गए किसी भी कमांड — और बिना --store और बिना प्रोजेक्ट पॉइंटर के — team-plans के लिए रिजॉल्व हो जाएगा। यह प्रीसेडेंस लिस्ट के नीचे बैठा है, इसलिए --store, एक लोकल रूट और एक प्रोजेक्ट store: पॉइंटर सभी अभी भी जीतते हैं। रूट बैनर और JSON root ब्लॉक source: "global_default" रिपोर्ट करते हैं स्टोर आईडी के साथ, ताकि आप हमेशा मशीन-वाइड डिफॉल्ट को रेपो के अपने पॉइंटर से अलग पहचान सकें। इसे openspec config unset defaultStore से क्लियर करें। यदि आईडी पंजीकृत नहीं है, तो कमांड एरर देते हैं और आपको इसे पंजीकृत करने या पुराने डिफॉल्ट को क्लियर करने के लिए कहते हैं।

कहानी: जिन आवश्यकताएँ टीम की सीमाओं को पार करती हैं

एक प्लेटफॉर्म टीम आवश्यकताओं का मालिक होती है। प्रोडक्ट टीम उनके खिलाफ बिल्ड करती है, अपने स्वयं के रेपो में, अपने स्वयं के डिजाइन के साथ। एक रेफरेंस इस संबंध को किसी के काम को हिलाए बिना वर्णित करता है।

   platform-reqs (स्टोर)                 api-server (कोड रेपो)
   प्लेटफॉर्म टीम द्वारा स्वामित्व में            एक प्रोडक्ट टीम द्वारा स्वामित्व में
   ┌──────────────────────────┐          ┌──────────────────────────┐
   │ openspec/specs/          │ ◀────────│ openspec/config.yaml     │
   │   payments/spec.md       │ पढ़ता है  │   references:            │
   │   auth/spec.md           │          │     - platform-reqs      │
   │                          │          │ openspec/specs/          │
   │ openspec/changes/        │          │   (उनके स्वयं के डिजाइन)    │
   │   platform work          │          │ openspec/changes/        │
   │                          │          │   (उनका स्वयं का कार्य)     │
   │                          │          └──────────────────────────┘
   └──────────────────────────┘

प्रोडक्ट टीम अपने रेपो के openspec/config.yaml में जिस पर यह निर्भर करता है उसे घोषित करती है:

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

रेफरेंस केवल पढ़ने योग्य संदर्भ होते हैं। रेपो अपना खुद का openspec/ रूट बनाए रखता है; कार्य वहीं रहता है। क्या बदलता है: उस रेपो में openspec instructions अब रेफरेंस किए गए स्टोर के स्पेक्स का इंडेक्स शामिल करता है — प्रत्येक के साथ एक लाइन सारांश और सटीक फेच कमांड (openspec show <spec-id> --type spec --store platform-reqs)। api-server में काम करने वाला एजेंट अपस्ट्रीम पेमेंट आवश्यकताओं को ढूंढ सकता है, उन्हें उद्धृत कर सकता है, और अपना लो-लेवल डिजाइन रेपो के अपने रूट में लिख सकता है — बिना किसी को संदर्भ चारों ओर पेस्ट किए।

एक रेफरेंस अपना क्लोन सोर्स ले जा सकता है, ताकि उन टीम सदस्यों जिनके पास स्टोर अभी तक नहीं है को पूरा फिक्स मिले बजाय किसी बेकार के सिरे के:

references:
  - { id: platform-reqs, remote: "git@github.com:acme/platform-reqs.git" }

जब आप प्लान और कोड को एक साथ खोलना चाहते हैं, तो वर्कसेट बनाएं। यह व्यक्तिगत और स्पष्ट है: प्रत्येक व्यक्ति उन फोल्डरों का चयन करता है जिनके साथ वह वास्तव में अपनी मशीन पर काम करता है। इन लोकल चेकआउट पाथ के बारे में कुछ भी शेयर किए गए प्लानिंग रेपो में कमिट नहीं किया जाता।

openspec workset create platform \
  --member ~/openspec/platform-reqs \
  --member ~/src/api-server \
  --member ~/src/web-app

आप हमेशा पूछ सकते हैं दो सवाल

"क्या मेरा सेटअप स्वस्थ है?" — openspec doctor करंट रूट और इसके रेफरेंस किए गए स्टोर्स को रीड-ओनली चेक करता है, हर फाइंडिंग के लिए पेस्ट करने योग्य फिक्स के साथ:

डॉक्टर

रूट
  स्थान: /Users/you/src/api-server
  ओपनस्पेक रूट: ठीक है

रेफरेंस
  - platform-reqs: ठीक है (/Users/you/openspec/platform-reqs)
  - design-system: रेफरेंस किया गया स्टोर 'design-system' इस मशीन पर पंजीकृत नहीं है।
    फिक्स: 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 context ओपनस्पेक घोषणाओं से वर्किंग सेट असेंबल करता है: रूट और उसके रेफरेंस किए गए स्टोर्स।

api-server (/Users/you/src/api-server) के लिए कार्य संदर्भ

ओपनस्पेक रूट
  api-server  /Users/you/src/api-server

रेफरेंस किए गए स्टोर्स
  platform-reqs  /Users/you/openspec/platform-reqs
    फेच: openspec show <spec-id> --type spec --store platform-reqs

दोनों एजेंट के लिए --json का समर्थन करते हैं। openspec context --code-workspace <path> अतिरिक्त रूप से पूरे सेट को शामिल करने वाली एक VS Code वर्कस्पेस फाइल लिखता है — यह कमांड द्वारा की जाने वाली एकमात्र लेखन कार्रवाई है।

वर्कसेट: उन फोल्डरों को फिर से खोलें जिनके साथ आप एक साथ काम करते हैं

उपरोक्त सभी से अलग: ज्यादातर लोग हर सत्र में एक ही कुछ फोल्डर एक साथ खोलते हैं — प्लानिंग रेपो और दो या तीन कोड रेपो। एक वर्कसेट उसकी व्यक्तिगत, नामित दृश्य होता है, जिसे आप अपने टूल ऑफ चॉइस में एक कमांड से फिर से खोल सकते हैं।

  वर्कसेट "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       आपके टूल में सभी तीन खोल दिए जाते हैं

openspec workset create platform \
  --member ~/openspec/team-plans --member ~/src/api-server \
  --tool code
openspec workset list

platform  (VS Code में खोलता है)
  team-plans  /Users/you/openspec/team-plans
  api-server  /Users/you/src/api-server

openspec workset open platform फिर से सहेजे गए टूल लॉन्च करता है: एडिटर (VS Code, Cursor) हर सदस्य के साथ एक विंडो खोलते हैं और वापस आ जाते हैं। पहला सदस्य प्राथमिक होता है। किसी भी समय --tool <id> के साथ टूल ओवरराइड करें। वर्कसेट जानबूझकर शेयर किए गए स्टेट नहीं होते हैं। वे आपकी मशीन पर रहते हैं, कभी कमिट नहीं होते, और काम के बारे में कोई दावा नहीं करते — वे केवल रिकॉर्ड करते हैं कि आप किसे एक साथ खोलना पसंद करते हैं। किसी वर्कसेट को हटाने से सदस्य फोल्डरों को कभी नुकसान नहीं पहुँचता। नए टूल कॉन्फ़िगरेशन होते हैं, कोड नहीं: किसी भी टूल जिसे वर्कस्पेस फाइल या प्रति-फोल्डर अटैच फ्लैग के माध्यम से लॉन्च किया जा सकता है, को ग्लोबल कॉन्फ़िग (openspec config edit) में openers कुंजी के अंतर्गत जोड़ा जा सकता है।

कमांड कहां काम करें यह कैसे तय करते हैं

हर सामान्य कमांड अपना रूट इस क्रम में रिजॉल्व करता है:

1. --store <id>          आपने स्पष्ट रूप से कहा है        → वह स्टोर
2. nearest openspec/     यहाँ एक वास्तविक प्लानिंग रूट है     → यह रेपो
   (क्रिएंट डायरेक्ट्री से ऊपर की ओर चलते हुए)
3. store: पॉइंटर        config.yaml एक स्टोर घोषित करता है  → वह स्टोर
4. defaultStore          ग्लोबल कॉन्फ़िग मशीन पर एक मशीन  → वह स्टोर
                         डिफॉल्ट सेट करती है
5. उपरोक्त में से कोई नहीं     इस मशीन पर पंजीकृत स्टोर्स हैं?     → चयन संकेत के साथ एरर
                         कोई स्टोर पंजीकृत नहीं है?         → करंट डायरेक्ट्री
                                                          (क्लासिक व्यवहार)

ओपनस्पेक रूट का उपयोग: लाइन (और --json आउटपुट में root ब्लॉक) आपको बताती है कि आप किस केस में हैं।

ज्ञात सीमाएँ

• बीटा आकार। इस पेज पर कुछ भी रिलीज़ के बीच बदल सकता है — नाम, फ्लैग, फाइल फॉर्मेट, JSON कीज़।
• मशीन प्रति स्टोर आईडी के लिए एक ही चेकआउट। एक ही आईडी के तहत दूसरा चेकआउट पंजीकृत करने से store unregister पहले करने के लिए संकेत के साथ विफल हो जाता है।
• कभी सिंक नहीं, डिज़ाइन द्वारा। ओपनस्पेक कभी क्लोन, पुल या पुश नहीं करता। एक पुराना चेकआउट तब तक पुराने स्पेक्स दिखाता है जब तक आप पुल नहीं करते; रेफरेंस डिस्क पर मौजूद किसी भी चीज़ से लाइव इंडेक्स की जाती हैं।
• खाली प्लानिंग फोल्डर अनुपस्थित हो सकते हैं। एक नए स्टोर में अभी तक गिट में openspec/changes/, openspec/specs/, या openspec/changes/archive/ नहीं हो सकता है। यह बीटा के दौरान स्वीकार्य है; ये फोल्डर तब तक दिखाई नहीं देते जब तक सामान्य कमांड उनके लिए फाइल नहीं बनाते।
• पॉइंटर रेपो पॉइंटर ही रहते हैं। एक केवल कॉन्फ़िग वाला रेपो जिसका openspec/config.yaml store: <id> घोषित करता है, उसे बाहरी की गई प्लानिंग के रूप में माना जाता है, पंजीकृत करने के लिए स्टोर चेकआउट के रूप में नहीं। यदि आप जानबूझकर उस रेपो को लोकल स्टोर रूट में कनवर्ट करना चाहते हैं, तो पहले store: लाइन हटा दें।
• कुछ कमांड जहां हैं वहीं रहते हैं। view, templates, schemas, और डिप्रेकेटेड नाउन फॉर्म (openspec change show, ...) केवल करंट डायरेक्ट्री पर काम करते हैं — कोई --store नहीं।
• पर-मशीन स्टेट पर-मशीन होता है। स्टोर रजिस्ट्री और वर्कसेट लोकल सेटिंग्स होती हैं। आपकी मशीन की लेआउट के बारे में कुछ भी कभी शेयर किए गए प्लानिंग में कमिट नहीं किया जाता है।
• वर्कसेट के लिए दो लॉन्च शैली। एक टूल जिसे वर्कस्पेस फाइल या प्रति-फोल्डर अटैच फ्लैग के साथ लॉन्च नहीं किया जा सकता, उसे ओपनर के रूप में नहीं जोड़ा जा सकता है।
• एजेंट JSON में एक ज्ञात केसिंग स्प्लिट है (स्टोर-फैमिली कीज स्नेक_केस हैं, वर्कफ्लो-फैमिली कैमलकेस)। इसे एजेंट कॉन्ट्रैक्ट में दस्तावेजित किया गया है; इसे एक वर्ज़न किए गए रिलीज़ तक एकीकृत करना स्थगित किया गया है।

चीजें कहां स्थित होती हैं

क्या	कहां	साझा किया जा सकता है?
स्टोर की योजना	<store>/openspec/ (स्पेक, परिवर्तन)	हां — इसे कमिट करें और पुश करें
स्टोर की पहचान	<store>/.openspec-store/store.yaml	हां — स्टोर के साथ ही कमिट होता है
स्टोर रजिस्ट्री	<data dir>/openspec/stores/registry.yaml	नहीं — केवल इस मशीन पर
वर्कसेट	<data dir>/openspec/worksets/	नहीं — केवल इस मशीन पर

<data dir> macOS और Linux पर ~/.local/share/openspec है (या $XDG_DATA_HOME/openspec जब सेट हो), और Windows पर %LOCALAPPDATA%\openspec है।

संदर्भ

इस पृष्ठ पर दिए गए हर कमांड के लिए सटिक फ्लैग्स और JSON आकार: CLI संदर्भ (स्टोर, डॉक्टर, कार्य संदर्भ, व्यक्तिगत वर्कसेट) और एजेंट कॉन्ट्रैक्ट।