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

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

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

openspec: command not found

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

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 पर चलता है, इसलिए आपको अपने 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. आप गलत जगह पर हो सकते हैं। स्लैश कमांड आपके AI असिस्टेंट की चैट में जाती है, न कि आपके टर्मिनल में। यदि आपने अपने शेल में /opsx:propose टाइप किया है, तो यही समस्या है। How Commands Work देखें।

2. फ़ाइलों को पुनर्जीवित करें (Regenerate)। अपनी प्रोजेक्ट रूट से:

   openspec update

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

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

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

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

6. पुष्टि करें कि आपका टूल कमांड फाइलों का समर्थन करता है। कुछ टूल (Kimi CLI, Trae, ForgeCode, Mistral Vibe) जनरेटेड opsx-* कमांड फ़ाइलों को प्राप्त नहीं करते हैं; वे इसके बजाय स्किल-आधारित आह्वान (skill-based invocations) का उपयोग करते हैं। फॉर्म प्रति टूल भिन्न होते हैं: Supported Tools और How Commands Work देखें।

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

"Change not found"

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

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

यह भी पुष्टि करें कि आप सही प्रोजेक्ट डायरेक्टरी में हैं।

"No artifacts ready"

हर आर्टिफैक्ट या तो पहले से ही बनाया जा चुका है या किसी निर्भरता (dependency) के लिए प्रतीक्षा करते हुए अवरुद्ध (blocked) है। देखें कि क्या रोक रहा है:

openspec status --change <name>

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

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

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

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

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

AI अधूरे या गलत आर्टिफैक्ट बनाता है

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

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

Archive समाप्त नहीं होता है, या अधूरे कार्यों के बारे में चेतावनी देता है

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

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

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

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

1. गलत फ़ाइल नाम। यह .yml नहीं होना चाहिए, बल्कि openspec/config.yaml होना चाहिए।
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 पर सीमित है, जानबूझकर, क्योंकि इसे हर अनुरोध में इंजेक्ट किया जाता है। इसका सारांश (summarize) करें, या पेस्ट करने के बजाय लंबी दस्तावेज़ों से लिंक आउट करें। संक्षिप्त संदर्भ भी बेहतर, तेज़ परिणाम देता है।

"Schema not found"

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

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

Customization देखें।

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

"Legacy files detected in non-interactive mode"

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

openspec init --force

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

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

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

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

अभी भी फँसे हुए हैं?

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

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