वर्कफ़्लो

यह गाइड OpenSpec के लिए सामान्य वर्कफ़्लो पैटर्न और प्रत्येक का उपयोग कब करना है, इस पर प्रकाश डालती है। बेसिक सेटअप के लिए, Getting Started देखें। कमांड रीफ़रेंस के लिए, Commands देखें。

दर्शन: एक्शन, फेज़ नहीं

पारंपरिक वर्कफ़्लो आपको फेज़ों के माध्यम से ले जाते हैं: प्लानिंग, फिर इम्प्लीमेंटेशन, फिर पूरा। लेकिन वास्तविक काम साफ़-सुथरे बॉक्स में नहीं बैठता।

OPSX एक अलग दृष्टिकोण अपनाता है:

Traditional (phase-locked):

  PLANNING ────────► IMPLEMENTING ────────► DONE
      │                    │
      │   "Can't go back"  │
      └────────────────────┘

OPSX (fluid actions):

  proposal ──► specs ──► design ──► tasks ──► implement

मुख्य सिद्धांत:

• एक्शन, फेज़ नहीं - कमांड वे चीज़ें हैं जो आप कर सकते हैं, न कि वे स्टेज जिनमें आप फँसे रहते हैं
• डिपेंडेंसीज़ एनेबलर्स हैं - ये दिखाते हैं कि क्या संभव है, न कि अगला क्या आवश्यक है

कस्टमाइज़ेशन: OPSX वर्कफ़्लो स्कीमाज़ द्वारा संचालित होते हैं जो आर्टिफैक्ट अनुक्रमों को परिभाषित करते हैं। कस्टम स्कीमा बनाने की विस्तृत जानकारी के लिए Customization देखें।

कार्यप्रवाह: एक नज़र में

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

flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

एआई सहायक कार्यप्रवाह को संचालित करता है, जबकि सीएलआई नियतात्मक खाका, स्थिति और कृति निर्देश प्रदान करता है:

sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

दो मोड

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

नई स्थापनाएँ डिफ़ॉल्ट रूप से core प्रोफ़ाइल का उपयोग करती हैं, जो प्रदान करता है:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

सामान्य प्रवाह:

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

अन्वेषण से शुरू करें (एक आदत जो बनाने लायक है)

/opsx:explore डिफ़ॉल्ट प्रोफ़ाइल का हिस्सा है, कोई उन्नत ऐड-ऑन नहीं। जब भी आपके पास समस्या हो लेकिन योजना न हो, तब यही कदम उठाना है—और एआई सहायक के साथ, ऐसा अधिकतर होता है।

You: /opsx:explore

AI:  What would you like to explore?

You: Our search results feel stale. I'm not sure if it's caching,
     indexing, or the query itself.

AI:  Let me look... [reads the search service and cache layer]
     It's the index: it only rebuilds nightly, so edits don't show
     up until the next day. Two options: rebuild on write (simple,
     more load) or a short-TTL cache invalidation (more moving parts,
     less load). Given your write volume is low, rebuild-on-write is
     the cleaner fix. Want to scope it?

You: Yes.

You: /opsx:propose rebuild-search-index-on-write

अन्वेषण कोई कृति नहीं बनाता और कोई कोड नहीं लिखता। यह एक मुफ्त, बिना जोखिम की बातचीत है जो एक अस्पष्ट चिंता को एक सटीक बदलाव में बदल देती है, जिससे आगे का प्रस्ताव पैना होता है। पहले से ही ठीक-ठीक जानते हैं कि आपको क्या चाहिए? इसे छोड़ें और सीधे /opsx:propose पर जाएँ। पूर्ण गाइड: पहले अन्वेषण करें।

विस्तारित/पूर्ण कार्यप्रवाह (कस्टम चयन)

यदि आप स्पष्ट खाका-निर्माण और निर्माण कमांड चाहते हैं (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), तो इन्हें सक्षम करें:

openspec config profile
openspec update

कार्यप्रवाह पैटर्न (विस्तारित मोड)

