# Konventionen

Sie gelten für die gesamte Plattform.

1. Open Source
2. Reproduzierbarkeit
3. Nachhaltigkeit (Energieeffizienz und Wiederverwendung von Hardware)
4. Abhängigkeiten auf Software- und Hardwareebene vermindern

## Projektlokaler Graphify-Skill

- Der versionierte Skill liegt einmalig unter
  `.agents/skills/graphify/`. Codex lädt diesen Repository-Pfad nativ; andere
  Agent-Skills-kompatible Laufzeiten verwenden denselben Pfad.
- In Codex wird der Skill mit `$graphify` aufgerufen. Laufzeiten mit
  Slash-Kommandos können `/graphify` verwenden. Sichtbare Herdr-Agenten lesen
  vor der Nutzung die vollständige `SKILL.md` und nur die dort für den
  aktuellen Schritt genannten Referenzen.
- Die reproduzierbare Basisinstallation erfolgt im Repository-Root mit
  `graphify install --project --platform agents`. Das PyPI-Paket heißt
  `graphifyy`; die installierte Skill-Version steht in
  `.agents/skills/graphify/.graphify_version`.
- Der aktuelle Graphify-Codex-Installer
  (`graphify install --project --platform codex`) schreibt zusätzlich nach
  `.codex/` und registriert einen Hook. Diese Erweiterung ist nicht Teil der
  gemeinsamen Skill-Installation und benötigt eigenen, exklusiven Dateibesitz.
- Nach einem Upstream-Update muss die Laufzeitauswahl in `SKILL.md` erhalten
  bleiben: Codex verwendet `spawn_agent`/`wait_agent`, generische Laufzeiten
  verwenden `Task`. Danach `agents/tests/roles.sh` ausführen.
- Der Skill installiert nur die Agentenanweisungen. Das ausführbare
  `graphify` muss in der jeweiligen Laufzeit separat verfügbar sein. Erzeugte
  Graphen und optionale Git-Hooks werden nur auf ausdrücklichen Auftrag
  angelegt.
- Ein Skill-Aufruf erweitert niemals Netzwerk-, Schreib-, Deployment- oder
  Freigaberechte. Für `graphify query`, `graphify path` und `graphify explain`
  gelten weiterhin Rolle, Auftrag und technische Allow-/Deny-Settings.
- Read-only Rollen dürfen dort erlaubte Query-/Path-/Explain-Aufrufe ohne
  `graphify save-result` oder `graphify reflect` verwenden. Wenn sie Graphify
  tatsächlich genutzt haben, nennen sie in ihrer normalen Übergabe knapp
  Query-Typ, Outcome (`useful`, `dead_end` oder `corrected`), zitierte
  Knoten/Quellen und bei `corrected` die Korrektur.
  Dieses Feedback bleibt nichtpersistierend und begründet keine
  Schreibberechtigung.
- Der persistierende Feedback-Loop bleibt für einen Kontext nur dann
  verbindlich, wenn Rolle und Auftrag einen explizit zugewiesenen Schreibpfad
  für abgeleitete Graphify-Metadaten erlauben: Ergebnis mit `graphify
  save-result --question "..." --answer "..." --type query|path_query|explain
  --nodes <zitierte Knoten> --outcome useful|dead_end|corrected [--correction
  "..."]` festhalten und `graphify reflect` nach dem bestehenden Ablauf
  verwenden. Das speist `graphify-out/reflections/LESSONS.md` (bevorzugte
  Quellen, bekannte Sackgassen, frühere Korrekturen); ohne diesen expliziten
  Schreibpfad sind beide Befehle untersagt.