@renoxar/koolie 1.25.0

package/.koolie/core/build/doc/04-geltungsbereich.md

@@ -0,0 +1,25 @@
+# 4 Geltungsbereich
+
+## 4.1 Sachlich
+
+Das Framework gilt für den Einsatz eines **KI-Codierassistenten** in Softwareentwicklungsprojekten mit Git-basiertem Entwicklungsprozess und den im verfügbaren Kontext genannten generischen Werkzeugklassen (Issue Tracking wie `<ISSUE_TRACKER>`, Git-Repository, Merge beziehungsweise Pull Requests, `<CI_CD_PLATFORM>`, statische Codeanalyse, automatisierte Tests, technische Dokumentation, Teamkommunikation und Wissensmanagement). Es umfasst Governance, Datenschutz- und Sicherheitsmodell, Arbeitsmodell, Skills, Prompts, Checklisten, Entscheidungsbäume, Onboarding, Framework-Qualitätssicherung, Pilotierung und Übernahme.
+
+Vorausgesetzt ist die **lokale, beobachtete** Nutzung: Der Assistent läuft in der Entwicklungsumgebung, eine Person verfolgt die Sitzung. Nicht Teil des Kerngeltungsbereichs – strukturell vorbereitet und standardmäßig deaktiviert (D-10, `<TBD: Freigabe Cloud/CLI-Nutzung>`): Cloud-Sitzungen, nicht-interaktive Läufe ohne beobachtende Person (auch die eines Kommandozeilen-Clients), automatisierte Reviews, Fremdagenten über offene Agentenprotokolle sowie Hintergrundläufe. Ausgeschlossen ist damit der Betrieb ohne beobachtende Person, nicht eine Oberfläche: Ein Kommandozeilen-Client in einer interaktiven Sitzung, die eine Person verfolgt, gehört zum Kerngeltungsbereich (D-386). Eine Freigabe dieser Formen erfordert eine Erweiterung des Sicherheitsmodells über den Änderungsprozess.
+
+**Welcher** Assistent zum Einsatz kommt, legt das gewählte Client Pack fest (Kap. 7a). Der Geltungsbereich ist davon unabhängig; die Durchsetzungstiefe der Zusagen ist es nicht – sie steht in der Fähigkeitsmatrix des Packs und ist vor Inbetriebnahme zu bewerten.
+
+## 4.2 Persönlich
+
+Es gilt für alle Personen, die im Geltungsbereich eines aktiven Project Overlays mit dem Assistenten arbeiten oder dessen Ergebnisse prüfen und freigeben – zunächst für die Rolle Softwareentwicklung; weitere Rollen (Softwarearchitektur, Requirements Engineering, Testing und QA, DevOps, Dokumentation, Code Review) sind über Role Packs strukturell vorgesehen (Ebene 6). Ohne dokumentierte Onboarding-Freigabe ist nur begleitetes Arbeiten zulässig.
+
+## 4.3 Organisatorisch und zeitlich
+
+Je Projekt wird der Geltungsbereich durch das Project Overlay konkretisiert (Repositorys, Pfade, Rollen, Freigaben); ohne aktives Overlay ist produktiver Einsatz unzulässig (nur Onboarding-Übungen auf dem synthetischen Übungsrepository). Voraussetzungen auf Organisationsebene – Werkzeugfreigabe, Datenschutz- und Vertragsprüfung, administrativ gesetzte Team-Einstellungen – sind Eingangsbedingungen (Klärungspunkte K-04 bis K-06) und werden über die Ebene der Organisationsvorgaben eingebunden. Das Framework gilt ab Übernahme (Adoption) in der jeweils referenzierten Release-Version bis zur Deaktivierung des Overlays.
+
+## 4.4 Produktstand und Grenzen der Aussagen
+
+Das Framework legt keinen Produktstand fest – ein Client Pack tut es. Jedes Pack nennt in seinem Kopf die **geprüfte Clientversion** und das Datum der Prüfung; ohne diese Angabe ist keine Einstufung `[TECHNISCH]` zulässig (Kap. 7a).
+
+Für das in diesem Dokument durchgehend verwendete Pack `devin-desktop` stehen die verbindliche Zielspanne, die geprüfte Punktversion, das Datum der Prüfung und der Stand der Produktbeobachtung **im Pack selbst** (Kap. 15.1). Sie stehen dort und nicht hier, weil sie sich mit dem Produkt ändern: Die Zielspanne ist der *geprüfte* Geltungsbereich und nicht der aktuelle Produktstand, und das Pack weist den Abstand zwischen beiden ausdrücklich aus, damit die Spanne nicht als „aktuell" gelesen wird.
+
+Alle produktbezogenen Aussagen tragen Belegstatus. **Die verbindliche Zielversion jedes ausgelieferten Packs ist festgelegt** (D-112). Wie weit seine Zeilen belegt sind, ist je Pack verschieden (Kap. 1, 7a.3); welche Zeile wie weit belegt ist, sagt die Belegspalte der jeweiligen Matrix – je Zeile, nicht als Gesamturteil.

package/.koolie/core/build/doc/05-glossar.md

@@ -0,0 +1,47 @@
+# 5 Begriffe und Glossar
+
+| Begriff | Bedeutung im Framework |
+|---|---|
+| KI-Codierassistent | Sammelbegriff für das Werkzeug, das dieses Framework steuert. Welches Produkt konkret, legt das Client Pack fest |
+| Client Pack | Abbildungsschicht für genau einen KI-Client: Pfadabbildung, Semantikabbildung und Fähigkeitsmatrix (Kap. 7a). Keine Regelebene |
+| Fähigkeitsmatrix | Einstufung jeder technischen Zusage des Frameworks je Client: `[TECHNISCH]` erzwungen · `[TEXTUELL]` nur Anweisung · `[NICHT ABBILDBAR]`. Die Zeilenzahl ist je Pack verschieden – ein Client, der für eine Zusage keinen Mechanismus hat, bekommt dafür auch keine Zeile (Kap. 7a.3) |
+| Kernzusage B1–B6 | Die sechs Zusagen, die dem Integritätsblock der Berechtigungsdatei entsprechen; eine Abweichung von `[TECHNISCH]` ist begründungs- und freigabepflichtig |
+| `claude-code` · `devin-desktop` · `openai-codex` | Die drei ausgelieferten Client Packs. **Welches Produkt, welcher Agent und welche geprüfte Version dahinterstehen, nennt der Kopf des jeweiligen Packs** (Kap. 7a.3, 15.1) – dieser Kern nennt es nicht, weil er sich sonst mit dem Produkt änderte (D-02, D-129). In diesem Dokument ist `devin-desktop` das durchgehende Beispiel |
+| Wurzel-Anweisungsdatei | zentrale Agentenanweisung im Wurzelverzeichnis; wird zu Beginn jeder Sitzung geladen `[DOK]`. Dateiname je Client Pack (Anhang 31.2) |
+| Regel (Rule) | Markdown-Datei in der Regelablage mit Ladebedingung. Quellform: Frontmatter `description`, `trigger` (`always_on`, `model_decision`, `glob`, `manual`, `agent`) und bei `glob` zusätzlich `globs`. Die Ladebedingung wird bei der Installation auf die Bedingungssprache des Clients abgebildet (D-27); welche das ist, steht im Client Pack `[DOK]` |
+| Skill | versionierte, testbare Arbeitsanweisung in der Skill-Ablage (`<name>/SKILL.md`); Aufruf `/name` `[DOK]`; Standard in Kap. 18 |
+| Subagent | eigenständiges Agentenprofil für abgegrenzte Teilaufgaben `[DOK]`; im Framework nur das lesende Profil `fw-reviewer` |
+| Hook | konfigurierter Eingriffspunkt im Agenten-Lebenszyklus (Hook-Konfiguration), kann Aktionen blockieren `[DOK]` |
+| Permission-Modus | Bestätigungsverhalten des Clients; Framework-Standard ist der Modus, der bei Schreiben und Befehlen rückfragt. Bezeichnungen je Client (bei `devin-desktop`: Normal, Accept Edits, Smart, Bypass, Autonomous `[DOK]`) |
+| Berechtigungsregeln | `deny`/`ask`/`allow`-Regeln in der Berechtigungsdatei; `deny` gewinnt immer `[DOK]`. Die Regelmenge liegt werkzeugneutral im Kern, die Werkzeugnamen entstehen aus der Semantikabbildung (Kap. 7a) |
+| Sandbox | optionale Isolation der Befehlsausführung mit Pfad- und Domainfilter `[DOK]`; Verfügbarkeit betriebssystemabhängig |
+| MCP | Model Context Protocol; Anbindung externer Werkzeuge/Server; im Framework nur nach Overlay-Freigabe, Standard `ask` `[DOK]` |
+| Spaces / Agent Command Center | Desktop-Funktionen für geteilten Kontext beziehungsweise parallele Agenten `[DOK]`; im Framework restriktiv geregelt (Kap. 12) |
+| Ebenen A–E | Trennungsmodell nach P10: A universelle Framework-Regeln, B Organisationsvorgaben, C Projektkonfiguration, D Rollen-/Technologieerweiterungen, E aufgabenbezogene flüchtige Informationen |
+| Framework Core | Ebene 3 der Prioritätshierarchie; projektunabhängige Module FW-CORE-00…10 unter `.koolie/core/framework/core/` |
+| Role Pack / Technology Pack | optionale rollen- beziehungsweise technologiebezogene Module (Ebenen 6 und 5) mit Laufzeitfassung `30-*` / `40-*` in der Regelablage |
+| Project Overlay | einzige projektspezifische Ebene (4): `.koolie/project-overlay/` plus Laufzeitfassung `20-*` in der Regelablage; austauschbar ohne Core-Änderung |
+| Overlay-Manifest | Register der für den Assistenten freigegebenen Projektdokumente (`overlay-manifest.yaml`) mit Klasse, Status, Ladeverhalten |
+| Kontextklasse K0–K3 | Zulässigkeitsstufen für Inhalte an den Assistenten: frei / projektintern freigegeben / nur nach Freigabe und Bereinigung / nie (Kap. 11) |
+| Kontrollstufe | Risikoklasse einer Aufgabe (niedrig/mittel/hoch) nach Faktoren R1–R13, Maximumprinzip (Kap. 13) |
+| Delegationsverbotsliste V1–V12 | Aufgaben und Entscheidungen, die nie an den Assistenten delegiert werden (Kap. 13) |
+| Betriebsmodus M1–M6 | Read-only Analysis, Guided Planning, Controlled Modification, Test and Validation, Documentation Support, Mandated Maintenance (Kap. 9) |
+| Mandat | Befristete Erlaubnis, die ein Mensch im eigenen Terminal erteilt (`mandat.py`): Der KI-Client trägt im Modus M6 Entscheidungen des Menschen in das Overlay ein; der Schutz-Hook sperrt das Overlay ohne Mandat (Kap. 9) |
+| Standardarbeitsablauf | die vierzehn Schritte jeder Assistenz-Aufgabe (Kap. 10) |
+| Stop-Bedingungen S1–S10 / Eskalationsstufen E0–E4 | definierte Anhalte- und Eskalationspunkte (Kap. 10, 25; Baum 5) |
+| Preflight | Pflichtprüfung vor jeder Assistenz-Aufgabe (Checkliste FW-CL-01) |
+| Ergebnisbericht | Pflichtabschluss jeder Sitzung nach festem Format (Kap. 10) |
+| KI-Nutzungsvermerk | Kennzeichnungsblock in Merge Requests (`.koolie/core/templates/MR_AI_DISCLOSURE.md`) |
+| Quality Gate | bestehende Prüfschranke des Projekts (`<QUALITY_GATE>`); gilt für KI-Code unverändert (P6) |
+| Merge Request | Änderungsvorschlag mit Review im Git-Prozess (plattformneutral; synonym Pull Request) |
+| MUSS / SOLL / KANN / DARF NICHT | Verbindlichkeitsstufen des Frameworks (Kap. 6) |
+| Belegstatus `[DOK]` / `[EMPF]` / `[KONZ]` | Kennzeichnung produktbezogener Aussagen: offiziell dokumentiert / begründete, noch nicht installationsgeprüfte Empfehlung / konzeptioneller Vorschlag |
+| `BELEG OFFEN` | Belegstand einer Aussage, deren Nachweis noch aussteht; die Zelle nennt Grund und Datum. Trägt keine Frist |
+| `<TBD: …>` | offene projekt- oder organisationsspezifische Entscheidung |
+| Platzhalter | registrierte variable Bezeichner in spitzen Klammern (Anhang 31.3) |
+| RACI | Verantwortungsmodell: Responsible, Accountable, Consulted, Informed (Kap. 25) |
+| Decision Log | fortgeschriebenes Entscheidungs- und Klärungsregister (`.koolie/core/governance/DECISION_LOG.md`) |
+| Übungsrepository | synthetisches Repository für Onboarding und Tests (Kap. 24, 26) |
+| Köder | präparierte Negativübungs-Inhalte (Injektion, Pseudo-Secret, Scope-Falle) im Übungsrepository |
+| Referenzbasis | Vor-Einführung-Vergleichswerte der Pilotmetriken (Kap. 27) |
+| Synthetisches Beispiel | erfundenes, ausdrücklich gekennzeichnetes Beispiel ohne Bezug zu realen Projekten, Personen oder Systemen |