त्वरित सुविधा

जब आप जानते हैं कि क्या बनाना है और बस निष्पादित करना है:

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

उदाहरण वार्तालाप:

You: /opsx:new add-logout-button

AI:  Created openspec/changes/add-logout-button/
     Ready to create: proposal

You: /opsx:ff

AI:  Creating all planning artifacts...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     Ready for implementation!

You: /opsx:apply

AI:  Working through tasks...
     ✓ Added logout button to header
     ✓ Implemented session clearing
     ✓ Added confirmation dialog
     All tasks complete!

You: /opsx:archive

AI:  ✓ Merged specs
     ✓ Archived change

के लिए सर्वोत्तम: छोटी से मध्यम सुविधाएँ, बग फिक्स, सीधे बदलाव।

अन्वेषणात्मक

जब आवश्यकताएँ अस्पष्ट हों या पहले जाँच-पड़ताल की ज़रूरत हो:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

उदाहरण वार्तालाप:

You: /opsx:explore

AI:  What would you like to explore?

You: I want to improve page load performance but I'm not sure
     where the bottlenecks are.

AI:  Let me help investigate...
     [Analyzes bundle sizes, identifies slow queries, reviews
     component render patterns]

     I found three main bottlenecks:
     1. Large unoptimized images
     2. Synchronous data fetching in ProductList
     3. Re-renders from context changes

     Which would you like to address first?

You: Let's tackle the data fetching issue.

You: /opsx:new optimize-product-list-fetching

AI:  Created change. Ready to create: proposal

You: /opsx:continue

AI:  Creating proposal based on our exploration...
     [Writes proposal incorporating investigation insights]

     Ready to create: specs, design
     Which would you like next?

You: /opsx:continue

AI:  Creating specs...

के लिए सर्वोत्तम: प्रदर्शन अनुकूलन, डिबगिंग, आर्किटेक्चर निर्णय, अस्पष्ट आवश्यकताएँ।

समानांतर बदलाव

एक साथ कई बदलावों पर काम करें:

Change A: /opsx:new ──► /opsx:ff ──► /opsx:apply (in progress)
                                         │
                                    context switch
                                         │
Change B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

उदाहरण वार्तालाप:

You: I'm working on add-dark-mode but got pulled into a bug fix

You: /opsx:new fix-login-redirect

AI:  Created openspec/changes/fix-login-redirect/

You: /opsx:ff

AI:  ✓ Created planning artifacts

You: /opsx:apply

AI:  Working on fix-login-redirect...
     [Implements the fix]
     All tasks complete!

You: /opsx:archive

AI:  ✓ Archived fix-login-redirect

You: Let's get back to dark mode

You: /opsx:apply add-dark-mode

AI:  Resuming add-dark-mode...
     Picking up at task 2.3: Update Header...

के लिए सर्वोत्तम: समानांतर कार्य धाराएँ, तत्काल व्यवधान, टीम सहयोग।

जब आपके पास कई पूर्ण बदलाव हों, तो /opsx:bulk-archive का उपयोग करें:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (all tasks done)
     - fix-login-redirect (all tasks done)
     - update-footer (all tasks done)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will apply in chronological order.

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-redirect
     ✓ Archived update-footer
     Specs merged in order: add-dark-mode → update-footer

बल्क आर्काइव यह पता लगाता है कि जब कई बदलाव एक ही विनिर्देशों को छूते हैं और यह जाँच कर विरोधों का समाधान करता है कि वास्तव में क्या कार्यान्वित है।

एक बदलाव को पूरा करना

अनुशंसित पूर्णता प्रवाह:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              validates          prompts to sync
              implementation     if needed

सत्यापन: अपना काम जाँचें

/opsx:verify तीन आयामों में आपकी कृतियों के विरुद्ध कार्यान्वयन को मान्य करता है:

You: /opsx:verify

AI:  Verifying add-auth...

     COMPLETENESS
     ✓ All 12 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "Session timeout after inactivity" not tested

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "event-driven" but implementation uses polling

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for session timeout scenario
     2. Consider refactoring to event-driven as designed, or update design.md

