# Playbook: Ein eigenes Tool hinzufügen

Die Suite schlägt die Tools vor, die ihre Packs kennen. Ein Projekt, das ein Tool nutzt, das die Suite nicht kennt, oder eine Hausregel hat, die es Schritt für Schritt abarbeiten will, hält ein **eigenes Pack**. Die Suite liest es neben ihren eigenen Packs, schlägt seine Stufen vor wie jede andere und beurteilt auf dieselbe Weise, ob sie erfüllt sind.

## Was du brauchst

Drei Dinge im Projekt, alle committet:

1. **Ein Verzeichnis** für das Pack, empfohlen `docs/agents/tooling-pack/`.
2. **`pack.json`** darin: das Pack, seine Tools und deren Stufen.
3. **Eine Markdown-Datei pro Tool**, genannt im Feld `details` des Tools, relativ zum Verzeichnis: was die Suite prüft, um eine Stufe als erfüllt zu werten (die *Erfüllungsprüfung*, Fulfilment check), und was ein Merge Request dafür enthält (der *MR-Umfang*, MR scope).

Füge dem Abschnitt `## Refactoring operations` in `docs/agents/issue-tracker.md` einen Punkt **Tooling Pack** hinzu, der das Verzeichnis nennt:

```markdown
- **Tooling Pack**: `docs/agents/tooling-pack/`
```

Ohne den Punkt schaut die Suite nicht nach. Das Onboarding fragt nicht danach; es führt ihn unter dem auf, was weggelassen wurde.

## Ein kleines Beispiel

Ein Projekt, das die Abhängigkeiten zwischen seinen Schichten mit Deptrac prüft und die Verstöße abarbeiten will:

```json
{
  "$schema": "../../../.agents/skills/continuous-refactoring/references/pack.schema.json",
  "pack": "house-rules",
  "scope": "php",
  "applies_when": "Always.",
  "tools": [
    {
      "tool": "deptrac",
      "name": "Deptrac",
      "uses": "qossmic/deptrac",
      "roles": ["architecture-rules"],
      "status": "recommended",
      "details": "deptrac.md",
      "stages": [
        {
          "slug": "deptrac-layers",
          "name": "Deptrac Layers",
          "track": "Guardrails",
          "requires": ["composer"],
          "waits_for": []
        },
        {
          "slug": "deptrac-strict",
          "name": "Deptrac Strict Rules",
          "track": "Guardrails",
          "requires": ["deptrac-layers"],
          "waits_for": []
        }
      ]
    }
  ]
}
```

`architecture-rules` ist eine Rolle, die die Suite nicht hat. Ein Pack, das eine Rolle hinzufügt, hält sie in einer `roles.json` neben der `pack.json`: ein Slug, ein Name, ein Zweck in einem Satz und das Signal, das sie speist, oder `null`. Die [Tooling-Übersicht](https://continuous-refactoring.de/de/docs/tooling.md) der Suite listet die Rollen, die sie hat; nimm eine davon, wo sie passt, damit die Suite dein Tool als Alternative zu ihrem eigenen sieht.

## Die Regeln

- **Hinzufügen, nie umdefinieren.** Slugs sind über die Packs der Suite und deine hinweg eindeutig: Ein Tool, eine Stufe, eine Rolle oder ein Pack mit demselben Slug beendet den Tooling-Schritt des Runs mit einem Fehler, der beide Stellen nennt. Ein Tool der Suite, das du nicht willst, wird mit einer Ablehnung abgelehnt, wie jedes andere.
- **Ein Tool mit mehreren Stufen hat einen eigenen Slug.** Ein Tool mit einer Stufe darf seinen Slug mit ihr teilen; fügst du eine zweite Stufe hinzu, benenne das Tool um, nicht die Stufe, denn deine Tickets und Ablehnungen nennen die Stufe.
- **Der Scope entscheidet, wer konkurriert.** Ein Pack nennt die Sprache, auf der es arbeitet (`"scope": "php"`). Tools eines Scopes konkurrieren um eine Rolle: Ein Projekt, das Mago statt PHPStan nutzt, nennt den Scope `php`, lehnt PHPStan ab, und Mago besetzt Static Analysis, sodass die Stufen von Rector nicht mehr auf PHPStan warten. Tools anderer Scopes nehmen einander nicht den Platz: Ein Code-Style-Tool für Twig und eines für PHP sind beide im Einsatz.
- **Eine Stufe kann auf die der Suite warten.** `requires` und `waits_for` können Stufen und Rollen der Packs der Suite nennen (`composer`, `static-analysis`); nichts der Suite wartet auf deine.
- **Es kommt zuletzt.** Die Stufen der Suite werden zuerst vorgeschlagen.
- **Applies when** ist ein Satz, den die Suite einmal pro Run am Projekt beurteilt. Das eigene Pack eines Projekts sagt meist „Always.“
- Die Zeile `"$schema"` zeigt auf das Schema in den installierten Skills des Projekts; damit kann ein Editor die Datei prüfen und vervollständigen. Schreibe die Datei in der Form, die die Packs der Suite haben: zwei Leerzeichen Einrückung, Objekte ein Schlüssel pro Zeile, Listen aus einfachen Werten auf einer Zeile.

## Wenn die Suite etwas umbenennt

Die Suite bekommt mit der Zeit neue Tools. Nimmt eines davon einen Slug, den dein Pack nutzt, endet der nächste Run mit dem Fehler oben. Benenne deinen Slug um; die Tickets der Suite behalten ihre.