समस्या निवारण (Troubleshooting)

निश्चित समस्याओं के लिए ठोस समाधान। प्रत्येक अनुभाग एक लक्षण का नाम बताता है, एक वाक्य में संभावित कारण की व्याख्या करता है, और आपको समाधान देता है। यदि आप अपनी समस्या यहाँ नहीं देखते हैं, तो FAQ मदद कर सकता है, और Discord निश्चित रूप से मदद करेगा।

इंस्टॉलेशन और सेटअप

openspec: command not found

CLI इंस्टॉल नहीं है, या आपका शेल इसे खोज नहीं पा रहा है। इसे वैश्विक स्तर पर इंस्टॉल करें और जांचें:

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

यदि यह इंस्टॉल हो गया है लेकिन फिर भी नहीं मिल रहा है, तो आपके वैश्विक npm bin निर्देशिका संभवतः आपके PATH में नहीं है। वैश्विक पैकेज कहाँ स्थित हैं, यह देखने के लिए npm prefix -g चलाएं: macOS और Linux पर बाइनरी उस निर्देशिका के bin/ में होती हैं, और Windows पर वे सीधे उसमें स्थित होती हैं। सुनिश्चित करें कि वह पथ आपके PATH में है। (npm 9 में npm bin -g को हटा दिया गया था।)

यदि आपने AI-सहायक इंस्टॉलेशन का उपयोग किया है, तो यह अपेक्षित हस्तांतरण बिंदु है: वह प्रॉम्प्ट आपके सहायक को आपके शेल स्टार्टअप फ़ाइलों को स्वयं संपादित करने के बजाय आपको PATH परिवर्तन दिखाने के लिए कहता है।

"Requires Node.js 20.19.0 or higher"

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

node --version

यदि आप OpenSpec इंस्टॉल करने के लिए bun का उपयोग करते हैं, तो ध्यान दें कि OpenSpec अभी भी Node पर चलता है, इसलिए आपको अपने PATH पर Node 20.19.0+ उपलब्ध रखने की आवश्यकता होगी, भले ही कुछ भी हो। इसके लिए Installation देखें।

openspec init ने मेरे AI टूल को कॉन्फ़िगर नहीं किया

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

openspec init --tools claude,cursor

सभी टूल IDs की पूरी सूची Supported Tools में है। सबके लिए --tools all का उपयोग करें, टूल सेटअप को छोड़ने के लिए --tools none का उपयोग करें।

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

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

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

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

   openspec update

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

   निर्देश फ़ाइलें इंस्टॉल किए गए CLI से आती हैं, इसलिए एक पुराना CLI हर चीज़ को अपडेटेड रिपोर्ट करता है बिना नए वर्कफ़्लो को कभी लिखे। openspec update अब इसके लिए जांच करता है और अपग्रेड करने का प्रस्ताव देता है — यदि आप इसे देखते हैं तो प्रस्ताव स्वीकार करें।

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

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

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

6. सुनिश्चित करें कि आपका टूल कमांड फ़ाइलों का समर्थन करता है। Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent, और साझा .agents टारगेट को opsx-* कमांड फ़ाइलें जनरेट नहीं होतीं; वे इसके बजाय स्किल-आधारित इन्वोकेशन का उपयोग करते हैं, इसलिए उनके लिए /opsx कभी ऑटोकम्प्लीट नहीं होगा। Codex में $openspec-propose, Kimi Code में /skill:openspec-propose, और बाकी में /openspec-propose टाइप करें। साझा .agents टारगेट विक्रेता-तटस्थ है, इसलिए /openspec-propose सामान्य रूप है, गारंटीकृत नहीं — यदि आपका असिस्टेंट इसका उत्तर नहीं देता है, तो जांचें कि यह स्किल को कैसे इन्वोक करता है, इसके अपने दस्तावेज़ों में। Amazon Q को कमांड फ़ाइलें मिलती हैं, लेकिन उन्हें अपने स्लैश मेनू में नहीं, बल्कि अपने प्रॉम्प्ट लाइब्रेरी में लोड करता है — वहाँ @opsx-propose टाइप करें, /opsx नहीं। हर टूल का रूप How To Invoke में सूचीबद्ध है।

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

"Change not found"

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

openspec list                    # सक्रिय परिवर्तन देखें
/opsx:apply add-dark-mode        # चैट में परिवर्तन का नाम दें

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

"No artifacts ready"

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

openspec status --change <name>

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

openspec validate चेतावनियों या त्रुटियों की रिपोर्ट करता है

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

openspec validate <name>           # एक आइटम वैलिडेट करें
openspec validate --all            # सब कुछ वैलिडेट करें
openspec validate --all --strict   # कठोर जांच, CI के लिए अच्छा
openspec validate --archived       # यदि आर्काइव्ड परिवर्तनों में अनचेक किए गए टास्क हैं तो विफल हो जाएं

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

