spec-driven

डिफ़ॉल्ट वर्कफ़्लो के आर्टिफैक्ट्स: उनका क्रम, उनके फ़ॉर्मेट और वह चेंज फ़ोल्डर जिसे वे उत्पन्न करते हैं।

spec-driven OpenSpec का अंतर्निहित डिफ़ॉल्ट स्कीमा है। schema.yaml उन फ़ील्ड को परिभाषित करता है जिन्हें यह सेट करता है।

आर्टिफैक्ट्स

वर्कफ़्लो चार आर्टिफैक्ट्स का ड्राफ़्ट तैयार करता है:

आर्टिफैक्ट	फ़ाइल	उद्देश्य
proposal	proposal.md	परिवर्तन की आवश्यकता क्यों है
specs	specs/<capability-path>/spec.md, प्रत्येक क्षमता के लिए एक	कौन-सा व्यवहार बदलता है
design	design.md	इसे कैसे बनाया जाए
tasks	tasks.md	कार्यान्वयन चेकलिस्ट

मसौदा तैयार करने का क्रम

             ┌─ specs ──┐
proposal ────┤          ├── tasks ── apply
             └─ design ─┘

प्रस्ताव सबसे पहले आता है। स्पेक और डिज़ाइन किसी भी क्रम में उसके बाद आते हैं, और कार्यों के लिए दोनों आवश्यक हैं। tasks.md तैयार हो जाने पर कार्यान्वयन (apply) शुरू होता है।

दो आर्टिफ़ैक्ट छोड़े जा सकते हैं:

• design: जब इसकी शर्तें लागू नहीं होतीं, तो एजेंट इसे छोड़ देता है और फिर भी tasks का मसौदा तैयार करता है।
• specs: परिवर्तन की .openspec.yaml में skip_specs: true सेट करें।

उदाहरण परिवर्तन फ़ोल्डर

add-user-auth नाम का परिवर्तन, जिसमें प्रत्येक आर्टिफ़ैक्ट का मसौदा तैयार है:

openspec/changes/add-user-auth/
├── .openspec.yaml      परिवर्तन मेटाडेटा, परिवर्तन बनाते समय लिखा जाता है
├── proposal.md
├── specs/
│   └── user-auth/
│       └── spec.md     प्रति क्षमता एक डेल्टा स्पेक
├── design.md
└── tasks.md

proposal.md

यह स्थापित करता है कि परिवर्तन क्यों आवश्यक है।

संरचना

एजेंट को आउटपुट फ़ॉर्मैट के रूप में मिलने वाला टेम्पलेट (templates/proposal.md):

# Proposal

## Why

<!-- इस परिवर्तन के प्रेरण का वर्णन करें। यह किस समस्या का समाधान करता है? अभी क्यों? -->

## What Changes

<!-- वर्णन करें कि क्या बदलेगा। नई क्षमताओं, संशोधनों या हटाने के बारे में विशिष्ट रहें। -->

## Capabilities

### New Capabilities
<!-- पेश की जा रही क्षमताएँ। प्रत्येक क्षमता का नाम ऐसे सुसंगत सिस्टम
     व्यवहार के आधार पर रखें जो सिस्टम के विकसित होने के साथ संबंधित आवश्यकताओं का स्वामित्व ले सके। कार्यान्वयन
     कार्यों या प्रस्ताव अनुभागों के नाम न दें। व्यापक कैच-ऑल नामों से बचें। आप जो पाथ सेगमेंट पेश करते हैं
     उनके लिए kebab-case का उपयोग करें (जैसे, user-auth या identity/user-auth)
     जो प्रोजेक्ट के मौजूदा स्पेक संगठन का पालन करें। प्रत्येक
     specs/<capability-path>/spec.md बनाता है। -->
- `<capability-path>`: <इस क्षमता के दायरे का संक्षिप्त विवरण>

### Modified Capabilities
<!-- मौजूदा क्षमताएँ जिनकी आवश्यकताएँ बदल रही हैं (केवल कार्यान्वयन नहीं)।
     केवल तभी यहाँ सूचीबद्ध करें जब स्पेक-स्तरीय व्यवहार बदलता हो। प्रत्येक के लिए एक डेल्टा स्पेक फ़ाइल आवश्यक है।
     openspec/specs/ के अंतर्गत सटीक मौजूदा पाथ का उपयोग करें। यदि कोई आवश्यकता
     परिवर्तन नहीं है तो खाली छोड़ें। बिना किसी क्षमता वाले परिवर्तन (शुद्ध रिफ़ैक्टर, टूलिंग, डॉक्स)
     को अपनी .openspec.yaml में `skip_specs: true` सेट करना चाहिए - openspec validate
     बिना उस मार्कर के शून्य-डेल्टा परिवर्तन को अस्वीकार करता है। केवल
     वैलिडेशन संतुष्ट करने के लिए कोई आवश्यकता न गढ़ें। -->
