समस्या निवारण

वास्तविक समस्याओं के लिए वास्तविक समाधान। प्रत्येक प्रविष्टि में एक लक्षण का नाम लिया गया है, संभावित कारण को एक वाक्य में समझाया गया है, और आपको उसका समाधान दिया गया है। यदि आपका मुद्दा यहां नहीं है, तो FAQ मदद कर सकता है, और डिस्कॉर्ड निश्चित रूप से मदद करेगा।

स्थापना और सेटअप

openspec: command not found

CLI स्थापित नहीं है, या आपका शेल इसे नहीं ढूंढ पा रहा है। इसे वैश्विक स्तर पर स्थापित करें और जांचें:

npm install -g @fission-ai/openspec@latest
openspec --version

यदि यह स्थापित हो गया है लेकिन अभी भी नहीं मिल रहा है, तो शायद आपका वैश्विक npm बिन निर्देशिका आपके PATH में नहीं है। वैश्विक बाइनरीज़ कहां स्थित हैं, यह देखने के लिए npm bin -g चलाएं, और सुनिश्चित करें कि वह पथ आपके शेल प्रोफाइल में मौजूद है।

"Requires Node.js 20.19.0 or higher"

OpenSpec Node 20.19.0+ पर चलता है। अपना संस्करण जांचें और आवश्यकता पड़ने पर अपग्रेड करें:

node --version

यदि आप OpenSpec स्थापित करने के लिए bun का उपयोग करते हैं, तो ध्यान दें कि OpenSpec अभी भी Node पर चलता है, इसलिए आपको किसी भी हाल में Node 20.19.0+ को अपने PATH पर उपलब्ध रखना होगा। अधिक जानकारी के लिए स्थापना देखें।

openspec init didn't configure my AI tool

Init आपसे कौन से टूल सेट अप करने हैं यह पूछता है। यदि आपने अपना टूल छोड़ दिया है या किसी अन्य को जोड़ना चाहते हैं, तो बस इसे फिर से चलाएं, या गैर-इंटरैक्टिव फॉर्म का उपयोग करें:

openspec init --tools claude,cursor

टूल आईडी की पूरी सूची समर्थित टूल्स में उपलब्ध है। सभी के लिए --tools all का उपयोग करें, टूल सेटअप को छोड़ने के लिए --tools none का उपयोग करें।

कमांड दिखाई नहीं दे रहे हैं

यदि /opsx:propose (या आपके टूल के बराबर) दिखाई नहीं दे रहा है या कुछ भी नहीं कर रहा है, तो इस सूची को नीचे की ओर जाकर जांचें। ये सबसे पहले जल्दी जांचने योग्य क्रम में व्यवस्थित हैं।

1. शायद आप गलत जगह पर हैं। स्लैश कमांड आपके AI असिस्टेंट के चैट में जाते हैं, आपके टर्मिनल में नहीं। यदि आपने /opsx:propose को अपने शेल में टाइप किया है, तो यही समस्या है। अधिक जानकारी के लिए कमांड कैसे काम करते हैं देखें।

2. फाइलों को फिर से जनरेट करें। अपने प्रोजेक्ट रूट से:

   openspec update

   यह आपके द्वारा कॉन्फ़िगर किए गए प्रत्येक टूल के लिए स्किल और कमांड फाइलों को फिर से लिखता है।

3. अपना असिस्टेंट रीस्टार्ट करें। अधिकांश टूल स्टार्टअप पर स्किल और कमांड के लिए स्कैन करते हैं। एक नया विंडो अक्सर इस काम करता है।

4. फाइलें मौजूद हैं यह पुष्टि करें। Claude Code के लिए, जांचें कि .claude/skills/ में openspec-* फोल्डर मौजूद हैं। अन्य टूल अपनी खुद की निर्देशिकाएं उपयोग करते हैं, जो सभी समर्थित टूल्स में सूचीबद्ध हैं।

5. जांचें कि आपने इस प्रोजेक्ट को इनिशियलाइज़ किया है। स्किल प्रत्येक प्रोजेक्ट के लिए लिखी जाती हैं। यदि आपने कोई रेपो क्लोन किया है या फोल्डर बदल दिए हैं, तो वहां openspec init (या openspec update) चलाएं।

