आर्टिफ़ैक्ट स्कीमा विनिर्देश

सभी Apothem ईकोसिस्टम आर्टिफ़ैक्ट के लिए प्रति-वर्ग YAML frontmatter टेम्पलेट और आवश्यक फ़ील्ड।

सत्य का स्रोत। मशीन-पठनीय, गेट-प्रवर्तित अनुबंध src/apothem/schemas/ के अंतर्गत प्रति-वर्ग JSON स्कीमा हैं (agent.schema.json, command.schema.json, skill.schema.json, …)। स्किल और कमांड स्कीमा additionalProperties: false घोषित करते हैं, इसलिए वे अज्ञात कुंजियों को अस्वीकार करते हैं; एजेंट, आउटपुट-स्टाइल और प्लान स्कीमा additionalProperties: true घोषित करते हैं। यह पृष्ठ और frontmatter-schema.mdx उन स्कीमा के दो मानव-पठनीय प्रक्षेपण हैं — यह पृष्ठ प्रति-वर्ग टेम्पलेट और हल किए गए उदाहरण वहन करता है, जबकि frontmatter-schema संक्षिप्त आवश्यक-कुंजी अनुक्रमणिका है। जहाँ कोई पृष्ठ JSON स्कीमा से असहमत हो, वहाँ स्कीमा ही मान्य होते हैं।

अवलोकनCopy Anchor Link

Apothem स्रोत वृक्ष के सभी आर्टिफ़ैक्ट (src/apothem/ और मूल कॉन्फ़िगरेशन सतह के अंतर्गत) में उनके आर्टिफ़ैक्ट प्रकार के लिए विशिष्ट अनिवार्य और वैकल्पिक फ़ील्ड वाला एक YAML frontmatter ब्लॉक (--- सीमांककों के बीच) होना ही चाहिए। यह दस्तावेज़ प्रत्येक प्रकार के लिए कैनोनिकल स्कीमा परिभाषित करता है।

सार्वभौमिक नियम:

• frontmatter YAML 1.2 के अनुरूप है
• सभी स्ट्रिंग मान दोहरे उद्धरण चिह्नों का उपयोग करते हैं, और खाली स्ट्रिंग "" के रूप में लिखी जाती है
• फ़ील्ड क्रम: पहले अनिवार्य फ़ील्ड, फिर प्रासंगिकता के अनुसार समूहित वैकल्पिक फ़ील्ड
• frontmatter में टिप्पणियाँ स्पेस के साथ # का उपयोग करती हैं: # comment
• पथ मान सापेक्ष होने चाहिए (कोई अग्रणी / नहीं) और क्रॉस-प्लेटफ़ॉर्म संगतता के लिए फ़ॉरवर्ड स्लैश (/) का उपयोग करने चाहिए

संस्करण परिपाटी (संस्करण-युक्त आर्टिफ़ैक्ट वर्ग — कमांड, सहायक, स्किल, CLAUDE.md):

• version सिमेंटिक है (MAJOR.MINOR.PATCH)। ब्रेकिंग स्कीमा या अनुबंध परिवर्तनों के लिए MAJOR बढ़ाएँ; योगात्मक, गैर-ब्रेकिंग परिवर्तनों (नए वैकल्पिक फ़ील्ड, अतिरिक्त खंड, अतिरिक्त एंटी-पैटर्न) के लिए MINOR; और किसी मौजूदा निर्देश को सुधारने वाले, अनुबंध को तोड़े बिना किए गए व्यवहार-संबंधी परिवर्तन के लिए PATCH।
• टाइपो सुधार, लिंक सुधार, फ़ॉर्मेटिंग, और केवल-टिप्पणी या केवल-दस्तावेज़ संपादन version को अपरिवर्तित छोड़ते हैं। केवल व्यवहार-संबंधी परिवर्तन ही उसे बढ़ाता है।
• updated सबसे हाल के संपादन की ISO 8601 तिथि (YYYY-MM-DD) है। इसे हर version वृद्धि के साथ बदलना ही चाहिए, और संस्करण न बढ़ाने वाले टाइपो या लिंक सुधार पर भी यह बदलता है।
• नए आर्टिफ़ैक्ट v0.Y.Z पर आरंभ होते हैं। vX.Y.Z पर पदोन्नति इंगित करती है कि आर्टिफ़ैक्ट का अनुबंध सार्वजनिक प्रतिबद्धता बनने लायक पर्याप्त स्थिर है।
• प्लान सूट इस परिपाटी से बाहर हैं। प्लान सूट में टाइपो सुधार सूट के संस्करण की PATCH संख्या बढ़ाता है (vX.Y.Z से vX.Y.(Z+1)) और Revision History पंक्ति जोड़ता है। डेवलपर गाइड प्लान-सूट संशोधन खंड में प्लान-सूट नियम का वर्णन करती है।