सत्यापन क्या जाँचता है:

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

सत्यापन आर्काइव को रोकता नहीं है, लेकिन यह उन मुद्दों को उजागर करता है जिन्हें आप पहले हल करना चाह सकते हैं।

आर्काइव: बदलाव को अंतिम रूप दें

/opsx:archive बदलाव को पूर्ण करता है और इसे संग्रह में ले जाता है:

You: /opsx:archive

AI:  Archiving add-auth...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (12/12 tasks complete)

     Delta specs: Not yet synced to main
     → Would you like to sync now?

You: Yes

AI:  ✓ Synced specs to openspec/specs/auth/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-auth/

     Change archived successfully.

यदि विनिर्देश सिंक नहीं हुए हैं तो आर्काइव संकेत देगा। यह अपूर्ण कार्यों पर नहीं रुकेगा, लेकिन चेतावनी देगा।

कब क्या उपयोग करें

/opsx:ff बनाम /opsx:continue

स्थिति	उपयोग करें
स्पष्ट आवश्यकताएँ, निर्माण के लिए तैयार	/opsx:ff
अन्वेषण कर रहे हैं, प्रत्येक चरण की समीक्षा करना चाहते हैं	/opsx:continue
विनिर्देशों से पहले प्रस्ताव पर पुनरावृति करना चाहते हैं	/opsx:continue
समय दबाव, तेज़ी से आगे बढ़ने की आवश्यकता	/opsx:ff
जटिल बदलाव, नियंत्रण चाहिए	/opsx:continue

मोटा नियम: यदि आप पूरा दायरा पहले से बता सकते हैं, तो /opsx:ff का उपयोग करें। यदि आप काम करते-करते इसे समझ रहे हैं, तो /opsx:continue का उपयोग करें।

कब अद्यतन करें बनाम कब नए सिरे से शुरू करें

एक सामान्य प्रश्न: किसी मौजूदा बदलाव को अद्यतन करना कब ठीक है, और कब आपको नया शुरू करना चाहिए?

मौजूदा बदलाव को अद्यतन करें जब:

• समान उद्देश्य, परिष्कृत कार्यान्वयन
• दायरा संकीर्ण हो (पहले MVP, बाकी बाद में)
• सीखने-आधारित सुधार (कोडबेस आपकी अपेक्षा के अनुरूप नहीं है)
• कार्यान्वयन के दौरान खोजों के आधार पर डिज़ाइन में बदलाव

नया बदलाव शुरू करें जब:

• उद्देश्य मूल रूप से बदल गया हो
• दायरा पूरी तरह से अलग कार्य में बदल गया हो
• मूल बदलाव को स्वतंत्र रूप से 'पूर्ण' चिह्नित किया जा सके
• पैच स्पष्ट करने से अधिक भ्रमित करें

                     ┌─────────────────────────────────────┐
                     │     Is this the same work?          │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          Same intent?      >50% overlap?      Can original
          Same problem?     Same scope?        be "done" without
                 │                  │          these changes?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    UPDATE            NEW  UPDATE       NEW  UPDATE          NEW

उदाहरण: "डार्क मोड जोड़ें"

• 'साथ ही कस्टम थीम का समर्थन करने की आवश्यकता है' → नया बदलाव (दायरा बढ़ गया)
• 'सिस्टम प्राथमिकता का पता लगाना उम्मीद से कठिन है' → अद्यतन (समान उद्देश्य)
• 'पहले टॉगल जारी करें, बाद में प्राथमिकताएँ जोड़ें' → पहले अद्यतन फिर आर्काइव, फिर नया बदलाव

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

बदलावों को केंद्रित रखें

प्रत्येक बदलाव में एक तार्किक कार्य इकाई। यदि आप "फीचर X जोड़ें और साथ ही Y का पुनर्निर्माण करें" कर रहे हैं, तो दो अलग-अलग बदलावों पर विचार करें।