- `<existing-capability-path>`: <कौन-सी आवश्यकता बदल रही है>

## Impact

<!-- प्रभावित कोड, API, निर्भरताएँ, सिस्टम -->

निर्देश

इस आर्टिफ़ैक्ट का मसौदा तैयार करते समय एजेंट को भेजा गया निर्देश (schema.yaml से):

वह प्रस्ताव दस्तावेज़ बनाएँ जो स्थापित करता है कि यह परिवर्तन क्यों आवश्यक है।

अनुभाग:
- **Why**: समस्या या अवसर पर 1-2 वाक्य। यह किस समस्या का समाधान करता है? अभी क्यों?
- **What Changes**: परिवर्तनों की बुलेट सूची। नई क्षमताओं, संशोधनों या हटाए जाने के बारे में विशिष्ट रहें। ब्रेकिंग परिवर्तनों को **BREAKING** से चिह्नित करें।
- **Capabilities**: पहचानें कि कौन-से स्पेक बनाए या संशोधित किए जाएँगे:
  - **New Capabilities**: पेश की जा रही क्षमताओं की सूची दें। प्रत्येक एक नया `specs/<capability-path>/spec.md` बनता है। प्रत्येक क्षमता का नाम किसी टिकाऊ सिस्टम व्यवहार (उदाहरण के लिए, `user-auth`) के आधार पर रखें, इस परिवर्तन के कार्य (उदाहरण के लिए, `add-login-endpoint`) के आधार पर नहीं। ऐसी सुसंगत सीमा चुनें जो सिस्टम के विकसित होने के साथ संबंधित आवश्यकताओं का स्वामित्व ले सके; व्यापक कैच-ऑल क्षमताओं से बचें। आप जो पाथ सेगमेंट पेश करते हैं उनके लिए kebab-case का उपयोग करें (जैसे, `user-auth` या `identity/user-auth`) और प्रोजेक्ट के मौजूदा स्पेक संगठन का पालन करें।
  - **Modified Capabilities**: उन मौजूदा क्षमताओं की सूची दें जिनकी आवश्यकताएँ बदल रही हैं। केवल तभी शामिल करें जब स्पेक-स्तरीय व्यवहार बदलता हो (केवल कार्यान्वयन विवरण नहीं)। प्रत्येक के लिए एक डेल्टा स्पेक फ़ाइल आवश्यक है। `openspec/specs/` के अंतर्गत सटीक मौजूदा पाथ का उपयोग करें। यदि कोई आवश्यकता नहीं बदलती तो खाली छोड़ें।
- **Impact**: प्रभावित कोड, API, निर्भरताएँ या सिस्टम।

महत्वपूर्ण: Capabilities अनुभाग महत्वपूर्ण है। यह प्रस्ताव और स्पेक चरणों के बीच
अनुबंध बनाता है। इसे भरने से पहले मौजूदा स्पेक का शोध करें:
प्रोजेक्ट की क्षमता-सूची के लिए `openspec list --specs` चलाएँ, फिर किसी भी संबंधित दिखने वाले के लिए
`openspec show "<spec-id>" --type spec --json --no-scenarios` चलाएँ - यह पूरी स्पेक फ़ाइलें कॉन्टेक्स्ट में लाए बिना
किसी क्षमता का उद्देश्य और आवश्यकता पाठ लौटाता है। दोनों कमांड में `--store "<id>"` केवल किसी पंजीकृत
स्टैंडअलोन स्टोर के लिए जोड़ें, और `--type spec` बनाए रखें: अन्यथा एक परिवर्तन और एक स्पेक
का नाम समान होना ambiguous-item त्रुटि है। `--specs` के बिना `openspec list` प्रगतिरत परिवर्तनों की सूची देता है, स्पेक की नहीं -
यह कभी नहीं दिखाता कि प्रोजेक्ट पहले से क्या कवर करता है। नए जैसे-समान नाम पेश करने के बजाय
किसी मौजूदा क्षमता के सटीक पाथ का पुनः उपयोग करें।
फ़िल्टर किया गया पाठ केवल एक अवलोकन है। यह तय करने से पहले कि क्या पहले से कवर है या क्या बदलना चाहिए,
प्रत्येक संबंधित स्पेक को पूरी तरह पढ़ें, परिदृश्यों सहित, `openspec show "<spec-id>" --type spec` से (वही `--store` नियम)।
यहाँ सूचीबद्ध प्रत्येक क्षमता के लिए एक संगत स्पेक फ़ाइल आवश्यक होगी।

