अवधारणाएँ

यह गाइड OpenSpec के पीछे के मुख्य विचारों और वे एक-दूसरे के साथ कैसे फिट होते हैं, इसकी व्याख्या करती है। व्यावहारिक उपयोग के लिए, शुरुआत करना और कार्यप्रवाह देखें।

दर्शन (Philosophy)

OpenSpec चार सिद्धांतों पर बनाया गया है:

fluid not rigid         — no phase gates, work on what makes sense
iterative not waterfall — learn as you build, refine as you go
easy not complex        — lightweight setup, minimal ceremony
brownfield-first        — works with existing codebases, not just greenfield

ये सिद्धांत क्यों महत्वपूर्ण हैं

द्रव (Fluid) न कि कठोर। पारंपरिक स्पेसिफिकेशन सिस्टम आपको चरणों में बांध देते हैं: पहले आप योजना बनाते हैं, फिर आप कार्यान्वयन करते हैं, और फिर आपका काम हो जाता है। OpenSpec अधिक लचीला है — आप अपने काम के लिए जो भी तार्किक लगे, उस क्रम में कलाकृतियाँ (artifacts) बना सकते हैं।

सीढ़ीदार (Iterative) न कि झरना (Waterfall)। आवश्यकताएँ बदलती हैं। समझ गहरी होती है। जो शुरुआत में एक अच्छा दृष्टिकोण लगता था, वह कोडबेस देखने के बाद भी सही नहीं हो सकता। OpenSpec इस वास्तविकता को स्वीकार करता है।

सरल (Easy) न कि जटिल। कुछ स्पेसिफिकेशन फ्रेमवर्क व्यापक सेटअप, कठोर प्रारूपों या भारी प्रक्रियाओं की मांग करते हैं। OpenSpec आपके रास्ते में नहीं आता। सेकंडों में इनिशियलाइज़ करें, तुरंत काम करना शुरू करें, केवल तभी कस्टमाइज़ करें जब आपको आवश्यकता हो।

ब्राउनफील्ड-फर्स्ट (Brownfield-first)। अधिकांश सॉफ्टवेयर कार्य शुरू से बनाना नहीं है — यह मौजूदा सिस्टमों को संशोधित करना है। OpenSpec का डेल्टा-आधारित दृष्टिकोण केवल नए सिस्टमों का वर्णन करने के बजाय मौजूदा व्यवहार में परिवर्तनों को निर्दिष्ट करना आसान बनाता है।

समग्र दृष्टिकोण (The Big Picture)

OpenSpec आपके काम को दो मुख्य क्षेत्रों में व्यवस्थित करता है:

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  Source of truth    │◄─────│  Proposed modifications       │   │
│   │  How your system    │ merge│  Each change = one folder     │   │
│   │  currently works    │      │  Contains artifacts + deltas  │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

Specs सत्य का स्रोत (source of truth) हैं — वे वर्णन करते हैं कि आपका सिस्टम वर्तमान में कैसे व्यवहार करता है।

Changes प्रस्तावित संशोधन (proposed modifications) हैं — ये अलग-अलग फ़ोल्डरों में रहते हैं जब तक आप उन्हें मर्ज करने के लिए तैयार नहीं हो जाते।

यह अलगाव महत्वपूर्ण है। आप बिना किसी टकराव के कई परिवर्तनों पर समानांतर रूप से काम कर सकते हैं। आप मुख्य स्पेक्स को प्रभावित करने से पहले एक परिवर्तन की समीक्षा कर सकते हैं। और जब आप किसी परिवर्तन को संग्रहीत (archive) करते हैं, तो उसके डेल्टा (deltas) सफाई से सत्य के स्रोत में मर्ज हो जाते हैं।

Specs (विनिर्देश)

Specs संरचित आवश्यकताओं और परिदृश्यों का उपयोग करके आपके सिस्टम के व्यवहार का वर्णन करते हैं।

संरचना (Structure)

openspec/specs/
├── auth/
│   └── spec.md           # प्रमाणीकरण (Authentication) व्यवहार
├── payments/
│   └── spec.md           # भुगतान प्रसंस्करण (Payment processing)
├── notifications/
│   └── spec.md           # अधिसूचना प्रणाली (Notification system)
└── ui/
    └── spec.md           # UI व्यवहार और थीम (UI behavior and themes)

डोमेन द्वारा स्पेक्स को व्यवस्थित करें — तार्किक समूह जो आपके सिस्टम के लिए मायने रखते हैं। सामान्य पैटर्न:

