अवधारणाएँ

यह मार्गदर्शिका 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

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

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

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

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

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

बड़ी तस्वीर

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

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

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

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

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

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

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

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

जब एक रिपॉज़िटरी योजना, कार्यान्वयन और अभिलेखागार प्रवाह का स्वामित्व रखती है तो Repo-स्थानिक OpenSpec प्रोजेक्ट सही डिफ़ॉल्ट हैं। कुछ कार्य कई रिपोज़ या फ़ोल्डरों तक फैला होता है। उस स्थिति के लिए, एक OpenSpec समन्वय कार्यक्षेत्र एक मशीन-स्थानिक दृश्य है जो लिंक किए गए पथों, opener स्थिति और एजेंट सेटअप को एक साथ रखता है।

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

workspace     = context stores, initiatives, repos और folders पर निजी स्थानिक दृश्य
context store = टिकाऊ साझा संदर्भ कंटेनर
initiative    = एक context store के अंदर टिकाऊ समन्वय संदर्भ
link          = किसी repo या folder के लिए एक स्थिर नाम जिसे कार्यक्षेत्र स्थानिक रूप से हल कर सकता है
change        = कार्य की एक योजनाबद्ध इकाई; कार्यान्वयन स्वामित्व वाले repo में होता है

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

getGlobalDataDir()/workspaces/<workspace-name>/
├── workspace.yaml                 # निजी स्थानिक दृश्य रिकॉर्ड
├── AGENTS.md                      # जनरेटेड रनटाइम मार्गदर्शन
└── <workspace-name>.code-workspace # जनरेटेड एडिटर कार्यक्षेत्र फ़ाइल

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

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

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

स्थिर लिंक नाम वह तरीका है जिससे एक कार्यक्षेत्र repo और फ़ोल्डरों को संदर्भित करता है। निजी कार्यक्षेत्र रिकॉर्ड api, web, या checkout जैसे नामों को रखता है और उन्हें इस रनटाइम के स्थानिक पथों पर मैप करता है।

# workspace.yaml
version: 1
name: platform
context: null
links:
  api: /repos/api
  web: /repos/web

जब एक कार्यक्षेत्र कोई initiative खोलता है, तो context चयनित context-store बाइंडिंग और initiative आईडी दर्ज करता है। रजिस्ट्री-चयनित स्टोर आईडी द्वारा पोर्टेबल रहते हैं; पथ-चयनित स्टोर जानबूझकर रनटाइम-स्थानिक पथ को संरक्षित करते हैं क्योंकि workspace.yaml निजी स्थानिक स्थिति है।

context:
  kind: initiative
  store:
    id: platform
    selector:
      kind: registry
      id: platform
  initiative:
    id: billing-launch

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

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

बड़ा monorepo:
  billing  -> /repos/platform/services/billing
  checkout -> /repos/platform/apps/checkout

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

getGlobalDataDir()/workspaces

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

OpenSpec अभी भी पुराने बीटा कार्यक्षेत्र रूट्स को संगतता इनपुट के रूप में पढ़ सकता है, लेकिन प्रबंधित कार्यक्षेत्र अब ऊपर दिए गए रूट workspace.yaml रिकॉर्ड का उपयोग करते हैं। कार्यक्षेत्र फ़ोल्डर अपने स्वयं के निजी स्थानिक दृश्य के लिए प्राधिकारी बना रहता है।

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

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

# गाइडेड सेटअप
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-cli

# स्थानिक रजिस्ट्री से ज्ञात कार्यक्षेत्र देखें
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 update
openspec workspace update --workspace platform --tools codex,claude

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

# एक initiative को स्थानिक कार्यक्षेत्र दृश्य के रूप में खोलें
openspec workspace open --initiative billing-launch --store platform
openspec workspace open --initiative billing-launch --store-path /repos/platform-context

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

