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

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

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

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

यह तब काम करना बंद कर देता है जब आपकी योजना एक रेपो से बड़ी हो:

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

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

आकार

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

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

1. स्टोर बस एक git रिपोजिटरी है। आप खुद commit, push, pull और review करते हैं। OpenSpec कभी भी अपने आप कुछ clone, sync या push नहीं करता।
2. घोषणाएँ, मशीनरी नहीं। रिपोजिटरी स्टोर से अपने संबंध का घोषण कर सकती हैं (नीचे दिखाया गया है)। घोषणाएँ बदलती हैं कि OpenSpec आपको क्या बता सकता है — कभी भी यह नहीं कि आपके कमांड कहाँ कार्य करते हैं।

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

दो कमांड आपको शून्य से एक कार्यशील, स्टोर-स्कोप्ड परिवर्तन तक ले जाते हैं:

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

Store ready: team-plans
Location: /Users/you/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.

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

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

यह पूरा मॉडल है। यहाँ से lifecycle बिल्कुल वही है जो आप जानते हैं — status, instructions, validate, archive — हर कमांड पर --store team-plans के साथ, और हर छापे गए hint में यह flag आपके लिए शामिल होता है। Using OpenSpec root: लाइन हमेशा बताती है कि कमांड कहाँ कार्य कर रहा है。

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

एक टीम अपने specs और changes को 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 पास करने से clone URL स्टोर की अपनी पहचान फ़ाइल (.openspec-store/store.yaml) के अंदर दर्ज हो जाता है, प्रारंभिक commit में। हर भविष्य की clone यह जानकर जन्म लेती है कि वह कहाँ से आई है, ताकि health checks और error messages उन टीम-मेट्स के लिए एक पूर्ण, pasteable fix छाप सकें जिनके पास यह अभी तक नहीं है।

हर टीम-मेट (हर मशीन पर एक बार):

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

काम साझा करना git है, जानबूझकर। एक change जो आप बनाते हैं, वह केवल आपके checkout में मौजूद रहता है जब तक आप इसे commit और push नहीं करते — बिल्कुल कोड की तरह। Plans को branches, pull requests और review मुफ़्त मिलते हैं, क्योंकि स्टोर एक साधारण रिपोजिटरी है।

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

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

अब web-app के अंदर चलाया गया हर OpenSpec कमांड बिना किसी flag के team-plans पर कार्य करता है:

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

Using OpenSpec root: team-plans (/Users/you/openspec/team-plans)
...

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

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

openspec config set defaultStore team-plans

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

उदाहरण: एक feature, दो component रिपोजिटरी

मान लीजिए add-checkout-promo दोनों checkout-api और checkout-web में बदलाव करता है। टीम को एक साझा product contract चाहिए, जबकि हर कोड रिपोजिटरी को अभी भी अपनी implementation tasks, branch और review चाहिए।

दो परतें उपयोग करें:

1. साझा व्यवहार team-plans में रखें।
2. Implementation plans हर component रिपोजिटरी में रखें और स्टोर को read-only upstream context के रूप में reference करें।

पहले, स्टोर में साझा contract की योजना बनाएं:

openspec new change add-checkout-promo --store team-plans
openspec status --change add-checkout-promo --store team-plans

Proposal और specs को components के बीच की सीमा पर व्यवहार का वर्णन करना चाहिए — उदाहरण के लिए, service द्वारा लौटाए गए promotion fields और frontend एक अयोग्य checkout को कैसे संभालता है। इस change को स्टोर रिपोजिटरी में किसी भी अन्य branch और pull request की तरह review करें।

प्लानिंग को क्या context दिखता है?

स्टोर चुनना OpenSpec root बदलता है; यह उस स्टोर का उपयोग करने वाली हर कोड रिपोजिटरी को discover या read नहीं करता। स्टोर instructions स्टोर में मौजूद artifacts और configured context देखते हैं। वे component कोड तभी देखते हैं जब वे फ़ोल्डर agent या editor के लिए भी उपलब्ध हों और agent उन्हें पढ़े।

एक workset प्लानिंग स्टोर और दोनों कोड रिपोजिटरी को साथ में खोलने का एक सुविधाजनक तरीका है:

openspec workset create checkout-promo \
  --member ~/openspec/team-plans \
  --member ~/src/checkout-api \
  --member ~/src/checkout-web \
  --tool code
openspec workset open checkout-promo

यह फ़ोल्डर को एक IDE workspace में दृश्यमान बनाता है। यह source context को स्टोर में copy नहीं करता, प्रभावित रिपोजिटरी चुनता नहीं है, या agent को उन्हें edit करने की अनुमति नहीं देता। स्थायी cross-component तथ्य साझा specs में रखें; इस पर निर्भर न करें कि planner source याद रखेगा जिसे वह संयोगवश देख रहा था।

हर रिपोजिटरी में implementation कैसे शुरू होती है?

जब कोई स्पष्ट --store या निकटतम openspec/ root लागू नहीं होता, तो store: team-plans pointer कमांड को उस स्टोर की ओर route करता है। यह एक स्टोर task list को उस directory से split नहीं करता जिससे apply invoke किया गया था। OpenSpec वर्तमान में tasks को रिपोजिटरी में route नहीं करता।

