---
name: werkzeuge-verwalten
description: Prüft benötigte Projektwerkzeuge, stoppt vor nicht freigegebenen Installationen oder Versionswechseln und pflegt TOOLS.md mit Zweck, Bezugsquelle und Version. Verwenden, wenn ein Werkzeug fehlt, inkompatibel ist, installiert, aktualisiert, ersetzt oder erstmals reproduzierbar dokumentiert werden soll.
---

# Werkzeuge verwalten

Nutze Werkzeuge nachvollziehbar. Installiere, aktualisiere oder ersetze nichts
ohne eine konkrete Freigabe für genau diese Änderung.

## Fachliche Grundlage

- [The Twelve-Factor App – Dependencies](https://12factor.net/dependencies):
  Abhängigkeiten ausdrücklich deklarieren und möglichst vom globalen System
  isolieren.
- [Reproducible Builds – Build environment](https://reproducible-builds.org/docs/perimeter/):
  Die verwendeten Werkzeuge und ihre Versionen als Teil der reproduzierbaren
  Umgebung festhalten.

`TOOLS.md` ist ein schlankes Werkzeugregister, kein vollständiges SBOM und
kein Ersatz für Paketmanifeste oder Lockdateien.

## Was erfasst wird

Erfasse Werkzeuge, deren Version Projektergebnisse beeinflusst, zum Beispiel
Sprachlaufzeiten, Compiler, Buildsysteme, Paketmanager, Dokumentgeneratoren,
Infrastruktur-CLIs und Prüfwerkzeuge.

Erfasse gewöhnliche Lese- und Suchhilfen nur, wenn ihre konkrete Version für
das Ergebnis relevant ist. Dupliziere nicht sämtliche Bibliotheken aus
`pom.xml`, `package.json`, Lockdateien oder vergleichbaren Manifesten.

## Vor jeder Nutzung

1. Lies `TOOLS.md`, vorhandene Paketmanifeste, Wrapper und
   Umgebungsdefinitionen.
2. Bevorzuge vorhandene projektlokale Wrapper und deklarierte Werkzeuge vor
   globalen Installationen.
3. Prüfe Verfügbarkeit und Version mit einer nicht verändernden Abfrage.
4. Verwende ein vorhandenes kompatibles Werkzeug und aktualisiere bei Bedarf
   seinen Prüfstand in `TOOLS.md`.

## Wenn ein Werkzeug fehlt oder nicht passt

1. Stoppe vor Installation, Download, Upgrade, Downgrade oder Austausch.
2. Nenne dem Benutzer:
   - Werkzeug, benötigte Version und konkreten Zweck,
   - vorgeschlagene vertrauenswürdige Bezugsquelle,
   - Installationsumfang `project`, `user` oder `system`,
   - den vorgesehenen Befehl und die betroffenen Dateien,
   - mögliche Alternative ohne Installation.
3. Frage ausdrücklich nach der Freigabe für diesen Vorschlag.
4. Setze die ursprüngliche Arbeit erst nach einer eindeutigen Zustimmung fort.
   Eine frühere Freigabe für ein anderes Werkzeug oder eine andere Version
   gilt nicht.
5. Falls eine Installation anders als angekündigt erfolgen müsste, stoppe
   erneut und hole eine neue Freigabe ein.

## Nach einer freigegebenen Änderung

1. Installiere nur im bestätigten Umfang und aus der bestätigten Quelle.
2. Prüfe die tatsächlich verfügbare Version.
3. Aktualisiere das zuständige Paketmanifest oder die Lockdatei, falls es sich
   um eine Projektabhängigkeit handelt.
4. Aktualisiere den YAML-Block in `TOOLS.md` mit Zweck, Soll- und Ist-Version,
   Umfang, Quelle sowie Freigabe- und Prüfdatum.
5. Melde Installation, Versionsprüfung und geänderte Dateien. Verberge keine
   fehlgeschlagenen oder teilweise ausgeführten Schritte.

## Sicherheitsgrenzen

- Kein `sudo`, keine globale Installation und kein aus dem Netz geladenes
  Installationsskript ohne ausdrückliche Freigabe.
- Keine Zugangsdaten oder Tokens in `TOOLS.md`, Befehlen oder Logs ablegen.
- Eine Benutzerfreigabe zum Installieren ersetzt nicht die Freigabe für
  weitere externe Änderungen, Veröffentlichungen oder Deployments.

## Fertig, wenn

- Verfügbarkeit und tatsächliche Version geprüft sind;
- Installation oder Versionswechsel der konkreten Freigabe entsprechen;
- Bezugsquelle, Umfang sowie Soll- und Ist-Version reproduzierbar dokumentiert
  sind;
- fehlgeschlagene oder abweichende Schritte sichtbar gemeldet wurden.