शुरुआत करें

यह गाइड बताता है कि इंस्टॉल और इनिशियलाइज़ करने के बाद OpenSpec कैसे काम करता है। इंस्टॉलेशन के निर्देशों के लिए, मुख्य README या इंस्टॉलेशन गाइड देखें। पूरे दस्तावेज़ सेट से नया हैं? दस्तावेज़ होम सभी चीजों का नक्शा बनाता है।

आप इन कमांड को कहां टाइप करें? दो जगह, और उन्हें मिलाना शुरुआती दौर में सबसे आम गलती है।

• openspec ... कमांड (जैसे openspec init) आपके टर्मिनल में चलते हैं।
• /opsx:... कमांड (जैसे /opsx:propose) आपके AI असिस्टेंट के चैट में चलते हैं, वही बॉक्स जहां आप उसे कोड लिखने के लिए कहते हैं।

शुरू करने के लिए कोई अलग "इंटरैक्टिव मोड" नहीं है। आपको बस चैट में स्लैश कमांड टाइप करना है और आपका असिस्टेंट बाद में सब कुछ संभाल लेगा। पूरा विवरण: कमांड कैसे काम करते हैं.

आपके पहले पाँच मिनट

पूरा लूप, जिसमें प्रत्येक चरण को उस जगह के लिए लेबल किया गया है जहां वह होता है:

TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project && openspec init
AI CHAT      /opsx:explore                    (optional: think it through first)
AI CHAT      /opsx:propose add-dark-mode      (AI drafts the plan; you review it)
AI CHAT      /opsx:apply                      (AI builds it)
AI CHAT      /opsx:archive                    (specs updated, change filed away)

सेटअप के लिए दो टर्मिनल चरण, फिर आप चैट में काम करेंगे। इस गाइड का बाकी हिस्सा प्रत्येक चरण क्या करता है और आपको क्या दिखेगा, इसका विवरण देता है।

अभी तक क्या बनाना है यह सुनिश्चित नहीं हैं? /opsx:explore से शुरुआत करें। यह एक बिना जोखिम के सोचने का साथी है जो आपके कोडबेस को पढ़ता है, विकल्पों का मूल्यांकन करता है, और किसी भी आर्टिफैक्ट या कोड मौजूद होने से पहले ही एक अस्पष्ट विचार को एक ठोस योजना में बदल देता है। जब सब कुछ स्पष्ट हो जाता है, तो यह /opsx:propose को सौंप देता है। यह उस AI के साथ काम करने का सबसे अच्छा आदत है जो अन्यथा आत्मविश्वास से गलत चीज बना लेता है। एक्सप्लोर गाइड देखें।

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

OpenSpec आप और आपके AI कोडिंग असिस्टेंट को किसी भी कोड लिखने से पहले यह सहमत होने में मदद करता है कि क्या बनाना है।

डिफॉल्ट क्विक पाथ (कोर प्रोफाइल):

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
   (optional)

जब आप यह तय कर रहे हैं कि क्या करना है तो /opsx:explore से शुरुआत करें, या जब आप पहले से जानते हैं तो सीधे /opsx:propose पर जाएं। एक्सप्लोर डिफॉल्ट प्रोफाइल में है, इसलिए जब भी आपको चाहिए यह वहां मौजूद रहता है।

एक्सपैंडेड पाथ (कस्टम वर्कफ्लो सिलेक्शन):

/opsx:new ──► /opsx:ff or /opsx:continue ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

डिफॉल्ट ग्लोबल प्रोफाइल core है, जिसमें propose, explore, apply, sync, और archive शामिल हैं। आप openspec config profile और फिर openspec update का उपयोग करके एक्सपैंडेड वर्कफ्लो कमांड को सक्षम कर सकते हैं।

OpenSpec क्या बनाता है

openspec init चलाने के बाद, आपका प्रोजेक्ट यह संरचना रखता है:

openspec/
├── specs/              # सत्य का स्रोत (आपकी सिस्टम का व्यवहार)
│   └── <domain>/
│       └── spec.md
├── changes/            # प्रस्तावित अपडेट (प्रत्येक बदलाव के लिए एक फोल्डर)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # डेल्टा स्पेक्स (क्या बदल रहा है)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # प्रोजेक्ट कॉन्फ़िगरेशन (वैकल्पिक)

दो मुख्य निर्देशिकाएं:

• specs/ - सत्य का स्रोत। ये स्पेक्स बताते हैं कि आपकी सिस्टम वर्तमान में कैसे व्यवहार करती है। डोमेन के अनुसार व्यवस्थित (जैसे specs/auth/, specs/payments/).