यह क्यों महत्वपूर्ण है:

• समीक्षा और समझना आसान
• स्वच्छ अभिलेख इतिहास
• स्वतंत्र रूप से शिप कर सकते हैं
• आवश्यक होने पर सरल रोलबैक

अस्पष्ट आवश्यकताओं के लिए /opsx:explore का उपयोग करें

कोई भी बदलाव स्वीकार करने से पहले, समस्या क्षेत्र का अन्वेषण करें:

You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle rate limiting for our API?

AI:  Let me investigate your current setup and options...
     [Researches codebase, considers patterns]

     I see three approaches we could take:
     1. Middleware-based (simple, per-endpoint)
     2. Redis-backed (scalable, shared state)
     3. Token bucket per user (fair, complex)

     Your current stack suggests #1 or #2. What's your scale?

अन्वेषण से आर्टिफैक्ट्स बनाने से पहले सोच स्पष्ट होती है।

अभिलेखित करने से पहले सत्यापित करें

/opsx:verify का उपयोग करके जाँचें कि कार्यान्वयन आर्टिफैक्ट्स से मेल खाता है:

You: /opsx:verify

AI:  Verifying add-dark-mode...

     ✓ All tasks in tasks.md are checked
     ✓ Requirements in specs have corresponding code
     ✓ Design decisions are reflected in implementation

     Ready to archive!

बदलाव बंद करने से पहले असंगतताएँ पकड़ता है।

बदलावों को स्पष्ट रूप से नाम दें

अच्छे नाम openspec list को उपयोगी बनाते हैं:

Good:                          Avoid:
add-dark-mode                  feature-1
fix-login-redirect             update
optimize-product-query         changes
implement-2fa                  wip

कमांड त्वरित संदर्भ

पूर्ण कमांड विवरण और विकल्पों के लिए, देखें Commands।

Command	Purpose	When to Use
/opsx:propose	बदलाव + योजना आर्टिफैक्ट्स बनाएँ	तेज़ डिफ़ॉल्ट पथ (core प्रोफ़ाइल)
/opsx:explore	AI के साथ विचारों पर चिंतन करें	अनिश्चित होने पर यहाँ से शुरू करें: अस्पष्ट आवश्यकताएँ, जाँच, विकल्पों की तुलना
/opsx:new	बदलाव स्केलफ़ोर्ड शुरू करें	विस्तारित मोड, स्पष्ट आर्टिफैक्ट नियंत्रण
/opsx:continue	अगला आर्टिफैक्ट बनाएँ	विस्तारित मोड, चरण-दर-चरण आर्टिफैक्ट निर्माण
/opsx:ff	सभी योजना आर्टिफैक्ट्स बनाएँ	विस्तारित मोड, स्पष्ट दायरा
/opsx:apply	कार्य कार्यान्वित करें	कोड लिखने के लिए तैयार
/opsx:verify	कार्यान्वयन सत्यापित करें	विस्तारित मोड, अभिलेखित करने से पहले
/opsx:sync	डेल्टा स्पेक्स मर्ज करें	विस्तारित मोड, वैकल्पिक
/opsx:archive	बदलाव पूर्ण करें	सभी कार्य समाप्त
/opsx:bulk-archive	कई बदलाव अभिलेखित करें	विस्तारित मोड, समानांतर कार्य

अगले चरण

• Writing Good Specs - एक मजबूत आवश्यकता और परिदृश्य कैसा दिखता है, और बदलाव का आकार कैसे ठीक करें
• Reviewing a Change - किसी भी कोड से पहले ड्राफ्ट किए गए योजना पर दो मिनट की समीक्षा
• OpenSpec on a Team - बदलाव शाखाओं और पुल अनुरोधों में कैसे फिट होते हैं
• Commands - विकल्पों के साथ पूर्ण कमांड संदर्भ
• Concepts - स्पेक्स, आर्टिफैक्ट्स और स्कीमा में गहन अध्ययन
• Customization - कस्टम वर्कफ़्लो बनाएँ