कार्यक्षेत्र कौशल केवल कार्यक्षेत्र रूट में स्थापित होते हैं। सक्रिय ग्लोबल प्रोफ़ाइल यह चयन करती है कि कौन से वर्कफ़्लो कौशल जनरेट हों; --tools यह चयन करता है कि कौन से एजेंट उन्हें प्राप्त करें। कार्यक्षेत्र सेटअप और अपडेट स्लैश कमांड फ़ाइलें नहीं बनाते, भले ही ग्लोबल डिलीवरी में कमांड शामिल हों। कार्यक्षेत्र-स्थानिक मार्गदर्शन रिफ्रेश करने और लिंक किए हुए repo या फ़ोल्डरों को संपादित किए बिना प्रबंधित कार्यक्षेत्र-स्थानिक कौशल निर्देशिकाओं को जोड़ने, रिफ्रेश करने या हटाने के लिए openspec workspace update चलाएं।

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

�नाए गए VS Code कार्यक्षेत्र पहले मान्य लिंक किए हुए repo या फ़ोल्डरों को सूचीबद्ध करते हैं, फिर जुड़ा होने पर initiative संदर्भ, फिर OpenSpec कार्यक्षेत्र फ़ाइलें। VS Code उन प्रविष्टियों को मल्टी-रूट कार्यक्षेत्र के रूप में प्रदर्शित करता है।

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

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

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

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

Specs

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

संरचना

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

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

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

Spec प्रारूप

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

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

## उद्देश्य
अनुप्रयोग के लिए प्रमाणीकरण और सत्र प्रबंधन।

## आवश्यकताएं

### आवश्यकता: उपयोगकर्ता प्रमाणीकरण
सफल लॉगिन पर सिस्टम JWT टोकन जारी करेगा।

#### परिदृश्य: मान्य प्रमाण-पत्र
- GIVEN मान्य प्रमाण-पत्र वाला उपयोगकर्ता
- WHEN उपयोगकर्ता लॉगिन फ़ॉर्म सबमिट करता है
- THEN JWT टोकन लौटाया जाता है
- AND उपयोगकर्ता को डैशबोर्ड पर रीडायरेक्ट किया जाता है

#### परिदृश्य: अमान्य प्रमाण-पत्र
- GIVEN अमान्य प्रमाण-पत्र
- WHEN उपयोगकर्ता लॉगिन फ़ॉर्म सबमिट करता है
- THEN त्रुटि संदेश प्रदर्शित होता है
- AND कोई टोकन जारी नहीं किया जाता

### आवश्यकता: सत्र समाप्ति
निष्क्रियता के 30 मिनट बाद सिस्टम को सत्र समाप्त करना होगा।

#### परिदृश्य: निष्क्रिय टाइमआउट
- GIVEN एक प्रमाणित सत्र
- WHEN गतिविधि के बिना 30 मिनट बीत जाते हैं
- THEN सत्र अमान्य हो जाता है
- AND उपयोगकर्ता को फिर से प्रमाणित होना होगा

प्रमुख तत्व:

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

Specs को इस तरह संरचित क्यों करें

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

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

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

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

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

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

एक spec एक व्यवहार अनुबंध है, कार्यान्वयन योजना नहीं।

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

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

Specs में बचें:

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

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

• यदि कार्यान्वयन बाहरी रूप से दृश्यमान व्यवहार को बदले बिना बदल सकता है, तो संभवतः यह spec में नहीं आता।

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

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

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

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

पूर्ण spec (उच्च जोखिम के लिए):

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

ज्यादातर परिवर्तनों को लाइट मोड में रहना चाहिए।

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

कई टीमों में, मनुष्य अन्वेषण करते हैं और एजेंट कलाकृतियाँ बनाते हैं। अभिप्रेत लूप है:

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

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

परिवर्तन (Changes)

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

