अवधारणाएँ

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

दर्शन

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

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

लचीला, कठोर नहीं। पारंपरिक स्पेक सिस्टम आपको चरणों में बांध देते हैं: पहले आप योजना बनाते हैं, फिर आप कार्यान्वयन करते हैं, फिर आपका काम पूरा हो जाता है। OpenSpec अधिक लचीला है — आप अपने काम के लिए समझ में आने वाले किसी भी क्रम में आर्टिफैक्ट बना सकते हैं।

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

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

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

बड़ी तस्वीर

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

┌────────────────────────────────────────────────────────────────────┐
│                        openspec/                                   │
│                                                                    │
│   ┌─────────────────────┐      ┌───────────────────────────────┐   │
│   │       specs/        │      │         changes/              │   │
│   │                     │      │                               │   │
│   │  सत्य का स्रोत    │◄─────│  प्रस्तावित संशोधन       │   │
│   │  आपका सिस्टम    │ merge│  प्रत्येक परिवर्तन = एक फ़ोल्डर     │   │
│   │  वर्तमान में कैसे काम करता है    │      │  कलाकृतियाँ + डेल्टा शामिल हैं  │   │
│   │                     │      │                               │   │
│   └─────────────────────┘      └───────────────────────────────┘   │
│                                                                    │
└────────────────────────────────────────────────────────────────────┘

स्पेक्स सत्य का स्रोत हैं — वे वर्णन करते हैं कि आपका सिस्टम वर्तमान में कैसे व्यवहार करता है।

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

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

समन्वय कार्यक्षेत्र

कार्यक्षेत्र समर्थन सक्रिय विकास के अधीन है और अभी उपयोग के लिए तैयार नहीं है। कार्यक्षेत्र व्यवहार के ऊपर बाहरी स्वचालन, एकीकरण, या लंबे समय तक चलने वाले वर्कफ़्लो न बनाएं; कमांड, स्थिति फ़ाइलें, और JSON आउटपुट किसी भी समय बदल सकते हैं।

नीचे दिए गए कमांड लिंक किए गए रेपो या फ़ोल्डरों में योजना बनाने के लिए पहला सेटअप प्रवाह प्रदान करते हैं।

रेपो-लोकल OpenSpec प्रोजेक्ट तब सही डिफ़ॉल्ट होते हैं जब एक रेपो योजना, कार्यान्वयन और संग्रह प्रवाह का स्वामित्व रखता है। कुछ कार्य कई रेपो या फ़ोल्डरों तक फैले होते हैं। उस मामले के लिए, एक OpenSpec समन्वय कार्यक्षेत्र टिकाऊ योजना का घर है।

कार्यक्षेत्र मानसिक मॉडल है:

text

workspace = जहाँ संबंधित क्रॉस-रेपो परिवर्तन रहते हैं
link      = एक स्थिर नाम जिसके लिए कार्यक्षेत्र योजना बना सकता है
change    = एक सुविधा, फिक्स, प्रोजेक्ट, या अन्य नियोजित कार्य

एक कार्यक्षेत्र का आकार रेपो-लोकल प्रोजेक्ट से भिन्न होता है:

text

workspace-folder/
├── changes/                       # कार्यक्षेत्र-स्तरीय योजना
└── .openspec-workspace/
    ├── workspace.yaml             # साझा कार्यक्षेत्र पहचान और लिंक नाम
    └── local.yaml                 # इस मशीन के स्थानीय पथ

रेपो-लोकल OpenSpec स्थिति मौजूदा आकार बनाए रखती है:

text

repo-root/
└── openspec/
    ├── specs/
    └── changes/

यह अंतर मायने रखता है। कार्यक्षेत्र फ़ोल्डर लिंक किए गए रेपो या फ़ोल्डरों में योजना बनाने के लिए एक समन्वय सतह है। प्रत्येक रेपो का openspec/ निर्देशिका रेपो-स्वामित्व वाले स्पेक्स, रेपो-लोकल परिवर्तनों और कार्यान्वयन योजना के लिए घर बनी रहती है। उपयोगकर्ताओं को कार्यक्षेत्र फ़ोल्डर के अंदर रेपो-लोकल openspec init चलाने की आवश्यकता नहीं है।