फ़ीचर क्षेत्र द्वारा: auth/, payments/, search/
घटक (component) द्वारा: api/, frontend/, workers/
बाउंडेड कॉन्टेक्स्ट (bounded context) द्वारा: ordering/, fulfillment/, inventory/

Spec फॉर्मेट

एक spec में आवश्यकताएं होती हैं, और प्रत्येक आवश्यकता के परिदृश्य होते हैं:

markdown

# Auth Specification (प्रमाणीकरण विनिर्देश)

## Purpose (उद्देश्य)
एप्लिकेशन के लिए प्रमाणीकरण और सत्र प्रबंधन।

## Requirements (आवश्यकताएं)

### Requirement: User Authentication (उपयोगकर्ता प्रमाणीकरण)
सिस्टम सफल लॉगिन पर एक JWT टोकन जारी करेगा।

#### Scenario: Valid credentials (वैध प्रमाण-पत्र)
- GIVEN a user with valid credentials (एक वैध प्रमाण-पत्र वाला उपयोगकर्ता)
- WHEN the user submits login form (जब उपयोगकर्ता लॉगिन फॉर्म जमा करता है)
- THEN a JWT token is returned (तब एक JWT टोकन लौटाया जाता है)
- AND the user is redirected to dashboard (और उपयोगकर्ता को डैशबोर्ड पर रीडायरेक्ट कर दिया जाता है)

#### Scenario: Invalid credentials (अवैध प्रमाण-पत्र)
- GIVEN invalid credentials (अवैध प्रमाण-पत्र)
- WHEN the user submits login form (जब उपयोगकर्ता लॉगिन फॉर्म जमा करता है)
- THEN an error message is displayed (तब एक त्रुटि संदेश प्रदर्शित होता है)
- AND no token is issued (और कोई टोकन जारी नहीं किया जाता)

### Requirement: Session Expiration (सत्र समाप्ति)
सिस्टम को निष्क्रियता के 30 मिनट बाद सत्र समाप्त करना चाहिए।

#### Scenario: Idle timeout (निष्क्रिय समय सीमा)
- GIVEN an authenticated session (एक प्रमाणित सत्र)
- WHEN 30 minutes pass without activity (जब बिना किसी गतिविधि के 30 मिनट बीत जाते हैं)
- THEN the session is invalidated (तब सत्र अमान्य हो जाता है)
- AND the user must re-authenticate (और उपयोगकर्ता को पुनः प्रमाणीकरण करना होगा)

मुख्य तत्व:

Element	Purpose (उद्देश्य)
`## Purpose`	इस spec के डोमेन का उच्च-स्तरीय विवरण
`### Requirement:`	एक विशिष्ट व्यवहार जो सिस्टम को होना चाहिए
`#### Scenario:`	कार्रवाई में आवश्यकता का एक ठोस उदाहरण
SHALL/MUST/SHOULD	RFC 2119 कीवर्ड्स जो आवश्यकता की शक्ति को इंगित करते हैं

इस तरह से Specs क्यों संरचित करें (Why Structure Specs This Way)

आवश्यकताएं "क्या" हैं — वे बताती हैं कि सिस्टम को क्या करना चाहिए, कार्यान्वयन (implementation) निर्दिष्ट किए बिना।

परिदृश्य "कब" हैं — वे ठोस उदाहरण प्रदान करते हैं जिनकी सत्यापन किया जा सकता है। अच्छे परिदृश्य:

परीक्षण योग्य होते हैं (आप उनके लिए एक स्वचालित परीक्षण लिख सकते हैं)
खुशहाल पथ (happy path) और एज केस दोनों को कवर करते हैं
Given/When/Then या इसी तरह के संरचित प्रारूप का उपयोग करते हैं

RFC 2119 कीवर्ड्स (SHALL, MUST, SHOULD, MAY) इरादे को संप्रेषित करते हैं:

MUST/SHALL — पूर्ण आवश्यकता
SHOULD — अनुशंसित है, लेकिन अपवाद मौजूद हैं
MAY — वैकल्पिक है

एक Spec क्या है (और क्या नहीं है)

एक spec एक व्यवहार अनुबंध (behavior contract) है, न कि कार्यान्वयन योजना।

अच्छी spec सामग्री:

अवलोकन योग्य व्यवहार जिस पर उपयोगकर्ता या डाउनस्ट्रीम सिस्टम निर्भर करते हैं
इनपुट, आउटपुट और त्रुटि की स्थितियाँ
बाहरी बाधाएं (सुरक्षा, गोपनीयता, विश्वसनीयता, संगतता)
परिदृश्य जिन्हें परीक्षण किया जा सके या स्पष्ट रूप से मान्य किया जा सके

Specs में क्या न रखें:

आंतरिक क्लास/फ़ंक्शन नाम
लाइब्रेरी या फ्रेमवर्क विकल्प
चरण-दर-चरण कार्यान्वयन विवरण
विस्तृत निष्पादन योजनाएं (ये design.md या tasks.md में होनी चाहिए)

त्वरित परीक्षण:

यदि कार्यान्वयन बाहरी रूप से दिखाई देने वाले व्यवहार को बदले बिना बदल सकता है, तो संभावना है कि यह spec में नहीं होना चाहिए।

हल्के रखें: प्रगतिशील कठोरता (Progressive Rigor)

OpenSpec नौकरशाही से बचने का लक्ष्य रखता है। उस सबसे हल्के स्तर का उपयोग करें जो परिवर्तन को सत्यापन योग्य बनाता हो।

लाइट Spec (डिफ़ॉल्ट):

संक्षिप्त व्यवहार-प्रथम आवश्यकताएं
स्पष्ट दायरा और गैर-लक्ष्य (non-goals)
कुछ ठोस स्वीकृति जाँचें

फुल Spec (अधिक जोखिम के लिए):

क्रॉस-टीम या क्रॉस-रिपॉजिटरी परिवर्तन
API/अनुबंध परिवर्तन, माइग्रेशन, सुरक्षा/गोपनीयता संबंधी चिंताएं
वे परिवर्तन जहां अस्पष्टता महंगी रीवर्क का कारण बन सकती है

अधिकांश परिवर्तनों को लाइट मोड में रहना चाहिए।

मानव + एजेंट सहयोग (Human + Agent Collaboration)

कई टीमों में, मनुष्य अन्वेषण करते हैं और एजेंट कलाकृतियों (artifacts) का मसौदा तैयार करते हैं। इच्छित लूप यह है:

मानव इरादा, संदर्भ और बाधाएं प्रदान करता है।
एजेंट इसे व्यवहार-प्रथम आवश्यकताओं और परिदृश्यों में परिवर्तित करता है।
एजेंट कार्यान्वयन विवरण को design.md और tasks.md में रखता है, न कि spec.md में।
सत्यापन कार्यान्वयन से पहले संरचना और स्पष्टता की पुष्टि करता है।

यह specs को मनुष्यों के लिए पठनीय और एजेंटों के लिए सुसंगत रखता है।

Changes (परिवर्तन)

एक परिवर्तन आपके सिस्टम में एक प्रस्तावित संशोधन है, जिसे इसे समझने और लागू करने के लिए आवश्यक सब कुछ के साथ एक फ़ोल्डर के रूप में पैक किया जाता है।

Change Structure (परिवर्तन संरचना)

openspec/changes/add-dark-mode/
├── proposal.md           # क्यों और क्या (Why and what)
├── design.md             # कैसे (तकनीकी दृष्टिकोण)
├── tasks.md              # कार्यान्वयन चेकलिस्ट
├── .openspec.yaml        # परिवर्तन मेटाडेटा (वैकल्पिक)
└── specs/                # डेल्टा स्पेक्स
    └── ui/
        └── spec.md       # ui/spec.md में क्या बदल रहा है

प्रत्येक परिवर्तन स्व-निहित होता है। इसमें ये शामिल होते हैं:

Artifacts — वे दस्तावेज़ जो इरादे, डिजाइन और कार्यों को कैप्चर करते हैं
Delta specs — यह निर्दिष्ट करने के लिए विनिर्देश कि क्या जोड़ा जा रहा है, संशोधित किया जा रहा है या हटाया जा रहा है
Metadata — इस विशिष्ट परिवर्तन के लिए वैकल्पिक कॉन्फ़िगरेशन

Changes Folders क्यों होते हैं (Why Changes Are Folders)

एक परिवर्तन को फ़ोल्डर के रूप में पैक करने के कई लाभ हैं:

सब कुछ एक साथ। प्रस्ताव, डिजाइन, कार्य और स्पेक्स एक ही स्थान पर रहते हैं। अलग-अलग स्थानों पर खोजने की आवश्यकता नहीं है।
समानांतर कार्य। एकाधिक परिवर्तन बिना किसी टकराव के एक साथ मौजूद हो सकते हैं। add-dark-mode पर काम करें जबकि fix-auth-bug भी प्रगति पर हो।
स्वच्छ इतिहास। जब संग्रहीत किया जाता है, तो परिवर्तन अपने पूरे संदर्भ के साथ changes/archive/ में चले जाते हैं। आप पीछे मुड़कर यह समझ सकते हैं कि क्या बदला गया है, न कि केवल क्यों।
समीक्षा-अनुकूल। एक परिवर्तन फ़ोल्डर की समीक्षा करना आसान होता है — इसे खोलें, प्रस्ताव पढ़ें, डिजाइन जांचें, spec deltas देखें।