• changes/ - प्रस्तावित संशोधन। प्रत्येक बदलाव को उसके सभी संबंधित आर्टिफैक्ट के साथ अपना अलग फोल्डर मिलता है। जब कोई बदलाव पूरा हो जाता है, तो उसके स्पेक्स मुख्य specs/ निर्देशिका में मिल जाते हैं।

आर्टिफैक्ट को समझना

प्रत्येक बदलाव फोल्डर में काम का मार्गदर्शन करने वाले आर्टिफैक्ट होते हैं:

आर्टिफैक्ट	उद्देश्य
proposal.md	"क्यों" और "क्या" - इरादा, स्कोप और दृष्टिकोण को कैप्चर करता है
specs/	जोड़े गए/संशोधित/हटाए गए आवश्यकताओं को दिखाने वाले डेल्टा स्पेक्स
design.md	"कैसे" - तकनीकी दृष्टिकोण और आर्किटेक्चर निर्णय
tasks.md	चेकबॉक्स वाला इंप्लीमेंटेशन चेकलिस्ट

आर्टिफैक्ट एक दूसरे पर निर्मित होते हैं:

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            जैसे-जैसे आप सीखें अपडेट करें

आप इंप्लीमेंटेशन के दौरान ज्यादा सीखने पर हमेशा वापस जाकर पहले के आर्टिफैक्ट को बेहतर बना सकते हैं।

डेल्टा स्पेक्स कैसे काम करते हैं

डेल्टा स्पेक्स OpenSpec में मुख्य अवधारणा हैं। ये आपके वर्तमान स्पेक्स के सापेक्ष क्या बदल रहा है, दिखाते हैं।

फॉर्मेट

डेल्टा स्पेक्स बदलाव के प्रकार को इंगित करने के लिए सेक्शन का उपयोग करते हैं:

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST require a second factor during login.

#### Scenario: OTP required
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented

## MODIFIED Requirements

### Requirement: Session Timeout
The system SHALL expire sessions after 30 minutes of inactivity.
(Previously: 60 minutes)

#### Scenario: Idle timeout
- GIVEN an authenticated session
- WHEN 30 minutes pass without activity
- THEN the session is invalidated

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA)

आर्काइव करने पर क्या होता है

जब आप कोई बदलाव आर्काइव करते हैं:

1. ADDED आवश्यकताओं को मुख्य स्पेक में जोड़ दिया जाता है
2. MODIFIED आवश्यकताएं मौजूदा वर्जन को बदल देती हैं
3. REMOVED आवश्यकताओं को मुख्य स्पेक से हटा दिया जाता है

ऑडिट इतिहास के लिए बदलाव फोल्डर को openspec/changes/archive/ में स्थानांतरित कर दिया जाता है।

उदाहरण: आपका पहला बदलाव

आइए किसी एप्लिकेशन में डार्क मोड जोड़ने की प्रक्रिया को समझते हैं।

1. बदलाव शुरू करें (डिफॉल्ट)

You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md — हम यह क्यों कर रहे हैं, क्या बदल रहा है
     ✓ specs/       — आवश्यकताएं और परिदृश्य
     ✓ design.md    — तकनीकी दृष्टिकोण
     ✓ tasks.md     — इंप्लीमेंटेशन चेकलिस्ट
     इंप्लीमेंटेशन के लिए तैयार!

यदि आपने एक्सपैंडेड वर्कफ्लो प्रोफाइल सक्षम कर लिया है, तो आप इसे दो चरणों में भी कर सकते हैं: पहले /opsx:new फिर /opsx:ff (या बढ़ते हुए /opsx:continue)。

2. क्या बनता है

proposal.md - इरादा कैप्चर करता है:

# प्रस्ताव: डार्क मोड जोड़ें

## इरादा
उपयोगकर्ताओं ने रात के समय उपयोग करने पर आंखों के तनाव को कम करने के लिए डार्क मोड विकल्प का अनुरोध किया है।

## स्कोप
- सेटिंग्स में थीम टॉगल जोड़ें
- सिस्टम प्रिफरेंस डिटेक्शन का समर्थन करें
- localStorage में प्रिफरेंस को सहेजें

## दृष्टिकोण
स्टेट मैनेजमेंट के लिए React कॉन्टेक्स्ट के साथ थीमिंग के लिए CSS कस्टम प्रॉपर्टीज का उपयोग करें।

specs/ui/spec.md - नई आवश्यकताओं को दिखाने वाला डेल्टा:

# UI के लिए डेल्टा

## ADDED Requirements

### Requirement: थीम सिलेक्शन
The system SHALL allow users to choose between light and dark themes.

#### Scenario: मैन्युअल टॉगल
- GIVEN किसी भी पेज पर उपयोगकर्ता
- WHEN उपयोगकर्ता थीम टॉगल पर क्लिक करता है
- THEN थीम तुरंत स्विच हो जाता है
- AND प्रिफरेंस सत्रों में भी बनी रहती है