स्थिर लिंक नाम वह तरीका है जिससे कार्यक्षेत्र योजना रेपो और फ़ोल्डरों को संदर्भित करती है। साझा कार्यक्षेत्र स्थिति api, web, या checkout जैसे नाम रखती है; प्रत्येक मशीन उन नामों को .openspec-workspace/local.yaml में अपने स्वयं के स्थानीय पथों से मैप करती है।

yaml

# .openspec-workspace/workspace.yaml
version: 1
name: platform
links:
  api: {}
  web: {}

yaml

# .openspec-workspace/local.yaml
version: 1
paths:
  api: /repos/api
  web: /repos/web

OpenSpec द्वारा बनाए गए कार्यक्षेत्र डिफ़ॉल्ट रूप से पोर्टेबल सहयोग स्थिति से .openspec-workspace/local.yaml को बाहर रखते हैं। .openspec-workspace/workspace.yaml पोर्टेबल बना रहता है क्योंकि यह कार्यक्षेत्र का नाम और स्थिर लिंक नाम संग्रहीत करता है, किसी उपयोगकर्ता के निरपेक्ष चेकआउट पथ नहीं।

लिंक किए गए पथ पूर्ण रेपो, एक बड़े मोनोरेपो के अंदर फ़ोल्डर, या अन्य मौजूदा फ़ोल्डर हो सकते हैं। कार्यक्षेत्र योजना में भाग लेने से पहले उन्हें रेपो-लोकल openspec/ स्थिति की आवश्यकता नहीं है। बाद में कार्यान्वयन, सत्यापन, या संग्रह वर्कफ़्लो के लिए अधिक रेपो तत्परता की आवश्यकता हो सकती है, लेकिन योजना दृश्यता लिंक से शुरू होती है।

text

multi-repo:
  api      -> /repos/api
  web      -> /repos/web

large monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

प्रबंधित कार्यक्षेत्र मानक OpenSpec डेटा निर्देशिका के अंतर्गत रहते हैं:

text

getGlobalDataDir()/workspaces

इसका मतलब है कि जब XDG_DATA_HOME सेट हो तो $XDG_DATA_HOME/openspec/workspaces, यूनिक्स-शैली फ़ॉलबैक पर ~/.local/share/openspec/workspaces, और नेटिव विंडोज़ फ़ॉलबैक पर %LOCALAPPDATA%\openspec\workspaces। नेटिव विंडोज़ शेल, PowerShell, और WSL2 प्रत्येक OpenSpec चलाने वाले रनटाइम के लिए पथ स्ट्रिंग रखते हैं। यह नींव D:\repo, /mnt/d/repo, और UNC WSL पथों के बीच अनुवाद नहीं करती है।

OpenSpec एक मशीन-लोकल रजिस्ट्री भी रखता है:

text

getGlobalDataDir()/workspaces/registry.yaml

रजिस्ट्री कार्यक्षेत्र नामों को कार्यक्षेत्र स्थानों से मैप करती है ताकि बाद में ग्लोबल कमांड कहीं से भी ज्ञात कार्यक्षेत्रों को सूचीबद्ध या चयनित कर सकें। यह केवल एक इंडेक्स है। प्रत्येक कार्यक्षेत्र फ़ोल्डर अपने .openspec-workspace/workspace.yaml और .openspec-workspace/local.yaml के लिए प्राधिकरण बना रहता है, इसलिए पुरानी रजिस्ट्री रिकॉर्ड की रिपोर्ट की जा सकती है और कार्यक्षेत्र को पुनर्परिभाषित किए बिना मरम्मत की जा सकती है।

कार्यक्षेत्र दृश्यता परिवर्तन प्रतिबद्धता नहीं है। एक कार्यक्षेत्र स्थापित करें जब OpenSpec को पता होना चाहिए कि कौन से रेपो या फ़ोल्डर प्रासंगिक हैं; बाद में एक परिवर्तन बनाएं जब आप किसी सुविधा, फिक्स, प्रोजेक्ट, या अन्य कार्य की योजना बनाने के लिए तैयार हों।

उपयोगी कमांड:

bash

# निर्देशित सेटअप
openspec workspace setup