6. पुष्टि करें कि आपका टूल कमांड फाइलों का समर्थन करता है। Codex और कुछ अन्य टूल्स (CodeArts, Kimi CLI, ForgeCode, Mistral Vibe) को opsx-* कमांड फाइलें जनरेट नहीं होती हैं; इसके बजाय वे स्किल-आधारित इनवोकेशन का उपयोग करते हैं। CodeX के लिए, .codex/skills/openspec-* जांचें। फॉर्म टूल के अनुसार भिन्न होते हैं: अधिक जानकारी के लिए समर्थित टूल्स और कमांड कैसे काम करते हैं देखें।

परिवर्तनों के साथ काम करना

"Change not found"

कमांड यह पता नहीं लगा पा रहा था कि आप किस परिवर्तन की बात कर रहे हैं। इसे स्पष्ट रूप से नाम दें, या जांचें कि क्या मौजूद है:

openspec list                    # see active changes
/opsx:apply add-dark-mode        # name the change in chat

साथ ही पुष्टि करें कि आप सही प्रोजेक्ट निर्देशिका में हैं।

"No artifacts ready"

प्रत्येक आर्टिफैक्ट या तो पहले ही बनाया गया है या किसी निर्भरता पर इंतज़ार करते हुए ब्लॉक हो गया है। यह देखें कि क्या ब्लॉक कर रहा है:

openspec status --change <name>

फिर पहले गुम निर्भरता बनाएं। क्रम याद रखें: प्रस्ताव स्पेक और डिज़ाइन को सक्षम करता है; स्पेक और डिज़ाइन एक साथ कार्यों को सक्षम करते हैं।

openspec validate reports warnings or errors

वेलिडेशन आपके स्पेक और परिवर्तनों को संरचनात्मक समस्याओं के लिए जांचता है। संदेश पढ़ें: इसमें फाइल और समस्या का नाम लिया गया है।

openspec validate <name>           # validate one item
openspec validate --all            # validate everything
openspec validate --all --strict   # stricter checks, good for CI

सामान्य कारणों में अनावश्यक अनुभाग की कमी (जैसे कोई स्पेक जिसमें कोई परिदृश्य नहीं है) या गलत फॉर्मेट किया गया डेल्टा हेडर शामिल है। फाइल को ठीक करें और फिर से चलाएं। आउटपुट फॉर्मेट को CLI संदर्भ दस्तावेजित करता है।

The AI created incomplete or wrong artifacts

AI के पास पर्याप्त संदर्भ नहीं था। कुछ लीवर मदद करते हैं:

• openspec/config.yaml में प्रोजेक्ट संदर्भ जोड़ें ताकि आपका स्टैक और परंपराएं हर अनुरोध में इंजेक्ट हो जाएं। अधिक जानकारी के लिए कस्टमाइज़ेशन देखें।
• केवल स्पेक जैसे आर्टिफैक्ट पर लागू होने वाली मार्गदर्शन के लिए प्रत्येक आर्टिफैक्ट के लिए rules: जोड़ें।
• प्रस्तावित करते समय अधिक विस्तृत विवरण दें।
• एक बार में एक आर्टिफैक्ट बनाने और प्रत्येक की समीक्षा करने के लिए विस्तारित /opsx:continue का उपयोग करें, इसके बजाय /opsx:ff से सभी को एक साथ कर लें।

Archive won't finish, or warns about incomplete tasks

आर्काइव अधूरे कार्यों पर ब्लॉक नहीं होगा, लेकिन यह आपको चेतावनी देता है, क्योंकि आर्काइव करना आमतौर पर कार्य पूर्ण हो गया है का अर्थ होता है। यदि कार्यों को जानबूझकर बचा हुआ है (आप आंशिक परिवर्तन फाइल कर रहे हैं), तो आगे बढ़ें। अन्यथा पहले कार्यों को पूरा करें। आर्काइव यह भी पेश करेगा कि आपके डेल्टा स्पेक को मुख्य स्पेक में सिंक करें यदि आपने अभी तक सिंक नहीं किया है; जब तक आपके पास ऐसा करने का कारण न हो, तो हां कहें।

कॉन्फ़िगरेशन

My config.yaml isn't being applied

तीन आम संदेहियां:

1. गलत फाइलनाम। यह openspec/config.yaml होना चाहिए, .yml नहीं।
2. अमान्य YAML। इसे किसी भी YAML वैलिडेटर के माध्यम से चलाएं; CLI सिंटैक्स त्रुटियों को लाइन नंबर के साथ भी रिपोर्ट करता है।
3. आपने रीस्टार्ट की उम्मीद की। आपको इसकी जरूरत नहीं है। कॉन्फ़िगरेशन परिवर्तन तुरंत लागू हो जाते हैं।

"Unknown artifact ID in rules: X"

rules: के तहत कोई कुंजी आपके स्कीमा में किसी भी आर्टिफैक्ट से मेल नहीं खाती है। डिफॉल्ट spec-driven स्कीमा के लिए वैध आईडी proposal, specs, design, tasks हैं। किसी भी स्कीमा के आईडी देखने के लिए:

openspec schemas --json

अधिक जानकारी के लिए कस्टमाइज़ेशन देखें।

"Context too large"

context: फ़ील्ड को जानबूझकर 50KB तक सीमित किया गया है, क्योंकि यह हर अनुरोध में इंजेक्ट होता है। इसे सारांशित करें, या लंबे दस्तावेजों को पेस्ट करने के बजाय उनके लिंक दें। कम संदर्भ से बेहतर, तेज़ परिणाम भी मिलते हैं।

"Schema not found"

आपके द्वारा संदर्भित स्कीमा नाम मौजूद नहीं है। उपलब्ध सूचीबद्ध करें और वर्तनी जांचें:

openspec schemas                    # list available schemas
openspec schema which <name>        # see where a schema resolves from
openspec schema init <name>         # create a custom one

अधिक जानकारी के लिए कस्टमाइज़ेशन देखें।

लेगेसी वर्कफ़्लो से माइग्रेशन

"Legacy files detected in non-interactive mode"

आप CI या गैर-इंटरैक्टिव शेल में हैं, और OpenSpec ने साफ करने के लिए पुरानी फाइलें पाई हैं लेकिन आपसे प्रॉम्प्ट नहीं कर सकता। स्वतः अनुमोदन करें:

openspec init --force

CodeX के लिए, OpenSpec $CODEX_HOME/prompts या ~/.codex/prompts में पुराने मैनेज्ड प्रॉम्प्ट फाइलों का पता लगा सकता है। यह सफाई OpenSpec की अनुमोदित सूची में आने वाले लेगेसी CodeX प्रॉम्प्ट फाइलनाम तक सीमित है, और गैर-इंटरैक्टिव openspec init केवल उन फाइलों को हटाता है जिनके रिप्लेसमेंट .codex/skills/openspec-* स्किल मौजूद हैं। जब तक आप --force पास नहीं करते, तब तक गैर-इंटरैक्टिव openspec update सभी लेगेसी सफाई को अछूता छोड़ देता है।

Commands didn't appear after migrating

अपना IDE रीस्टार्ट करें। स्किल स्टार्टअप पर डिटेक्ट होती हैं। यदि वे अभी भी दिखाई नहीं दे रहे हैं, तो openspec update चलाएं और समर्थित टूल्स में फाइल लोकेशन की जांच करें।

My old project.md wasn't migrated

यह जानबूझकर किया गया है। OpenSpec कभी भी project.md को स्वतः हटाता नहीं क्योंकि इसमें आपके द्वारा लिखा गया संदर्भ हो सकता है। उपयोगी भागों को config.yaml के context: अनुभाग में स्थानांतरित करें, फिर इसे खुद हटा दें। माइग्रेशन गाइड इसमें से गुजरता है, जिसमें आप अपने AI को डिस्टिलिंग करने के लिए दे सकने वाला एक प्रॉम्प्ट भी शामिल है।

अभी भी समस्या में हैं?

• डिस्कॉर्ड: discord.gg/YctCnvvshC
• गिटहब इश्यू: github.com/Fission-AI/OpenSpec/issues
• अपने टर्मिनल से: openspec feedback "what went wrong" आपके लिए एक इश्यू खोलता है।

जब आप कोई समस्या रिपोर्ट करते हैं, तो अपना OpenSpec संस्करण (openspec --version), अपना Node संस्करण (node --version), अपना AI टूल, और सटीक कमांड और आउटपुट शामिल करें। यह मदद को काफी तेज़ बनाता है।