#### Scenario: सिस्टम प्रिफरेंस
- GIVEN जिस उपयोगकर्ता की कोई सहेजी हुई प्रिफरेंस नहीं है
- WHEN एप्लिकेशन लोड होता है
- THEN सिस्टम का पसंदीदा कलर स्कीम उपयोग में लिया जाता है

tasks.md - इंप्लीमेंटेशन चेकलिस्ट:

# टास्क

## 1. थीम इंफ्रास्ट्रक्चर
- [ ] 1.1 लाइट/डार्क स्टेट के साथ ThemeContext बनाएं
- [ ] 1.2 कलर के लिए CSS कस्टम प्रॉपर्टीज जोड़ें
- [ ] 1.3 localStorage पर्सिस्टेंस इंप्लीमेंट करें

## 2. UI कॉम्पोनेंट्स
- [ ] 2.1 ThemeToggle कॉम्पोनेंट बनाएं
- [ ] 2.2 सेटिंग्स पेज में टॉगल जोड़ें
- [ ] 2.3 क्विक टॉगल शामिल करने के लिए Header अपडेट करें

## 3. स्टाइलिंग
- [ ] 3.1 डार्क थीम कलर पैलेट परिभाषित करें
- [ ] 3.2 CSS वेरिएबल्स का उपयोग करने के लिए कॉम्पोनेंट्स अपडेट करें

3. इंप्लीमेंट करें

You: /opsx:apply

AI:  टास्क्स पर काम कर रहा हूं...
     ✓ 1.1 लाइट/डार्क स्टेट के साथ ThemeContext बनाया
     ✓ 1.2 globals.css में CSS कस्टम प्रॉपर्टीज जोड़ी
     ✓ 1.3 localStorage पर्सिस्टेंस इंप्लीमेंट की
     ✓ 2.1 ThemeToggle कॉम्पोनेंट बनाया
     ...
     सभी टास्क्स पूरे हो गए!

इंप्लीमेंटेशन के दौरान, यदि आप पाते हैं कि डिज़ाइन में समायोजन की जरूरत है, तो बस आर्टिफैक्ट को अपडेट करें और जारी रखें।

4. आर्काइव करें

You: /opsx:archive

AI:  add-dark-mode को आर्काइव कर रहा हूं...
     ✓ स्पेक्स को openspec/specs/ui/spec.md में मिला दिया
     ✓ openspec/changes/archive/2025-01-24-add-dark-mode/ में स्थानांतरित कर दिया
     हो गया! अगली फीचर के लिए तैयार।

अब आपके डेल्टा स्पेक्स मुख्य स्पेक्स का हिस्सा हैं, जो आपकी सिस्टम के काम करने की विधि को दस्तावेजित करते हैं।

सत्यापन और समीक्षा

अपने बदलावों की जांच करने के लिए CLI का उपयोग करें:

# सक्रिय बदलावों की सूची बनाएं
openspec list

# बदलाव का विवरण देखें
openspec show add-dark-mode

# स्पेक फॉर्मेटिंग को वैलिडेट करें
openspec validate add-dark-mode

# इंटरैक्टिव डैशबोर्ड
openspec view

अगले कदम

• पहले एक्सप्लोर करें - किसी विचार को कमिट करने से पहले उसे सोचने के लिए /opsx:explore का उपयोग करें
• बदलाव की समीक्षा करें - किसी भी कोड लिखने से पहले AI द्वारा बनाई गई योजना में क्या जांचें
• अच्छे स्पेक्स लिखें - एक मजबूत आवश्यकता और परिदृश्य कैसे दिखें
• एक मौजूदा प्रोजेक्ट में OpenSpec का उपयोग करें - एक बड़े ब्राउनफील्ड कोडबेस पर काम शुरू करें
• बदलाव में संपादन और इटरेशन - आर्टिफैक्ट अपडेट करें, वापस जाएं, मैन्युअल संपादनों को समन्वयित करें
• एक नजर में कोर कॉन्सेप्ट - एक पेज पर पूरा मेंटल मॉडल
• उदाहरण और रेसिपी - वास्तविक बदलाव, शुरुआत से अंत तक
• वर्कफ्लो - सामान्य पैटर्न और प्रत्येक कमांड का उपयोग कब करें
• कमांड - सभी स्लैश कमांड के लिए पूरा संदर्भ
• कॉन्सेप्ट - स्पेक्स, बदलाव और स्कीमा की गहरी समझ
• कस्टमाइज़ेशन - OpenSpec को अपने अनुसार काम कराएं
• स्टोर्स - रेपो या टीम्स में फैला प्लानिंग? इसे अपने अलग रेपो में रखें (बीटा)
• FAQ और समस्या निवारण - जब आप कठिनाई में फंसें