@renoxar/koolie 1.25.0

package/QUICKSTART.en.md

@@ -0,0 +1,135 @@
+# Quickstart – try Koolie in ten minutes
+
+*Deutsche Fassung: [QUICKSTART.md](QUICKSTART.md). The German version is authoritative; all further
+documentation is in German and marked (German).*
+
+This quickstart installs Koolie into an **empty practice repository** and shows what is created. It does not
+start an AI client and does not change any existing project. The client pack `claude-code` serves as the
+example; every other pack works the same way (step 3).
+
+To adopt Koolie in an **existing** project, read the [adoption guide](.koolie/core/docs/ADOPTION_GUIDE.md)
+(German) afterwards. For the first working day in a project that already uses Koolie, start with the
+[onboarding quick start](.koolie/core/onboarding/QUICKSTART.md) (German).
+
+## Prerequisites
+
+- **Git** and **Python 3.8 or later** (no additional packages). If Python is called `python3` on your system,
+  use that instead of `python` in all commands below.
+- A command line with a POSIX shell – on Windows, for example, Git Bash. Step 2 can also be done with the
+  starters `install.cmd` (Windows) or `install.command` (macOS) in the root of the release archive; they ask
+  for the same information. The other steps need the command line.
+- Koolie itself: the **unpacked release archive** or a **clone** of this repository. Steps 1 to 4 run from its
+  root directory, steps 5 and 6 inside the practice repository.
+- **Or from a package source**, without archive or clone: `uvx koolie` (also `pipx run koolie`, `npx @renoxar/koolie`)
+  replaces `python .koolie/core/install.py` in steps 2 and 3, and steps 1 to 4 run from any directory; the
+  command shows the banner first. If you installed it with `pip install koolie` and `koolie` is not found, run
+  `python -m koolie`.
+
+All output of the installer and the validator is in German; this guide quotes the lines you need.
+
+## Step 1: Create a practice repository
+
+```bash
+mkdir ../koolie-uebung
+git -C ../koolie-uebung init
+echo "# Practice project" > ../koolie-uebung/README.md
+git -C ../koolie-uebung add README.md
+git -C ../koolie-uebung commit -m "Start"
+```
+
+## Step 2: Install Koolie
+
+```bash
+python .koolie/core/install.py --target ../koolie-uebung --client claude-code
+```
+
+From a package source, the same step is `uvx koolie --target ../koolie-uebung --client claude-code`.
+Without arguments, `uvx koolie` started inside the practice repository opens the dialog with that directory as
+the default.
+
+`--target` copies only the core (`.koolie/core/`) into the practice repository and creates the files the
+client needs there. At the end, the installer lists the next steps for a real project. Its messages are in
+German.
+
+⚠️ On Windows, no copied path may exceed 259 characters. If the practice repository is nested too deeply, the
+installer stops before the first copy and states how many characters are too many. In that case, choose a
+shorter location and replace `../koolie-uebung` with it in all commands – in Git Bash, for example,
+`/c/koolie-uebung`.
+
+## Step 3: Choose a different client (optional)
+
+```bash
+python .koolie/core/install.py --list-clients
+```
+
+shows the available client packs. What each client enforces technically is recorded in its **capability
+matrix**; the [overview of the client packs](.koolie/core/clients/README.md) (German), section 6, summarises
+them. The file names in step 4 apply to `claude-code`; which files another pack creates is listed in the
+[runtime glossary](.koolie/core/docs/RUNTIME_GLOSSARY.md) (German). For this quickstart, `claude-code` is enough.
+
+## Step 4: Look at what was created
+
+| Path in the practice repository | What it is |
+|---|---|
+| `CLAUDE.md` | the **instruction file** the client loads at start – with the framework's rules, for example *"Never: `git push` …"* (in German) |
+| `.claude/settings.json` | the **permission file**: what the client blocks technically (`deny`), asks about (`ask`) or may do without asking (`allow`), plus the hooks |
+| `.claude/rules/`, `.claude/skills/`, `.claude/agents/` | short versions of the rules, the framework's skills and a read-only review profile |
+| `.koolie/core/` | the **core** – identical in every project, never edit by hand |
+| `.koolie/project-overlay/` | the **project overlay** – the project configuration the team fills in |
+
+The blocked publication from the [README](README.en.md#what-is-enforced--and-what-is-not) – `git push` – is in
+`.claude/settings.json`:
+
+```bash
+grep -n "git push" ../koolie-uebung/.claude/settings.json
+```
+
+The output shows `Bash(git push:*)` twice: in `permissions.deny`, where the client reads the block, and in
+`_core_rules_integrity.deny_must_contain`, the list of core rules the validator checks the file against.
+
+## Step 5: Commit and check
+
+```bash
+echo "__pycache__/" > ../koolie-uebung/.gitignore
+git -C ../koolie-uebung add -A
+git -C ../koolie-uebung commit -m "Koolie installed"
+cd ../koolie-uebung
+python .koolie/core/tests/scripts/validate-framework.py
+```
+
+**Expected:** `Ergebnis: 0 Fehler, 0 Warnungen` (result: 0 errors, 0 warnings). Among other things, the
+validator checks that the core rules of the permission file are complete. The `.gitignore` entry is needed
+because the core's tools create Python bytecode on every run; without it, the validator reports a warning.
+
+## Step 6: See what is missing for real use
+
+```bash
+python .koolie/core/tests/scripts/validate-framework.py --check-overlay-ready
+```
+
+**Expected:** several lines containing `FEHLER` (error) and `enthält offene <TBD>-Werte` (contains open
+`<TBD>` values) for files under `.koolie/project-overlay/` and for the overlay rule in `.claude/rules/`. That is
+correct: the overlay has not been filled in yet. Until it has been filled in, reviewed and set to active, the
+agent works read-only in the project. Which
+values a project has to enter and who approves them is described in the
+[adoption guide](.koolie/core/docs/ADOPTION_GUIDE.md) (German).
+
+## Step 7: Run the client against it (optional)
+
+If you have Claude Code installed, you can start a session in the practice repository and ask the assistant
+to push a commit. **Expected** (this is what was measured): the assistant declines; if it tries anyway, the
+client rejects the call. This has **not been re-checked** for this quickstart – it was measured on 2026-09-17
+with Claude Code 2.1.274 ([protocol](.koolie/core/tests/protocols/2026-09-17-sitzungstest-schranken.md),
+German). A model can behave differently – that is why the technical block exists, and why the capability
+matrix names its limit.
+
+## Clean up
+
+The practice repository can be deleted afterwards – seen from the directory where you ran step 1, it is
+`../koolie-uebung`.
+
+## Next steps
+
+- [README](README.en.md): what Koolie is, who it is for, which clients are supported and how far.
+- [Adoption guide](.koolie/core/docs/ADOPTION_GUIDE.md) (German): taking Koolie into an existing project, updates, costs, deployment architecture and coexistence with another agent framework.
+- [Overview of the client packs](.koolie/core/clients/README.md) (German): capability matrices and their evidence.

package/QUICKSTART.md

@@ -0,0 +1,129 @@
+# Quickstart – Koolie in zehn Minuten ausprobieren
+
+*English version: [QUICKSTART.en.md](QUICKSTART.en.md). Die deutsche Fassung ist maßgeblich.*
+
+Dieser Quickstart installiert Koolie in ein **leeres Übungs-Repository** und zeigt, was dabei entsteht. Er
+startet keinen KI-Client und verändert kein bestehendes Projekt. Als Beispiel dient das Client Pack
+`claude-code`; jedes andere Pack funktioniert genauso (Schritt 3).
+
+Wer Koolie in ein **bestehendes** Projekt übernehmen will, liest danach den
+[Übernahmeleitfaden](.koolie/core/docs/ADOPTION_GUIDE.md). Wer in einem Projekt, das Koolie schon nutzt, den
+ersten Arbeitstag hat, beginnt mit dem [Quick-Start des Onboardings](.koolie/core/onboarding/QUICKSTART.md).
+
+## Voraussetzungen
+
+- **Git** und **Python ab 3.8** (ohne Zusatzpakete). Heißt der Aufruf auf dem System `python3`, gilt er in allen
+  Befehlen unten statt `python`.
+- Eine Kommandozeile mit POSIX-Shell – unter Windows zum Beispiel Git Bash. Schritt 2 lässt sich auch mit den
+  Startern `install.cmd` (Windows) oder `install.command` (macOS) in der Wurzel des Release-Archivs erledigen;
+  sie fragen dieselben Angaben ab. Die übrigen Schritte brauchen die Kommandozeile.
+- Koolie selbst: das **entpackte Release-Archiv** oder ein **Klon** dieses Repositorys. Die Schritte 1 bis 4
+  laufen aus dessen Wurzelverzeichnis, ab Schritt 5 im Übungs-Repository.
+- **Oder über eine Paketquelle**, ohne Archiv und ohne Klon: `uvx koolie` (auch `pipx run koolie`,
+  `npx @renoxar/koolie`) ersetzt in den Schritten 2 und 3 den Aufruf `python .koolie/core/install.py`, und die
+  Schritte 1 bis 4 laufen aus einem beliebigen Verzeichnis; der Befehl gibt vorher das Banner aus. Wer ihn mit
+  `pip install koolie` installiert und `koolie` danach nicht findet, ruft `python -m koolie` auf.
+
+## Schritt 1: Ein Übungs-Repository anlegen
+
+```bash
+mkdir ../koolie-uebung
+git -C ../koolie-uebung init
+echo "# Übungsprojekt" > ../koolie-uebung/README.md
+git -C ../koolie-uebung add README.md
+git -C ../koolie-uebung commit -m "Start"
+```
+
+## Schritt 2: Koolie installieren
+
+```bash
+python .koolie/core/install.py --target ../koolie-uebung --client claude-code
+```
+
+Über eine Paketquelle lautet derselbe Schritt `uvx koolie --target ../koolie-uebung --client claude-code`.
+Ohne Argumente startet `uvx koolie` im Übungs-Repository den Dialog, mit diesem Verzeichnis als Vorgabe.
+
+`--target` kopiert nur den Kern (`.koolie/core/`) in das Übungs-Repository und legt dort die Dateien an, die
+der Client braucht. Am Ende nennt der Installer die nächsten Schritte für ein echtes Projekt.
+
+⚠️ Unter Windows darf kein kopierter Pfad länger als 259 Zeichen werden. Liegt das Übungs-Repository zu tief,
+hält der Installer vor der ersten Kopie an und nennt, wie viele Zeichen zu viel sind – dann einen kürzeren Ort
+wählen und `../koolie-uebung` in allen Befehlen durch ihn ersetzen, in Git Bash zum Beispiel `/c/koolie-uebung`.
+
+## Schritt 3: Einen anderen Client wählen (optional)
+
+```bash
+python .koolie/core/install.py --list-clients
+```
+
+zeigt die verfügbaren Client Packs. Welcher Client was technisch durchsetzt, steht in der
+[Übersicht der Client Packs](.koolie/core/clients/README.md), Abschnitt 6. Die Dateinamen in Schritt 4 gelten
+für `claude-code`; welche Dateien ein anderes Pack anlegt, nennt das
+[Laufzeitglossar](.koolie/core/docs/RUNTIME_GLOSSARY.md). Für diesen Quickstart genügt `claude-code`.
+
+## Schritt 4: Ansehen, was entstanden ist
+
+| Pfad im Übungs-Repository | Was es ist |
+|---|---|
+| `CLAUDE.md` | die **Anweisungsdatei**, die der Client beim Start lädt – mit den Regeln des Frameworks, zum Beispiel *„Nie: `git push` …“* |
+| `.claude/settings.json` | die **Berechtigungsdatei**: Was der Client technisch verweigert (`deny`), erfragt (`ask`) oder ohne Rückfrage darf (`allow`), dazu die Hooks |
+| `.claude/rules/`, `.claude/skills/`, `.claude/agents/` | Kurzfassungen der Regeln, die Skills des Frameworks und ein nur lesendes Review-Profil |
+| `.koolie/core/` | der **Kern** – in jedem Projekt gleich, nie von Hand ändern |
+| `.koolie/project-overlay/` | das **Project Overlay** – die Projektkonfiguration, die das Team ausfüllt |
+
+Die gesperrte Veröffentlichung aus der [README](README.md#was-durchgesetzt-wird--und-was-nicht) – `git push` – steht in
+`.claude/settings.json`:
+
+```bash
+grep -n "git push" ../koolie-uebung/.claude/settings.json
+```
+
+Die Ausgabe nennt `Bash(git push:*)` zweimal: in `permissions.deny`, wo der Client die Sperre liest, und in
+`_core_rules_integrity.deny_must_contain`, der Liste der Kernregeln, gegen die der Validator die Datei prüft.
+
+## Schritt 5: Den Stand festhalten und prüfen
+
+```bash
+echo "__pycache__/" > ../koolie-uebung/.gitignore
+git -C ../koolie-uebung add -A
+git -C ../koolie-uebung commit -m "Koolie installiert"
+cd ../koolie-uebung
+python .koolie/core/tests/scripts/validate-framework.py
+```
+
+**Erwartet:** `Ergebnis: 0 Fehler, 0 Warnungen`. Der Validator prüft unter anderem, dass die Kernregeln der
+Berechtigungsdatei vollständig sind. Die `.gitignore` gehört dazu, weil die Werkzeuge des Kerns bei jedem Lauf
+Python-Bytecode erzeugen; ohne sie meldet der Validator eine Warnung.
+
+## Schritt 6: Sehen, was für den echten Einsatz fehlt
+
+```bash
+python .koolie/core/tests/scripts/validate-framework.py --check-overlay-ready
+```
+
+**Erwartet:** mehrere Zeilen mit `FEHLER` und `enthält offene <TBD>-Werte` zu Dateien unter
+`.koolie/project-overlay/` und zur Overlay-Regel in `.claude/rules/`. Das ist richtig so: Das Overlay ist noch
+nicht ausgefüllt. Solange es nicht ausgefüllt, geprüft und auf aktiv gesetzt ist, arbeitet der Agent im
+Projekt nur lesend. Welche Werte
+ein Projekt eintragen muss und wer sie freigibt, beschreibt der
+[Übernahmeleitfaden](.koolie/core/docs/ADOPTION_GUIDE.md).
+
+## Schritt 7: Den Client dagegen laufen lassen (optional)
+
+Wer Claude Code installiert hat, kann im Übungs-Repository eine Sitzung starten und den Assistenten bitten,
+einen Commit zu pushen. **Erwartet**, weil so gemessen: Der Assistent lehnt ab; versucht er es trotzdem,
+weist der Client den Aufruf zurück. Für diesen Quickstart ist das **nicht erneut geprüft** worden – gemessen
+wurde es am 2026-09-17 mit Claude Code 2.1.274
+([Protokoll](.koolie/core/tests/protocols/2026-09-17-sitzungstest-schranken.md)). Ein Modell kann sich
+anders verhalten – deshalb gibt es die technische Sperre, und deshalb nennt die Fähigkeitsmatrix ihre Grenze.
+
+## Aufräumen
+
+Das Übungs-Repository kann danach gelöscht werden – aus dem Verzeichnis, in dem Schritt 1 lief, ist es
+`../koolie-uebung`.
+
+## Wie es weitergeht
+
+- [README](README.md): was Koolie ist, für wen es gedacht ist, welche Clients in welchem Stand unterstützt werden.
+- [Übernahmeleitfaden](.koolie/core/docs/ADOPTION_GUIDE.md): Aufnahme in ein bestehendes Projekt, Aktualisierung, Kosten, Einsatzarchitektur und das Nebeneinander mit einem anderen Agenten-Rahmenwerk.
+- [Übersicht der Client Packs](.koolie/core/clients/README.md): Fähigkeitsmatrizen und ihre Belege.

package/README.en.md

@@ -0,0 +1,108 @@
+# Koolie
+
+**Governance for AI coding assistants – one rule source for every client, enforced technically wherever the client allows it.**
+
+[![PyPI](https://img.shields.io/pypi/v/koolie)](https://pypi.org/project/koolie/)
+[![npm](https://img.shields.io/npm/v/@renoxar/koolie)](https://www.npmjs.com/package/@renoxar/koolie)
+[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](LICENSE)
+
+*Deutsch: [README.md](README.md). The German documentation is authoritative; further documents are in German.*
+
+A team working with AI coding assistants needs more than an instruction file: shared rules for every
+assistant, technical blocks wherever a rule must not be broken, and clear points where a human decides.
+Koolie brings exactly that into an existing Git repository – and states openly, for each client, which rule
+it really enforces and which only acts as an instruction.
+
+## Quick start
+
+In your project directory:
+
+```bash
+uvx koolie                  # or: pipx run koolie · npx @renoxar/koolie
+```
+
+The command fetches Koolie, offers the current directory as the project and asks for your AI client.
+Afterwards the project holds the instruction file, the permissions and a guard hook for that client. Without
+a package registry, use the release archive and the starters `install.cmd` / `install.command`.
+
+**Want to try it first?** The [quickstart](QUICKSTART.en.md) installs Koolie into an empty practice repository
+– in ten minutes, without starting an AI client.
+
+## How it works
+
+```text
+  Core  .koolie/core/            Project overlay  .koolie/project-overlay/
+  rules, skills, checklists,     paths, approval routes, project documents
+  guard hook, validator          – owned by the project
+            │                               │
+            └───────────────┬───────────────┘
+                            ▼
+                Client pack per AI client
+       instruction file · permissions · hooks · skills
+       (e.g. CLAUDE.md and .claude/ for Claude Code)
+```
+
+- **One core for all clients.** Rules and skills are written once, tool-neutral; a team with mixed tools shares
+  the same rules.
+- **The project stays in charge.** Project values live in the overlay. A new release updates a project with the
+  same command: it detects the existing core and offers to upgrade it; the overlay is never touched.
+- **Control levels instead of trust.** The assistant handles small tasks on its own; from "medium" it needs a
+  confirmed plan, at "high" an explicit approval.
+
+## What is enforced – and what is not
+
+| Kind of rule | What it means | Example |
+|---|---|---|
+| **Technical** | The client enforces it, whatever the model does | `git push` is blocked; secret files cannot be read |
+| **Instruction** | The rule is in the model's context; it can follow it | "Do not change files outside the approved scope" |
+| **Human** | Approvals, reviews, decisions | A person approves a release |
+
+Each client pack keeps a **capability matrix** that assigns every promise to one of these kinds – backed by a
+measurement on the client. Koolie complements a good standard setup (branch protection, CI, managed settings);
+it does not replace it.
+
+## Supported clients
+
+| Client | Pack | Status |
+|---|---|---|
+| Claude Code | [`claude-code`](.koolie/core/clients/claude-code/CLIENT_PACK.md) | pilot |
+| Cursor | [`cursor`](.koolie/core/clients/cursor/CLIENT_PACK.md) | pilot |
+| Devin Desktop | [`devin-desktop`](.koolie/core/clients/devin-desktop/CLIENT_PACK.md) | pilot |
+| Kiro | [`kiro`](.koolie/core/clients/kiro/CLIENT_PACK.md) | pilot |
+| OpenAI Codex CLI | [`openai-codex`](.koolie/core/clients/openai-codex/CLIENT_PACK.md) | pilot, only with approval by the security officer |
+
+*Pilot* means: fully built, measured on real installations, meant for accompanied use. The limits of each
+client are listed in its pack (German).
+
+## Who is it for?
+
+- **Development teams** that use AI assistants every day and want shared, verifiable rules.
+- **Technical leads** – team leads, architecture, security, data protection – who must show what a tool
+  enforces technically.
+
+Koolie is not meant for running an agent fully autonomously without human approvals.
+
+## Documentation
+
+| Topic | Where |
+|---|---|
+| Try it in ten minutes | [`QUICKSTART.en.md`](QUICKSTART.en.md) |
+| Adopt in a project, update, costs | [Adoption guide](.koolie/core/docs/ADOPTION_GUIDE.md) (German) |
+| First day in a project that uses Koolie | [Onboarding](.koolie/core/onboarding/QUICKSTART.md) (German) |
+| Client packs and capability matrices | [`clients/README.md`](.koolie/core/clients/README.md) (German) |
+| The rules themselves | [`framework/core/`](.koolie/core/framework/core/) (German) |
+| Changes and plans | [`CHANGELOG.md`](.koolie/core/CHANGELOG.md) · [`ROADMAP.md`](.koolie/core/docs/ROADMAP.md) (German) |
+| Contributing to the framework | [`CONTRIBUTING.md`](CONTRIBUTING.md) (German) |
+
+## Why "Koolie"?
+
+A Koolie is an Australian herding dog. It does not drive the herd and does not replace the shepherd – it keeps
+the flock together, on course and within bounds. That is what this framework is meant to do with an AI
+assistant.
+
+## License
+
+[GPL-3.0](LICENSE) with an additional permission: files created from the templates and any output of the tools
+belong to the project that creates them. Merely using Koolie – also commercially – puts no obligations on you;
+the details are in [`LICENSE-HINWEIS.md`](.koolie/core/LICENSE-HINWEIS.md) (German).
+Copyright © 2026 `<FRAMEWORK_OWNER>`.

package/README.md

@@ -0,0 +1,107 @@
+# Koolie
+
+**Governance für KI-Coding-Assistenten – eine Regelquelle für jeden Client, technisch durchgesetzt, wo der Client es kann.**
+
+[![PyPI](https://img.shields.io/pypi/v/koolie)](https://pypi.org/project/koolie/)
+[![npm](https://img.shields.io/npm/v/@renoxar/koolie)](https://www.npmjs.com/package/@renoxar/koolie)
+[![Lizenz: GPL-3.0](https://img.shields.io/badge/Lizenz-GPL--3.0-blue)](LICENSE)
+
+*English: [README.en.md](README.en.md)*
+
+Wer mit KI-Coding-Assistenten im Team arbeitet, braucht mehr als eine Anweisungsdatei: gemeinsame Regeln für
+jeden Assistenten, technische Sperren dort, wo eine Regel nicht verletzt werden darf, und klare Stellen, an
+denen ein Mensch entscheidet. Koolie bringt genau das in ein bestehendes Git-Repository – und sagt für jeden
+Client offen, welche Regel er wirklich erzwingt und welche nur als Anweisung wirkt.
+
+## Schnellstart
+
+Im Verzeichnis des Projekts:
+
+```bash
+uvx koolie                  # oder: pipx run koolie · npx @renoxar/koolie
+```
+
+Der Befehl holt Koolie, zeigt das aktuelle Verzeichnis als Projekt an und fragt nach dem KI-Client. Danach
+liegen im Projekt die Anweisungsdatei, die Berechtigungen und ein Schutz-Hook für diesen Client. Ohne
+Paketquelle geht es mit dem Release-Archiv und den Startern `install.cmd` / `install.command`.
+
+**Erst ausprobieren?** Der [Quickstart](QUICKSTART.md) installiert Koolie in ein leeres Übungs-Repository – in
+zehn Minuten, ohne einen KI-Client zu starten.
+
+## So funktioniert es
+
+```text
+  Kern  .koolie/core/            Project Overlay  .koolie/project-overlay/
+  Regeln, Skills, Checklisten,   Pfade, Freigabewege, Projektdokumente
+  Schutz-Hook, Validator         – gehört dem Projekt
+            │                               │
+            └───────────────┬───────────────┘
+                            ▼
+                  Client Pack je KI-Client
+       Anweisungsdatei · Berechtigungen · Hooks · Skills
+       (z. B. CLAUDE.md und .claude/ für Claude Code)
+```
+
+- **Ein Kern für alle Clients.** Regeln und Skills stehen einmal, werkzeugneutral; ein Team mit gemischten
+  Werkzeugen teilt dieselben Regeln.
+- **Das Projekt bleibt bei sich.** Projektwerte leben im Overlay. Ein neues Release übernimmt ein Projekt mit
+  demselben Befehl: Er erkennt den vorhandenen Kern und bietet das Heben an, das Overlay bleibt unberührt.
+- **Kontrollstufen statt Vertrauen.** Kleine Aufgaben erledigt der Assistent selbst, ab „mittel“ braucht er
+  einen bestätigten Plan, bei „hoch“ eine ausdrückliche Freigabe.
+
+## Was durchgesetzt wird – und was nicht
+
+| Art der Regel | Was das heißt | Beispiel |
+|---|---|---|
+| **Technisch** | Der Client erzwingt sie, egal was das Modell tut | `git push` ist gesperrt; Secret-Dateien sind lesegeschützt |
+| **Als Anweisung** | Die Regel steht im Kontext des Modells; es kann ihr folgen | „Ändere keine Dateien außerhalb des freigegebenen Scopes“ |
+| **Beim Menschen** | Freigaben, Reviews, Entscheidungen | Ein Release gibt ein Mensch frei |
+
+Jedes Client Pack führt eine **Fähigkeitsmatrix**, die jede Zusage einer dieser Arten zuordnet – mit Beleg aus
+einer Messung am Client. Koolie ergänzt eine gute Standardkonfiguration (Branch-Schutz, CI, verwaltete
+Einstellungen); es ersetzt sie nicht.
+
+## Unterstützte Clients
+
+| Client | Pack | Stand |
+|---|---|---|
+| Claude Code | [`claude-code`](.koolie/core/clients/claude-code/CLIENT_PACK.md) | Pilot |
+| Cursor | [`cursor`](.koolie/core/clients/cursor/CLIENT_PACK.md) | Pilot |
+| Devin Desktop | [`devin-desktop`](.koolie/core/clients/devin-desktop/CLIENT_PACK.md) | Pilot |
+| Kiro | [`kiro`](.koolie/core/clients/kiro/CLIENT_PACK.md) | Pilot |
+| OpenAI Codex CLI | [`openai-codex`](.koolie/core/clients/openai-codex/CLIENT_PACK.md) | Pilot, Inbetriebnahme nur mit Freigabe der Sicherheitsverantwortlichen |
+
+*Pilot* heißt: vollständig gebaut, an realen Installationen gemessen, für den begleiteten Einsatz gedacht. Die
+Grenzen jedes Clients stehen in seinem Pack.
+
+## Für wen?
+
+- **Entwicklungsteams**, die KI-Assistenten im Alltag nutzen und gemeinsame, prüfbare Regeln wollen.
+- **Technische Verantwortliche** – Teamleitung, Architektur, Sicherheit, Datenschutz –, die belegen müssen,
+  was ein Werkzeug technisch einhält.
+
+Nicht gedacht ist Koolie für den vollständig autonomen Betrieb eines Agenten ohne menschliche Freigaben.
+
+## Dokumentation
+
+| Thema | Wo |
+|---|---|
+| Ausprobieren in zehn Minuten | [`QUICKSTART.md`](QUICKSTART.md) |
+| In ein Projekt übernehmen, aktualisieren, Kosten | [Übernahmeleitfaden](.koolie/core/docs/ADOPTION_GUIDE.md) |
+| Erster Arbeitstag in einem Projekt mit Koolie | [Onboarding](.koolie/core/onboarding/QUICKSTART.md) |
+| Client Packs und Fähigkeitsmatrizen | [`clients/README.md`](.koolie/core/clients/README.md) |
+| Die Regeln selbst | [`framework/core/`](.koolie/core/framework/core/) |
+| Änderungen und Planung | [`CHANGELOG.md`](.koolie/core/CHANGELOG.md) · [`ROADMAP.md`](.koolie/core/docs/ROADMAP.md) |
+| Am Framework mitarbeiten | [`CONTRIBUTING.md`](CONTRIBUTING.md) |
+
+## Warum „Koolie“?
+
+Ein Koolie ist ein australischer Hütehund. Er treibt die Herde nicht und ersetzt den Schäfer nicht – er hält
+sie beisammen, in Richtung und an den Grenzen. Genau das soll dieses Framework mit einem KI-Assistenten tun.
+
+## Lizenz
+
+[GPL-3.0](LICENSE) mit einer Zusatzerlaubnis: Dateien, die aus den Vorlagen entstehen, und jede Ausgabe der
+Werkzeuge gehören dem Projekt, das sie erzeugt. Wer Koolie nur benutzt – auch kommerziell –, hat daraus keine
+Pflichten; die Einzelheiten stehen in [`LICENSE-HINWEIS.md`](.koolie/core/LICENSE-HINWEIS.md).
+Copyright © 2026 `<FRAMEWORK_OWNER>`.

package/install.cmd

@@ -0,0 +1,44 @@
+@echo off
+rem Koolie - Starter fuer Windows (D-362, CR-2026-140).
+rem
+rem Sucht ein Python ab 3.8 und ruft den Dialog .koolie\core\install_dialog.py auf.
+rem Die Installationslogik steht in install.py; dieser Starter enthaelt keine.
+rem
+rem BEWUSST OHNE SPRUNGMARKEN (goto, call :marke): Das Release-Archiv liefert diese
+rem Datei mit LF-Zeilenenden aus, und cmd.exe findet Sprungmarken in einer LF-Datei
+rem nicht zuverlaessig. Eine Sonde haelt das fest.
+rem
+rem Pfade stehen innerhalb von Klammerbloecken immer in Anfuehrungszeichen: Ein Pfad
+rem wie "C:\Program Files (x86)\..." schloesse den Block sonst an seiner Klammer.
+rem
+rem Der Store-Platzhalter WindowsApps\python.exe startet kein Python; er faellt an der
+rem Versionsprobe durch wie jeder andere Kandidat, der nicht antwortet.
+setlocal
+set "KOOLIE_KERN=%~dp0.koolie\core"
+set "KOOLIE_PY="
+if not exist "%KOOLIE_KERN%\install_dialog.py" (
+    echo FEHLER: install_dialog.py fehlt unter "%KOOLIE_KERN%".
+    echo Dieser Starter gehoert in die Wurzel des entpackten Frameworks.
+) else (
+    for %%K in ("py -3" "python3" "python") do (
+        if not defined KOOLIE_PY (
+            %%~K -c "import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)" >nul 2>&1 && set "KOOLIE_PY=%%~K"
+        )
+    )
+)
+if exist "%KOOLIE_KERN%\install_dialog.py" if not defined KOOLIE_PY (
+    echo Koolie braucht Python 3.8 oder neuer - gefunden wurde keines.
+    echo.
+    echo Installieren, zum Beispiel:
+    echo   winget install Python.Python.3.12
+    echo oder von python.org - dort "Add python.exe to PATH" waehlen.
+    echo Danach ein NEUES Fenster oeffnen und diesen Starter erneut aufrufen.
+)
+set "KOOLIE_RC=1"
+if defined KOOLIE_PY (
+    %KOOLIE_PY% "%KOOLIE_KERN%\install_dialog.py"
+)
+if defined KOOLIE_PY set "KOOLIE_RC=%ERRORLEVEL%"
+echo.
+if not defined KOOLIE_KEINE_PAUSE pause
+endlocal & exit /b %KOOLIE_RC%

package/install.command

@@ -0,0 +1,46 @@
+#!/bin/sh
+# Koolie - Starter fuer macOS (D-362, CR-2026-140).
+#
+# Sucht ein Python ab 3.8 und ruft den Dialog .koolie/core/install_dialog.py auf.
+# Die Installationslogik steht in install.py; dieser Starter enthaelt keine.
+#
+# Ein Doppelklick im Finder oeffnet diese Datei im Terminal. Das setzt das
+# Ausfuehrungsrecht voraus - das Repositorium fuehrt die Datei mit Modus 100755, und
+# eine Sonde haelt es fest. Ohne das Recht: im Terminal "sh install.command".
+#
+# macOS bringt unter /usr/bin/python3 einen Platzhalter mit, der ohne die Command
+# Line Tools kein Python startet, sondern deren Installation anbietet. Er faellt an
+# der Versionsprobe durch wie jeder andere Kandidat, der nicht antwortet.
+#
+# POSIX-sh, keine bash-Eigenheiten: Der Starter soll auch unter Linux und in Git Bash
+# laufen, wo er geprueft wird.
+
+cd "$(dirname "$0")" || exit 1
+KOOLIE_KERN="$(pwd)/.koolie/core"
+KOOLIE_PY=""
+KOOLIE_RC=1
+
+if [ ! -f "$KOOLIE_KERN/install_dialog.py" ]; then
+    echo "FEHLER: install_dialog.py fehlt unter \"$KOOLIE_KERN\"."
+    echo "Dieser Starter gehoert in die Wurzel des entpackten Frameworks."
+else
+    for kandidat in python3 python; do
+        if command -v "$kandidat" >/dev/null 2>&1 && \
+           "$kandidat" -c 'import sys; sys.exit(0 if sys.version_info >= (3, 8) else 1)' >/dev/null 2>&1; then
+            KOOLIE_PY="$kandidat"
+            break
+        fi
+    done
+    if [ -z "$KOOLIE_PY" ]; then
+        echo "Koolie braucht Python 3.8 oder neuer - gefunden wurde keines."
+        echo
+        echo "Installieren, zum Beispiel:"
+        echo "  von python.org"
+        echo "  oder mit Homebrew: brew install python"
+        echo "Danach dieses Fenster schliessen und den Starter erneut aufrufen."
+    else
+        "$KOOLIE_PY" "$KOOLIE_KERN/install_dialog.py"
+        KOOLIE_RC=$?
+    fi
+fi
+exit "$KOOLIE_RC"

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@renoxar/koolie",
+  "version": "1.25.0",
+  "description": "Rules, skills and a protective hook for AI coding assistants - one rule source, installed per project.",
+  "license": "GPL-3.0-only",
+  "homepage": "https://github.com/Renoxar/koolie",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Renoxar/koolie.git"
+  },
+  "bin": {
+    "koolie": "paketquellen/npm/koolie.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "readme": "# Koolie\n\n**Governance for AI coding assistants \u2013 one rule source for every client, enforced technically wherever the client allows it.**\n\n[![PyPI](https://img.shields.io/pypi/v/koolie)](https://pypi.org/project/koolie/)\n[![npm](https://img.shields.io/npm/v/@renoxar/koolie)](https://www.npmjs.com/package/@renoxar/koolie)\n[![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://github.com/Renoxar/koolie/blob/v1.25.0/LICENSE)\n\n*Deutsch: [README.md](https://github.com/Renoxar/koolie/blob/v1.25.0/README.md). The German documentation is authoritative; further documents are in German.*\n\nA team working with AI coding assistants needs more than an instruction file: shared rules for every\nassistant, technical blocks wherever a rule must not be broken, and clear points where a human decides.\nKoolie brings exactly that into an existing Git repository \u2013 and states openly, for each client, which rule\nit really enforces and which only acts as an instruction.\n\n## Quick start\n\nIn your project directory:\n\n```bash\nuvx koolie                  # or: pipx run koolie \u00b7 npx @renoxar/koolie\n```\n\nThe command fetches Koolie, offers the current directory as the project and asks for your AI client.\nAfterwards the project holds the instruction file, the permissions and a guard hook for that client. Without\na package registry, use the release archive and the starters `install.cmd` / `install.command`.\n\n**Want to try it first?** The [quickstart](https://github.com/Renoxar/koolie/blob/v1.25.0/QUICKSTART.en.md) installs Koolie into an empty practice repository\n\u2013 in ten minutes, without starting an AI client.\n\n## How it works\n\n```text\n  Core  .koolie/core/            Project overlay  .koolie/project-overlay/\n  rules, skills, checklists,     paths, approval routes, project documents\n  guard hook, validator          \u2013 owned by the project\n            \u2502                               \u2502\n            \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n                            \u25bc\n                Client pack per AI client\n       instruction file \u00b7 permissions \u00b7 hooks \u00b7 skills\n       (e.g. CLAUDE.md and .claude/ for Claude Code)\n```\n\n- **One core for all clients.** Rules and skills are written once, tool-neutral; a team with mixed tools shares\n  the same rules.\n- **The project stays in charge.** Project values live in the overlay. A new release updates a project with the\n  same command: it detects the existing core and offers to upgrade it; the overlay is never touched.\n- **Control levels instead of trust.** The assistant handles small tasks on its own; from \"medium\" it needs a\n  confirmed plan, at \"high\" an explicit approval.\n\n## What is enforced \u2013 and what is not\n\n| Kind of rule | What it means | Example |\n|---|---|---|\n| **Technical** | The client enforces it, whatever the model does | `git push` is blocked; secret files cannot be read |\n| **Instruction** | The rule is in the model's context; it can follow it | \"Do not change files outside the approved scope\" |\n| **Human** | Approvals, reviews, decisions | A person approves a release |\n\nEach client pack keeps a **capability matrix** that assigns every promise to one of these kinds \u2013 backed by a\nmeasurement on the client. Koolie complements a good standard setup (branch protection, CI, managed settings);\nit does not replace it.\n\n## Supported clients\n\n| Client | Pack | Status |\n|---|---|---|\n| Claude Code | [`claude-code`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/claude-code/CLIENT_PACK.md) | pilot |\n| Cursor | [`cursor`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/cursor/CLIENT_PACK.md) | pilot |\n| Devin Desktop | [`devin-desktop`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/devin-desktop/CLIENT_PACK.md) | pilot |\n| Kiro | [`kiro`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/kiro/CLIENT_PACK.md) | pilot |\n| OpenAI Codex CLI | [`openai-codex`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/openai-codex/CLIENT_PACK.md) | pilot, only with approval by the security officer |\n\n*Pilot* means: fully built, measured on real installations, meant for accompanied use. The limits of each\nclient are listed in its pack (German).\n\n## Who is it for?\n\n- **Development teams** that use AI assistants every day and want shared, verifiable rules.\n- **Technical leads** \u2013 team leads, architecture, security, data protection \u2013 who must show what a tool\n  enforces technically.\n\nKoolie is not meant for running an agent fully autonomously without human approvals.\n\n## Documentation\n\n| Topic | Where |\n|---|---|\n| Try it in ten minutes | [`QUICKSTART.en.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/QUICKSTART.en.md) |\n| Adopt in a project, update, costs | [Adoption guide](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/docs/ADOPTION_GUIDE.md) (German) |\n| First day in a project that uses Koolie | [Onboarding](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/onboarding/QUICKSTART.md) (German) |\n| Client packs and capability matrices | [`clients/README.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/clients/README.md) (German) |\n| The rules themselves | [`framework/core/`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/framework/core/) (German) |\n| Changes and plans | [`CHANGELOG.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/CHANGELOG.md) \u00b7 [`ROADMAP.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/docs/ROADMAP.md) (German) |\n| Contributing to the framework | [`CONTRIBUTING.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/CONTRIBUTING.md) (German) |\n\n## Why \"Koolie\"?\n\nA Koolie is an Australian herding dog. It does not drive the herd and does not replace the shepherd \u2013 it keeps\nthe flock together, on course and within bounds. That is what this framework is meant to do with an AI\nassistant.\n\n## License\n\n[GPL-3.0](https://github.com/Renoxar/koolie/blob/v1.25.0/LICENSE) with an additional permission: files created from the templates and any output of the tools\nbelong to the project that creates them. Merely using Koolie \u2013 also commercially \u2013 puts no obligations on you;\nthe details are in [`LICENSE-HINWEIS.md`](https://github.com/Renoxar/koolie/blob/v1.25.0/.koolie/core/LICENSE-HINWEIS.md) (German).\nCopyright \u00a9 2026 `<FRAMEWORK_OWNER>`.\n",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/paketquellen/README.md

@@ -0,0 +1,41 @@
+# Paketquellen
+
+Dieser Ordner baut Koolie für Paketquellen (`CR-2026-168`, D-518 bis D-521). **Veröffentlicht wird auf PyPI und npm** – seit `1.24.0`, als Schritt 9 von `RELEASE_PROCESS.md` 4.2 mit der Signatur der Marke als Freigabe (D-530). Scoop und Homebrew sind gebaut, nicht veröffentlicht (`K-209`).
+
+| Datei | Zweck |
+|---|---|
+| `koolie_befehl.py` | Der Befehl `koolie`: ohne Argumente der Installationsdialog mit dem aktuellen Verzeichnis als Vorgabe (D-532), mit Argumenten `install.py`, davor das Banner (D-519); `koolie --version` |
+| `koolie.cmd` | Hülle für Windows aus dem entpackten Release-Archiv (Scoop) |
+| `npm/koolie.js` | Hülle für npm: sucht Python ab 3.8 und erbt das Terminal |
+| `bauen.py` | Baut aus dem Release-Archiv Wheel, npm-Paket, Scoop-Manifest und Homebrew-Formel und prüft sie nach |
+
+## Bauen
+
+```
+python paketquellen/bauen.py --archiv <koolie-X.Y.Z.tar.gz> --aus <ablage>
+```
+
+Das Archiv ist das aus `RELEASE_PROCESS.md` 4.1, Schritt 5. Die Download-Adresse der Manifeste ist das GitHub-Release der Marke; `--url-basis` setzt eine andere, etwa für eine Messung mit einem lokalen Server.
+
+`--vorab N` baut eine Vorabversion für TestPyPI (`<V>.devN`, npm `<V>-dev.N`), vor der Signatur aus dem Arbeitsbaum (D-529):
+
+```
+git -c core.eol=lf -c core.autocrlf=input archive --format=tar.gz --prefix=koolie-<V>/ -o <ablage>/koolie-<V>.tar.gz $(git stash create)
+python paketquellen/bauen.py --archiv <ablage>/koolie-<V>.tar.gz --aus <ablage> --vorab 1
+```
+
+Die Beschreibung auf PyPI und npm ist `README.en.md` mit absoluten Links auf die Marke im GitHub-Spiegel; npm bekommt sie über das Feld `readme` der `package.json`, die Dateien im Paket bleiben die des Archivs (D-528).
+
+## Warum das Banner im Befehl steht
+
+Gemessen am 2026-09-30 (Protokoll `.koolie/core/tests/protocols/2026-09-30-paketquellen.md`): pip führt beim Installieren nichts aus, npm verschluckt die Ausgabe eines Installationsskripts, Chocolatey gibt ihm kein Terminal. Der Befehl `koolie` läuft dagegen immer im Terminal des Nutzers – und erst er bringt Koolie ins Projekt.
+
+## Stand je Paketquelle
+
+| Paketquelle | Stand |
+|---|---|
+| PyPI (pip, pipx, uv) | **veröffentlicht** seit `1.24.1` als `koolie` (TestPyPI zuerst, D-529; `1.24.0` nur auf TestPyPI, D-534) |
+| npm | als `@renoxar/koolie` (D-535) – der Name `koolie` ist auf npm gesperrt; erste Veröffentlichung mit `1.25.0` |
+| Scoop | gebaut, lokal gemessen (`7zip` wird mitinstalliert, `K-206`), nicht veröffentlicht (`K-209`) |
+| Homebrew | gebaut, nicht gemessen (`K-205`), nicht veröffentlicht (`K-209`) |
+| Chocolatey, winget | ohne Ziel (`K-204`) |