स्कीमा: नियमCopy Anchor Link

पथ पैटर्न: src/apothem/rules/*.md

उद्देश्य: व्यवहारगत अधिदेश और परिचालन निर्देश।

अनिवार्य फ़ील्डCopy Anchor Link

---
name: "kebab-case-identifier"
description: "One-line description"
pathFilter: "**/*.py, **/*.toml"
alwaysApply: true | false
---

वैकल्पिक फ़ील्डCopy Anchor Link

नियमों में कोई वैकल्पिक frontmatter फ़ील्ड नहीं होता, और — अन्य आर्टिफ़ैक्ट वर्गों के विपरीत — कोई version / updated / scope / portability फ़ील्ड भी नहीं होता। ऊपर के चार अनिवार्य फ़ील्ड ही frontmatter_grep द्वारा लागू किया जाने वाला पूर्ण नियम frontmatter अनुबंध हैं।

उदाहरणCopy Anchor Link

---
name: "operational-mandates"
description: "Behavioral definitions for CM-1 through CM-10: violation indicators and recovery actions"
pathFilter: ""
alwaysApply: true
---

# Rule: Operational Mandates
...

स्कीमा: कमांडCopy Anchor Link

पथ पैटर्न: src/apothem/commands/*.md

उद्देश्य: स्लैश कमांड परिभाषाएँ (/plan-execute, /freshify, आदि)।

अनिवार्य फ़ील्डCopy Anchor Link

---
name: "command-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this command does"
argument-hint: "[argument-pattern]"
disable-model-invocation: true | false
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

वैकल्पिक फ़ील्डCopy Anchor Link

कमांड में कोई वैकल्पिक frontmatter फ़ील्ड नहीं होता — ऊपर के आठ अनिवार्य फ़ील्ड ही command.schema.json (additionalProperties: false) द्वारा लागू किया जाने वाला पूर्ण कमांड frontmatter अनुबंध हैं।

उदाहरणCopy Anchor Link

---
name: "plan-execute"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Executes a specific phase from a Master Plan Suite with conformity checking and quality gates"
argument-hint: "[path/to/plan-suite/] [phase-id] [--dry-run]"
disable-model-invocation: true
portability: "universal"
allowed-tools: "Read, Glob, Grep"
---

# /plan-execute — Execute a Specific Phase
...

स्कीमा: सहायकCopy Anchor Link

पथ पैटर्न:

src/apothem/agents/*.md

उद्देश्य: समानांतर अन्वेषण, ऑडिटिंग, और गुणवत्ता गेटों के लिए स्थायी सहायक परिभाषाएँ (जिन्हें प्रत्यायोजित कार्यकर्ता भी कहा जाता है)।

अनिवार्य फ़ील्डCopy Anchor Link

---
name: "agent-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this agent specializes in"
tools: "Tool1, Tool2, Tool3"
disallowedTools: "Write, Edit"
maxTurns: 20
effort: "high" | "medium" | "low"
---

वैकल्पिक फ़ील्डCopy Anchor Link

permissionMode: "default"       # Permission handling
memory: user | project | local  # Persistent-memory scope; omit for none
pattern: "Research" | "Audit" | "Implementation" | "Quality"  # Agent team pattern
portability: "universal"

उदाहरणCopy Anchor Link

---
name: "codebase-explorer"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Deep codebase exploration — find patterns, trace dependencies, discover conventions, map architecture"
tools: "Read, Glob, Grep, Bash"
disallowedTools: "Write, Edit, TodoWrite"
maxTurns: 20
effort: "high"
permissionMode: "default"
portability: "universal"
---

You are a codebase exploration specialist...

स्कीमा: स्किलCopy Anchor Link

पथ पैटर्न: src/apothem/skills/*/SKILL.md

उद्देश्य: पहचान संकेतों और निष्पादन प्रक्रियाओं के साथ पुन: प्रयोज्य तकनीक परिभाषाएँ।

अनिवार्य फ़ील्डCopy Anchor Link

---
name: "skill-name"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "What this skill teaches"
archetype: "workflow-template"
userInvocable: true | false
disable-model-invocation: true | false
allowed-tools: "Read, Glob, Grep"
---