package/.koolie/core/build/doc/06-leitprinzipien.md

@@ -0,0 +1,5 @@
+# 6 Leitprinzipien
+
+Die zehn Leitprinzipien sind der normative Kern des Frameworks; jedes weitere Kapitel operationalisiert sie. Sie stammen aus dem Arbeitsauftrag und sind im Modul FW-CORE-00 verbindlich gefasst – zusammen mit den Konventionen für Verbindlichkeitsstufen, Belegstatus und Platzhalter, die in diesem Dokument durchgängig verwendet werden. Das Modul wird hier vollständig wiedergegeben.
+
+{{EMBED-RAW:.koolie/core/framework/core/00-principles.md:1}}

package/.koolie/core/build/doc/07-architektur.md

@@ -0,0 +1,60 @@
+# 7 Framework-Architektur
+
+## 7.1 Überblick
+
+Die Architektur trennt drei Dinge, die in KI-Regelwerken häufig vermischt werden: **was immer gilt** (Kern), **was vom Einsatzkontext abhängt** (Packs und Overlay) und **wie ein konkretes Werkzeug es ausführt** (Laufzeitschicht). Daraus ergeben sich die vier geforderten Ebenen – Framework Core, Role Packs, Technology Packs, Project Overlay – eingebettet zwischen die Organisationsebene darüber und den flüchtigen Aufgabenkontext darunter, sowie quer dazu die Unterscheidung zwischen kanonischer Form (`.koolie/core/framework/`, werkzeugneutral) und **Laufzeitform**. Wie die Laufzeitform aussieht und wo sie liegt, entscheidet das gewählte Client Pack – die Abbildungsschicht, die Kap. 7a beschreibt.
+
+```mermaid
+flowchart TD
+    subgraph EXT["außerhalb des Frameworks"]
+        L1["Ebene 1: Gesetz und Regulierung"]
+        L2["Ebene 2: Organisationsvorgaben<br/>(Einbindungspunkt .koolie/core/framework/org-policies/)"]
+    end
+    subgraph FW["Framework-Repository"]
+        L3["Ebene 3: Framework Core<br/>.koolie/core/framework/core/ · FW-CORE-00…10"]
+        L5["Ebene 5: Technology Packs<br/>.koolie/core/framework/tech-packs/"]
+        L6["Ebene 6: Role Packs<br/>.koolie/core/framework/role-packs/"]
+        L4["Ebene 4: Project Overlay<br/>.koolie/project-overlay/ (austauschbar je Projekt)"]
+        RT["Laufzeitschicht (je Client Pack)<br/>Wurzel-Anweisung · Regeln · Skills ·<br/>Berechtigungen · Hooks · Agentenprofile"]
+    end
+    L8["Ebene 8: Aufgabenbezogene Nutzeranweisung<br/>(Ebene E, flüchtig)"]
+    L1 --> L2 --> L3
+    L3 --> L4
+    L3 --> L5
+    L3 --> L6
+    L4 --> RT
+    L5 --> RT
+    L6 --> RT
+    L3 --> RT
+    RT --> L8
+```
+
+Textfassung des Diagramms: Gesetz und Organisationsvorgaben stehen über dem Framework und werden nicht kopiert, sondern eingebunden. Der Framework Core speist sowohl die optionalen Packs als auch das Overlay; alle vier Ebenen werden über die Laufzeitschicht wirksam, in der die Nutzeranweisung (Ebene 8) die konkrete Aufgabe formuliert. Skills (Ebene 7) sind Teil der Laufzeitschicht.
+
+Die Laufzeitschicht ist **kein** Bestandteil des Repositorys: Sie entsteht bei der Installation aus dem Kern und sieht je Client Pack anders aus. Die Abbildungsschicht, die das leistet, ist keine weitere Regelebene – die Hierarchie bleibt achtstufig (Kap. 7a.2).
+
+## 7.2 Ebene 3 – Framework Core (projektunabhängig)
+
+Allgemeingültige Regeln in elf Modulen – FW-CORE-00 bis FW-CORE-10: 00 Leitprinzipien und Konventionen, 01 Governance-Grundsätze, 02 Kontext- und Datenschutzmodell, 03 Sicherheitsmodell, 04 Qualitätsgrundsätze, 05 Arbeitsmodell (Standardarbeitsablauf und Betriebsmodi), 06 Prompting-Regeln, 07 Review-Regeln, 08 Skill-Standard, 09 Risikoklassifizierung, 10 Fehler- und Eskalationsverfahren. Der Core enthält Platzhalter-Schnittstellen für alles Projektspezifische, aber keine Projektwerte; er ändert sich nur über Framework-Releases.
+
+## 7.3 Ebene 6 – Role Packs (optional, rollenbezogen)
+
+Module je Tätigkeit. **Ausgeliefert werden zwei:** Softwareentwicklung als Referenzpack (`RP-DEV`) und Requirements Engineering (`RP-RE`) mit dem Skill `role-re-ticket` – dem dreizehnten Skill des Frameworks und dem einzigen, der nicht aus dem Kern stammt. Softwarearchitektur, Testing und QA, DevOps, Dokumentation und Code Review sind strukturell vorgesehen. Ein Role Pack konkretisiert Arbeitsweise, typische Aufgaben mit Modus- und Stufenzuordnung, rollenspezifische Kontextquellen, Prüfpunkte und gegebenenfalls Skills (`role-<pack>-…`). Es enthält keine Governance-Regeln und keine Projektwerte; Aktivierung erfolgt je Projekt über das Overlay; die Laufzeitfassung `30-*` lädt bei Relevanz; kennt ein Client keine modellentschiedene Ladebedingung, lädt sie dort unbedingt.
+
+## 7.4 Ebene 5 – Technology Packs (optional, technologiebezogen)
+
+Module je Technologieaspekt (Programmiersprache, Anwendungsframework, Build-System, Testframework, Datenbank, API-Technologie, Frontend, Backend, Container, CI/CD). Inhalt: Konventionen und Idiome, Testkonventionen, typische Fehlerquellen KI-generierten Codes in dieser Technologie, technologiespezifische Sicherheitsmuster, gegebenenfalls Skills (`tech-<pack>-…`). Die Laufzeitfassung `40-*` bindet sich an die Dateimuster der Technologie und lädt genau dann, wenn passende Dateien berührt werden `[DOK]` – vorausgesetzt, der Client kennt an Dateimuster gebundene Regeln. Ein Client ohne diesen Mechanismus braucht einen der Ersatzwege aus seiner Fähigkeitsmatrix. Ausgeliefert wird bewusst eine Vorlage statt eines konkreten Packs; das erste Pack für `<TECH_STACK>` entsteht in Roadmap-AP4.
+
+## 7.5 Ebene 4 – Project Overlay (ausschließlich projektspezifisch)
+
+Die einzige Ebene, die ein Projekt ausfüllt und die beim Projektwechsel getauscht wird: Steckbrief und Freigabestatus, Architektur-Kurzfassung mit kritischen Komponenten, Repository-Struktur, erlaubte und ausgeschlossene Verzeichnisse, Build-/Test-/Prüfbefehle, Quality Gates, Sprachen und Frameworks, Conventions, Branching- und Merge-Modell, Definition of Ready und Done, zulässige Kontexte und Werkzeugfreigaben, ausgeschlossene Daten, Rollen und Freigaben, Eskalationswege, projektspezifische Skills, dokumentierte Ausnahmen sowie das **Dokumenten-Manifest**, über das künftige projektspezifische Dokumente (KI-Governance, Vorgehensmodell, Roadmap, Architekturvorgaben, Coding Guidelines, Definition of Ready/Done, Branching-Strategie, Deployment-, Security- und Qualitätsvorgaben, Rollenbeschreibungen, Glossar) als Kontext eingebunden werden, ohne den Core zu ändern (Kap. 17). Laufzeitfassung: die Overlay-Regel `20-project-overlay.md` (immer geladen, kompakt) plus optionale Overlay-Regeldateien `2N-*`.
+
+## 7.6 Querschnitt: kanonische Ebene und Laufzeitschicht (Tool Independence)
+
+Alle normativen Inhalte liegen werkzeugneutral in `.koolie/core/framework/` (kanonische Langform). Der KI-Client liest die **Laufzeitfassungen**: die Wurzel-Anweisungsdatei, die Regelablage mit den Kurzfassungen, die Skill-Ablage mit den ausführbaren Verfahren, die Berechtigungsdatei, die Hook-Konfiguration und die Agentenprofile. Welche Datei- und Verzeichnisnamen das je Client sind, führt das Laufzeitglossar (Anhang 31.2); im Fließtext nennt der Kern nur die Begriffe.
+
+Die Laufzeitfassungen verweisen auf die Langform und dürfen ihr nicht widersprechen (Konsistenztest FW-KO-02). Sie werden **erzeugt**, nicht gepflegt: Ihre Quellen liegen einmal im Kern, und die Installation bringt sie in die Form des gewählten Client Packs. Ein Werkzeugwechsel ersetzt damit nicht eine dünne Schicht von Hand, sondern die Abbildung – ein neues Client Pack (P8, Kap. 7a).
+
+## 7.7 Erweiterbarkeit
+
+Neue Rollen → neues Role Pack aus der Vorlage; neue Technologie → neues Technology Pack; neues Projekt → neues Overlay; neue wiederkehrende Aufgabe → neuer Skill nach Standard; neue Organisationsvorgabe → Verweisblatt in Ebene B; neue Werkzeuggeneration → neue Laufzeitschicht. Für jede Erweiterung existieren Vorlage, Namenskonvention, Owner-Modell und Validierung; die Einordnungsfrage beantwortet Entscheidungsbaum 6 (Kap. 23).