एक संदेश को अपनी नोट值得它的 own note:

MODIFIED "<requirement>" omits scenario(s) the current spec still has: "<scenario>"

एक MODIFIED आवश्यकता पूरी आवश्यकता ब्लॉक को प्रतिस्थापित करती है, इसलिए उसे हर उस परिदृश्य को लेना होगा जो परिवर्तन के बाद जीवित रहता है, न कि केवल उनको जिन्हें आपने संपादित किया है। openspec/specs/<capability-path>/spec.md से नामित परिदृश्यों को डेल्टा में वापस कॉपी करें, पथ में किसी भी डोमेन निर्देशिका को बनाए रखते हुए। यह अक्सर एक पुराने परिवर्तन पर दिखाई देता है जब किसी अन्य के परिवर्तन ने उसी आवश्यकता में एक परिदृश्य जोड़ा — आर्काइव किसी भी स्थिति में उस परिवर्तन को अस्वीकार कर देता है, और वैलिडेशन अब इसे लागू करने से पहले कहता है।

AI ने अपूर्ण या गलत आर्टिफैक्ट बनाए

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

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

आर्काइव पूरा नहीं हो रहा है, या अपूर्ण टास्क के बारे में चेतावनी दे रहा है

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

"User force closed the prompt with 0 null"

कुछ ऐसा चला जिसने openspec archive चलाया जहाँ कोई प्रश्न का उत्तर नहीं दे सकता — एक AI एजेंट इसे किसी टूल से कॉल कर रहा है, एक CI जॉब, या कोई भी शेल जिसका stdin बंद है। आर्काइव अधिकतम तीन पुष्टियाँ पूछता है, और एक अउत्तर योग्य प्रश्न पहले उस कच्चे संदेश के साथ विफल हो जाता था।

--yes पास करें ताकि वे पहले से ही उत्तर दे सकें:

openspec archive <change-name> --yes

उन सभी फ्लैग्स को बनाए रखें जिन्हें आप पहले से पास कर रहे थे — --skip-specs और --no-validate आर्काइव के कार्य को बदलते हैं, इसलिए एक साधारण --yes रीरन एक समान कमांड नहीं है। वर्तमान संस्करण आपको फ्लैग का नाम बताते हैं और एक Fix: लाइन प्रिंट करते हैं जिसे आप पेस्ट कर सकते हैं। यदि आप किसी सूची से चुनना चाहते थे, तो परिवर्तन का नाम स्पष्ट रूप से पास करें: पिक्कर को भी उत्तर की आवश्यकता होती है।

यदि आपने इसके बजाय आर्काइव को किसी फ़ाइल में रीडायरेक्ट करके या किसी टूल द्वारा कैप्चर करके चलाया और हां, उत्तर पाइप किया (printf 'y\n' | openspec archive …), तो पुराने संस्करणों ने प्रॉम्प्ट खींचते समय उस कैप्चर में टर्मिनल एस्केप कोड लिखे — कुछ वातावरणों में काफी हद तक फ़ाइल को बढ़ा दिया। वर्तमान संस्करण तब तक पुष्टि प्रॉम्प्ट्स को सादे टेक्स्ट के रूप में पढ़ते हैं जब stdout एक टर्मिनल नहीं होता है, और एक बिना तर्क के openspec archive (जो अन्यथा एक इंटरैक्टिव परिवर्तन पिक्कर खींचेगा) आपको पहले से ही एक परिवर्तन नाम पास करने के लिए कहता है, कैप्चर में एक मेनू रेंडर करने के बजाय। किसी भी स्थिति में, रीडायरेक्टेड और एजेंट रन साफ़ रहते हैं; --yes (परिवर्तन नाम के साथ) पास करने से प्रॉम्प्ट्स पूरी तरह से स्किप हो जाते हैं।

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

मेरा config.yaml लागू नहीं हो रहा है

तीन आम संदिग्ध:

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

"Unknown artifact ID in rules: X"

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

openspec schemas --json

"Context too large"

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

"Schema not found"

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

openspec schemas                    # उपलब्ध स्कीमा सूचीबद्ध करें
openspec schema which <name>        # देखें कि एक स्कीमा कहाँ से रिज़ॉल्व होती है
openspec schema init <name>         # एक कस्टम बनाएं

Customization देखें।

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

"Legacy files detected in non-interactive mode"

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

openspec init --force

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

माइग्रेशन के बाद कमांड दिखाई नहीं दिए

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

मेरी पुरानी project.md माइग्रेट नहीं हुई

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

अभी भी फंस गए हैं?

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

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