# स्वचालन-अनुकूल सेटअप
openspec workspace setup --no-interactive --name platform --link /repos/api --link web=/repos/web
openspec workspace setup --no-interactive --name platform --link /repos/api --opener codex

# स्थानीय रजिस्ट्री से ज्ञात कार्यक्षेत्र देखें
openspec workspace list
openspec workspace ls

# चयनित कार्यक्षेत्र के लिए लिंक जोड़ें या मरम्मत करें
openspec workspace link /repos/api
openspec workspace link api-service /repos/api
openspec workspace relink api-service /new/path/to/api

# जाँचें कि यह मशीन क्या हल कर सकती है
openspec workspace doctor
openspec workspace doctor --workspace platform

# लिंक किया गया कार्य सेट खोलें
openspec workspace open
openspec workspace open platform --agent github-copilot
openspec workspace open --editor

workspace setup हमेशा मानक कार्यक्षेत्र स्थान पर कार्यक्षेत्र बनाता है, इसे स्थानीय रजिस्ट्री में रिकॉर्ड करता है, कार्यक्षेत्र स्थान दिखाता है, और कम से कम एक लिंक किया गया रेपो या फ़ोल्डर आवश्यक है। इंटरैक्टिव सेटअप एक पसंदीदा ओपनर के लिए पूछता है। गैर-इंटरैक्टिव सेटअप एक को तभी संग्रहीत करता है जब --opener codex, --opener claude, --opener github-copilot, या --opener editor प्रदान किया जाता है।

OpenSpec रूट कार्यक्षेत्र ओपन फ़ाइलें भी बनाए रखता है: AGENTS.md में एक OpenSpec-प्रबंधित मार्गदर्शन ब्लॉक, VS Code और GitHub Copilot-in-VS-Code ओपन के लिए एक मशीन-लोकल <workspace-name>.code-workspace फ़ाइल, और उस बनाए रखी गई .code-workspace फ़ाइल के लिए एक विशिष्ट अनदेखा प्रविष्टि। उपयोगकर्ता-लिखित *.code-workspace फ़ाइलें ट्रैक करने योग्य रहती हैं क्योंकि अनदेखा नियम केवल बनाए रखी गई फ़ाइल को लक्षित करता है।

बनाए रखा गया VS Code कार्यक्षेत्र समन्वय रूट को . के रूप में और मान्य लिंक किए गए रेपो या फ़ोल्डरों को अतिरिक्त रूट के रूप में शामिल करता है। VS Code उन प्रविष्टियों को मल्टी-रूट कार्यक्षेत्र के रूप में प्रदर्शित करता है।

workspace open संग्रहीत पसंदीदा ओपनर के साथ लिंक किया गया कार्य सेट खोलता है जब तक कि उस एक सत्र के लिए --agent <tool> या --editor पास नहीं किया जाता। दोनों ओपनर ओवरराइड पास करना एक त्रुटि है। रूट कार्यक्षेत्र ओपन अन्वेषण और योजना के लिए लिंक किए गए रेपो और फ़ोल्डरों को दृश्यमान बनाता है; कार्यान्वयन तब शुरू होता है जब उपयोगकर्ता स्पष्ट रूप से कार्यान्वयन कार्य के लिए कहता है।

workspace link और workspace relink केवल मौजूदा फ़ोल्डर रिकॉर्ड करते हैं; वे लिंक किए गए रेपो या फ़ोल्डर को बनाते, कॉपी करते, ले जाते, प्रारंभ करते, या संपादित नहीं करते हैं। एक सफल लिंक या रीलिंक के बाद, OpenSpec प्रबंधित मार्गदर्शन, VS Code कार्यक्षेत्र फ़ाइल, और अनदेखा नियम को रीफ़्रेश करता है।

कार्यक्षेत्र कमांड जिन्हें एक कार्यक्षेत्र की आवश्यकता होती है, --workspace <name> के साथ कहीं से भी चल सकते हैं। यदि आप उन्हें किसी कार्यक्षेत्र फ़ोल्डर या उपनिर्देशिका के अंदर चलाते हैं, तो OpenSpec उस वर्तमान कार्यक्षेत्र का उपयोग करता है। यदि कई ज्ञात कार्यक्षेत्र उपलब्ध हैं और आप --workspace <name> पास नहीं करते हैं, तो मानव कमांड एक पिकर दिखाते हैं; --json और --no-interactive प्रॉम्प्ट करने के बजाय एक संरचित स्थिति त्रुटि के साथ विफल होते हैं।

