Artefakt-Schema-Spezifikation

YAML-Frontmatter-Vorlagen pro Klasse und Pflichtfelder für alle Artefakte des Apothem-Ökosystems.

Maßgebliche Quelle. Der maschinenlesbare, vom Gate erzwungene Vertrag sind die JSON-Schemas pro Klasse unter src/apothem/schemas/ (agent.schema.json, command.schema.json, skill.schema.json, …). Die Schemas für Skills und Befehle deklarieren additionalProperties: false und lehnen daher unbekannte Schlüssel ab; die Schemas für Agenten, Output-Styles und Pläne deklarieren additionalProperties: true. Diese Seite und frontmatter-schema.mdx sind die beiden menschenlesbaren Projektionen dieser Schemas; diese Seite enthält die Vorlagen und ausgearbeiteten Beispiele pro Klasse, frontmatter-schema den knappen Index der Pflichtschlüssel. Widerspricht eine Seite den JSON-Schemas, haben die Schemas Vorrang.

ÜberblickCopy Anchor Link

Alle Artefakte im Apothem-Quellbaum (unter src/apothem/ und in der Konfigurationsoberfläche der Wurzel) müssen einen YAML-Frontmatter-Block (zwischen ----Trennzeichen) enthalten, mit Pflicht- und optionalen Feldern, die für ihren Artefakttyp spezifisch sind. Dieses Dokument definiert das kanonische Schema für jeden Typ.

Universelle Regeln:

• Das Frontmatter ist YAML-1.2-konform
• Alle Zeichenkettenwerte verwenden doppelte Anführungszeichen, und eine leere Zeichenkette wird als "" geschrieben
• Feldreihenfolge: Pflichtfelder zuerst, optionale Felder nach Relevanz gruppiert
• Kommentare im Frontmatter verwenden # mit Leerzeichen: # comment
• Pfadwerte müssen relativ sein (kein führender /) und für plattformübergreifende Kompatibilität Schrägstriche (/) verwenden

Versionierungskonvention (versionierte Artefaktklassen — Commands, Helfer, Skills, CLAUDE.md):

• version ist semantisch (MAJOR.MINOR.PATCH). Erhöhen Sie MAJOR bei inkompatiblen Schema- oder Vertragsänderungen; MINOR bei additiven, nicht inkompatiblen Änderungen (neue optionale Felder, zusätzliche Abschnitte, zusätzliche Antimuster); PATCH bei einer Verhaltensänderung, die eine bestehende Direktive korrigiert, ohne den Vertrag zu brechen.
• Tippfehlerkorrekturen, Linkkorrekturen, Formatierungen sowie reine Kommentar- oder Dokumentationsänderungen lassen version unverändert. Nur eine Verhaltensänderung erhöht sie.
• updated ist das ISO-8601-Datum (YYYY-MM-DD) der jüngsten Bearbeitung. Es muss sich bei jeder Erhöhung von version ändern und ändert sich auch bei einer Tippfehler- oder Linkkorrektur ohne Versionserhöhung.
• Neue Artefakte beginnen bei v0.Y.Z. Die Hochstufung auf vX.Y.Z zeigt an, dass der Vertrag des Artefakts stabil genug ist, um eine öffentliche Zusage zu sein.
• Plan-Suiten fallen nicht unter diese Konvention. Eine Tippfehlerkorrektur an einer Plan-Suite erhöht die PATCH-Nummer der Suite-Version (vX.Y.Z zu vX.Y.(Z+1)) und hängt eine Zeile an die Revisionshistorie an. Der Entwicklerleitfaden beschreibt die Plan-Suite-Regel in seinem Abschnitt zu Revisionen von Plan-Suiten.

Schema: RegelnCopy Anchor Link

Pfadmuster: src/apothem/rules/*.md

Zweck: Verhaltensmandate und operative Direktiven.

PflichtfelderCopy Anchor Link

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

Optionale FelderCopy Anchor Link

Regeln haben keine optionalen Frontmatter-Felder und — anders als andere Artefaktklassen — auch keine Felder version / updated / scope / portability. Die vier obigen Pflichtfelder sind der vollständige Frontmatter-Vertrag für Regeln, den frontmatter_grep erzwingt.

BeispielCopy 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
...

Schema: CommandsCopy Anchor Link

Pfadmuster: src/apothem/commands/*.md

Zweck: Definitionen von Slash-Commands (/plan-execute, /freshify usw.).

PflichtfelderCopy 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"
---

Optionale FelderCopy Anchor Link

Commands haben keine optionalen Frontmatter-Felder — die acht obigen Pflichtfelder sind der vollständige Frontmatter-Vertrag für Commands, den command.schema.json (additionalProperties: false) erzwingt.

BeispielCopy 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
...

Schema: HelferCopy Anchor Link

Pfadmuster:

src/apothem/agents/*.md

Zweck: Persistente Helfer-Definitionen (auch delegierte Worker genannt) für parallele Exploration, Audits und Qualitätstore.

PflichtfelderCopy 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"
---

Optionale FelderCopy 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"

BeispielCopy 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...

Schema: SkillsCopy Anchor Link

Pfadmuster: src/apothem/skills/*/SKILL.md

Zweck: Wiederverwendbare Technik-Definitionen mit Erkennungssignalen und Ausführungsprozeduren.

PflichtfelderCopy 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"
---

Optionale FelderCopy Anchor Link

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

BeispielCopy 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
...

Schema: HooksCopy Anchor Link

Pfadmuster: der hooks-Block in settings.json plus die Python-Implementierungen unter src/apothem/hooks/.

Zweck: Ereignisgesteuerte Validatoren und Handler für die Zustandsverwaltung deklarieren, die der Host an klar definierten Punkten des Lebenszyklus aufruft.