package/.koolie/core/build/doc/07a-abbildungsschicht.md

@@ -0,0 +1,66 @@
+# 7a Client Packs: die Abbildungsschicht
+
+## 7a.1 Das Problem, das diese Schicht löst
+
+Ein Framework, dessen Datenschutz- und Sicherheitszusagen bei einem KI-Client von der Engine erzwungen werden und bei einem anderen nur als Prosa im Prompt stehen, muss diesen Unterschied sichtbar machen. Sonst erzeugt es falsche Sicherheit – genau dort, wo es am meisten schadet.
+
+Dazu kommt die Pfadfrage: Ein Kern, der die Laufzeitpfade eines bestimmten Clients nennt, ist nicht werkzeugneutral – wer mit einem anderen Werkzeug installiert, liest Pfade, die bei ihm nicht existieren. Die **Abbildungsschicht** macht diese Bindung explizit und austauschbar.
+
+Ein **Client Pack** beantwortet für genau einen Client zwei Fragen:
+
+1. **Wohin** gehören die Laufzeitartefakte – Wurzel-Anweisungsdatei, Regeldateien, Skills, Berechtigungen, Hooks, Subagentenprofile?
+2. **Welche Zusagen setzt dieser Client technisch durch** – und welche bleiben eine Anweisung, der das Modell folgen kann oder auch nicht?
+
+Die zweite Frage ist der eigentliche Grund für die Schicht.
+
+## 7a.2 Keine Regelebene
+
+Die achtstufige Prioritätshierarchie (Kap. 7) bleibt **unverändert**. Ein Client Pack führt keine Verhaltensregel ein, lockert keine bestehende und steht in keiner Konfliktbeziehung zu Core, Overlay oder Packs. Es übersetzt die Ebenen 3 bis 7 in die Artefakte eines konkreten Clients und dokumentiert die Durchsetzungstiefe. Entsteht ein Widerspruch zwischen einem Client Pack und der kanonischen Langform, gilt die Langform; das Pack wird korrigiert.
+
+{{EMBED-RAW:.koolie/core/clients/README.md:1}}
+## 7a.3 Die Fähigkeitsmatrix
+
+Kern jedes Client Packs. Sie stuft jede technische Zusage des Frameworks in eine von drei Klassen ein – `[TECHNISCH]` (die Engine erzwingt sie), `[TEXTUELL]` (nur Anweisung im Kontext) oder `[NICHT ABBILDBAR]` – und macht damit messbar, was zuvor Behauptung war.
+
+**Die Zeilenzahl ist keine Eigenschaft des Frameworks, sondern eine des Packs.** `devin-desktop` etwa führt Zeilen (A2, M4, M5, M6, M7), für die `claude-code` keinen Mechanismus hat und die dort deshalb fehlen. Eine Zusage ohne Mechanismus bekommt keine Zeile; sie bekommt eine Begründung im Pack.
+
+Sechs dieser Zusagen sind **Kernzusagen** (B1 bis B6) und entsprechen dem Integritätsblock der Berechtigungsdatei. Weicht eine von `[TECHNISCH]` ab, ist sie im Pack einzeln zu begründen, im Overlay als Ausnahme zu führen und durch `<SECURITY_CONTACT>` freizugeben.
+
+Dieses Dokument verwendet `devin-desktop` als durchgehendes Beispiel; seine Matrix steht in Kap. 15.1. Zum Vergleich hier die beiden anderen Packs – derselbe Kern, andere Clients. Zuerst `claude-code`:
+
+{{EMBED-RAW:.koolie/core/clients/claude-code/CLIENT_PACK.md:1}}
+Dann `openai-codex`, dessen Belege durchweg Messungen sind (D-396):
+
+{{EMBED-RAW:.koolie/core/clients/openai-codex/CLIENT_PACK.md:1}}
+Der Vergleich der Matrizen ist die Probe aufs Exempel: `devin-desktop` und `claude-code` bilden alle sechs Kernzusagen ab – **drei davon technisch in jedem Zugriffskanal** (B1, B2, B6), drei nur für den direkten Zugriff (B3, B4, B5); für Shell und Unterprozess tragen sie die Regelschicht. Bei `openai-codex` sind B3 und B5 `[NICHT ABBILDBAR]`; das Pack begründet es, und ein Projekt braucht dafür eine dokumentierte Ausnahme mit Freigabe durch `<SECURITY_CONTACT>` (siehe oben).
+
+**Ein Vergleich der Gesamtzahlen trägt dagegen nicht, und das hat zwei Gründe.** Erstens sind die Matrizen unterschiedlich lang. Zweitens – und das wiegt schwerer – **messen die Zahlen Verschiedenes:** Die Belege sind auf verschiedenen Wegen gewonnen – durch Beobachtung an einer laufenden Installation, durch Messung am Client oder durch Abgleich mit der Herstellerdokumentation –, und welcher Weg für eine Zeile gilt, sagt ihre Belegspalte. Bei `claude-code` ist der Beleg überwiegend ein Dokumentenabgleich, bei `openai-codex` durchweg eine Messung. **Ein Dokumentenabgleich belegt `[DOK]`, nicht `[TECHNISCH]` im Sinne einer beobachteten Wirkung.** Die Summen stehen in Abschnitt 3 jedes Packs; Prüfung 31 rechnet sie bei jedem Validatorlauf aus der Matrix nach.
+
+## 7a.4 Form und Semantik
+
+Ein Client Pack enthält **drei Dateien** – die Fähigkeitsmatrix `CLIENT_PACK.md`, die maschinenlesbare Abbildung `manifest.json` und eine erklärende README der Laufzeitschicht unter `root-template/`. Alles Übrige liegt einmal im Kern und wird bei der Installation übersetzt. Dabei sind zwei Fälle zu unterscheiden, und der Unterschied ist wesentlich:
+
+**Formtransformation.** Der Inhalt ist derselbe, nur die Schreibweise unterscheidet sich – ein Frontmatter-Feld heißt anders, eine Werkzeugliste ist kommagetrennt statt eingerückt. Das betrifft Regeltexte, Wurzel-Anweisung, Agentenprofil, Skills und die Vorlagen.
+
+Die Ladebedingung einer Regel ist dagegen **keine** Formfrage, sondern eine zweite Semantikabbildung (D-27): Die Kernquelle kennt fünf Ladetrigger, ein Client kennt seine eigene Bedingungssprache. Bei `claude-code` heißt sie `paths` und bindet eine Regel an Glob-Muster; `always_on` und `model_decision` bilden dort auf unbedingtes Laden ab – eine Verschärfung. Ein Ladetrigger ohne Eintrag in der Abbildung lässt die Installation scheitern; er wird nicht verworfen.
+
+**Semantikabbildung.** Die Werkzeuge selbst unterscheiden sich. Ein Client trennt Ändern und Anlegen in zwei Werkzeuge, ein anderer nicht; Befehlsverbote greifen hier wörtlich (`Exec(git reset --hard)`) und dort präfixbasiert (`Bash(git reset:*)`); Netzzugriff ist einmal ein Werkzeug mit Muster und einmal zwei ohne. Das betrifft Berechtigungen und Hooks – und damit genau die Regeln, an denen die Kernzusagen hängen.
+
+Für den zweiten Fall genügt Sorgfalt nicht. Eine beim Nachziehen vergessene Regel wäre eine stille Lücke, während die Fähigkeitsmatrix weiterhin `[TECHNISCH]` behauptet. Die Abbildung erzwingt deshalb drei Eigenschaften und bricht die Installation ab, wenn eine verletzt ist:
+
+| Zusicherung | Warum |
+|---|---|
+| Keine `deny`- oder `ask`-Regel ohne Zielwerkzeug beim Client | Sie wegzulassen wäre eine Lockerung. Bei `allow` ist Weglassen zulässig – es fällt auf den strengeren Standard zurück |
+| Die Präfixform eines Befehlsverbots muss ein Präfix der wörtlichen Form sein | Damit ist die Präfixform nachweislich mindestens so breit; die Abweichung ist belegbar eine Verschärfung |
+| Bei `allow` müssen wörtliche und Präfixform übereinstimmen | Dort wäre jede Verbreiterung eine Lockerung |
+
+Der Integritätsblock der Berechtigungsdatei wird aus derselben Quelle erzeugt; der Validator gleicht die installierte Datei dagegen ab. Eine entfernte Kernregel fällt dadurch auf, auch wenn das Projekt zugleich die Integritätsliste gekürzt hat. Das gilt für Packs mit einer Berechtigungsdatei im JSON-Format; `openai-codex` schreibt seine Berechtigungen im TOML-Format und ohne Integritätsblock – welche Prüfungen dieses Pack deshalb nicht erreichen, führt es selbst in Abschnitt 5.
+
+Die werkzeugneutrale Regelmenge, aus der jedes Pack seine Berechtigungen erzeugt:
+
+{{EMBED:.koolie/core/framework/runtime/permissions.json:json}}
+## 7a.5 Was das für ein Projekt bedeutet
+
+Die Wahl des Client Packs fällt bei der Erstinstallation (`install.py --client`; der Dialog der Starter fragt sie ab, Kap. 15.2) und wird im Overlay dokumentiert. Sie ist keine Geschmacksfrage: Bevor ein Pack in Betrieb geht, ist seine Fähigkeitsmatrix zu lesen und jede Kernzusage ohne technische Durchsetzung freizugeben. Ein Wechsel des Clients ist ein eigener Vorgang mit erneuter Bewertung – nicht ein Schalter.
+
+Für ein weiteres Client Pack ist Roadmap-AP2 mit der Fähigkeitsmatrix des neuen Packs zu wiederholen. Solange dessen Zielversion nicht festgelegt und geprüft ist, gilt das Pack als **unbelegt**.