प्रत्येक परिवर्तन को या तो कम से कम एक क्षमता (नई या संशोधित) घोषित करनी होगी
या स्पष्ट रूप से स्पेक से बाहर रहना होगा: `openspec validate` शून्य डेल्टा वाले परिवर्तन को
अस्वीकार करता है, जब तक परिवर्तन की `.openspec.yaml` में `skip_specs: true` सेट न हो।
`skip_specs: true` का उपयोग केवल तब करें जब कोई स्पेक-स्तरीय व्यवहार न बदले (शुद्ध रिफ़ैक्टर, टूलिंग, डॉक्स) -
स्पेक व्यवहार का वर्णन करते हैं, इसलिए यदि व्यवहार नहीं बदलता, तो किसी स्पेक को भी नहीं बदलना चाहिए।
केवल वैलिडेशन संतुष्ट करने के लिए कोई आवश्यकता न गढ़ें।

इसे संक्षिप्त रखें (1-2 पृष्ठ)। "क्यों" पर ध्यान दें, "कैसे" पर नहीं -
कार्यान्वयन विवरण design.md में होते हैं।

यह आधार है - स्पेक, डिज़ाइन और कार्य सभी इसी पर बनते हैं।

डेल्टा स्पेक (spec.md)

परिभाषित करता है कि कौन-सा व्यवहार बदलता है, प्रस्ताव में सूचीबद्ध प्रत्येक क्षमता के लिए एक डेल्टा स्पेक के साथ।

प्रत्येक डेल्टा स्पेक अपनी क्षमता फ़ोल्डर के भीतर का spec.md है। openspec validate और openspec archive specs/ के अंतर्गत किसी अन्य फ़ाइल में लिखे गए डेल्टा अनुभागों को अस्वीकार करते हैं, जैसे specs/user-auth.md, क्योंकि आर्काइव उन्हें कभी मर्ज नहीं करता।

संरचना

एजेंट को आउटपुट फ़ॉर्मैट के रूप में मिलने वाला टेम्पलेट (templates/spec.md):

# Spec Delta

## Purpose
<!-- केवल नई क्षमताएँ: यह क्षमता किस लिए है, इस पर एक या दो वाक्य (50+ अक्षर)। मौजूदा क्षमता के लिए इस अनुभाग को हटा दें। -->

## ADDED Requirements

### Requirement: <!-- आवश्यकता का नाम -->
<!-- आवश्यकता का पाठ -->

#### Scenario: <!-- परिदृश्य का नाम -->
- **WHEN** <!-- शर्त -->
- **THEN** <!-- अपेक्षित परिणाम -->

निर्देश

इस आर्टिफ़ैक्ट का मसौदा तैयार करते समय एजेंट को भेजा गया निर्देश (schema.yaml से):

ऐसी विनिर्देश फ़ाइलें बनाएँ जो परिभाषित करें कि सिस्टम को क्या करना चाहिए।

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

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

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

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

प्रस्ताव के Capabilities अनुभाग में सूचीबद्ध प्रत्येक क्षमता के लिए एक स्पेक फ़ाइल बनाएँ।
`<capability-path>` `specs/` के सापेक्ष स्पेक निर्देशिका है (उदाहरण के लिए,
`user-auth` या `identity/user-auth`)। पूरा पाथ बनाए रखें:
- नई क्षमताएँ: प्रस्ताव से सटीक पाथ `specs/<capability-path>/spec.md` पर उपयोग करें। प्रस्ताव में नया पेश किया गया कोई भी पाथ सेगमेंट kebab-case में होना चाहिए। प्रोजेक्ट के मौजूदा संगठन का पालन करें; जब प्रोजेक्ट फ़्लैट लेआउट का उपयोग करता है तो नया डोमेन स्तर न जोड़ें।
- संशोधित क्षमताएँ: `specs/<capability-path>/spec.md` पर डेल्टा बनाते समय `openspec/specs/<capability-path>/` से सटीक मौजूदा पाथ का उपयोग करें। डेल्टा लिखने से पहले उस पाथ की पुष्टि के लिए `openspec list --specs` चलाएँ, और `--store "<id>"` केवल किसी पंजीकृत स्टैंडअलोन स्टोर के लिए जोड़ें - गलत टाइप किया गया या गढ़ा गया पाथ उस क्षमता को लक्षित करता है जो मौजूद नहीं है, न कि उसे जिसका आपने अर्थ लिया था। क्षमता को स्थानांतरित या पुनर्नामित न करें।