Artifacts (कलाकृतियाँ)

Artifacts वे दस्तावेज़ हैं जो किसी परिवर्तन के भीतर होते हैं और कार्य का मार्गदर्शन करते हैं।

The Artifact Flow (कलाकृति प्रवाह)

proposal ──────► specs ──────► design ──────► tasks ──────► implement
    │               │             │              │
   why            what           how          steps
 + scope        changes       approach      to take

Artifacts एक-दूसरे पर निर्मित होते हैं। प्रत्येक artifact अगले के लिए संदर्भ प्रदान करता है।

Artifact Types (कलाकृति प्रकार)

Proposal (`proposal.md`)

प्रस्ताव इरादे, दायरे और दृष्टिकोण को उच्च स्तर पर कैप्चर करता है।

markdown

# Proposal: Add Dark Mode (प्रस्ताव: डार्क मोड जोड़ना)

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

## Scope (दायरा)
शामिल है:
- सेटिंग्स में थीम टॉगल
- सिस्टम प्राथमिकता का पता लगाना
- localStorage में प्राथमिकता बनाए रखना

शामिल नहीं है:
- कस्टम रंग थीम (भविष्य का कार्य)
- प्रति-पृष्ठ थीम ओवरराइड

## Approach (दृष्टिकोण)
स्टेट प्रबंधन के लिए React context के साथ थीमिंग हेतु CSS custom properties का उपयोग करें। पहली बार लोड पर सिस्टम वरीयता का पता लगाएं, मैन्युअल ओवरराइड की अनुमति दें।

प्रस्ताव को कब अपडेट करें:

दायरे में परिवर्तन (संकीर्ण करना या विस्तारित करना)
इरादा स्पष्ट होता है (समस्या की बेहतर समझ)
दृष्टिकोण मौलिक रूप से बदल जाता है

Specs (delta specs in `specs/`)

Delta specs क्या बदल रहा है इसका वर्णन करते हैं, न कि पूरी spec को दोहराते हैं। नीचे Delta Specs देखें।

Design (`design.md`)

Design तकनीकी दृष्टिकोण और वास्तुकला निर्णयों को कैप्चर करता है।

markdown

# Design: Add Dark Mode (डिज़ाइन: डार्क मोड जोड़ना)

## Technical Approach (तकनीकी दृष्टिकोण)
प्रॉप ड्रिलिंग से बचने के लिए थीम स्टेट को React Context के माध्यम से प्रबंधित किया जाता है। CSS custom properties क्लास टॉगलिंग के बिना रनटाइम स्विचिंग सक्षम करते हैं।

## Architecture Decisions (वास्तुकला निर्णय)

### Decision: Context over Redux (Redux पर Context का उपयोग)
थीम स्टेट के लिए React Context का उपयोग करना क्योंकि:
- सरल बाइनरी स्थिति (हल्का/गहरा)
- कोई जटिल स्टेट ट्रांजिशन नहीं
- Redux निर्भरता जोड़ने से बचा जाता है

### Decision: CSS Custom Properties (CSS कस्टम प्रॉपर्टीज़)
CSS-in-JS के बजाय CSS variables का उपयोग करना क्योंकि:
- मौजूदा स्टाइलशीट के साथ काम करता है
- कोई रनटाइम ओवरहेड नहीं
- ब्राउज़र-देशी समाधान