प्रत्यक्ष कार्यक्षेत्र कमांड स्क्रिप्ट के लिए JSON आउटपुट का समर्थन करते हैं। JSON प्रतिक्रियाएँ प्राथमिक डेटा को workspace, workspaces, या link ऑब्जेक्ट में रखती हैं और status एरे में चेतावनियों या त्रुटियों की रिपोर्ट करती हैं। स्वस्थ ऑब्जेक्ट status: [] का उपयोग करते हैं।

स्पेक्स

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

संरचना

openspec/specs/
├── auth/
│   └── spec.md           # प्रमाणीकरण व्यवहार
├── payments/
│   └── spec.md           # भुगतान प्रसंस्करण
├── notifications/
│   └── spec.md           # सूचना प्रणाली
└── ui/
    └── spec.md           # UI व्यवहार और थीम

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

सुविधा क्षेत्र द्वारा: auth/, payments/, search/
घटक द्वारा: api/, frontend/, workers/
सीमित संदर्भ द्वारा: ordering/, fulfillment/, inventory/

स्पेक प्रारूप

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

markdown

# प्रमाणीकरण विनिर्देश

उद्देश्य

एप्लिकेशन के लिए प्रमाणीकरण और सत्र प्रबंधन।

आवश्यकताएँ

आवश्यकता: उपयोगकर्ता प्रमाणीकरण

सिस्टम सफल लॉगिन पर एक JWT टोकन जारी करेगा।

परिदृश्य: मान्य क्रेडेंशियल

दिया गया मान्य क्रेडेंशियल वाला एक उपयोगकर्ता
जब उपयोगकर्ता लॉगिन फॉर्म सबमिट करता है
तो एक JWT टोकन लौटाया जाता है
और उपयोगकर्ता को डैशबोर्ड पर रीडायरेक्ट किया जाता है

परिदृश्य: अमान्य क्रेडेंशियल

दिया गया अमान्य क्रेडेंशियल
जब उपयोगकर्ता लॉगिन फॉर्म सबमिट करता है
तो एक त्रुटि संदेश प्रदर्शित होता है
और कोई टोकन जारी नहीं किया जाता है

आवश्यकता: सत्र समाप्ति

सिस्टम 30 मिनट की निष्क्रियता के बाद सत्रों को समाप्त कर देगा।

परिदृश्य: निष्क्रिय टाइमआउट

दिया गया एक प्रमाणित सत्र
जब गतिविधि के बिना 30 मिनट बीत जाते हैं
तो सत्र अमान्य हो जाता है
और उपयोगकर्ता को फिर से प्रमाणित करना होगा


**मुख्य तत्व:**

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

### विनिर्देशों को इस तरह संरचित क्यों करें

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

**परिदृश्य "कब" हैं** — वे ठोस उदाहरण प्रदान करते हैं जिन्हें सत्यापित किया जा सकता है। अच्छे परिदृश्य:
- परीक्षण योग्य होते हैं (आप उनके लिए एक स्वचालित परीक्षण लिख सकते हैं)
- सुखद मार्ग और एज केस दोनों को कवर करते हैं
- दिया/जब/तब या समान संरचित प्रारूप का उपयोग करते हैं

**RFC 2119 कीवर्ड** (SHALL, MUST, SHOULD, MAY) इरादा बताते हैं:
- **MUST/SHALL** — पूर्ण आवश्यकता
- **SHOULD** — अनुशंसित, लेकिन अपवाद मौजूद हैं
- **MAY** — वैकल्पिक

### विनिर्देश क्या है (और क्या नहीं है)

एक विनिर्देश एक **व्यवहार अनुबंध** है, कार्यान्वयन योजना नहीं।

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

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

त्वरित परीक्षण:
- यदि बाहरी रूप से दिखने वाले व्यवहार को बदले बिना कार्यान्वयन बदल सकता है, तो यह संभवतः विनिर्देश में नहीं होना चाहिए।