स्पेक फ़ाइलें एक-एक करके लिखें, ताकि उपयोगकर्ता को प्रगति दिखे और बाधित रन पहले से लिखी
फ़ाइलें बनाए रखे:
- कुछ भी लिखने से पहले, प्रस्ताव में सूचीबद्ध क्षमताओं की तुलना पहले से मौजूद
  `specs/<capability-path>/spec.md` फ़ाइलों से करें, और उस पहली क्षमता से शुरू करें जिसकी कोई फ़ाइल नहीं है। जब तक उपयोगकर्ता न कहे, मौजूदा फ़ाइल को फिर से न लिखें।
- प्रत्येक फ़ाइल से पहले, एक पंक्ति में बताएँ कि आप कौन-सी क्षमता लिख रहे हैं।
- प्रत्येक फ़ाइल को मसौदा तैयार होते ही लिखें। पहली फ़ाइल लिखने से पहले हर फ़ाइल की योजना न बनाएँ।
- तब रुकें जब प्रस्ताव में सूचीबद्ध प्रत्येक क्षमता की अपनी फ़ाइल हो जाए।

कम से कम एक स्पेक फ़ाइल होनी चाहिए, जब तक परिवर्तन की `.openspec.yaml` में
`skip_specs: true` सेट न हो (कोई स्पेक-स्तरीय व्यवहार परिवर्तन नहीं) - `openspec validate`
बिना उस मार्कर के शून्य-डेल्टा परिवर्तन को अस्वीकार करता है। यदि प्रस्ताव में कोई
क्षमता सूचीबद्ध नहीं है और `skip_specs` सेट नहीं है, तो पहले प्रस्ताव पर पुनर्विचार करें।