वैकल्पिक फ़ील्डCopy Anchor Link

argument-hint: "[args...]"                           # Usage pattern if userInvocable

उदाहरणCopy Anchor Link

---
name: "ecosystem-audit"
version: "X.Y.Z"
updated: "2026-04-20"
description: "Comprehensive blind audit of the apothem ecosystem"
archetype: "audit-template"
userInvocable: true
disable-model-invocation: false
allowed-tools: "Read, Glob, Grep, Agent, TodoWrite"
argument-hint: "[--focus area] [--fix]"
---

## Purpose
...

स्कीमा: हुकCopy Anchor Link

पथ पैटर्न: settings.json का hooks ब्लॉक, साथ ही src/apothem/hooks/ के अंतर्गत Python कार्यान्वयन।

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

सेटिंग्स-फ़ाइल स्कीमाCopy Anchor Link

hooks शीर्ष-स्तरीय कुंजी इवेंट नामों को मैचर ब्लॉकों की सरणियों से मैप करती है:

"hooks": {
  "<EventName>": [
    {
      "matcher": "<pattern>",
      "hooks": [
        {
          "type": "command",
          "command": "${PYTHON_BIN}",
          "args": ["${HARNESS_ROOT}/.apothem/support/hooks/dispatch.py", "<EventName>", "<message-name>"],
          "timeout": <seconds>,
          "statusMessage": "<short human-readable label>"
        }
      ]
    }
  ]
}

-m apothem.hooks.dispatch रूप उस स्रोत चेकआउट से विकास के लिए है जिसमें PYTHONPATH=src हो।

आवश्यक इवेंटCopy Anchor Link

Claude Code टेम्पलेट चार इवेंट पंजीकृत करता है: SessionStart, PreToolUse, PostToolUse और Stop। scripts/dev/validate_hooks.py settings.json में नीचे की तालिका के पाँच इवेंटों की जाँच करता है, जो एक भिन्न समूह है, और जिस भी इवेंट को वह नहीं पाता उसे विफलता के रूप में नहीं, बल्कि चेतावनी के रूप में रिपोर्ट करता है। PostToolUse पंजीकृत है, किंतु इन पाँच में से एक नहीं है। PreCompact और PostCompact उन पाँच में शामिल हैं, किंतु Claude Code पर पंजीकृत नहीं हैं (हुक संदर्भ), इसलिए वहाँ चेकर दोनों के बारे में चेतावनी देता है।

टाइमआउट मान कैनोनिकल हुक-इवेंट बजट को प्रतिबिंबित करते हैं — नीचे दी गई तालिका उन्हें पाठक की सुविधा के लिए दोहराती है; कैनोनिकल स्रोत ही निर्णायक है।

dispatch.py अग्रगामी संगतता के लिए अपनी इवेंट श्वेतसूची पर UserPromptSubmit और Notification को भी स्वीकार करता है; शिप किए गए टेम्पलेट में इनमें से कोई भी जुड़ा हुआ नहीं है। सक्षम करने के लिए उसी exec-form पैटर्न वाला एक मैचर ब्लॉक जोड़ें।

Python परतCopy Anchor Link

हर हुक कमांड एक ही Python डिस्पैचर से होकर गुज़रता है:

सत्यापनCopy Anchor Link

scripts/dev/validate_hooks.py हुक अनुबंध लागू करता है:

• settings.json JSON के रूप में पार्स होता है और तालिका के पाँचों इवेंटों में से प्रत्येक को घोषित करता है; कोई इवेंट गायब हो तो वह विफलता नहीं, चेतावनी है।
• तीनों Python स्क्रिप्ट मौजूद हैं और वैध Python के रूप में पार्स होती हैं।
• --context-file आर्ग्युमेंट द्वारा संदर्भित सभी संदेश फ़ाइलें मौजूद हैं।
• src/apothem/hooks/**.py में कोई हार्डकोडेड निरपेक्ष उपयोगकर्ता पथ (C:\Users\... आदि) नहीं दिखता।
• src/apothem/hooks/ और scripts/ के अंतर्गत शेल आर्टिफ़ैक्ट अनुमोदित लोकेटर / बूटस्ट्रैप स्टब तक सीमित हैं।

स्कीमा: CLAUDE.mdCopy Anchor Link

पथ: CLAUDE.md (रूट)

उद्देश्य: परियोजना-दायरे वाले Claude Code निर्देश।

अनिवार्य YAML frontmatterCopy Anchor Link

---
name: "CLAUDE"
version: "MAJOR.MINOR.PATCH"
updated: "YYYY-MM-DD"
description: "Project-scoped Claude Code instructions for the Apothem source repository"
scope: "project"
portability: "project-local"
---

अनुभागCopy Anchor Link

CLAUDE.md गद्य अनुभागों में लिखा जाता है, जिनका वर्णन CLAUDE.md पर है। कोई भी वैलिडेटर निश्चित अनुभाग-सूची की माँग नहीं करता: scripts/dev/validate_ecosystem.py ऊपर की frontmatter कुंजियों की जाँच करता है।

सत्यापन चेकलिस्टCopy Anchor Link

हर आर्टिफ़ैक्ट को इन जाँचों को पूरा करना ही चाहिए:

frontmatter सत्यापनCopy Anchor Link

• YAML वाक्यविन्यास की दृष्टि से वैध है (कोई पार्सिंग त्रुटि नहीं)
• आर्टिफ़ैक्ट प्रकार के सभी अनिवार्य फ़ील्ड मौजूद हैं
• name kebab-case परिपाटी का पालन करता है
• version सिमेंटिक है (MAJOR.MINOR.PATCH)
• updated ISO 8601 तिथि प्रारूप (YYYY-MM-DD) में है
• description एक गैर-खाली, एकल-पंक्ति स्ट्रिंग है
• वैकल्पिक फ़ील्ड अपेक्षित enum मानों से मेल खाते हैं (यदि लागू हो)
• फ़ील्ड नामों में कोई टाइपो नहीं (स्कीमा से कैनोनिकल नामों का उपयोग करें)
• कोई अतिरिक्त व्हाइटस्पेस या स्वरूपण समस्या नहीं

सामग्री सत्यापनCopy Anchor Link

• सामग्री समापन --- के बाद नई पंक्ति पर शुरू होती है; Markdown-परिवार की फ़ाइलों में उसके बाद की पहली सामग्री कैनोनिकल SPDX हेडर पंक्ति होती है
• कोई प्लान-आंतरिक संदर्भ नहीं (CM-7 अनुपालन)
• क्रॉस-संदर्भ हल होते हैं (यदि अन्य आर्टिफ़ैक्ट सूचीबद्ध हों)
• लिंक फ़ॉरवर्ड स्लैश वाले सापेक्ष पथों का उपयोग करते हैं

पोर्टेबिलिटी सत्यापनCopy Anchor Link

• कोई हार्डकोडेड निरपेक्ष पथ नहीं (सापेक्ष पथ का उपयोग करें)
• सार्वभौमिक-दायरे वाले आर्टिफ़ैक्ट में कोई Windows-विशिष्ट सिंटैक्स नहीं
• पथ विभाजक फ़ॉरवर्ड स्लैश का उपयोग करते हैं
• एनवायरनमेंट वेरिएबल प्लेटफ़ॉर्म-अज्ञेय प्रारूप (${VAR} या टूल-नेटिव) का उपयोग करते हैं

टिप्पणियाँCopy Anchor Link

• सुरक्षा के रूप में संगति: कैनोनिकल frontmatter स्वचालित सत्यापन, टूलिंग, और क्रॉस-आर्टिफ़ैक्ट सत्यापन को संभव बनाता है। विचलन जल्दी ही एक-दूसरे पर जुड़ते जाते हैं।
• पोर्टेबिलिटी घोषणा: सभी आर्टिफ़ैक्ट सार्वभौमिक नहीं हो सकते। बाधाओं को स्पष्ट रूप से घोषित करें — मौन बग शिप करने से बेहतर है किसी चेतावनी को दस्तावेज़ित करना।
• नामों के लिए kebab-case: URL, स्क्रिप्ट, और कमांड-लाइन संदर्भों में उपयोग करने में आसान। नामों के लिए स्पेस, अंडरस्कोर, और camelCase से बचें।
• संस्करण-वृद्धि अनुशासन: हर व्यवहार बदलने वाले संपादन को version और updated दोनों एक साथ बढ़ाने ही चाहिए। टाइपो सुधार, लिंक सुधार और फ़ॉर्मेटिंग परिवर्तन संस्करण को अपरिवर्तित छोड़ते हैं; नए वैकल्पिक अनुभाग या एंटी-पैटर्न MINOR बढ़ाते हैं; संरचनात्मक पुनर्गठन या अनुबंध परिवर्तन MAJOR बढ़ाते हैं।