### इसे हल्का रखें: प्रगतिशील कठोरता

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

**लाइट विनिर्देश (डिफ़ॉल्ट):**
- छोटे व्यवहार-प्रथम आवश्यकताएँ
- स्पष्ट दायरा और गैर-लक्ष्य
- कुछ ठोस स्वीकृति जाँचें

**पूर्ण विनिर्देश (उच्च जोखिम के लिए):**
- क्रॉस-टीम या क्रॉस-रेपो परिवर्तन
- API/अनुबंध परिवर्तन, माइग्रेशन, सुरक्षा/गोपनीयता चिंताएँ
- परिवर्तन जहाँ अस्पष्टता महंगे पुनर्कार्य का कारण बनने की संभावना है

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

### मानव + एजेंट सहयोग

कई टीमों में, मानव अन्वेषण करते हैं और एजेंट आर्टिफैक्ट तैयार करते हैं। इच्छित लूप है:

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

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

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

एक परिवर्तन (change) आपके सिस्टम में प्रस्तावित संशोधन है, जिसे एक फ़ोल्डर के रूप में पैक किया जाता है जिसमें इसे समझने और लागू करने के लिए आवश्यक सभी चीज़ें शामिल होती हैं।

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

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


प्रत्येक परिवर्तन स्व-निहित (self-contained) होता है। इसमें शामिल हैं:
- **आर्टिफ़ैक्ट्स** — दस्तावेज़ जो उद्देश्य, डिज़ाइन और कार्यों को कैप्चर करते हैं
- **डेल्टा स्पेक्स** — विनिर्देश जो बताते हैं कि क्या जोड़ा, संशोधित या हटाया जा रहा है
- **मेटाडेटा** — इस विशिष्ट परिवर्तन के लिए वैकल्पिक कॉन्फ़िगरेशन

### परिवर्तन फ़ोल्डर क्यों हैं

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

1. **सब कुछ एक साथ।** प्रस्ताव, डिज़ाइन, कार्य और स्पेक्स एक ही स्थान पर रहते हैं। अलग-अलग जगहों पर खोजने की ज़रूरत नहीं।

2. **समानांतर कार्य।** कई परिवर्तन एक साथ मौजूद हो सकते हैं बिना टकराव के। `add-dark-mode` पर काम करते समय `fix-auth-bug` भी प्रगति में हो सकता है।

3. **स्वच्छ इतिहास।** आर्काइव करते समय, परिवर्तन अपने पूरे संदर्भ के साथ `changes/archive/` में चले जाते हैं। आप पीछे मुड़कर देख सकते हैं और न केवल समझ सकते हैं कि क्या बदला, बल्कि क्यों बदला।

4. **समीक्षा-अनुकूल।** एक परिवर्तन फ़ोल्डर की समीक्षा करना आसान है — इसे खोलें, प्रस्ताव पढ़ें, डिज़ाइन जांचें, स्पेक डेल्टा देखें।

## आर्टिफ़ैक्ट्स (Artifacts)

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

### आर्टिफ़ैक्ट प्रवाह (The Artifact Flow)

proposal ──────► specs ──────► design ──────► tasks ──────► implement │ │ │ │ why what how steps

scope changes approach to take


आर्टिफ़ैक्ट्स एक-दूसरे पर आधारित होते हैं। प्रत्येक आर्टिफ़ैक्ट अगले के लिए संदर्भ प्रदान करता है।

### आर्टिफ़ैक्ट प्रकार (Artifact Types)

#### प्रस्ताव (`proposal.md`)

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