## Data Flow (डेटा प्रवाह)
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :root)
```

## File Changes (फ़ाइल परिवर्तन)
- `src/contexts/ThemeContext.tsx` (नया)
- `src/components/ThemeToggle.tsx` (नया)
- `src/styles/globals.css` (संशोधित)

Design को कब अपडेट करें:

कार्यान्वयन से पता चलता है कि दृष्टिकोण काम नहीं करेगा
बेहतर समाधान खोजा जाता है
निर्भरताएं या बाधाएं बदल जाती हैं

Tasks (`tasks.md`)

Tasks कार्यान्वयन चेकलिस्ट — चेकमार्क के साथ ठोस चरण होते हैं।

markdown

# Tasks (कार्य)

## 1. Theme Infrastructure (थीम बुनियादी ढाँचा)
- [ ] 1.1 Create ThemeContext with light/dark state (हल्के/गहरे स्टेट के साथ ThemeContext बनाएं)
- [ ] 1.2 Add CSS custom properties for colors (रंगों के लिए CSS कस्टम प्रॉपर्टीज़ जोड़ें)
- [ ] 1.3 Implement localStorage persistence (localStorage स्थिरता लागू करें)
- [ ] 1.4 Add system preference detection (सिस्टम प्राथमिकता का पता लगाना जोड़ें)

## 2. UI Components (UI घटक)
- [ ] 2.1 Create ThemeToggle component (ThemeToggle घटक बनाएं)
- [ ] 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 (CSS वेरिएबल्स का उपयोग करने के लिए घटकों को अपडेट करें)
- [ ] 3.3 Test contrast ratios for accessibility (पहुँच योग्यता के लिए कंट्रास्ट अनुपात का परीक्षण करें)

Task सर्वोत्तम अभ्यास:

संबंधित कार्यों को शीर्षकों के तहत समूहित करें
पदानुक्रमित संख्याकरण (1.1, 1.2, आदि) का उपयोग करें
कार्यों को इतना छोटा रखें कि वे एक सत्र में पूरे हो सकें
कार्य पूरा होने पर उन्हें चेक ऑफ करें

Delta Specs (डेल्टा विनिर्देश)

Delta specs वह मुख्य अवधारणा है जो OpenSpec को brownfield development के लिए काम करने योग्य बनाती है। वे पूरी spec को दोहराने के बजाय क्या बदल रहा है इसका वर्णन करते हैं।

The Format (प्रारूप)

markdown

# Delta for Auth (Auth के लिए डेल्टा)

## ADDED Requirements (जोड़ी गई आवश्यकताएं)

### Requirement: Two-Factor Authentication (दो-कारक प्रमाणीकरण)
सिस्टम को TOTP-आधारित दो-कारक प्रमाणीकरण का समर्थन करना चाहिए।

#### Scenario: 2FA enrollment (2FA नामांकन)
- GIVEN a user without 2FA enabled (एक ऐसे उपयोगकर्ता के साथ जिसके पास 2FA सक्षम नहीं है)
- WHEN the user enables 2FA in settings (जब उपयोगकर्ता सेटिंग्स में 2FA को सक्षम करता है)
- THEN a QR code is displayed for authenticator app setup (तब ऑथेंटिकेटर ऐप सेटअप के लिए एक QR कोड प्रदर्शित होता है)
- AND the user must verify with a code before activation (और सक्रियण से पहले उपयोगकर्ता को कोड के साथ सत्यापित करना होगा)

#### Scenario: 2FA login (2FA लॉगिन)
- GIVEN a user with 2FA enabled (एक ऐसे उपयोगकर्ता के साथ जिसके पास 2FA सक्षम है)
- WHEN the user submits valid credentials (जब उपयोगकर्ता वैध प्रमाण-पत्र जमा करता है)
- THEN an OTP challenge is presented (तब एक OTP चुनौती प्रस्तुत की जाती है)
- AND login completes only after valid OTP (और केवल वैध OTP के बाद लॉगिन पूरा होता है)

## MODIFIED Requirements (संशोधित आवश्यकताएं)

### Requirement: Session Expiration (सत्र समाप्ति)
सिस्टम को निष्क्रियता के 15 मिनट बाद सत्र समाप्त करना चाहिए।
(पहले: 30 मिनट)

#### Scenario: Idle timeout (निष्क्रिय समय सीमा)
- GIVEN an authenticated session (एक प्रमाणित सत्र)
- WHEN 15 minutes pass without activity (जब बिना किसी गतिविधि के 15 मिनट बीत जाते हैं)
- THEN the session is invalidated (तब सत्र अमान्य हो जाता है)

## REMOVED Requirements (हटाए गए/अप्रचलित आवश्यकताएं)

### Requirement: Remember Me (याद रखें)
(2FA के पक्ष में अप्रचलित। उपयोगकर्ताओं को प्रत्येक सत्र में पुनः प्रमाणीकरण करना चाहिए।)

Delta Sections (डेल्टा खंड)

Section	Meaning (अर्थ)	What Happens on Archive (संग्रहीत होने पर क्या होता है)
`## ADDED Requirements`	नई आवश्यकता	मुख्य spec में जोड़ा जाता है
`## MODIFIED Requirements`	बदली हुई आवश्यकता	मौजूदा आवश्यकता को प्रतिस्थापित करता है
`## REMOVED Requirements`	अप्रचलित व्यवहार	मुख्य spec से हटा दिया जाता है

Deltas क्यों, पूर्ण Specs नहीं (Why Deltas Instead of Full Specs)

स्पष्टता। एक डेल्टा ठीक वही दिखाता है जो बदल रहा है। एक पूरी spec को पढ़ने के लिए, आपको इसे वर्तमान संस्करण के साथ मानसिक रूप से अंतर करना होगा।