परिवर्तन संरचना (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
    │               │             │              │
  क्यों           क्या          कैसे         चरण
 + दायरा       बदलाव         दृष्टिकोण     उठाने हैं

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

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

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

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

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

इंटेंट

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

स्कोप

इसमें शामिल है:

• सेटिंग्स में थीम टॉगल
• सिस्टम प्राथमिकता का पता लगाना
• localStorage में प्राथमिकता को संग्रहीत करना

इसमें शामिल नहीं है:

• कस्टम रंग थीम (भविष्य का कार्य)
• प्रति-पृष्ठ थीम ओवरराइड

दृष्टिकोण

थीमिंग के लिए CSS कस्टम प्रॉपर्टीज का उपयोग करें और स्थिति प्रबंधन के लिए एक React कॉन्टेक्स्ट का उपयोग करें। पहली बार लोड होने पर सिस्टम प्राथमिकता का पता लगाएं, मैनुअल ओवरराइड की अनुमति दें।

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

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

डेल्टा स्पेक्स **क्या बदल रहा है** इसका वर्णन करते हैं, जो वर्तमान स्पेक्स के सापेक्ष है। नीचे [डेल्टा स्पेक्स](#डेल्टा-स्पेक्स) देखें।

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

डिज़ाइन **तकनीकी दृष्टिकोण** और **आर्किटेक्चर निर्णयों** को कैप्चर करता है।

````markdown
# डिजाइन: डार्क मोड जोड़ें

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

## आर्किटेक्चर निर्णय

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

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

## डेटा फ़्लो

ThemeProvider (कॉन्टेक्स्ट) │ ▼ ThemeToggle ◄──► localStorage │ ▼ CSS Variables (:root पर लागू)

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

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

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

कार्य (tasks.md)

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

# कार्य

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

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

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

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

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

डेल्टा स्पेक्स

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

प्रारूप

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

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

### आवश्यकता: दो-कारक प्रमाणीकरण
सिस्टम TOTP-आधारित दो-कारक प्रमाणीकरण का समर्थन करना चाहिए।

#### परिदृश्य: 2FA नामांकन
- दिया गया 2FA सक्षम के बिना एक उपयोगकर्ता
- जब उपयोगकर्ता सेटिंग्स में 2FA सक्षम करता है
- तो प्रमाणक ऐप सेटअप के लिए एक QR कोड प्रदर्शित होता है
- और सक्रियण से पहले उपयोगकर्ता को एक कोड से सत्यापित करना होगा

#### परिदृश्य: 2FA लॉगिन
- दिया गया 2FA सक्षम वाला एक उपयोगकर्ता
- जब उपयोगकर्ता मान्य क्रेडेंशियल्स सबमिट करता है
- तो एक OTP चुनौती प्रस्तुत की जाती है
- और लॉगिन केवल मान्य OTP के बाद पूरा होता है

## संशोधित आवश्यकताएं

### आवश्यकता: सत्र समाप्ति
सिस्टम निष्क्रियता के 15 मिनट बाद सत्रों की समय-सीमा समाप्त कर देनी चाहिए।
(पहले: 30 मिनट)

#### परिदृश्य: निष्क्रिय टाइमआउट
- दिया गया एक प्रमाणित सत्र
- जब गतिविधि के बिना 15 मिनट बीत जाते हैं
- तो सत्र अमान्य हो जाता है

## हटाई गई आवश्यकताएं

### आवश्यकता: मुझे याद रखें
(2FA के पक्ष में अवमूल्यित। उपयोगकर्ताओं को प्रत्येक सत्र में फिर से प्रमाणित करना चाहिए।)

डेल्टा अनुभाग

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

डेल्टा क्यों, पूर्ण स्पेक्स क्यों नहीं

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

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

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

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

स्कीमाएं

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

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

# 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] # पहले दोनों स्पेक्स और डिज़ाइन की आवश्यकता है

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

                    प्रस्ताव
                   (मूल नोड)
                       │
         ┌─────────────┴─────────────┐
         │                           │
         ▼                           ▼
      स्पेक्स                       डिज़ाइन
   (आवश्यकता:                  (आवश्यकता:
    प्रस्ताव)                   प्रस्ताव)
         │                           │
         └─────────────┬─────────────┘
                       │
                       ▼
                    कार्य
                (आवश्यकता:
                स्पेक्स, डिज़ाइन)

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

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

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

स्पेक-संचालित विकास के लिए मानक कार्यप्रवाह:

प्रस्ताव → स्पेक्स → डिज़ाइन → कार्य → कार्यान्वयन

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

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

अपनी टीम के कार्यप्रवाह के लिए कस्टम स्कीमाएं बनाएं:

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

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

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

# 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

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

1. डेल्टाज़ मर्ज करें। प्रत्येक डेल्टा स्पेक अनुभाग (जोड़ी गई/संशोधित/हटाई गई) संबंधित मुख्य स्पेक पर लागू किया जाता है।

2. आर्काइव में ले जाएं। परिवर्तन फ़ोल्डर changes/archive/ में ले जाया जाता है, कालानुक्रमित क्रम के लिए एक दिनांक उपसर्ग के साथ।

3. संदर्भ संरक्षित करें। सभी आर्टिफैक्ट्स आर्काइव में अक्षुण्ण रहते हैं। आप हमेशा यह समझने के लिए वापस देख सकते हैं कि परिवर्तन क्यों किया गया।

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

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

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

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

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

┌──────────────────────────────────────────────────────────────────────────────┐
│                           OPENSPEC फ़्लो                                     │
│                                                                              │
│   ┌────────────────┐                                                         │
│   │  1. शुरू करें      │  /opsx:propose (कोर) या /opsx:new (विस्तारित)          │
│   │     परिवर्तन     │                                                         │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  2. बनाएं         │  /opsx:ff या /opsx:continue (विस्तारित कार्यप्रवाह)      │
│   │     आर्टिफैक्ट्स  │  प्रस्ताव → स्पेक्स → डिज़ाइन → कार्य बनाता है             │
│   │                │  (स्कीमा निर्भरताओं पर आधारित)                          │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  3. कार्यान्वयन  │  /opsx:apply                                            │
│   │     कार्य        │  कार्यों के माध्यम से काम करें, उन्हें चेक करें                  │
│   │                │◄──── जैसे-जैसे आप सीखें आर्टिफैक्ट्स अपडेट करें                │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐                                                         │
│   │  4. सत्यापित करें │  /opsx:verify (वैकल्पिक)                                │
│   │     कार्य        │  जांचें कि कार्यान्वयन स्पेक्स से मेल खाता है                   │
│   └───────┬────────┘                                                         │
│           │                                                                  │
│           ▼                                                                  │
│   ┌────────────────┐     ┌──────────────────────────────────────────────┐    │
│   │  5. आर्काइव      │────►│  डेल्टा स्पेक्स मुख्य स्पेक्स में मर्ज हो जाते हैं         │    │
│   │     परिवर्तन     │     │  परिवर्तन फ़ोल्डर आर्काइव/ में ले जाया जाता है        │    │
│   └────────────────┘     │  स्पेक्स अब अपडेटेड सत्य का स्रोत हैं                  │    │
│                          └──────────────────────────────────────────────┘    │
│                                                                              │
└──────────────────────────────────────────────────────────────────────────────┘

सद्गुण चक्र:

1. स्पेक्स वर्तमान व्यवहार का वर्णन करते हैं
2. परिवर्तन संशोधनों का प्रस्ताव करते हैं (डेल्टाज़ के रूप में)
3. कार्यान्वयन परिवर्तनों को वास्तविक बनाता है
4. आर्काइव डेल्टाज़ को स्पेक्स में मर्ज करता है
5. स्पेक्स अब नए व्यवहार का वर्णन करते हैं
6. अगला परिवर्तन अपडेटेड स्पेक्स पर आधारित होता है

शब्दावली

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

अगले कदम

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