शुरुआत कैसे करें

यह गाइड समझाती है कि 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 के साथ काम करने का सबसे अच्छा आदत है, जो वरना आत्मविश्वास से गलत चीज़ बना देगा। Explore गाइड देखें।

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

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

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

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

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

विस्तारित पाथ (कस्टम वर्कफ़्लो चयन):

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

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

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

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

openspec/
├── specs/              # Source of truth (your system's behavior)
│   └── <domain>/
│       └── spec.md
├── changes/            # Proposed updates (one folder per change)
│   └── <change-name>/
│       ├── proposal.md
│       ├── design.md
│       ├── tasks.md
│       └── specs/      # Delta specs (what's changing)
│           └── <domain>/
│               └── spec.md
└── config.yaml         # Project configuration (optional)

दो मुख्य डायरेक्टरी:

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

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

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

हर परिवर्तन फ़ोल्डर में ऐसे आर्टिफैक्ट्स होते हैं जो काम की दिशा निर्देश देते हैं:

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

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

proposal ──► specs ──► design ──► tasks ──► implement
   ▲           ▲          ▲                    │
   └───────────┴──────────┴────────────────────┘
            update as you learn

आप हमेशा वापस जाकर पहले के आर्टिफैक्ट्स को परिष्कृत कर सकते हैं जैसे-जैसे आप इम्प्लीमेंटेशन के दौरान और जानते जाते हैं।

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

डेल्टा स्पेक्स 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 — why we're doing this, what's changing
     ✓ specs/       — requirements and scenarios
     ✓ design.md    — technical approach
     ✓ tasks.md     — implementation checklist
     Ready for implementation!

अगर आपने विस्तारित वर्कफ़्लो प्रोफ़ाइल सक्षम की है, तो आप इसे दो स्टेप्स में भी कर सकते हैं: /opsx:new फिर /opsx:ff (या /opsx:continue क्रमिक रूप से)।

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

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

# Proposal: Add Dark Mode

## Intent
Users have requested a dark mode option to reduce eye strain
during nighttime usage.

## Scope
- Add theme toggle in settings
- Support system preference detection
- Persist preference in localStorage

## Approach
Use CSS custom properties for theming with a React context
for state management.

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

# Delta for UI

## ADDED Requirements

### Requirement: Theme Selection
The system SHALL allow users to choose between light and dark themes.

#### Scenario: Manual toggle
- GIVEN a user on any page
- WHEN the user clicks the theme toggle
- THEN the theme switches immediately
- AND the preference persists across sessions

#### Scenario: System preference
- GIVEN a user with no saved preference
- WHEN the application loads
- THEN the system's preferred color scheme is used

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

# Tasks

## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext with light/dark state
- [ ] 1.2 Add CSS custom properties for colors
- [ ] 1.3 Implement localStorage persistence

## 2. UI Components
- [ ] 2.1 Create ThemeToggle component
- [ ] 2.2 Add toggle to settings page
- [ ] 2.3 Update Header to include quick toggle

## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variables

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

You: /opsx:apply

AI:  Working through tasks...
     ✓ 1.1 Created ThemeContext with light/dark state
     ✓ 1.2 Added CSS custom properties to globals.css
     ✓ 1.3 Implemented localStorage persistence
     ✓ 2.1 Created ThemeToggle component
     ...
     All tasks complete!

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

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

You: /opsx:archive

AI:  Archiving add-dark-mode...
     ✓ Merged specs into openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/
     Done! Ready for the next feature.

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

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

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

# List active changes
openspec list

# View change details
openspec show add-dark-mode

# Validate spec formatting
openspec validate add-dark-mode

# Interactive dashboard
openspec view

अगले कदम

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