अनुकूलन

OpenSpec अनुकूलन के तीन स्तर प्रदान करता है:

स्तर	यह क्या करता है	सबसे उपयुक्त
परियोजना कॉन्फ़िगरेशन	डिफ़ॉल्ट सेट करें, संदर्भ/नियम इंजेक्ट करें	अधिकांश टीमें
कस्टम स्कीमा	अपनी स्वयं की कार्यप्रवाह कलाकृतियाँ परिभाषित करें	अनूठी प्रक्रियाओं वाली टीमें
वैश्विक ओवरराइड	सभी परियोजनाओं में स्कीमा साझा करें	पावर उपयोगकर्ता

---

परियोजना कॉन्फ़िगरेशन

openspec/config.yaml फ़ाइल OpenSpec को अपनी टीम के लिए अनुकूलित करने का सबसे आसान तरीका है। यह आपको यह करने देता है:

• डिफ़ॉल्ट स्कीमा सेट करें - हर कमांड में --schema छोड़ें
• परियोजना संदर्भ इंजेक्ट करें - AI आपकी तकनीकी स्टैक, परंपराओं आदि को देखता है
• प्रति-कलाकृति नियम जोड़ें - विशिष्ट कलाकृतियों के लिए कस्टम नियम
• प्रति-संचालन मार्गदर्शन जोड़ें - apply और archive कार्य के लिए सलाहकार वरीयताएँ
• एकीकरण विकल्पों को याद रखें - जैसे GitHub Copilot क्लाउड कोडिंग एजेंट का ऑप्ट-इन

त्वरित सेटअप

openspec init

यह आपको इंटरैक्टिव रूप से कॉन्फ़िग बनाने की प्रक्रिया में मार्गदर्शन करता है। या मैन्युअल रूप से एक बनाएं:

# openspec/config.yaml
schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js, PostgreSQL
  API style: RESTful, documented in docs/api.md
  Testing: Jest + React Testing Library
  We value backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan
    - Identify affected teams
  specs:
    - Use Given/When/Then format
    - Reference existing patterns before inventing new ones

operations:
  apply:
    guidance:
      - Run focused tests before the full suite
  archive:
    guidance:
      - Keep the completion summary concise

# `openspec init` द्वारा सेट किया जाता है जब आप GitHub Copilot चुनते हैं (या अस्वीकार करते हैं)
# क्लाउड कोडिंग एजेंट; नियंत्रित करता है कि `init`/`update` इसकी फ़ाइलें उत्पन्न करते हैं या नहीं।
githubCopilot:
  cloudAgent: false

यह कैसे काम करता है

डिफ़ॉल्ट स्कीमा:

# कॉन्फ़िग के बिना
openspec new change my-feature --schema spec-driven

# कॉन्फ़िग के साथ - स्कीमा स्वचालित है
openspec new change my-feature

संदर्भ और नियम इंजेक्शन:

जब कोई कलाकृति उत्पन्न की जाती है, तो आपका संदर्भ और नियम AI प्रॉम्प्ट में इंजेक्ट किए जाते हैं:

<context>
Tech stack: TypeScript, React, Node.js, PostgreSQL
...
</context>

<rules>
- Include rollback plan
- Identify affected teams
</rules>