टकराव से बचाव। दो परिवर्तन एक ही spec फ़ाइल को छू सकते हैं बिना किसी टकराव के, बशर्ते कि वे विभिन्न आवश्यकताओं को संशोधित कर रहे हों।

समीक्षा दक्षता। समीक्षक बदलाव देखते हैं, न कि अपरिवर्तित संदर्भ को। उन चीज़ों पर ध्यान केंद्रित करें जो मायने रखती हैं।

Brownfield fit. अधिकांश कार्य मौजूदा व्यवहार को संशोधित करता है। Deltas संशोधनों को afterthought के बजाय प्रथम श्रेणी (first-class) बनाते हैं।

स्कीमा (Schemas)

स्कीमा वर्कफ़्लो के लिए आर्टिफैक्ट प्रकारों और उनकी निर्भरताओं को परिभाषित करते हैं।

स्कीमा कैसे काम करते हैं

yaml

# openspec/schemas/spec-driven/schema.yaml
name: spec-driven
artifacts:
  - id: proposal
    generates: proposal.md
    requires: []              # कोई निर्भरता नहीं, पहले बनाया जा सकता है

  - id: specs
    generates: specs/**/*.md
    requires: [proposal]      # बनाने से पहले proposal की आवश्यकता है

  - id: design
    generates: design.md
    requires: [proposal]      # specs के साथ समानांतर में बनाया जा सकता है

  - id: tasks
    generates: tasks.md
    requires: [specs, design] # पहले specs और design दोनों की आवश्यकता है

आर्टिफैक्ट एक निर्भरता ग्राफ बनाते हैं:

                    proposal
                   (मूल नोड)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      specs                       design
   (आवश्यकताएँ:                  (आवश्यकताएँ:
    proposal)                   proposal)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    tasks
                (आवश्यकताएँ:
                specs, design)

निर्भरताएं गेट नहीं, बल्कि सक्षमकर्ता (enablers) होती हैं। वे यह दर्शाती हैं कि क्या बनाया जा सकता है, न कि आपको आगे क्या बनाना चाहिए। यदि आपको इसकी आवश्यकता नहीं है तो आप design को छोड़ सकते हैं। आप proposal पर निर्भर होने के कारण design से पहले या बाद में specs बना सकते हैं — दोनों केवल proposal पर ही निर्भर करते हैं।

अंतर्निहित स्कीमा (Built-in Schemas)

spec-driven (डिफ़ॉल्ट)

स्पेक-ड्रिवन डेवलपमेंट के लिए मानक वर्कफ़्लो:

proposal → specs → design → tasks → implement

किसके लिए सबसे अच्छा है: अधिकांश फीचर कार्य जहाँ आप कार्यान्वयन से पहले स्पेक्स पर सहमत होना चाहते हैं।

कस्टम स्कीमा (Custom Schemas)

अपनी टीम के वर्कफ़्लो के लिए कस्टम स्कीमा बनाएँ:

bash

# शुरू से बनाएं
openspec schema init research-first

# या किसी मौजूदा को फ़ॉर्क करें
openspec schema fork spec-driven research-first

कस्टम स्कीमा का उदाहरण:

yaml

# openspec/schemas/research-first/schema.yaml
name: research-first
artifacts:
  - id: research
    generates: research.md
    requires: []           # पहले रिसर्च करें

  - id: proposal
    generates: proposal.md
    requires: [research]   # प्रस्ताव (proposal) रिसर्च पर आधारित है

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # specs/design को छोड़ दें, सीधे tasks पर जाएँ

कस्टम स्कीमा बनाने और उपयोग करने के बारे में पूरी जानकारी के लिए Customization देखें।

संग्रह (Archive)

संग्रहण (Archiving) मुख्य स्पेक्स में इसके डेल्टा स्पेक्स को मर्ज करके और इतिहास के लिए परिवर्तन को संरक्षित करके बदलाव को पूरा करता है।

संग्रहण करते समय क्या होता है

संग्रहण से पहले:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ merge
        ├── tasks.md                 │
        └── specs/                   │
            └── auth/                │
                └── spec.md ─────────┘


संग्रहण के बाद:

openspec/
├── specs/
│   └── auth/
│       └── spec.md        # अब इसमें 2FA की आवश्यकताएँ शामिल हैं
└── changes/
    └── archive/
        └── 2025-01-24-add-2fa/    # इतिहास के लिए संरक्षित
            ├── proposal.md
            ├── design.md
            ├── tasks.md
            └── specs/
                └── auth/
                    └── spec.md