डेल्टा ऑपरेशन (## हेडर का उपयोग करें):
- **ADDED Requirements**: नई क्षमताएँ
- **MODIFIED Requirements**: बदला हुआ व्यवहार - इसमें पूरा अद्यतन कंटेंट अवश्य शामिल होना चाहिए
- **REMOVED Requirements**: अप्रचलित सुविधाएँ - इसमें **Reason** और **Migration** अवश्य शामिल होने चाहिए
- **RENAMED Requirements**: केवल नाम परिवर्तन - FROM:/TO: प्रारूप का उपयोग करें

प्रारूप आवश्यकताएँ:
- प्रत्येक आवश्यकता: `### Requirement: <name>` और उसके बाद विवरण
- मानकीय आवश्यकताओं के लिए SHALL/MUST का उपयोग करें (should/may से बचें)
- प्रत्येक परिदृश्य: WHEN/THEN प्रारूप के साथ `#### Scenario: <name>`
- **CRITICAL**: परिदृश्यों में ठीक 4 हैशटैग (`####`) का उपयोग होना चाहिए। 3 हैशटैग या बुलेट का उपयोग करने पर चुपचाप विफलता होगी।
- प्रत्येक आवश्यकता में कम से कम एक परिदृश्य होना चाहिए।
- प्रत्येक परिदृश्य में एक WHEN/GIVEN चरण (उसका ट्रिगर) और एक THEN चरण (उसका परिणाम) होना चाहिए। केवल AND पंक्तियों या सामान्य गद्य वाला परिदृश्य भी परिदृश्य माना जाता है, लेकिन `openspec validate` इसे चेतावनी के रूप में चिह्नित करता है: सामान्य वैलिडेशन फिर भी पास होता है, पर `openspec validate --strict` इस पर विफल होता है।
- प्रत्येक आवश्यकता का विवरण (`### Requirement:` और उसके पहले परिदृश्य के बीच का पाठ) 500 अक्षरों या कम तक रखें। `openspec validate` ADDED आवश्यकताओं में और मुख्य स्पेक में लंबे विवरणों को चिह्नित करता है। यह एक चेतावनी है: सामान्य वैलिडेशन फिर भी पास होता है, पर `openspec validate --strict` इस पर विफल होता है। नई आवश्यकता लिखते समय, प्रति आवश्यकता एक व्यवहार बताएँ: उदाहरणों और एज केसों को परिदृश्यों में ले जाएँ, और कई व्यवहारों को कवर करने वाली आवश्यकता को अलग-अलग `### Requirement:` ब्लॉकों में विभाजित करें, प्रत्येक के अपने परिदृश्यों के साथ। MODIFIED के अंतर्गत, मौजूदा आवश्यकता ब्लॉक को पूरा रखें; केवल लंबाई पूरी करने के लिए मौजूदा पाठ को कभी विभाजित, छोटा या पुनर्लिखित न करें। मौजूदा लंबी आवश्यकता को केवल तब विभाजित करें जब उपयोगकर्ता इसके लिए कहे, उसी उद्देश्य से किए गए परिवर्तन में: MODIFIED के अंतर्गत, उसका हेडर और हर परिदृश्य रखें और उसका अर्थ बदले बिना उसके विवरण को एक व्यवहार तक घटा दें, फिर हटाए गए प्रत्येक व्यवहार को अपने स्वयं के परिदृश्यों के साथ एक अलग ADDED आवश्यकता के रूप में जोड़ें।

केवल नई क्षमताओं के लिए: डेल्टा स्पेक का पहला अनुभाग `## Purpose` है -
एक या दो वाक्य (50+ अक्षर, अन्यथा `openspec validate --strict` इसे बहुत संक्षिप्त बताता है) जो वर्णन करें कि यह क्षमता किस लिए है। आर्काइव इसे उस मुख्य स्पेक में कॉपी करता है जो वह बनाता है; इसके बिना नया मुख्य स्पेक `TBD ... Update Purpose after archive` प्लेसहोल्डर के साथ छूट जाता है जिसे हाथ से भरना पड़ता है। मौजूदा क्षमता के डेल्टा में `## Purpose` न जोड़ें - उस स्पेक में पहले से एक है और डेल्टा वाला अनदेखा कर दिया जाता है। मौजूदा क्षमता का Purpose बदलने के लिए - बचे हुए `TBD` प्लेसहोल्डर सहित - सीधे `<planningHome.root>/openspec/specs/<capability-path>/spec.md` संपादित करें। `planningHome.root` `openspec instructions ... --json` प्रतिक्रिया से आता है। रेपो-सापेक्ष पाथ के बजाय हमेशा इसका उपयोग करें: जब भी परिवर्तन किसी स्टोर में रहता है - चाहे वह `--store` से आया हो, किसी प्रोजेक्ट के `store:` पॉइंटर से, या किसी वैश्विक डिफ़ॉल्ट स्टोर से - यह उस स्टोर पर हल होता है, और अन्यथा वर्तमान रेपो पर। यह पता लगाने की कोशिश न करें कि कौन-सा मामला लागू है; फ़ील्ड में पहले से यह है।

MODIFIED आवश्यकताओं का वर्कफ़्लो:
1. `<planningHome.root>/openspec/specs/<capability-path>/spec.md` में मौजूदा आवश्यकता खोजें (ऊपर वही स्टोर-सजग रूट)
2. पूरा आवश्यकता ब्लॉक कॉपी करें (`### Requirement:` से सभी परिदृश्यों तक)
3. `## MODIFIED Requirements` के अंतर्गत पेस्ट करें और नए व्यवहार को दर्शाने के लिए संपादित करें
4. सुनिश्चित करें कि हेडर टेक्स्ट ठीक मेल खाता है (व्हाइटस्पेस-असंवेदनशील)

सामान्य गलती: आंशिक कंटेंट के साथ MODIFIED का उपयोग करने से आर्काइव के समय विवरण खो जाता है।
यदि मौजूदा व्यवहार बदले बिना नई चिंताएँ जोड़ रहे हैं, तो इसके बजाय ADDED का उपयोग करें।

उदाहरण (एक नई क्षमता, इसलिए इसका पहला अनुभाग `## Purpose` है):
```
# Spec Delta

## उद्देश्य

उपयोगकर्ताओं को अपना डेटा उत्पाद से पोर्टेबल प्रारूप में बाहर निकालने की सुविधा देता है।

## ADDED आवश्यकताएँ

### आवश्यकता: उपयोगकर्ता डेटा निर्यात कर सकता है
सिस्टम उपयोगकर्ताओं को अपना डेटा CSV प्रारूप में निर्यात करने की अनुमति देगा।

#### परिदृश्य: सफल निर्यात
- **जब** उपयोगकर्ता "Export" बटन पर क्लिक करता है
- **तब** सिस्टम उपयोगकर्ता का सारा डेटा वाली CSV फ़ाइल डाउनलोड करता है

## REMOVED आवश्यकताएँ

### आवश्यकता: लेगेसी निर्यात
**कारण**: नई निर्यात प्रणाली द्वारा प्रतिस्थापित
**माइग्रेशन**: /api/v2/export पर नया निर्यात एंडपॉइंट उपयोग करें
```

स्पेक्स परीक्षण योग्य होने चाहिए - प्रत्येक परिदृश्य एक संभावित परीक्षण केस है।

design.md

design.md समझाता है कि परिवर्तन को कैसे लागू किया जाए। इसका मसौदा केवल तब तैयार किया जाता है जब परिवर्तन के लिए इसकी आवश्यकता हो।

संरचना

एजेंट को आउटपुट प्रारूप के रूप में प्राप्त होने वाला टेम्पलेट (templates/design.md):

# डिज़ाइन

## संदर्भ

<!-- वर्तमान स्थिति और बाधाएँ जो दृष्टिकोण को आकार देती हैं। प्रेरणा के लिए proposal.md देखें - इसे दोबारा न लिखें -->

## लक्ष्य / गैर-लक्ष्य

**लक्ष्य:**
<!-- यह डिज़ाइन क्या प्राप्त करना चाहता है -->

**गैर-लक्ष्य:**
<!-- जो स्पष्ट रूप से दायरे से बाहर है -->

## निर्णय

<!-- तर्क और विचार किए गए विकल्पों सहित प्रमुख डिज़ाइन निर्णय -->

## जोखिम / समझौते

<!-- ज्ञात जोखिम और समझौते -->

निर्देश

इस आर्टिफ़ैक्ट का मसौदा तैयार करते समय एजेंट को भेजा गया निर्देश (schema.yaml):

परिवर्तन को कैसे लागू करना है, यह समझाने वाला डिज़ाइन दस्तावेज़ बनाएँ।

design.md कब शामिल करें (केवल तभी बनाएँ जब कोई भी लागू हो):
- क्रॉस-कटिंग परिवर्तन (कई सेवाएँ/मॉड्यूल) या नया आर्किटेक्चरल पैटर्न
- नई बाहरी निर्भरता या महत्वपूर्ण डेटा मॉडल परिवर्तन
- सुरक्षा, प्रदर्शन या माइग्रेशन जटिलता
- ऐसी अस्पष्टता जिसे कोडिंग से पहले तकनीकी निर्णयों से लाभ हो

अनुभाग:
- **संदर्भ**: केवल वर्तमान स्थिति और आवश्यक बाधाएँ जो दृष्टिकोण को समझाने के लिए आवश्यक हैं। प्रेरणा के लिए प्रस्ताव का संदर्भ दें, उसे दोबारा न लिखें (उदा., "proposal.md देखें - क्यों")।
- **लक्ष्य / गैर-लक्ष्य**: यह डिज़ाइन क्या प्राप्त करता है और क्या स्पष्ट रूप से बाहर रखता है। प्रस्ताव के दायरे को दोबारा न लिखें - केवल डिज़ाइन-स्तरीय सीमाएँ जोड़ें।
- **निर्णय**: तर्क के साथ प्रमुख तकनीकी विकल्प (Y के बजाय X क्यों?)। प्रत्येक निर्णय के लिए विचार किए गए विकल्प शामिल करें।
- **जोखिम / समझौते**: ज्ञात सीमाएँ, ऐसी बातें जो गलत हो सकती हैं। प्रारूप: [जोखिम] → शमन
- **माइग्रेशन योजना**: डिप्लॉय करने के चरण, रोलबैक रणनीति (यदि लागू हो)
- **खुले प्रश्न**: ऐसी अज्ञात बातें जिनका उत्तर बाद में सुरक्षित रूप से दिया जा सकता है, बिना
  स्पेक्स, दृष्टिकोण या कार्य विभाजन को बदले। यदि कोई नहीं है तो छोड़ दें।

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

आर्किटेक्चर और दृष्टिकोण पर ध्यान दें, पंक्ति-दर-पंक्ति कार्यान्वयन पर नहीं।
प्रस्ताव "क्यों" और "क्या" को कवर करता है; डिज़ाइन "कैसे" को कवर करता है। प्रेरणा के लिए
प्रस्ताव का और, एक बार लिखे जाने पर, आवश्यकताओं के लिए स्पेक्स का संदर्भ दें -
यदि कोई अनुभाग उन्हें केवल दोबारा लिखेगा, तो उसके बजाय उनकी ओर इंगित करें।

अच्छे डिज़ाइन दस्तावेज़ तकनीकी निर्णयों के पीछे का "क्यों" समझाते हैं।

tasks.md

कार्यान्वयन को जाँचने योग्य कार्यों में विभाजित करता है। apply यहाँ प्रगति को ट्रैक करता है।

संरचना

एजेंट को आउटपुट प्रारूप के रूप में प्राप्त होने वाला टेम्पलेट (templates/tasks.md):

# कार्य

## 1. <!-- कार्य समूह का नाम -->

- [ ] 1.1 <!-- कार्य विवरण -->
- [ ] 1.2 <!-- कार्य विवरण -->

## 2. <!-- कार्य समूह का नाम -->

- [ ] 2.1 <!-- कार्य विवरण -->
- [ ] 2.2 <!-- कार्य विवरण -->

निर्देश

इस आर्टिफ़ैक्ट का मसौदा तैयार करते समय एजेंट को भेजा गया निर्देश (schema.yaml):

कार्य सूची बनाएँ जो कार्यान्वयन कार्य को विभाजित करती है।

कार्य लिखने से पहले, design.md में खुले प्रश्न जाँचें। यदि उनमें से कोई भी
यह बदल देगा कि क्या बनाया जाएगा, तो पहले उपयोगकर्ता के साथ उसे हल करें - कार्य सूची में
कोई अकथित धारणा शामिल न करें।

**महत्वपूर्ण: ट्रैक किए गए कार्यों के लिए नीचे दिए गए टेम्पलेट का पालन करें।** apply चरण प्रगति को ट्रैक करने के लिए
चेकबॉक्स प्रारूप को पार्स करता है। केवल `x` वाला बॉक्स पूर्ण माना जाता है,
ऊपरी या निचला केस और किसी भी स्पेसिंग के साथ, इसलिए `- [ x]` भी पूर्ण है। हर
अन्य मार्कर, जिसमें `- [~]`, `- [-]` और खाली `- []` शामिल हैं, अपूर्ण के रूप में
पढ़ा जाता है। चेकबॉक्स रहित पंक्ति बिल्कुल ट्रैक नहीं होती।

दिशानिर्देश:
- संबंधित ट्रैक किए गए कार्यों को ## क्रमांकित शीर्षकों के अंतर्गत समूहित करें
- प्रत्येक ट्रैक किए गए कार्य MUST एक चेकबॉक्स हो: `- [ ] X.Y कार्य विवरण`
- कार्य इतने छोटे होने चाहिए कि एक सत्र में पूरे हो सकें
- कार्यों को निर्भरता के अनुसार क्रम दें (पहले क्या किया जाना चाहिए?)
- कार्यान्वयन और सत्यापन कार्य को ट्रैक करें जिन्हें
  आर्काइव से पहले पूरा किया जा सकता है। यदि अनुरोधित वर्कफ़्लो में आर्काइव या ऐसा कार्य शामिल है जिसके लिए
  इस परिवर्तन को आर्काइव करना आवश्यक है, तो उन चरणों को tasks.md के अंत में
  वैकल्पिक `## Workflow follow-up` अनुभाग में सादे बुलेट के रूप में संरक्षित करें। ये
  बुलेट ट्रैक किए गए कार्य प्रगति के बाहर संदर्भ जानकारी हैं।
- प्रत्येक कार्य MUST बताए कि पूर्णता को कैसे सत्यापित करना है (एक परीक्षण, कमांड,
  अवलोकनीय व्यवहार, या वितरित आर्टिफ़ैक्ट)। सत्यापन को
  उस कार्य के चेकबॉक्स विवरण में रखें। अलग सत्यापन कार्य केवल तब उपयोग करें
  जब यह व्यापक एकीकरण या सिस्टम व्यवहार की जाँच करता हो जो
  कई कार्यान्वयन कार्यों में फैला हो।
- प्रत्येक कार्य समूह MUST अपने स्वयं के कार्य के लिए आवश्यक परीक्षण और दस्तावेज़ीकरण
  शामिल करे। परीक्षण या दस्तावेज़ीकरण को अंतिम समूह में न एकत्र करें -
  जब कोई देर वाला समूह पहली बार किसी पुराने समूह के कार्य का उपयोग करता है, तो विफलताएँ
  बीच के प्रत्येक समूह से पीछे की ओर फैलती हैं और पुनःकार्य करने को मजबूर करती हैं। जिस समूह के कार्य के लिए
  इनमें से कोई भी आवश्यक नहीं है, जैसे स्कैफोल्डिंग या निर्भरता सेटअप,
  उसमें भी इनमें से कोई नहीं होता। अंतिम समूह केवल एकीकरण जाँच के लिए है, न कि
  उन परीक्षणों और दस्तावेज़ों के लिए जो किसी पहले के समूह को देने थे।

उदाहरण:
```
# कार्य

## 1. सेटअप

- [ ] 1.1 नई मॉड्यूल संरचना बनाएँ और सत्यापित करें कि अपेक्षित फ़ाइलें मौजूद हैं
- [ ] 1.2 package.json में निर्भरताएँ जोड़ें और सत्यापित करें कि पैकेज इंस्टॉलेशन सफल होता है

## 2. मुख्य कार्यान्वयन

- [ ] 2.1 डेटा निर्यात फ़ंक्शन लागू करें और सत्यापित करें कि निर्यात परीक्षण पास होता है
- [ ] 2.2 CSV फ़ॉर्मेटिंग यूटिलिटीज़ जोड़ें और सत्यापित करें कि यूनिट परीक्षण कोटिंग और डेलिमिटर्स को कवर करते हैं
- [ ] 2.3 docs/export.md में निर्यात API का दस्तावेज़ीकरण करें और सत्यापित करें कि दस्तावेज़ीकृत कमांड लिखे अनुसार चलता है
```

जब लागू हो, तो वर्कफ़्लो फ़ॉलो-अप को सादे बुलेट के रूप में जोड़ें, उदाहरण के लिए:
```
## Workflow follow-up

- परियोजना की समीक्षा आवश्यकताओं के पूरा होने के बाद परिवर्तन को आर्काइव करें।
- आर्काइव किए गए परिणाम को सत्यापित करें।
```

क्या बनाना है इसके लिए स्पेक्स का और इसे कैसे बनाना है इसके लिए डिज़ाइन का संदर्भ दें।

Apply

Apply योजना से कार्यान्वयन तक का हैंडऑफ़ है। Apply वह चरण है जो tasks.md पर काम करता है, न कि कोई आर्टिफ़ैक्ट।

• प्रारंभ: जब tasks.md मौजूद हो और उसमें कम से कम एक कार्य सूचीबद्ध हो।
• ट्रैक करता है: tasks.md में चेकबॉक्स। उन्हें चिह्नित करना प्रगति रिकॉर्ड है।
• समाप्ति: हर चेकबॉक्स चिह्नित। OpenSpec फिर परिवर्तन को आर्काइव करने का सुझाव देता है।

सेटिंग्स

apply की सेटिंग्स (schema.yaml):

apply:
  requires: [tasks]
  tracks: tasks.md
  # निर्देश: नीचे दिखाया गया है

निर्देश

कार्यान्वयन शुरू होने पर एजेंट को भेजा गया निर्देश (schema.yaml):

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

schema.yaml

पूर्ण schema.yaml, जिसमें निर्देशों के मुख्य भाग छोड़ दिए गए हैं। प्रत्येक को ऊपर उसके अनुभाग में पूर्ण रूप में दिखाया गया है।

name: spec-driven
version: 1
description: Default OpenSpec workflow - proposal → specs → design → tasks
artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document outlining the change
    template: proposal.md
    # निर्देश: ऊपर proposal.md के अंतर्गत पूर्ण रूप में दिखाया गया है
    requires: []

  - id: specs
    generates: "specs/**/*.md"
    description: Detailed specifications for the change
    template: spec.md
    # निर्देश: ऊपर Delta specs के अंतर्गत पूर्ण रूप में दिखाया गया है
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Technical design document with implementation details
    template: design.md
    # निर्देश: ऊपर design.md के अंतर्गत पूर्ण रूप में दिखाया गया है
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Implementation checklist with trackable tasks
    template: tasks.md
    # निर्देश: ऊपर tasks.md के अंतर्गत पूर्ण रूप में दिखाया गया है
    requires:
      - specs
      - design

apply:
  requires: [tasks]
  tracks: tasks.md
  # निर्देश: ऊपर Apply के अंतर्गत पूर्ण रूप में दिखाया गया है