```markdown
# Proposal: Add Dark Mode

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

## Scope
In scope:
- Theme toggle in settings
- System preference detection
- Persist preference in localStorage

Out of scope:
- Custom color themes (future work)
- Per-page theme overrides

## Approach
Use CSS custom properties for theming with a React context
for state management. Detect system preference on first load,
allow manual override.

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

दायरा बदलता है (संकुचित या विस्तारित)
उद्देश्य स्पष्ट होता है (समस्या की बेहतर समझ)
दृष्टिकोण मूल रूप से बदलता है

स्पेक्स (`specs/` में डेल्टा स्पेक्स)

डेल्टा स्पेक्स वर्तमान स्पेक्स के सापेक्ष क्या बदल रहा है इसका वर्णन करते हैं। नीचे डेल्टा स्पेक्स देखें।

डिज़ाइन (`design.md`)

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

markdown

# Design: Add Dark Mode

## Technical Approach
Theme state managed via React Context to avoid prop drilling.
CSS custom properties enable runtime switching without class toggling.

## Architecture Decisions

### Decision: Context over Redux
Using React Context for theme state because:
- Simple binary state (light/dark)
- No complex state transitions
- Avoids adding Redux dependency

### Decision: CSS Custom Properties
Using CSS variables instead of CSS-in-JS because:
- Works with existing stylesheet
- No runtime overhead
- Browser-native solution

## Data Flow
```
ThemeProvider (context)
       │
       ▼
ThemeToggle ◄──► localStorage
       │
       ▼
CSS Variables (applied to :root)
```

## File Changes
- `src/contexts/ThemeContext.tsx` (new)
- `src/components/ThemeToggle.tsx` (new)
- `src/styles/globals.css` (modified)

डिज़ाइन को कब अपडेट करें:

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

कार्य (`tasks.md`)

कार्य कार्यान्वयन चेकलिस्ट हैं — चेकबॉक्स के साथ ठोस कदम।

markdown

# 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
- [ ] 1.4 Add system preference detection

## 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.3 Test contrast ratios for accessibility

कार्यों की सर्वोत्तम प्रथाएँ:

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

डेल्टा स्पेक्स (Delta Specs)

डेल्टा स्पेक्स वह मुख्य अवधारणा है जो OpenSpec को ब्राउनफ़ील्ड डेवलपमेंट के लिए कारगर बनाती है। ये पूरे स्पेक को दोहराने के बजाय क्या बदल रहा है इसका वर्णन करते हैं।

प्रारूप (The Format)

markdown

# Delta for Auth

## ADDED Requirements

### Requirement: Two-Factor Authentication
The system MUST support TOTP-based two-factor authentication.

#### Scenario: 2FA enrollment
- GIVEN a user without 2FA enabled
- WHEN the user enables 2FA in settings
- THEN a QR code is displayed for authenticator app setup
- AND the user must verify with a code before activation

#### Scenario: 2FA login
- GIVEN a user with 2FA enabled
- WHEN the user submits valid credentials
- THEN an OTP challenge is presented
- AND login completes only after valid OTP

## MODIFIED Requirements

### Requirement: Session Expiration
The system MUST expire sessions after 15 minutes of inactivity.
(Previously: 30 minutes)

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

## REMOVED Requirements

### Requirement: Remember Me
(Deprecated in favor of 2FA. Users should re-authenticate each session.)

डेल्टा अनुभाग (Delta Sections)

अनुभाग	अर्थ	आर्काइव पर क्या होता है
`## ADDED Requirements`	नया व्यवहार	मुख्य स्पेक में जोड़ा जाता है
`## MODIFIED Requirements`	बदला हुआ व्यवहार	मौजूदा आवश्यकता को प्रतिस्थापित करता है
`## REMOVED Requirements`	पदावनत व्यवहार	मुख्य स्पेक से हटाया जाता है

पूर्ण स्पेक्स के बजाय डेल्टा क्यों

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

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

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

ब्राउनफ़ील्ड अनुकूलता। अधिकांश कार्य मौजूदा व्यवहार को संशोधित करता है। डेल्टा संशोधनों को प्रथम श्रेणी बनाते हैं, न कि बाद का विचार।

स्कीमाएँ

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

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

yaml

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

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

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

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

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

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

निर्भरताएँ सक्षमकर्ता हैं, गेट नहीं। वे दिखाती हैं कि क्या बनाना संभव है, न कि आपको अगला क्या बनाना चाहिए। यदि आपको डिज़ाइन की आवश्यकता नहीं है तो आप उसे छोड़ सकते हैं। आप स्पेक्स को डिज़ाइन से पहले या बाद में बना सकते हैं — दोनों केवल प्रस्ताव पर निर्भर करते हैं।