package/.koolie/core/build/doc/08-trennung.md

@@ -0,0 +1,24 @@
+# 8 Trennung zwischen Core und Projektkonfiguration
+
+## 8.1 Das Trennprinzip
+
+Die Wiederverwendbarkeit des Frameworks steht und fällt mit einer harten Regel: **Ein Projektwechsel tauscht ausschließlich Ebene 4 (Project Overlay); er darf niemals Anpassungen am Framework Core erzwingen.** Umgekehrt enthält der Core keine einzige projektspezifische Angabe – wo er Projektwissen braucht, definiert er eine benannte Schnittstelle in Form eines registrierten Platzhalters (`<ALLOWED_PATHS>`, `<TEST_COMMAND>`, `<APPROVAL_ROLE>` …), die das Overlay füllt.
+
+## 8.2 Mechanik der Trennung
+
+| Mechanismus | Wirkung |
+|---|---|
+| Platzhalter-Schnittstellen (Anhang 31.3) | Core-Regeln bleiben generisch formulierbar; Projekte füllen Werte ausschließlich im Overlay und in der Berechtigungsdatei |
+| Verschärfungsprinzip (Kap. 25) | Das Overlay darf konkretisieren und verschärfen, nie lockern – Core-Garantien gelten damit projektübergreifend |
+| Getrennte Ablage und Ownership | Core: Framework Owner über Releases; Overlay: Overlay Owner über den Projektprozess; technische Schreibsperren (`Write(.koolie/core/**)` – das Kernverzeichnis als Ganzes, einschließlich der Skripte, die die Schutzzusagen durchsetzen –, dazu Laufzeitschicht, Wurzel-Anweisungsdatei und `Write(.koolie/project-overlay/**)` als `deny`) |
+| Dokumenten-Manifest | Projektwissen wird als registriertes Dokument mit Klasse und Ladeverhalten eingebunden – nie durch Editieren von Core-Dateien (Kap. 17) |
+| Integritätsprüfung | `validate-framework.py` prüft unter anderem, dass die Kernregeln in der Berechtigungsdatei unverändert enthalten sind (`_core_rules_integrity`) und Overlay-Pflichtfelder gefüllt sind (`--strict-overlay`) |
+| Release-Abgleich | Bei Übernahme und Aktualisierung werden Core-Bestandteile byte-gleich aus dem Release übernommen (Adoption Guide, CL-10/CL-11) |
+
+## 8.3 Grenzfälle und ihre Auflösung
+
+Regeln mit gemischtem Charakter werden getrennt: die generische Logik wandert mit Platzhalter in den Core, der Wert in das Overlay (**Beispiel (synthetisch):** „Der Assistent führt nur freigegebene Testbefehle aus" ist Core; „der Testbefehl lautet `build-tool test`" ist Overlay). Stellt ein Projekt fest, dass eine Core-Regel für alle denkbaren Projekte falsch oder unvollständig ist, ist das ein Änderungsantrag an den Framework Owner – bis zur Entscheidung gilt die Regel oder eine dokumentierte, befristete Ausnahme (nie eine stille lokale Abweichung). Die vollständige Einordnungslogik – einschließlich Ebene B (Organisationsvorgaben werden eingebunden, nicht kopiert) und Ebene E (Aufgabenkontext bleibt außerhalb des Repositorys) – bildet Entscheidungsbaum 6 ab (Kap. 23).
+
+## 8.4 Nachweis der Trennung
+
+Alle versionierten Markdown-Dateien des Kerns – beim Bau dieses Dokuments {{ZAHL:*.md}} – werden bei jedem Validatorlauf automatisiert auf Projektneutralität geprüft (Sperrbegriffs-, E-Mail-, IP-, Hostnamen- und URL-Prüfungen; Kap. 26). **Der Validator prüft zusätzlich die Werkzeugneutralität selbst:** Kein anweisender Träger des Kerns nennt einen Produktnamen oder einen Pfad, der genau einem Client Pack gehört (Prüfung 14 und 48). Sämtliche variablen Inhalte laufen über das Platzhalterregister; die Overlay-Vorlage ist eine reine Vorlage mit Ausfüllhinweisen und `<TBD>`-Feldern. Das Overlay-Muster *General Development* (`--overlay general`) füllt davon nur Platzhalter, deren Wert eine Sperre ist, und bringt allgemeine, projektneutrale Musterdokumente mit (D-355, D-359). Synthetische Beispiele sind als solche gekennzeichnet und verwenden offensichtlich fiktive Bezeichner.

package/.koolie/core/build/doc/09-betriebsmodi.md