संग्रह प्रक्रिया (The Archive Process)

डेल्टा मर्ज करें। प्रत्येक डेल्टा स्पेक सेक्शन (जोड़ा गया/संशोधित किया गया/हटाया गया) को संबंधित मुख्य स्पेक पर लागू किया जाता है।
संग्रहण में ले जाएँ। परिवर्तन फ़ोल्डर को कालानुक्रमिक क्रम के लिए एक तिथि उपसर्ग के साथ changes/archive/ में ले जाया जाता है।
संदर्भ संरक्षित करें। सभी आर्टिफैक्ट संग्रह में बरकरार रहते हैं। आप हमेशा यह समझने के लिए पीछे मुड़कर देख सकते हैं कि कोई बदलाव क्यों किया गया था।

संग्रहण क्यों महत्वपूर्ण है (Why Archive Matters)

स्वच्छ स्थिति। सक्रिय परिवर्तन (changes/) केवल प्रगति पर चल रहे काम को दिखाते हैं। पूरा हो चुका काम हट जाता है।

ऑडिट ट्रेल। संग्रह हर बदलाव के पूर्ण संदर्भ को संरक्षित करता है — न कि सिर्फ यह क्या बदला, बल्कि वह प्रस्ताव जो बताता है कि क्यों, डिज़ाइन जो बताता है कि कैसे, और कार्य जो दिखाता है कि कितना काम हुआ।

स्पेक विकास (Spec evolution)। जैसे-जैसे परिवर्तन संग्रहीत किए जाते हैं, स्पेक्स स्वाभाविक रूप से विकसित होते हैं। प्रत्येक संग्रह अपने डेल्टा को मर्ज करता है, समय के साथ एक व्यापक विनिर्देशन का निर्माण करता है।

यह सब एक साथ कैसे फिट होता है

┌──────────────────────────────────────────────────────────────────────────────┐
│                              OPENSPEC FLOW                                   │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. START      │  /opsx:propose (core) or /opsx:new (expanded)           │
│   │     CHANGE     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. CREATE     │  /opsx:ff or /opsx:continue (expanded workflow)         │
│   │     ARTIFACTS  │  यह proposal → specs → design → tasks बनाता है              │
│   │                │  (स्कीमा निर्भरताओं पर आधारित)                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. IMPLEMENT  │  /opsx:apply                                            │
│   │     TASKS      │  कार्य पर काम करें, उन्हें चिह्नित करते जाएँ                  │
│   │                │◄──── सीखते समय आर्टिफैक्ट अपडेट करें                      │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. VERIFY     │  /opsx:verify (वैकल्पिक)                                │
│   │     WORK       │  जाँचें कि कार्यान्वयन स्पेक्स से मेल खाता है या नहीं         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. ARCHIVE    │────►│  डेल्टा स्पेक्स मुख्य स्पेक्स में मर्ज होते हैं          │    │
│   │     CHANGE     │     │  परिवर्तन फ़ोल्डर archive/ में चला जाता है           │    │
│   └────────────────┘     │  स्पेक्स अब सत्य का अद्यतन स्रोत हैं                   │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

सद्गुणी चक्र (The virtuous cycle):

स्पेक्स वर्तमान व्यवहार का वर्णन करते हैं।
परिवर्तन संशोधन प्रस्तावित करते हैं (डेल्टा के रूप में)।
कार्यान्वयन परिवर्तनों को वास्तविक बनाता है।
संग्रह डेल्टा को स्पेक्स में मर्ज करता है।
स्पेक्स अब नए व्यवहार का वर्णन करते हैं।
अगला परिवर्तन अपडेटेड स्पेक्स पर आधारित होता है।

शब्दावली (Glossary)

शब्द	परिभाषा
Artifact	किसी बदलाव के भीतर एक दस्तावेज़ (प्रस्ताव, डिज़ाइन, कार्य, या डेल्टा स्पेक्स)।
Archive	बदलाव को पूरा करने और उसके डेल्टा को मुख्य स्पेक्स में मर्ज करने की प्रक्रिया।
Change	सिस्टम में प्रस्तावित संशोधन, जिसे आर्टिफैक्ट के साथ एक फ़ोल्डर के रूप में पैक किया जाता है।
Delta spec	वर्तमान स्पेक्स के सापेक्ष परिवर्तनों (जोड़ा गया/संशोधित किया गया/हटाया गया) का वर्णन करने वाला स्पेक।
Domain	स्पेक्स के लिए एक तार्किक समूहीकरण (उदाहरण: `auth/`, `payments/`)।
Requirement	वह विशिष्ट व्यवहार जो सिस्टम को होना चाहिए।
Scenario	आवश्यकता का एक ठोस उदाहरण, आमतौर पर Given/When/Then प्रारूप में।
Schema	आर्टिफैक्ट प्रकारों और उनकी निर्भरताओं की परिभाषा।
Spec	प्रणाली के व्यवहार का वर्णन करने वाला विनिर्देशन (specification), जिसमें आवश्यकताएँ और परिदृश्य शामिल होते हैं।
Source of truth	`openspec/specs/` निर्देशिका, जिसमें वर्तमान में सहमत व्यवहार होता है।