<template>
[Schema's built-in template]
</template>

• संदर्भ सभी कलाकृतियों में दिखाई देता है
• नियम केवल मिलान वाली कलाकृति के लिए दिखाई देते हैं

संचालन मार्गदर्शन:

operations.apply.guidance और operations.archive.guidance वैकल्पिक सरणियाँ हैं जो एक एजेंट को उन संचालनों का संचालन कैसे करना चाहिए, इसके लिए सलाहकार निर्देश प्रदान करती हैं। ये rules से अलग हैं: संचालन मार्गदर्शन कलाकृति सामग्री को सीमित नहीं करता है, और कलाकृति नियमों को कभी भी संचालन मार्गदर्शन के रूप में पुनः नामांकित नहीं किया जाता है।

Apply और archive निष्पादन के समय ये इनपुट लाते हैं:

openspec instructions apply --change my-feature --json
openspec instructions archive --change my-feature --json

दोनों सतहें अलग-अलग वैकल्पिक फ़ील्ड के रूप में वर्तमान परियोजना context और मिलान operationGuidance लौटाती हैं। प्रत्येक आह्वान समाधित मूल से एक ताज़ा स्नैपशॉट पढ़ता है। जब --store <id> चुना जाता है, तो परिवर्तन, संदर्भ और मार्गदर्शन सभी उस स्टोर से आते हैं, न कि वर्तमान रिपॉजिटरी से। Archive निर्देश आदेश केवल पढ़ने के लिए है: यह डेल्टा स्पेक्स का निरीक्षण या मर्ज नहीं करता है, मुख्य स्पेक्स नहीं लिखता है, परिवर्तन को स्थानांतरित नहीं करता है, या स्थैतिक संग्रह कार्यप्रवाह नहीं चलाता है।

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

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

संग्रह और स्पेक-सिंक इनपुट सुरक्षा:

संग्रह, बल्क संग्रह और स्टैंडअलोन सिंक openspec status --json से artifactPaths.specs.existingOutputPaths का उपयोग केवल डेल्टा-स्पेक स्रोत के रूप में करते हैं। बिना specs कलाकृति वाली स्कीमा, या जिस परिवर्तन की ठोस आउटपुट सूची खाली है, के पास सिंक करने के लिए कुछ नहीं है; अन्य कलाकृतियों का उपयोग डेल्टा स्पेक्स का अनुमान लगाने के लिए नहीं किया जाता है।

सिमैंटिक मर्ज द्वारा मुख्य स्पेक लिखने से पहले, कार्यप्रवाह वर्तमान openspec instructions specs --change <name> --json आउटपुट का उपभोग करता है। लौटाए गए specs नियम केवल उस मर्ज द्वारा उत्पादित मुख्य स्पेक्स को सीमित करते हैं। एकल संग्रह उस स्नैपशॉट को इनलाइन सिंक में पास करता है, स्टैंडअलोन सिंक इसे सीधे प्राप्त करता है, और बल्क संग्रह अपने पहले स्पेक लेखन से पहले हर आवश्यक स्नैपशॉट प्राप्त करता है। एक गैर-शून्य या अमान्य JSON archive/specs निर्देश प्रतिक्रिया एक लुकअप विफलता है, खाली इनपुट नहीं: कार्यप्रवाह प्रभावित स्पेक लेखन या परिवर्तन स्थानांतरण से पहले रुक जाता है (बल्क संग्रह के लिए, किसी भी बैच लेखन या स्थानांतरण से पहले)।

यह कॉन्फ़िगरेशन संग्रह निष्पादन चरणों, उपयोगकर्ता संकेतों, फ़ाइल सिस्टम संचालन, सिमैंटिक मर्ज स्वामित्व, प्रत्यक्ष openspec archive कमांड, या कलाकृति rules की संरचना और आउटपुट को नहीं बदलता है।

स्कीमा समाधान क्रम

जब OpenSpec को एक स्कीमा की आवश्यकता होती है, तो यह इस क्रम में जाँच करता है:

1. CLI फ़्लैग: --schema <name>
2. परिवर्तन मेटाडेटा (परिवर्तन फ़ोल्डर में .openspec.yaml)
3. परियोजना कॉन्फ़िग (openspec/config.yaml)
4. डिफ़ॉल्ट (spec-driven)

---

Custom Schemas

जब प्रोजेक्ट कॉन्फ़िग पर्याप्त न हो, तो एक पूरी तरह कस्टम वर्कफ़्लो के साथ अपना स्कीमा बनाएं। कस्टम स्कीमा आपके प्रोजेक्ट के openspec/schemas/ डायरेक्टरी में रहते हैं और आपके कोड के साथ version-controlled होते हैं।

your-project/
├── openspec/
│   ├── config.yaml        # Project config
│   ├── schemas/           # Custom schemas live here
│   │   └── my-workflow/
│   │       ├── schema.yaml
│   │       └── templates/
│   └── changes/           # Your changes
└── src/

Fork an Existing Schema

कस्टमाइज़ करने का सबसे तेज़ तरीका किसी built-in स्कीमा का fork लेना है:

openspec schema fork spec-driven my-workflow

यह पूरा spec-driven स्कीमा openspec/schemas/my-workflow/ में कॉपी करता है जहाँ आप इसे मुफ़्त में एडिट कर सकते हैं।

आपको क्या मिलता है:

openspec/schemas/my-workflow/
├── schema.yaml           # Workflow definition
└── templates/
    ├── proposal.md       # Template for proposal artifact
    ├── spec.md           # Template for specs
    ├── design.md         # Template for design
    └── tasks.md          # Template for tasks

अब वर्कफ़्लो बदलने के लिए schema.yaml एडिट करें, या AI द्वारा जनरेट किए जाने वाले आउटपुट बदलने के लिए templates एडिट करें。

Create a Schema from Scratch

एक बिल्कुल नए वर्कफ़्लो के लिए:

# Interactive
openspec schema init research-first

# Non-interactive
openspec schema init rapid \
  --description "Rapid iteration workflow" \
  --artifacts "proposal,tasks" \
  --default

Schema Structure

एक स्कीमा आपके वर्कफ़्लो में artifacts की परिभाषा करता है और वे एक-दूसरे पर कैसे निर्भर करते हैं:

# openspec/schemas/my-workflow/schema.yaml
name: my-workflow
version: 1
description: My team's custom workflow

artifacts:
  - id: proposal
    generates: proposal.md
    description: Initial proposal document
    template: proposal.md
    instruction: |
      Create a proposal that explains WHY this change is needed.
      Focus on the problem, not the solution.
    requires: []

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    instruction: |
      Create a design document explaining HOW to implement.
    requires:
      - proposal    # Can't create design until proposal exists

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

मुख्य fields:

Field	Purpose
id	Unique identifier, commands और rules में उपयोग होता है
generates	Output filename (globs जैसे specs/**/*.md सपोर्ट करता है)
template	templates/ डायरेक्टरी में template file
instruction	इस artifact बनाने के लिए AI instructions
requires	Dependencies - कौन से artifacts पहले मौजूद होने चाहिए

Artifacts को उस क्रम में लिस्ट करें जिसमें आप उन्हें लिखा जाना चाहते हैं। requires तय करता है कि क्या संभव है; artifacts: list का क्रम तय करता है कि जब कई artifacts एक साथ ready हों तो कौन पहले आएगा।

Templates

Templates वे markdown files हैं जो AI को मार्गदर्शन देती हैं। जब उस artifact को बनाने के समय वे prompt में inject की जाती हैं।

<!-- templates/proposal.md -->
## Why

<!-- Explain the motivation for this change. What problem does this solve? -->

## What Changes

<!-- Describe what will change. Be specific about new capabilities or modifications. -->

## Impact

<!-- Affected code, APIs, dependencies, systems -->

Templates में ये शामिल हो सकते हैं:

• Section headers जो AI को भरने चाहिए
• AI के मार्गदर्शन के लिए HTML comments
• Expected structure दिखाते हुए example formats

Validate Your Schema

कस्टम स्कीमा उपयोग करने से पहले उसे validate करें:

openspec schema validate my-workflow

यह जाँच करता है:

• schema.yaml syntax सही है
• सभी referenced templates मौजूद हैं
• कोई circular dependencies नहीं हैं
• Artifact IDs वैध हैं

Use Your Custom Schema

बनने के बाद, अपने स्कीमा का उपयोग इस प्रकार करें:

# Specify on command
openspec new change feature --schema my-workflow

# Or set as default in config.yaml
schema: my-workflow

Debug Schema Resolution

पता नहीं कौन सा स्कीमा उपयोग हो रहा है? इससे जाँच करें:

# See where a specific schema resolves from
openspec schema which my-workflow

# List all available schemas
openspec schema which --all

Output दिखाता है कि यह आपके प्रोजेक्ट से, user directory से, या package से आ रहा है:

Schema: my-workflow
Source: project
Path: /path/to/project/openspec/schemas/my-workflow

---

Note: OpenSpec user-level schemas भी सपोर्ट करता है ~/.local/share/openspec/schemas/ पर, जो projects के बीच शेयर करने के लिए उपयोगी हैं, लेकिन project-level schemas openspec/schemas/ में अनुशंसित हैं क्योंकि वे आपके कोड के साथ version-controlled होते हैं।

---

Examples

Rapid Iteration Workflow

तेज़ iterations के लिए एक minimal वर्कफ़्लो:

# openspec/schemas/rapid/schema.yaml
name: rapid
version: 1
description: Fast iteration with minimal overhead

artifacts:
  - id: proposal
    generates: proposal.md
    description: Quick proposal
    template: proposal.md
    instruction: |
      Create a brief proposal for this change.
      Focus on what and why, skip detailed specs.
    requires: []

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires: [proposal]

apply:
  requires: [tasks]
  tracks: tasks.md

Adding a Review Artifact

Default का fork लें और एक review step जोड़ें:

openspec schema fork spec-driven with-review

फिर schema.yaml एडिट करके ये जोड़ें:

  - id: review
    generates: review.md
    description: Pre-implementation review checklist
    template: review.md
    instruction: |
      Create a review checklist based on the design.
      Include security, performance, and testing considerations.
    requires:
      - design

  - id: tasks
    # ... existing tasks config ...
    requires:
      - specs
      - design
      - review    # Now tasks require review too

---

Community Schemas

OpenSpec community-maintained schemas भी सपोर्ट करता है जो standalone repositories के माध्यम से distributed होते हैं। ये opinionated वर्कफ़्लो प्रदान करते हैं जो OpenSpec को अन्य tools या systems के साथ integrate करते हैं, बिल्कुल वैसे ही जैसे github/spec-kit's community extension catalog spec-kit के लिए काम करता है।

Community schemas OpenSpec core में vendored नहीं होते — वे अपने-अपने repositories में अपने-अपने release cadence के साथ रहते हैं। इन्हें उपयोग करने के लिए, schema bundle को अपने प्रोजेक्ट के openspec/schemas/<schema-name>/ डायरेक्टरी में कॉपी करें (हर repo की README में install instructions हैं)।

Schema	Maintainer	Repository	Description
intent-driven	@harikrishnan83	intent-driven-dev/openspec-schemas	Implementation से पहले change intent, observable behaviour, technical design, और durable architectural decisions को capture करता है। Change-local ADR review manifest जोड़ता है और qualifying long-lived decisions को immutable, supersedable ADRs के रूप में लिखता है।
superpowers-bridge	@JiangWay	JiangWay/openspec-schemas	OpenSpec का artifact governance obra/superpowers execution skills (brainstorming, writing-plans, TDD via subagents, code review, finishing) के साथ integrate करता है。एक evidence-first retrospective artifact जोड़ता है जो Superpowers द्वारा नatively cover नहीं किए जाने वाले gap को भरता है।
nanopm	@nmrtn	nmrtn/nanopm	PM-first वर्कफ़्लो। Implementation के upstream nanopm की planning pipeline (audit → strategy → roadmap → PRD) चलाता है। Product planning को OpenSpec के spec-driven engineering वर्कफ़्लो से bridge करता है। Artifacts .nanopm/ से पढ़े जाते हैं यदि मौजूद हों — proposal audit से source करता है, design strategy से, और tasks PRD breakdown से।
e2e-runbooks	@Lukk17	Lukk17/openspec-schemas	Capability-level end-to-end test runbooks। हर capability को एक immutable spec, एक immutable tasks-template, और हर execution के लिए एक timestamped run record मिलता है। Assertions केवल observable behaviour होते हैं (HTTP status, response body, persisted state — कभी log substrings नहीं); हर run start/end UTC, duration, और best-estimate LLM token consumption record करता है।
anvil	@jikkujoyce	jikkujoyce/openspec-schemas	TDD discipline और adversarial review step के साथ spec-driven वर्कफ़्लो। Flow: proposal → specs → design → review → test-plan → tasks → apply → verify। review एक fresh-context, read-only reviewer द्वारा लिखा जाता है (जब उपलब्ध हो तो दूसरा model) और एक VERDICT: line emit करता है जो agent को test-plan, tasks, और apply को gate करने के लिए बताता है; OpenSpec केवल यह जाँच करता है कि artifacts मौजूद हैं, इसलिए gate को अपने CI या hook से enforce करें। test-plan हर spec scenario को एक named test से map करता है और एक red/green ledger के रूप में काम करता है जिसे verify audit करता है।

Community schema contribute करना चाहते हैं? अपने repository के link के साथ एक issue खोलें, या इस table में एक row जोड़ने के लिए PR submit करें।

---

See Also

• CLI Reference: Schema Commands - Full command documentation