@@ -0,0 +1,18 @@
+# 9 Betriebsmodi
+
+Jede KI-Aufgabe läuft in genau einem von sechs Betriebsmodi; der Modus wird im Preflight festgelegt (Entscheidungsbaum 3) und begrenzt Schreibrechte, Befehlsausführung und erwartete Ausgabe. Ohne ausdrückliche Angabe gilt der nur lesende Modus M1; ein Moduswechsel innerhalb einer Sitzung erfordert eine ausdrückliche menschliche Anweisung und wird im Ergebnisbericht vermerkt.
+
+| Modus | Zweck in einem Satz | Schreiben | Befehle | Typische Skills |
+|---|---|---|---|---|
+| **M1 Read-only Analysis** | Verstehen, prüfen, erklären – Befunde nur mit Fundstellen | nein | keine (bei Review-Unterstützung: nur lesende Git-Befehle) | `fw-repo-analyze`, `fw-code-explain`, `fw-change-analyze`, `fw-error-analyze`, `fw-review-support` |
+| **M2 Guided Planning** | prüfbaren Änderungsplan erarbeiten – mit Halte-Punkt vor jeder Umsetzung | nur Plan-Datei außerhalb des Quellcodes | nein | `fw-plan`, `fw-bugfix-prepare` |
+| **M3 Controlled Modification** | freigegebene Änderung in kleinen, berichteten Schritten umsetzen | nur im freigegebenen Scope | nur freigegebene Build-/Test-/Lint-Befehle | `fw-change-small`, `fw-refactor` |
+| **M4 Test and Validation** | Tests erstellen und ausführen, Aussagekraft bewerten | nur `<TEST_PATHS>` | nur freigegebene Testbefehle | `fw-tests` |
+| **M5 Documentation Support** | Dokumentation aus dem belegten Code-Stand pflegen | nur `<DOC_PATHS>` | nur lesende Git-Befehle | `fw-docs-update`, `fw-mr-description` |
+| **M6 Mandated Maintenance** | Entscheidungen des Menschen direkt in Overlay und Projektdokumentation eintragen – bei der Einrichtung, nach einem Framework-Update, im laufenden Projekt | Overlay im Umfang des Mandats, `<DOC_PATHS>` | lesende Git-Befehle, Prüfbefehle des Frameworks | `fw-overlay-pflege` |
+
+**Das Mandat (seit 1.17.0).** Entscheiden bleibt beim Menschen; das Eintragen darf der Assistent übernehmen, statt eine Vorlage zum Abschreiben zu liefern. Der Mensch erteilt dafür im eigenen Terminal ein befristetes Mandat (`python .koolie/core/mandat.py erteilen --rolle Architekt --umfang overlay --minuten 60`). Der Schutz-Hook sperrt das Overlay, solange kein Mandat es deckt, und sperrt das Mandat selbst für jede Operation des Assistenten – er kann es sich nicht selbst geben. Geprüft wird im Merge Request. `mandat.py beenden` gleicht danach Status, Version und Pfadlisten in die immer geladene Laufzeitfassung ab. Jede Sperre erklärt sich in vier Zeilen – gesperrt, warum, Lösung mit Befehl, Folge –, damit niemand nachfragen muss.
+
+Jeder Modus ist im Modul FW-CORE-05 (vollständig in Kapitel 10 wiedergegeben) mit denselben sieben Merkmalen normiert: Zweck, zulässige Aktionen, verbotene Aktionen, benötigter Kontext, Prüfpflichten, Abbruchkriterien, erwartete Ausgabe – ergänzt um die konkrete Umsetzung beim Client Pack `devin-desktop` mit Belegstatus (Plan-Modus `[DOK]`, Skill-`allowed-tools` und -`permissions` `[DOK]`, Permission-Modus Normal `[DOK]`, Hook-Absicherung `[EMPF]`). Die Zulässigkeit je Kontrollstufe regelt Kapitel 13: Ab Stufe mittel setzt M3 einen bestätigten Plan voraus, ab Stufe hoch eine dokumentierte Freigabe mit begleitender Person; M4 bleibt auf Stufe hoch auf testseitige Artefakte beschränkt.
+
+Bewusste Festlegungen: Der rückfragende Permission-Modus (bei `devin-desktop`: **Normal**) ist Standard für alle Modi; **Bypass** ist untersagt und **Smart**/**Accept Edits** sind nur über dokumentierte Ausnahme für Stufe niedrig zulässig (D-05). Hintergrund-Subagenten sind für M3 untersagt; für M1 ist das nur lesende Profil zulässig. Parallele Agentensitzungen (Agent Command Center `[DOK]`) sind auf unabhängige Aufgaben der Stufe niedrig begrenzt.

package/.koolie/core/build/doc/10-arbeitsablauf.md

@@ -0,0 +1,5 @@
+# 10 Standardarbeitsablauf
+
+Der Standardarbeitsablauf führt jede KI-Aufgabe durch vierzehn Schritte – vom Verstehen über Datenschutzprüfung, Analyse, Planung und Freigabepunkt bis zu Umsetzung, Tests, Dokumentation und Übernahme über den bestehenden Review-Prozess. Er ist zusammen mit den Betriebsmodi und den Querschnittsregeln (Sitzungsdisziplin, Befehlsausführung, Fehlerverhalten, fehlender Kontext, Ergebnisbericht) im Modul FW-CORE-05 normiert, das hier vollständig wiedergegeben wird. Die operative Kurzfassung ist als always-on-Regel Teil der Laufzeitschicht (Datei `00-framework-core.md` der Regelablage).
+
+{{EMBED-RAW:.koolie/core/framework/core/05-working-model.md:1}}

package/.koolie/core/build/doc/11-datenschutz.md

@@ -0,0 +1,5 @@
+# 11 Kontext- und Datenschutzmodell
+
+Das Kontext- und Datenschutzmodell beantwortet die Frage, **welcher Inhalt den Assistenten überhaupt erreichen darf** – mit vier Klassen (K0 frei, K1 projektintern freigegeben, K2 nur nach Freigabe und Bereinigung, K3 nie), einer klaren Ausgangsannahme (jeder Kontext verlässt den Arbeitsplatz in die Anbieterverarbeitung; die vertraglichen Bedingungen sind organisationsspezifisch zu prüfen), Bereitstellungsregeln nach dem Least-Context-Prinzip, einem Freigabeverfahren für K2, einem definierten Vorfallverhalten und technischen Absicherungen in der Laufzeitschicht. Das Modul FW-CORE-02 wird hier vollständig wiedergegeben; die operative Anwendung erfolgt über Entscheidungsbaum 1 (Kap. 23) und die Checkliste FW-CL-02 (Kap. 22), die Einbindung projektspezifischer Dokumente über das Overlay-Manifest (Kap. 17).
+
+{{EMBED-RAW:.koolie/core/framework/core/02-privacy.md:1}}

package/.koolie/core/build/doc/12-sicherheit.md

@@ -0,0 +1,5 @@
+# 12 Sicherheitsmodell
+
+Das Sicherheitsmodell benennt Schutzziele und zehn konkrete Bedrohungen des KI-gestützten Arbeitens (vom Kontextabfluss über Prompt Injection und Supply-Chain-Risiken bis zur Umgehung von Quality Gates) und stellt ihnen vier Kontrollschichten entgegen: organisationsweite Einstellungen, versionierte Repository-Konfiguration (Berechtigungspolitik mit `deny`-Vorrang, Hooks), Sitzungsdisziplin und menschliche Prüfebene. Kein Einzelmechanismus trägt allein. Das Modul FW-CORE-03 wird hier vollständig wiedergegeben; die konkrete Berechtigungsdatei steht in Kapitel 15.4, die Prüfroutinen in den Kapiteln 22 (FW-CL-06) und 26 (Testklassen PI, DS, ZA).
+
+{{EMBED-RAW:.koolie/core/framework/core/03-security.md:1}}

package/.koolie/core/build/doc/13-risiko.md

@@ -0,0 +1,5 @@
+# 13 Risikoklassifizierung
+
+Die Risikoklassifizierung ist das operative Steuerungsinstrument je Aufgabe – ausdrücklich keine rechtliche Klassifizierung. Dreizehn Faktoren (Umfang, Kritikalität, Sicherheitsrelevanz, Datenschutzbezug, Produktionsnähe, Reversibilität, Testbarkeit, Reichweite, externe Abhängigkeiten, Authentifizierung/Autorisierung, Datenmodelle und Schnittstellen, Automatisierungsgrad, Fehlerfolgen) bestimmen nach dem Maximumprinzip eine von drei Kontrollstufen; jeder Stufe sind zulässige Betriebsmodi, Prüfungen, Freigaben, Dokumentationsumfang und Eskalationskriterien zugeordnet. Ergänzend fixiert die Delegationsverbotsliste V1–V12, was unabhängig von jeder Stufe nie an den Assistenten geht. Keine Einstufung ersetzt die menschliche Prüfung. Das Modul FW-CORE-09 wird hier vollständig wiedergegeben; die Anwendung ist Teil des Preflights (FW-CL-01, Entscheidungsbaum 2).
+
+{{EMBED-RAW:.koolie/core/framework/core/09-risk-model.md:1}}

package/.koolie/core/build/doc/14-rollen.md

@@ -0,0 +1,9 @@
+# 14 Rollen und Verantwortlichkeiten
+
+Verantwortung im Framework liegt ausnahmslos bei Menschen; der Assistent ist Werkzeug und taucht in keiner Verantwortungszuordnung auf (P1). Alle Rollen sind generisch; die Zuordnung zu Personen erfolgt außerhalb des Repositorys im Teamverzeichnis der Organisation.
+
+Die Rollenlandschaft in Kürze: Der **Framework Owner** verantwortet Core, Releases, Prioritätshierarchie, Testkatalog und Produktbeobachtung; **Modul-Owner** verantworten einzelne Packs und Skill-Gruppen. Je Projekt verantwortet der **Overlay Owner** (`<APPROVAL_ROLE>`) die Projektkonfiguration, Freigaben der Stufe hoch und Ausnahmen; **`<SECURITY_CONTACT>`** und **`<DATA_PROTECTION_CONTACT>`** tragen die Sicherheits- beziehungsweise Datenschutzfreigaben und die Vorfallbehandlung; **`<PRODUCT_OWNER_ROLE>`** und **`<ARCHITECT_ROLE>`** entscheiden fachliche beziehungsweise architektonische Fragen; **Reviewerinnen und Reviewer** prüfen nach den Review-Regeln; **Mentorinnen und Mentoren** begleiten das Onboarding bis zur dokumentierten Freigabe; **Entwicklerinnen und Entwickler** verantworten jede einzelne Nutzung von Preflight bis Ergebnisbericht; die **Projektleitung** verantwortet Pilot und Einführungsentscheidungen. Bei Personalunion in kleinen Teams bleibt das Vier-Augen-Prinzip je Aktivität verpflichtend erhalten.
+
+Die verbindliche Kurzfassung der Framework-Rollen enthält das Governance-Grundsatzmodul FW-CORE-01 (nachfolgend vollständig); die vollständige Aktivitäten-RACI-Vorlage steht in Kapitel 25.2, die projektbezogenen Zuständigkeiten definiert das Overlay in den Abschnitten 15 und 16.
+
+{{EMBED-RAW:.koolie/core/framework/core/01-governance.md:1}}

package/.koolie/core/build/doc/15-referenzstruktur.md

@@ -0,0 +1,124 @@
+# 15 Technische Referenzstruktur
+
+## 15.1 Belegstatus und Durchsetzungstiefe
+
+Für die Struktur wurden keine Client-Konventionen erfunden. Jede verwendete Konvention trägt einen **Belegstatus** – **offiziell dokumentiert** `[DOK]`, **technisch begründete Empfehlung** `[EMPF]` (aus dokumentierten Mechanismen abgeleitet, noch nicht in einer Installation ausgeführt), **konzeptioneller Vorschlag** `[KONZ]` (Framework-Konvention ohne Produktbezug) oder **noch nicht belegt** (`BELEG OFFEN`, mit Grund und Datum).
+
+Die Zuordnung von Mechanismen zu Dateinamen ist keine Eigenschaft des Frameworks, sondern eine des jeweiligen Client Packs (Kap. 7a) – dort wird sie geführt, versioniert und maschinenlesbar gehalten. Dieses Kapitel bettet sie ein, statt sie ein zweites Mal aufzuschreiben.
+
+Der Belegstatus beantwortet die Frage „ist das dokumentiert?“. Die **Fähigkeitsmatrix** beantwortet die zweite, wichtigere: „setzt der Client es durch?“ Beide zusammen ergeben die Durchsetzungstiefe einer Zusage. Für das Client Pack, das dieses Dokument als durchgehendes Beispiel verwendet:
+
+{{EMBED-RAW:.koolie/core/clients/devin-desktop/CLIENT_PACK.md:1}}
+**Die Spalte „Einstufung“ nennt die vorgesehene Durchsetzungstiefe, die Spalte „Beleg“ ihren Nachweisstand** – beide stehen je Zeile, und das ist der Punkt: Ein Gesamturteil über eine Matrix gibt es nicht. Für dieses Pack ist Roadmap-AP2 abgeschlossen; welche Zeilen an einer laufenden Installation beobachtet sind, sagt die Belegspalte, und genau eine sagt noch `BELEG OFFEN` – dauerhaft, weil von außen nicht beobachtbar, was ein Client indexiert. **Zwei der Messungen sind zum Schlechteren ausgegangen**, haben also die zuvor vorgesehene Einstufung widerlegt; das steht in den betreffenden Zeilen und ist nicht eingeebnet worden.
+
+## 15.2 Repository-Struktur
+
+Der gesamte unveränderliche Kern liegt in **einem** Verzeichnis: `.koolie/core/`. Im Wurzelverzeichnis des Projekts stehen nur die Dinge, die dort stehen müssen: die Wurzel-Anweisungsdatei und die Laufzeitschicht, weil der KI-Client sie ausschließlich dort findet, sowie `.koolie/project-overlay/` als austauschbare Projektkonfiguration. Wie diese Bestandteile heißen, entscheidet das gewählte Client Pack. **Der Baum unten nennt sie deshalb mit ihren Platzhaltern** (D-310) – so gilt er für alle ausgelieferten Packs; Anhang 31.2 löst jeden davon je Pack auf.
+
+Angelegt und aktualisiert werden die Wurzelbestandteile durch `.koolie/core/install.py`. Damit ist die Übernahme in ein Projekt das Kopieren eines Ordners und ein Skriptaufruf (Kap. 28). `install.py --target <projekt>` erledigt beides in einem Schritt: Es kopiert **nur** `.koolie/core/`, nie ganz `.koolie/` (D-354), und installiert danach mit dem kopierten Skript. Zwei Starter in der Wurzel des Release-Archivs, `install.cmd` für Windows und `install.command` für macOS, fragen die Angaben dafür ab – Projektverzeichnis, Client Pack, Overlay-Muster (D-362). Voraussetzung auf dem Zielrechner ist Python ab 3.8 (D-363). Unter Windows prüft `--target` vor der ersten Kopie, ob ein Pfad im Zielprojekt die Längengrenze reißt, und kopiert dann nichts (D-368). `--lieferumfang` wählt zwischen dem ganzen Kern (`voll`) und dem Kern ohne die Nachweisschicht aus Änderungsanträgen, Abnahmeprotokollen, Erhebungen und `build/` (`nutzung`); die Wahl steht im Projekt in `.koolie/core/LIEFERUMFANG` und gilt beim Heben weiter (D-367). `--overlay general` legt bei der Erstinstallation statt des leeren Overlays das Overlay-Muster *General Development* an (D-355).
+
+```text
+<REPOSITORY_NAME>/                       # Projekt-Repository
+├── <ROOT_INSTRUCTION_FILE>              # Wurzel-Anweisungsdatei (Kap. 16), erzeugt
+├── <ROOT_INSTRUCTION_LOCAL>.example     # Vorlage persönliche Ergänzung, erzeugt
+│                                        #   (nicht bei jedem Pack, siehe dessen Abschnitt 5)
+├── <MCP_FILE>.example                   # MCP-Vorlage (Standard: keine Server), wo das
+│                                        #   Pack eine eigene MCP-Datei hat
+├── .gitignore                           # gehört dem Projekt; install.py meldet, welche
+│                                        #   Kerndateien es ignoriert (D-349)
+├── <RUNTIME_DIR>/                       # LAUFZEITSCHICHT – vollständig erzeugt
+│   ├── README.md                        # Mechanismen, Modi, Sitzungsfreigaben
+│   ├── rules/                           # 00/10/15 Core-Kurzfassungen · 20 Overlay
+│   │                                    # · 2N Overlay-Erweiterungen · 30 Role Packs
+│   │                                    # · 40 Technology Packs · Vorlagen
+│   │                                    # · je nach Pack eine Befehlsregeldatei
+│   ├── skills/                          # fw-*: 12 Referenz-Skills · role-*/tech-*:
+│   │                                    #   aktivierte Packs · prj-*: projekteigene
+│   ├── agents/fw-reviewer.md            # nur lesendes Review-Subagentenprofil
+│   ├── <PERMISSIONS_FILE>               # Berechtigungen deny/ask/allow; im JSON-Format
+│   │                                    #   mit Integritätsblock
+│   └── <HOOKS_FILE>                     # Hook-Konfiguration – je nach Pack dieselbe
+│                                        #   Datei wie <PERMISSIONS_FILE> (D-32, siehe unten)
+│
+├── .koolie/                             # ein Verzeichnis für Kern und Projektkonfiguration
+│   ├── core/                            # DER KERN – byte-gleich zum Release
+│   │                                    # (bei `nutzung` ohne die mit † markierten Ablagen)
+│   │   ├── install.py                   # legt die Wurzelbestandteile an (--update / --check / --target)
+│   │   ├── install_dialog.py            # Dialog hinter den Startern des Archivs (D-362)
+│   │   ├── clientmap.py                 # Semantikabbildung Berechtigungen und Hooks (Kap. 7a)
+│   │   ├── VERSION · CHANGELOG.md       # Versionsstand, Änderungsverzeichnis
+│   │   ├── LICENSE · LICENSE-HINWEIS.md # Lizenz und Hinweis dazu
+│   │   ├── LIEFERUMFANG                 # nur im Projekt: voll | nutzung (D-367)
+│   │   ├── OWNERS.md                    # Ownership je Bereich (Governance)
+│   │   ├── clients/                     # ABBILDUNGSSCHICHT – je Client drei Dateien
+│   │   │   ├── README.md · _template/   # Regeln der Schicht, Vorlage für neue Packs
+│   │   │   ├── claude-code/             # CLIENT_PACK.md · manifest.json · root-template/
+│   │   │   ├── devin-desktop/           # dito
+│   │   │   └── openai-codex/            # dito
+│   │   ├── framework/                   # KANONISCHE, WERKZEUGNEUTRALE EBENE
+│   │   │   ├── core/00…10-*.md          # Framework Core, elf Module (Kap. 6, 10–14, 18, 25)
+│   │   │   ├── runtime/                 # Laufzeitfassung, einmal für alle Clients:
+│   │   │   │                            # Wurzel-Anweisung · Regeltexte · Agentenprofil
+│   │   │   │                            # · permissions.json · hooks.json · Vorlagen
+│   │   │   ├── skills/                  # fw-* Referenz-Skills, eine Quelle je Skill
+│   │   │   ├── role-packs/              # Ebene 6 – RP-DEV und RP-RE ausgeliefert
+│   │   │   ├── tech-packs/              # Ebene 5 – Vorlage, kein konkretes Pack
+│   │   │   ├── overlay-patterns/        # Overlay-Muster general (--overlay general, D-355)
+│   │   │   └── org-policies/            # Ebene B: Einbindungspunkt + Klassifizierungs-Mapping
+│   │   ├── templates/                   # Project-Overlay-Saat · Regelvorlagen · SKILL_TEMPLATE
+│   │   ├── prompts/                     # Prompt-Bibliothek FW-PR-001…012 + README (Kap. 21)
+│   │   ├── checklists/                  # FW-CL-01…11 + README (Kap. 22)
+│   │   ├── decision-trees/              # FW-DT-01…06 + README (Kap. 23; Mermaid validiert)
+│   │   ├── onboarding/                  # QUICKSTART · GUIDE · MENTOR_CHECKLIST · exercises/
+│   │   │                                # · KNOWLEDGE_CHECK · COMPLETION_CRITERIA · REFERENCE
+│   │   ├── examples/                    # ausschließlich synthetische Beispiele
+│   │   ├── governance/                  # DECISION_LOG · RACI · PRIORITY_HIERARCHY
+│   │   │                                # · RELEASE_PROCESS · ADOPTION_REGISTRY
+│   │   │                                # · EXCEPTION/FEEDBACK/INCIDENT · change-requests/ †
+│   │   ├── pilot/                       # PILOT_CONCEPT · METRICS (Kap. 27)
+│   │   ├── docs/                        # ADOPTION_GUIDE · ROADMAP · RUNTIME_GLOSSARY
+│   │   │                                # · PLACEHOLDER_REGISTRY
+│   │   ├── tests/                       # TEST_CATALOG.md · EDGE_CASES.md · scripts/
+│   │   │                                # · protocols/ † · erhebungen/ †
+│   │   └── build/ †                     # Assemblierung dieses Dokuments aus den Kapitelquellen
+│   │
+│   └── project-overlay/                 # EBENE 4 (austauschbar; Kap. 17)
+│       ├── OVERLAY.md                   # 21 Abschnitte mit Ausfüllhinweisen
+│       ├── overlay-manifest.yaml        # Register eingebundener Dokumente
+│       ├── forbidden-terms.txt          # projektlokale Sperrbegriffe (verbleibt im Projekt)
+│       ├── documents/<13 Typverzeichnisse>/  # freigegebene Dokumente/Auszüge + README
+│       └── exceptions/EXCEPTIONS.md     # Ausnahmeregister des Projekts
+│
+└── <Produktivcode des Projekts>         # backend/, frontend/, src/, test/ …
+```
+
+**Warum diese Aufteilung.** Lägen die Verzeichnisse und Dateien des Kerns direkt im Wurzelverzeichnis neben dem Produktivcode, wäre bei jeder Übernahme und Aktualisierung zu klären, was zum Framework gehört und was zum Projekt. Die Bündelung ändert nichts an der inhaltlichen Ebenenhierarchie (Kap. 7); sie trennt lediglich physisch, was ohnehin logisch getrennt ist: Der Kern ist ein Ordner, den man ersetzt; das Projekt ist alles daneben.
+
+**Die Laufzeitschicht ist Erzeugnis, nicht Quelle.** Kein Bestandteil von ihr wird von Hand geschrieben. Regeltexte, Skills, Agentenprofil, Berechtigungen und Hooks liegen einmal unter `.koolie/core/framework/runtime/` beziehungsweise `framework/skills/` und werden bei der Installation in die Form des gewählten Client Packs gebracht (Kap. 7a). Ein Client Pack selbst enthält **drei Dateien**: die Pfad- und Semantikabbildung (`manifest.json`), die Fähigkeitsmatrix (`CLIENT_PACK.md`) und eine erklärende README der Laufzeitschicht (D-36).
+
+**Die Hook-Konfiguration steht dort, wo der Client sie nachweislich liest, nicht dort, wo seine Dokumentation sie nennt** (D-32). Bei `devin-desktop` und `claude-code` ist das die **Berechtigungsdatei**; eine eigene Hook-Datei wird für sie nicht erzeugt, weil gemessen ist, dass ein Client aus ihr **keinen** Hook ausführte, während dieselbe Konfiguration in der Berechtigungsdatei sofort auslöste (`AP2-DD-10`). `openai-codex` führt die Hook-Konfiguration in einer eigenen Hook-Datei, die dieser Client nachweislich liest (sein Pack, Zeilen H1 bis H3).
+
+**Grenze der Bündelung.** Die Wurzel-Anweisungsdatei und die Laufzeitschicht lassen sich nicht mitverschieben – beide Ladeorte sind Werkzeugkonvention und nicht konfigurierbar `[DOK]`. Die Laufzeitschicht enthält deshalb Kern- und Projektbestandteile gemischt. Genau diese Mischung löst `install.py` auf: **Core** wird bei `--update` überschrieben, **Saat** (Berechtigungsdatei, Overlay, Overlay-Regel) nur bei der Erstinstallation angelegt und danach nie wieder angefasst. `--check` meldet, wenn eine Core-Datei im Wurzelverzeichnis lokal verändert wurde – also an der falschen Stelle bearbeitet.
+
+Damit sind alle geforderten Inhalte logisch abgebildet: zentrale Agentenanweisungen, Framework Core, Datenschutz- und Sicherheitsregeln (Core 02/03 plus Laufzeitregel 10), allgemeine Entwicklungsregeln (Core 04/06/07 plus Laufzeitregel 15), projektspezifisches Overlay, Rollenmodule, Technologiepakete, Skills, Skill-Vorlagen, Prompt-Vorlagen, Checklisten, Onboarding, Beispiele, Tests und Validierungen der Agentenanweisungen, Änderungsverzeichnis sowie Governance und Ownership.
+
+## 15.3 Laufzeitschicht im Detail
+
+Die folgende Dokumentationsdatei der Laufzeitschicht beschreibt verbindlich, was der KI-Client aus dem Repository liest, welche Mechanismen bewusst nicht verwendet werden, welche Sitzungsfreigaben zulässig sind – und, in einem eigenen Abschnitt, die Systematik der Regelablage:
+
+{{EMBED-RAW:<RUNTIME_DIR>/README.md:1}}
+Diese Systematik steht **hier** und nicht in der Regelablage selbst, weil der KI-Client jede Datei der Regelablage als Regel führt und damit ladbar macht – bei einem Pack sogar unbedingt. **Ein Verzeichnis, das als Regelmenge gelesen wird, enthält nur Regeln** (D-36); erklärender Text steht eine Ebene höher.
+
+## 15.4 Zentrale Konfigurationsdateien
+
+Die folgenden Dateien sind **erzeugt**. Sie stammen aus einer Referenzinstallation, die beim Bau dieses Dokuments angelegt wird – bei einem anderen Client Pack sehen sie anders aus, ohne dass sich eine Regel ändert. Die Quellen liegen unter `.koolie/core/framework/runtime/`. **Bei `devin-desktop` und `claude-code` zeigen Berechtigungsdatei und Hook-Konfiguration auf dieselbe Datei**; sie wird dann einmal abgedruckt, und die zweite Stelle verweist darauf – zweimal dieselbe Datei abzudrucken ließe den Leser einen Unterschied suchen, den es nicht gibt.
+
+**Berechtigungen** – restriktiver Standard; bei einer Berechtigungsdatei im JSON-Format mit Kernregel-Integritätsblock. Die Regelmenge ist werkzeugneutral; Werkzeugnamen, Musterform und der Integritätsblock entstehen aus der Semantikabbildung des Client Packs (Kap. 7a, `clientmap.py`):
+
+{{EMBED:<PERMISSIONS_FILE>:permissions_format}}
+**Hooks** – technische Prüfung vor Werkzeugaufrufen sowie Statusmeldung beim Sitzungsstart (Einstufung des Mechanismus: Block H der Fähigkeitsmatrix des Packs, D-396; Skripte `[EMPF]`; die Skripte selbst tragen den Status `entwurf` – sie sind Werkzeuge und keine Modulträger und zählen für Kriterium 3 der 1.0.0-Definition nicht mit):
+
+{{EMBED:<HOOKS_FILE>:json}}
+**Subagentenprofil** – nur lesende Review-Zulieferung:
+
+{{EMBED:<AGENTS_DIR>/fw-reviewer.md}}

package/.koolie/core/build/doc/16-agentenanweisung.md

@@ -0,0 +1,8 @@
+# 16 Zentrale Agentenanweisung
+
+Die zentrale Agentenanweisung ist die produktionsnahe Vorlage der Wurzel-Anweisungsdatei im Workspace-Wurzelverzeichnis. Sie wird vom KI-Client zu Beginn jeder Sitzung als always-on-Regel geladen `[DOK]`, bleibt bewusst unter der konservativ angesetzten 12.000-Zeichen-Grenze und regelt alle im Auftrag geforderten Punkte: Rolle des Agenten (1), Priorität und Hierarchie der Anweisungen (2), zulässigen Arbeitsbereich (3), Umgang mit fehlendem Kontext und Rückfragen statt Annahmen (4), Analyse vor Änderung (5), zulässige Dateioperationen (6), Befehlsausführung (7), Umgang mit Tests (8) und Fehlern (9), Änderungsumfang und Nachvollziehbarkeit (10), Datenschutz, Secrets und personenbezogene Daten (11), Sicherheit einschließlich Prompt-Injection-Abwehr (12), Abhängigkeiten und Architekturentscheidungen (13), Dokumentationspflicht sowie Commit- und Merge-Request-Unterstützung (14), menschliche Prüfung und Freigabe (15), Abbruch- und Eskalationsbedingungen (16) und die Skill-/Modusbindung (17). Projektwerte erscheinen ausschließlich als Platzhalter; die Datei wird nur über den Framework-Änderungsprozess geändert und ist für den KI-Client selbst schreibgesperrt (Berechtigungen und Hook).
+
+**Der Abstand zur Grenze ist klein und wird gemessen, nicht geschätzt.** Gemessen wird an der erzeugten Datei und nicht an der Quelle, weil die Platzhalter beim Erzeugen aufgelöst werden und die Länge sich dabei ändert. Gezählt am 2026-09-22: 11.887 Zeichen beim Pack `devin-desktop` und 11.894 bei `claude-code` – 113 beziehungsweise 106 Zeichen unter der Grenze; die Quelle allein war 11.924 Zeichen lang. Die Grenze ist eine Vorgabe des Frameworks und keine Produkteigenschaft: Ein Abgleich gegen die Herstellerdokumentation hat für Regeldateien keine Zeichengrenze gefunden (Anhang 31.5, V1). Seit `1.9.2` ist sie eine Warnung; verbindlich ist die Summe, die jede Sitzung lädt – Wurzel-Anweisung und unbedingt geladene Regeln zusammen höchstens 40.000 Zeichen (D-387).
+
+{{EMBED:<ROOT_INSTRUCTION_FILE>}}
+{{LOKALE-ERGAENZUNG}}

package/.koolie/core/build/doc/17-overlay.md

@@ -0,0 +1,29 @@
+# 17 Projekt-Overlay
+
+Das Project Overlay ist die einzige Stelle, an der ein Projekt das Framework konfiguriert. Die Vorlage enthält alle geforderten Abschnitte – Projektsteckbrief, technische Architektur, Repository-Struktur, erlaubte und ausgeschlossene Verzeichnisse, Build- und Testbefehle, Qualitätsprüfungen, Sprachen und Frameworks, Coding Conventions, Branching- und Merge-Modell, Definition of Ready und Done, zulässige Kontexte, ausgeschlossene Daten, Rollen und Freigaben, Eskalationsweg, projektspezifische Skills, dokumentierte Ausnahmen – durchgängig mit Platzhaltern und Ausfüllhinweisen, dazu den Aktivierungsmechanismus (Status `aktiv` erst nach Projektübernahme-Checkliste und strikter Validierung) und den Änderungsverlauf.
+
+Kernstück der geforderten Overlay-Erweiterung ist der **Manifest-Mechanismus** (Abschnitt 19 der Vorlage): Künftige projektspezifische Dokumente – KI-Governance-Rahmenwerk, KI-Vorgehensmodell, Projektroadmap, Architekturvorgaben, Coding Guidelines, Definition of Ready, Definition of Done, Branching-Strategie, Deployment-Vorgaben, Security-Vorgaben, Qualitätsrichtlinien, Rollenbeschreibungen, Projektglossar – werden unter `.koolie/project-overlay/documents/<typ>/` abgelegt (oder als Verweisblatt geführt), im Manifest mit Kontextklasse, Status, Freigabe und Ladeverhalten registriert und je nach Ladeverhalten als Kurzfassung (`summary`), bei Bedarf (`on-demand`), als eigene Overlay-Regeldatei (`rule`, der Regelablage `2N-*`) oder gar nicht (`never`) für den Assistenten wirksam. Nicht registrierte Dokumente gelten als K3. Der Framework Core bleibt dabei in jedem Fall unverändert.
+
+## 17.1 Overlay-Vorlage
+
+{{EMBED:.koolie/core/templates/project-overlay/OVERLAY.md}}
+## 17.2 Manifest-Vorlage
+
+{{EMBED:.koolie/core/templates/project-overlay/overlay-manifest.yaml:yaml}}
+## 17.3 Laufzeitfassung (always-on-Regel)
+
+Die kompakte, immer geladene Laufzeitfassung des Overlays – vom Projekt synchron zur Vorlage gepflegt, unter 6.000 Zeichen:
+
+{{EMBED:<RULES_DIR>/20-project-overlay.md}}
+## 17.4 Vorlage für Overlay-Regelerweiterungen
+
+Für Dokumente mit Ladeverhalten `rule`:
+
+{{EMBED:.koolie/core/templates/rules/21-overlay-TEMPLATE.md.template}}
+## 17.5 Begleitdateien
+
+Regeln des Dokumentenverzeichnisses und Ausnahmeregister:
+
+{{EMBED-RAW:.koolie/core/templates/project-overlay/documents/README.md:1}}
+{{EMBED-RAW:.koolie/core/templates/project-overlay/exceptions/EXCEPTIONS.md:1}}
+Ein vollständig ausgefülltes Beispiel (synthetisch) der Laufzeitfassung zeigt `.koolie/core/examples/example-overlay-runtime.md` (im Repository enthalten).

package/.koolie/core/build/doc/18-skill-standard.md

@@ -0,0 +1,5 @@
+# 18 Skill-Standard
+
+Der Skill-Standard definiert einheitlich, was ein Skill ist, wie er abgelegt, benannt, versioniert, getestet und gepflegt wird und welche 23 Pflichtinhalte jeder Skill trägt – von ID, Version, Status und Zweck über Trigger, Vorbedingungen, Eingaben, Kontextquellen und ausgeschlossene Informationen bis zu Arbeitsschritten, Grenzen, Rückfragenregeln, Ausgabeformat, Qualitätskriterien, Prüf- und Freigabeschritt, Fehlerbehandlung, Beispielen, Negativbeispielen, Testfällen, Owner und Änderungsverlauf. Normative Anweisungen (SKILL.md) und erläuternde Beispiele (EXAMPLES.md) sind dateiweise getrennt; Testfälle (TESTS.md) und Änderungsverlauf (CHANGELOG.md) machen jeden Skill einzeln prüf- und wartbar. Das Modul FW-CORE-08 wird hier vollständig wiedergegeben.
+
+{{EMBED-RAW:.koolie/core/framework/core/08-skill-conventions.md:1}}

package/.koolie/core/build/doc/19-skill-template.md

@@ -0,0 +1,5 @@
+# 19 Skill-Template
+
+Das vollständig ausfüllbare, kommentierte Skill-Template setzt den Standard aus Kapitel 18 in eine Datei um: dokumentiertes Frontmatter (nur belegte Felder), Metadatentabelle, die sieben Pflichtabschnitte mit Ausfüllhinweisen als Kommentare sowie vorbereitete Fehlerbehandlungs- und Qualitätskriterienblöcke. Neue Skills entstehen ausschließlich aus dieser Vorlage; die strukturelle Konformität prüft `.koolie/core/tests/scripts/validate-framework.py`.
+
+{{EMBED:.koolie/core/templates/SKILL_TEMPLATE.md}}

package/.koolie/core/build/doc/20-referenz-skills.md

@@ -0,0 +1,70 @@
+# 20 Referenz-Skills
+
+Die dreizehn Referenz-Skills decken die geforderten Aufgaben ab und bilden zusammen den Standardweg jeder Änderung (verstehen → bewerten → planen → umsetzen → testen → prüfen → beschreiben). Jeder Skill ist projektneutral, verlangt Rückfragen bei Unklarheiten, macht Annahmen sichtbar, begrenzt den Scope, definiert Prüfungen, besitzt ein festes Ausgabeformat und bringt Positiv- wie Negativtestfälle mit (mindestens zwei beziehungsweise drei je Skill; gezählt am 2026-09-22: je zwei Positiv- und drei bis fünf Negativtestfälle, zusammen 72 Zellen).
+
+Alle dreizehn stehen im Status `pilot`, Owner `<FRAMEWORK_OWNER>`; sie durchlaufen den Lebenszyklus aus Kapitel 18, und ihre Versionen stehen in der Metadatentabelle jeder SKILL.md. Ihre Testzellen sind an einer laufenden Sitzung abgenommen, nicht abgezeichnet – der Ergebnisstatus jeder Zelle nennt sein Protokoll und das gemessene Client Pack mit Produktstand.
+
+**Ein vierzehnter Skill liegt außerhalb dieses Kapitels:** `role-re-ticket` gehört zum Role Pack Requirements Engineering (Ebene 6, Kap. 7.3) und wird nicht mit dem Kern installiert, sondern mit dem Pack aktiviert. Er bringt fünf Positiv- und zehn Negativtestfälle mit.
+
+| ID | Skill (`/aufruf`) | Auftragspunkt | Modus | Werkzeuge | Trigger |
+|---|---|---|---|---|---|
+| FW-SK-001 | `fw-repo-analyze` | Repository analysieren | M1 | read, grep, glob | user, model |
+| FW-SK-002 | `fw-code-explain` | Bestehenden Code erklären | M1 | read, grep, glob | user, model |
+| FW-SK-003 | `fw-change-analyze` | Änderung fachlich und technisch analysieren | M1 | read, grep, glob | user, model |
+| FW-SK-004 | `fw-plan` | Implementierungsplan erzeugen | M2 | read, grep, glob | user, model |
+| FW-SK-005 | `fw-change-small` | Kleine Codeänderung umsetzen | M3 | read, grep, glob, edit, exec | user |
+| FW-SK-006 | `fw-tests` | Unit Tests erstellen oder erweitern | M4 | read, grep, glob, edit, exec | user |
+| FW-SK-007 | `fw-refactor` | Code refaktorieren | M3 | read, grep, glob, edit, exec | user |
+| FW-SK-008 | `fw-error-analyze` | Fehler analysieren | M1 | read, grep, glob | user, model |
+| FW-SK-009 | `fw-bugfix-prepare` | Bugfix vorbereiten | M2 | read, grep, glob | user, model |
+| FW-SK-010 | `fw-review-support` | Code Review unterstützen | M1 | read, grep, glob, exec (nur lesende Git-Befehle) | user |
+| FW-SK-011 | `fw-docs-update` | Dokumentation aktualisieren | M5 | read, grep, glob, edit | user |
+| FW-SK-012 | `fw-mr-description` | Merge-Request-Beschreibung erstellen | M5 | read, grep, glob, exec (nur lesende Git-Befehle) | user |
+| FW-SK-013 | `fw-overlay-pflege` | Entscheidungen in das Overlay eintragen (Einrichtung, Framework-Update, Eintrag) | M6 | read, grep, glob, edit, exec (Prüfbefehle, lesende Git-Befehle) | user |
+
+Nachfolgend die normativen Skill-Dateien (SKILL.md) aller dreizehn Skills. Die Begleitdateien (EXAMPLES.md mit synthetischen Positiv- und Negativbeispielen, TESTS.md mit den Testfällen, CHANGELOG.md) liegen je Skill im Repository; stellvertretend ist für FW-SK-001 der vollständige Satz wiedergegeben (Abschnitt 20.13).
+
+## 20.1 FW-SK-001 `fw-repo-analyze`
+
+{{EMBED:<SKILLS_DIR>/fw-repo-analyze/SKILL.md}}
+## 20.2 FW-SK-002 `fw-code-explain`
+
+{{EMBED:<SKILLS_DIR>/fw-code-explain/SKILL.md}}
+## 20.3 FW-SK-003 `fw-change-analyze`
+
+{{EMBED:<SKILLS_DIR>/fw-change-analyze/SKILL.md}}
+## 20.4 FW-SK-004 `fw-plan`
+
+{{EMBED:<SKILLS_DIR>/fw-plan/SKILL.md}}
+## 20.5 FW-SK-005 `fw-change-small`
+
+{{EMBED:<SKILLS_DIR>/fw-change-small/SKILL.md}}
+## 20.6 FW-SK-006 `fw-tests`
+
+{{EMBED:<SKILLS_DIR>/fw-tests/SKILL.md}}
+## 20.7 FW-SK-007 `fw-refactor`
+
+{{EMBED:<SKILLS_DIR>/fw-refactor/SKILL.md}}
+## 20.8 FW-SK-008 `fw-error-analyze`
+
+{{EMBED:<SKILLS_DIR>/fw-error-analyze/SKILL.md}}
+## 20.9 FW-SK-009 `fw-bugfix-prepare`
+
+{{EMBED:<SKILLS_DIR>/fw-bugfix-prepare/SKILL.md}}
+## 20.10 FW-SK-010 `fw-review-support`
+
+{{EMBED:<SKILLS_DIR>/fw-review-support/SKILL.md}}
+## 20.11 FW-SK-011 `fw-docs-update`
+
+{{EMBED:<SKILLS_DIR>/fw-docs-update/SKILL.md}}
+## 20.12 FW-SK-012 `fw-mr-description`
+
+{{EMBED:<SKILLS_DIR>/fw-mr-description/SKILL.md}}
+## 20.13 FW-SK-013 `fw-overlay-pflege`
+
+{{EMBED:<SKILLS_DIR>/fw-overlay-pflege/SKILL.md}}
+## 20.14 Begleitdateien am Beispiel FW-SK-001 (vollständiger Satz)
+
+{{EMBED:<SKILLS_DIR>/fw-repo-analyze/EXAMPLES.md}}
+{{EMBED:<SKILLS_DIR>/fw-repo-analyze/TESTS.md}}
+{{EMBED:<SKILLS_DIR>/fw-repo-analyze/CHANGELOG.md}}