Schema der Settings-DateiCopy Anchor Link

Der Schlüssel hooks der obersten Ebene ordnet Ereignisnamen Arrays von Matcher-Blöcken zu:

"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>"
        }
      ]
    }
  ]
}

Die Form -m apothem.hooks.dispatch ist für die Entwicklung aus einem Quell-Checkout mit PYTHONPATH=src gedacht.

Erforderliche EreignisseCopy Anchor Link

Die Claude-Code-Vorlage registriert vier Ereignisse: SessionStart, PreToolUse, PostToolUse und Stop. scripts/dev/validate_hooks.py prüft settings.json auf die fünf Ereignisse in der Tabelle unten, eine andere Menge, und meldet jedes, das es nicht findet, als Warnung, nicht als Fehlschlag. PostToolUse ist registriert, gehört aber nicht zu den fünf. PreCompact und PostCompact gehören zu den fünf, sind aber für Claude Code nicht registriert (Hook-Referenz); der Prüfer warnt dort daher vor beiden.

Die Timeout-Werte spiegeln die kanonischen Budgets der Hook-Ereignisse wider — die Tabelle unten gibt sie zur Bequemlichkeit der Lesenden wieder; maßgeblich ist die kanonische Quelle.

dispatch.py akzeptiert zur Vorwärtskompatibilität auch UserPromptSubmit und Notification auf seiner Ereignis-Whitelist; keines der beiden ist in den ausgelieferten Vorlagen verdrahtet. Fügen Sie zum Aktivieren einen Matcher-Block mit demselben Exec-Form-Muster hinzu.

Python-SchichtCopy Anchor Link

Jeder Hook-Befehl läuft über denselben Python-Dispatcher:

ValidierungCopy Anchor Link

scripts/dev/validate_hooks.py erzwingt den Hook-Vertrag:

• settings.json lässt sich als JSON parsen und deklariert jedes der fünf Ereignisse in der Tabelle; ein fehlendes Ereignis ist eine Warnung, kein Fehlschlag.
• Alle drei Python-Skripte existieren und lassen sich als gültiges Python parsen.
• Alle Nachrichtendateien, auf die --context-file-Argumente verweisen, existieren.
• In src/apothem/hooks/**.py erscheinen keine fest codierten absoluten Benutzerpfade (C:\Users\... usw.).
• Shell-Artefakte unter src/apothem/hooks/ und scripts/ sind auf die genehmigten Locator- / Bootstrap-Stubs beschränkt.

Schema: CLAUDE.mdCopy Anchor Link

Pfad: CLAUDE.md (Wurzel)

Zweck: Projektbezogene Anweisungen für Claude Code.

Verpflichtendes 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"
---

AbschnitteCopy Anchor Link

CLAUDE.md ist in Prosa-Abschnitten verfasst und unter CLAUDE.md beschrieben. Kein Validator verlangt eine feste Abschnittsliste: scripts/dev/validate_ecosystem.py prüft die oben genannten Frontmatter-Schlüssel.

Validierungs-ChecklisteCopy Anchor Link

Jedes Artefakt muss diese Prüfungen bestehen:

Frontmatter-ValidierungCopy Anchor Link

• YAML ist syntaktisch gültig (keine Parsing-Fehler)
• Alle Pflichtfelder für den Artefakttyp sind vorhanden
• name folgt der Kebab-Case-Konvention
• version ist semantisch (MAJOR.MINOR.PATCH)
• updated liegt im ISO-8601-Datumsformat vor (YYYY-MM-DD)
• description ist eine nicht leere, einzeilige Zeichenkette
• Optionale Felder entsprechen den erwarteten Enum-Werten (falls zutreffend)
• Keine Tippfehler in Feldnamen (verwenden Sie die kanonischen Namen aus dem Schema)
• Kein überflüssiger Leerraum und keine Formatierungsprobleme

InhaltsvalidierungCopy Anchor Link

• Der Inhalt beginnt in einer neuen Zeile nach dem schließenden ---; bei Dateien der Markdown-Familie ist die kanonische SPDX-Header-Zeile der erste Inhalt danach
• Keine plan-internen Verweise (CM-7-Konformität)
• Querverweise lassen sich auflösen (falls andere Artefakte aufgeführt werden)
• Links verwenden relative Pfade mit Schrägstrichen

PortabilitätsvalidierungCopy Anchor Link

• Keine fest codierten absoluten Pfade (relative verwenden)
• Keine Windows-spezifische Syntax in Artefakten mit universellem Geltungsbereich
• Pfadtrennzeichen sind Schrägstriche
• Umgebungsvariablen verwenden ein plattformunabhängiges Format (${VAR} oder tool-nativ)

HinweiseCopy Anchor Link

• Konsistenz als Sicherheit: Kanonisches Frontmatter ermöglicht automatisierte Validierung, Tooling und artefaktübergreifende Verifikation. Abweichungen summieren sich schnell.
• Portabilitätserklärung: Nicht alle Artefakte können universell sein. Deklarieren Sie Einschränkungen ausdrücklich — besser einen Vorbehalt dokumentieren, als einen stillen Fehler auszuliefern.
• Kebab-Case für Namen: Leicht zu verwenden in URLs, Skripten und Kommandozeilenkontexten. Vermeiden Sie Leerzeichen, Unterstriche und camelCase bei Namen.
• Hygiene bei Versionsanhebungen: Jede Bearbeitung, die das Verhalten ändert, muss version und updated gemeinsam erhöhen. Tippfehler-, Link- und Formatierungskorrekturen lassen die Version unverändert; neue optionale Abschnitte oder Antimuster erhöhen MINOR; strukturelle Umgestaltungen oder Vertragsänderungen erhöhen MAJOR.