जब हर component को स्वतंत्र रूप से स्कोप्ड apply/review cycle चाहिए, तो उसे एक स्थानीय OpenSpec root दें और केंद्रीय स्टोर का reference करें, उसे point करने के बजाय:

# checkout-api/openspec/config.yaml (और इसी तरह checkout-web में)
schema: spec-driven
references:
  - team-plans

साझा contract स्वीकृत होने और स्टोर के main specs में उपलब्ध होने के बाद, component के हिस्से के लिए एक छोटा स्थानीय change बनाएं:

cd ~/src/checkout-api
openspec new change implement-checkout-promo-api

cd ~/src/checkout-web
openspec new change implement-checkout-promo-ui

हर रिपोजिटरी के instructions में reference index स्टोर spec का summary और सटीक openspec show ... --store team-plans fetch कमांड प्रदान करता है। हर स्थानीय proposal उस साझा contract का उल्लेख करता है, और इसके tasks केवल उस component में काम का वर्णन करते हैं। फिर हर रिपोजिटरी में अलग से /opsx:apply चलाएं; root resolution artifacts और implementation edits को उस रिपोजिटरी तक सीमित रखता है। Service और frontend changes अब स्वतंत्र रूप से test, review, merge और archive किए जा सकते हैं।

यदि implementation को साझा स्टोर change अभी भी सक्रिय होने के दौरान शुरू करना होता है, तो इसे स्पष्ट रूप से fetch करें: openspec show add-checkout-promo --store team-plans; reference indexes canonical स्टोर specs सूचीबद्ध करते हैं, active स्टोर changes नहीं। स्टोर branch और component branches को उनके pull-request descriptions में जोड़े रखें ताकि reviewers देख सकें कि हर implementation contract के किस संस्करण का पालन कर रहा है।

कहानी: requirements जो टीम की सीमाओं को पार करते हैं

एक platform टीम requirements की मालकिन है। Product teams उनके अपने रिपोजिटरी में, अपने अपने designs के साथ उनके आधार पर निर्माण करते हैं। एक reference उस संबंध का वर्णन करता है बिना किसी के काम को हटाए।

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

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

references:
  - platform-reqs

References read-only context हैं। रिपोजिटरी अपना openspec/ root रखती है; काम वहीं रहता है。क्या बदलता है: उस रिपोजिटरी में openspec instructions अब referenced स्टोर के specs का एक index शामिल करता है — हर एक में एक-लाइन summary और सटीक fetch कमांड (openspec show <spec-id> --type spec --store platform-reqs)। api-server में काम कर रहा agent upstream payment requirements ढूंढ सकता है, उनका उल्लेख कर सकता है, और रिपोजिटरी के अपने root में अपना low-level design लिख सकता है — बिना किसी के context paste किए।

एक reference अपने clone source भी ले सकता है, ताकि उन टीम-मेट्स को जो स्टोर अभी तक नहीं रखते, एक पूर्ण fix मिले dead end के बजाय:

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

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

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

दो प्रश्न जो आप हमेशा पूछ सकते हैं

"मेरा सेटअप स्वस्थ है?" — openspec doctor वर्तमान root और इसके referenced स्टोर की जाँच करता है, read-only, हर finding के लिए एक pasteable fix के साथ:

Doctor

Root
  Location: /Users/you/src/api-server
  OpenSpec root: ok

References
  - platform-reqs: ok (/Users/you/openspec/platform-reqs)
  - 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 context OpenSpec घोषणाओं से working set एकत्र करता है: root और उसके referenced स्टोर।

Working context for api-server (/Users/you/src/api-server)

OpenSpec root
  api-server  /Users/you/src/api-server

Referenced stores
  platform-reqs  /Users/you/openspec/platform-reqs
    Fetch: openspec show <spec-id> --type spec --store platform-reqs

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

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

ऊपर बताई गई सभी बातों से अलग: अधिकांश लोग हर सत्र में एक ही कुछ फ़ोल्डर्स एक साथ खोलते हैं — प्लानिंग रिपो के अलावा दो या तीन कोड रिपो। एक वर्कसेट (workset) उसी का एक व्यक्तिगत, नामित व्यू होता है, जिसे आपकी पसंदीदा टूल में एक कमांड से फिर से खोला जा सकता है।

  workset "platform"                 openspec workset open platform
  ├── team-plans   ~/openspec/team-plans         │
  ├── api-server   ~/src/api-server              ▼
  └── web-app      ~/src/web-app       all three open in your tool

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

platform  (opens in 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>          you said so explicitly        → that store
2. nearest openspec/     a real planning root here     → this repo
   (walking up from cwd)
3. store: pointer        config.yaml declares a store  → that store
4. defaultStore          global config sets a machine  → that store
                         default
5. none of the above     stores registered on this     → error with a
                         machine?                        selection hint
                         no stores registered?         → the current
                                                          directory
                                                          (classic behavior)

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

ज्ञात सीमाएँ

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

चीज़ें कहाँ रहती हैं

क्या	कहाँ	शेयर्ड?
एक स्टोर की प्लानिंग	<store>/openspec/ (specs, changes)	हाँ — इसे कमिट और पुश करें
एक स्टोर की पहचान	<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 reference (Stores, Doctor, Working context, Personal worksets) और एजेंट कॉन्ट्रैक्ट।