अंतर्निहित स्कीमाएँ

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

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

proposal → specs → design → tasks → implement

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

कस्टम स्कीमाएँ

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

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]   # शोध द्वारा सूचित प्रस्ताव

  - id: tasks
    generates: tasks.md
    requires: [proposal]   # स्पेक्स/डिज़ाइन छोड़ें, सीधे कार्यों पर जाएँ

कस्टम स्कीमाएँ बनाने और उपयोग करने के बारे में पूर्ण विवरण के लिए कस्टमाइज़ेशन देखें।

आर्काइव

आर्काइविंग एक परिवर्तन को पूरा करती है, उसके डेल्टा स्पेक्स को मुख्य स्पेक्स में विलय करके और इतिहास के लिए परिवर्तन को संरक्षित करके।

जब आप आर्काइव करते हैं तो क्या होता है

आर्काइव से पहले:

openspec/
├── specs/
│   └── auth/
│       └── spec.md ◄────────────────┐
└── changes/                         │
    └── add-2fa/                     │
        ├── proposal.md              │
        ├── design.md                │ विलय
        ├── 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

आर्काइव प्रक्रिया

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

आर्काइव महत्वपूर्ण क्यों है

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

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

स्पेक विकास। जैसे-जैसे परिवर्तन आर्काइव होते हैं, स्पेक्स स्वाभाविक रूप से बढ़ते हैं। प्रत्येक आर्काइव अपने डेल्टा को विलय करता है, समय के साथ एक व्यापक विनिर्देश का निर्माण करता है।

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

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

सद्गुण चक्र:

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

शब्दावली

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

अगले कदम

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

अवधारणाएँ ​

दर्शन ​

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

बड़ी तस्वीर ​

समन्वय कार्यक्षेत्र ​

स्पेक्स ​

संरचना ​

स्पेक प्रारूप ​

उद्देश्य ​

आवश्यकताएँ ​

आवश्यकता: उपयोगकर्ता प्रमाणीकरण ​

परिदृश्य: मान्य क्रेडेंशियल ​

परिदृश्य: अमान्य क्रेडेंशियल ​

आवश्यकता: सत्र समाप्ति ​

परिदृश्य: निष्क्रिय टाइमआउट ​

स्पेक्स (specs/ में डेल्टा स्पेक्स) ​

डिज़ाइन (design.md) ​

कार्य (tasks.md) ​

डेल्टा स्पेक्स (Delta Specs) ​

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

डेल्टा अनुभाग (Delta Sections) ​

पूर्ण स्पेक्स के बजाय डेल्टा क्यों ​

स्कीमाएँ ​

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

अंतर्निहित स्कीमाएँ ​

कस्टम स्कीमाएँ ​

आर्काइव ​

जब आप आर्काइव करते हैं तो क्या होता है ​

आर्काइव प्रक्रिया ​

आर्काइव महत्वपूर्ण क्यों है ​

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

शब्दावली ​

अगले कदम ​

अवधारणाएँ

दर्शन

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

बड़ी तस्वीर

समन्वय कार्यक्षेत्र

स्पेक्स

संरचना

स्पेक प्रारूप

उद्देश्य

आवश्यकताएँ

आवश्यकता: उपयोगकर्ता प्रमाणीकरण

परिदृश्य: मान्य क्रेडेंशियल

परिदृश्य: अमान्य क्रेडेंशियल

आवश्यकता: सत्र समाप्ति

परिदृश्य: निष्क्रिय टाइमआउट

स्पेक्स (`specs/` में डेल्टा स्पेक्स)

डिज़ाइन (`design.md`)

कार्य (`tasks.md`)

डेल्टा स्पेक्स (Delta Specs)

प्रारूप (The Format)

डेल्टा अनुभाग (Delta Sections)

पूर्ण स्पेक्स के बजाय डेल्टा क्यों

स्कीमाएँ

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

अंतर्निहित स्कीमाएँ

कस्टम स्कीमाएँ

आर्काइव

जब आप आर्काइव करते हैं तो क्या होता है

आर्काइव प्रक्रिया

आर्काइव महत्वपूर्ण क्यों है

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

शब्दावली

अगले कदम