अगले कदम (Next Steps)

Getting Started - व्यावहारिक शुरुआती चरण
Workflows - सामान्य पैटर्न और कब किसका उपयोग करें
Commands - पूर्ण कमांड संदर्भ
Customization - कस्टम स्कीमा बनाएँ और अपने प्रोजेक्ट को कॉन्फ़िगर करें

अवधारणाएँ ​

दर्शन (Philosophy) ​

ये सिद्धांत क्यों महत्वपूर्ण हैं ​

समग्र दृष्टिकोण (The Big Picture) ​

Specs (विनिर्देश) ​

संरचना (Structure) ​

Spec फॉर्मेट ​

इस तरह से Specs क्यों संरचित करें (Why Structure Specs This Way) ​

एक Spec क्या है (और क्या नहीं है) ​

हल्के रखें: प्रगतिशील कठोरता (Progressive Rigor) ​

मानव + एजेंट सहयोग (Human + Agent Collaboration) ​

Changes (परिवर्तन) ​

Change Structure (परिवर्तन संरचना) ​

Changes Folders क्यों होते हैं (Why Changes Are Folders) ​

Artifacts (कलाकृतियाँ) ​

The Artifact Flow (कलाकृति प्रवाह) ​

Artifact Types (कलाकृति प्रकार) ​

Proposal (proposal.md) ​

Specs (delta specs in specs/) ​

Design (design.md) ​

Tasks (tasks.md) ​

Delta Specs (डेल्टा विनिर्देश) ​

The Format (प्रारूप) ​

Delta Sections (डेल्टा खंड) ​

Deltas क्यों, पूर्ण Specs नहीं (Why Deltas Instead of Full Specs) ​

स्कीमा (Schemas) ​

स्कीमा कैसे काम करते हैं ​

अंतर्निहित स्कीमा (Built-in Schemas) ​

कस्टम स्कीमा (Custom Schemas) ​

संग्रह (Archive) ​

संग्रहण करते समय क्या होता है ​

संग्रह प्रक्रिया (The Archive Process) ​

संग्रहण क्यों महत्वपूर्ण है (Why Archive Matters) ​

यह सब एक साथ कैसे फिट होता है ​

शब्दावली (Glossary) ​

अगले कदम (Next Steps) ​

अवधारणाएँ

दर्शन (Philosophy)

ये सिद्धांत क्यों महत्वपूर्ण हैं

समग्र दृष्टिकोण (The Big Picture)

Specs (विनिर्देश)

संरचना (Structure)

Spec फॉर्मेट

इस तरह से Specs क्यों संरचित करें (Why Structure Specs This Way)

एक Spec क्या है (और क्या नहीं है)

हल्के रखें: प्रगतिशील कठोरता (Progressive Rigor)

मानव + एजेंट सहयोग (Human + Agent Collaboration)

Changes (परिवर्तन)

Change Structure (परिवर्तन संरचना)

Changes Folders क्यों होते हैं (Why Changes Are Folders)

Artifacts (कलाकृतियाँ)

The Artifact Flow (कलाकृति प्रवाह)

Artifact Types (कलाकृति प्रकार)

Proposal (`proposal.md`)

Specs (delta specs in `specs/`)

Design (`design.md`)

Tasks (`tasks.md`)

Delta Specs (डेल्टा विनिर्देश)

The Format (प्रारूप)

Delta Sections (डेल्टा खंड)

Deltas क्यों, पूर्ण Specs नहीं (Why Deltas Instead of Full Specs)

स्कीमा (Schemas)

स्कीमा कैसे काम करते हैं

अंतर्निहित स्कीमा (Built-in Schemas)

कस्टम स्कीमा (Custom Schemas)

संग्रह (Archive)

संग्रहण करते समय क्या होता है

संग्रह प्रक्रिया (The Archive Process)

संग्रहण क्यों महत्वपूर्ण है (Why Archive Matters)

यह सब एक साथ कैसे फिट होता है

शब्दावली (Glossary)

अगले कदम (Next Steps)