¶Architektur

Wie die Suite aufgebaut ist, für alle, die sie verstehen oder erweitern wollen. Um einen Run als Nutzer zu steuern, siehe das Run-Playbook; für das Vokabular CONTEXT.md.

¶Zwei Skills, alles andere eine Referenz

/continuous-refactoring            ← ein Run: von den offenen Tickets zu einem geöffneten Merge Request
   └── references/
         ├── Onboarding, die Operationen und ihre Vorlagen
         ├── Arbeitsliste, Abgleich, Track-Wahl
         ├── einen Tooling-Track scannen, Tickets anlegen, Auswahl, Ablehnungen
         ├── der Investigation-Track, die Signale, die Suche nach strukturellen Kandidaten
         ├── Design-Schritt, Umsetzungsschritt, Review, den Merge Request öffnen
         └── der Tooling-Baum: sein Parser, das Modell, die Packs, eine Datei pro Tool

/continuous-housekeeping           ← der Housekeeping-Track allein, ohne Track-Wahl
   └── references/
         ├── der Housekeeping-Track
         └── Housekeeping einrichten

• continuous-refactoring enthält den Run: wie der Aufruf gelesen wird, die Regeln eines Entscheidungspunkts, die zehn Schritte und wie ein Run endet. Jeder Schritt verweist auf die Referenz mit seinen Details, sodass ein Run nur lädt, was er erreicht.
• continuous-housekeeping ist ein zweiter Einstiegspunkt für einen Track. Er braucht keine Track-Wahl, und das macht ihn geeignet für einen Zeitplan. Ein Run von continuous-refactoring, der Housekeeping wählt, liest dieselbe Housekeeping-Referenz, es gibt also eine einzige Beschreibung des Ablaufs.

Beide werden von einem Menschen eingetippt; keiner wird vom Agenten von sich aus gewählt. Ein Schritt, der nur liest und urteilt – die Erfüllungsurteile eines Scans, die Erkundung nach strukturellen Kandidaten, ein Review –, kann zusammen mit seiner Referenz an einen Subagenten übergeben werden, damit sein Abwägen aus dem Hauptgespräch herausbleibt. Ein Subagent fragt nichts und schreibt nichts; jeder Entscheidungspunkt bleibt im Gespräch mit dir.

¶Ein Run, Schritt für Schritt

Housekeeping und Investigation ersetzen die Schritte 5 bis 7 durch ihren eigenen Weg zu einem Ticket; ab dem Design-Schritt kehrt Investigation in die Kette zurück, und Housekeeping liefert über denselben Merge-Request-Schritt.

¶Entscheidungspunkte und die zwei Modi

Jeder Schreibvorgang in deinen Tracker, deine Forge oder deine Dateien folgt aus einem Entscheidungspunkt: Befunde, Optionen, eine Empfehlung. Alles vor dem ersten ist rein lesend.

• Interaktiv, der Standard: Die Suite fragt und wartet.
• Autonom, im Aufruf oder mitten im Run gesagt: Die Suite nimmt ihre Empfehlung und sagt das in einem Satz.

Autonom ist dieselbe Kette mit genommener Empfehlung, es gibt also einen Pfad zu pflegen und nichts zu konfigurieren. Der Modus wird nie gespeichert. Ein interaktiver Run, auf den niemand antwortet, endet an diesem Entscheidungspunkt; sein Bericht ist der Entscheidungspunkt selbst, und nichts wurde geschrieben. Ein Schreibvorgang wartet in jedem Modus auf einen Menschen: eine Änderung an der AGENTS.md des Projekts.

¶Zuerst die eigenen Skills des Projekts

Am Design-Schritt und am Umsetzungsschritt schaut die Suite auf die Skills, die im Gespräch angeboten werden, und darauf, was die AGENTS.md des Projekts über Planen und Umsetzen sagt. Sie empfiehlt, was die AGENTS.md nennt, sonst einen passenden Skill des Projekts, sonst einen passenden Skill von anderswo und erst dann ihr eigenes Verfahren. Die Wahl ist ein Entscheidungspunkt und wird in jedem Run neu getroffen, ein morgen installierter Skill ändert also morgen die Empfehlung. Ein autonomer Run nutzt die eigenen Verfahren der Suite. Ein Skill, den nur du aufrufen kannst, steht einem Agenten nicht zur Verfügung; dafür lässt dich ein Run die Planung – und, sobald der Plan auf dem Ticket steht, die Umsetzung – in eine eigene Session mitnehmen und endet dort. Ein späterer Run nimmt das Ticket über den Plan, den Branch oder den Merge Request auf, den er vorfindet.

Die Suite erwartet zwei Dinge zurück: von der Planung ein Ticket, das einen umsetzbaren Plan trägt; von der Umsetzung einen Branch, dessen Checks grün sind. Den Merge Request öffnet sie selbst, sofern nicht schon einer offen ist, sodass ein Run gleich endet, wer auch immer die Änderung gebaut hat. Eine Entscheidung, die es wert ist, festgehalten zu werden, wird ein ADR auf demselben Branch – nur dort, wo die Domain-Doku des Projekts sagt, wo ADRs liegen.

¶Was die Suite berichtet

Ein Satz, wenn ein Schritt beginnt, und einer mit seinem Ergebnis; eine Zeile pro Schreibvorgang, während er passiert, mit dem Ding und wo es liegt. Ein Run schließt mit zwei Zeilen: Status – was er getan hat und wo er endete – und Next – was du jetzt tun kannst. Eine Aussage, dass etwas offen, behoben oder grün ist, wird nach dem letzten Push aus der Forge gelesen.

¶Kein eigener Zustand

Ein Ticket, das die Suite anlegt, nennt sein Thema in einfachen Worten – den Namen des Tools – in Titel und Text, damit eine spätere Suche es findet. Es gibt keine versteckte Markierung und keinen festen Titel. Vor dem Anlegen sucht die Suite nach einem bestehenden Ticket zum Thema, offen oder geschlossen, und macht auf deinem weiter, statt ein Duplikat anzulegen.

¶Tracker und Forge

Die Suite fragt nie, welchen Tracker ein Projekt nutzt. Sie liest benannte Operationen aus dem Abschnitt ## Refactoring operations in docs/agents/issue-tracker.md. Drei sind Pflicht: wie Tickets gesucht werden, wie ein erledigtes erkannt wird und wo Merge Requests liegen. Die anderen sind optional – wie Refactoring-Tickets und priorisierte markiert werden, wie ein Merge Request und sein Ticket aufeinander verweisen, wie ein Ticket zugewiesen wird, wie es als bereit markiert wird, sobald die Suite ihren Plan gepostet hat, wie abgelehnte Arbeit festgehalten wird, wie ein Ticket sagt, was es blockiert, und wo die Housekeeping-Vorlage liegt. Ein Projekt, dessen Tracker eine davon nicht kennt, lässt sie weg, und die Suite nimmt den schlichteren Weg; für einige schlägt sie eine Antwort vor, sobald sie zum ersten Mal gebraucht wird, und schreibt sie in den Abschnitt.

Der Tracker und die Forge – das System, das das Repository und seine Merge Requests hostet – sind zwei Dinge. Auf einem GitHub- oder GitLab-Projekt sind sie dasselbe System, und verschiedene, wo Tickets in Redmine und der Code auf GitLab liegen. Das Onboarding schreibt den Abschnitt: aus einer Vorlage für GitHub, GitLab und lokale Markdown-Dateien, aus deinen Antworten für alles andere.

¶Der Tooling-Baum

Safety Net und Guardrails arbeiten über den Tooling-Baum: die Tools, die ein Projekt einführen kann, beschrieben als Rollen (Roles – wofür ein Tool da ist: statische Analyse, Code-Style, Tests …), besetzt von Tools (PHPStan, Psalm, PHP CS Fixer …), die Stufen (Stages) haben – ein Grad eines Tools, etwa ein PHPStan-Level, und die Einheit, für die ein Ticket angelegt wird. Tools kommen in Packs mit einer Bedingung, unter der sie gelten: jedes Projekt, ein Projekt mit PHP-Code, ein eigenes Pack des Projekts (tooling-model.md enthält die Regeln). Eine Stufe setzt andere zuerst voraus (eine Stufe, eine Rolle oder eine von mehreren Alternativen) und kann warten, bis andere entschieden sind – erfüllt oder abgelehnt.

• Erfüllung wird beurteilt, nicht erkannt. Jede Stufe hat eine Erfüllungsprüfung (Fulfilment check), jede Rolle einen Zweck (Purpose); ein Agent beurteilt, ob das Projekt den Zweck bereits erfüllt – ein von Hand eingerichtetes Tool oder ein Äquivalent unter anderem Namen zählt also. Es gibt keine Liste von Dependency-Namen. Eine Rolle, die ein anderes Tool schon besetzt, tritt an die Stelle des empfohlenen: Einem Projekt mit Psalm wird PHPStan nicht angeboten. Ein paar Tools gibt es auf Anfrage: nie ungefragt angeboten, einmal angefragt wie jedes andere bearbeitet.
• Der Parser macht nur Graphenlogik. tooling_tree.py bekommt übergeben, welche Packs gelten, welche Stufen erfüllt sind, welche Rollen, Tools oder Stufen abgelehnt wurden und welche Runtime das Projekt zulässt, und antwortet, was das bedeutet: die Stufen pro Track, ihre Reihenfolge, was jede zurückhält, welche Stufen eine Ablehnung schließt und welche abgelehnte zurückkommen kann, weil ihre Runtime-Version jetzt erreicht ist. Er liest die Packs und die Tracker-Datei des Projekts und hält keine Datei.
• Safety Net hat ein Gate, und es wird berechnet. Safety Net ist erfüllt, wenn jede seiner Stufen erfüllt oder durch eine Ablehnung geschlossen ist; diese Antwort entscheidet, ob ein autonomer Run beim Safety Net stoppt, und Guardrails-Stufen warten darauf.
• Ein Projekt kann ein eigenes Pack hinzufügen. Ein Punkt Tooling Pack in seiner Tracker-Datei nennt ein Verzeichnis mit einer pack.json (und einer roles.json, wenn es Rollen hinzufügt). Der Parser liest es nach den Packs der Suite und weist einen Slug zurück, den die Suite schon hat; ein Pack nennt einen Scope, damit Tools für verschiedene Sprachen einander nicht den Platz nehmen.
• Die Packs werden für Menschen gezeichnet, nicht vom Run gelesen. docs/tooling/ enthält, aus den Packs generiert, eine Tabelle der Rollen und eine Seite pro Pack mit seinen Tools, Stufen und einem Diagramm, was was voraussetzt. Der Generator schreibt auch das JSON der Packs in einer festen Form, und der Validator schlägt bei einem Pack, einer Rolle oder einer Seite fehl, die veraltet ist, sodass die Seiten nicht auseinanderlaufen können. Sie werden nicht mit den Skills ausgeliefert.
• Ein Tooling-Merge-Request ist klein und sachlich: eine Stufe, und ihre eigene Erfüllungsprüfung sagt, wann er fertig ist.

Parser und Packs werden zusammen innerhalb von continuous-refactoring ausgeliefert, ein kopierter oder verlinkter Skill ist also vollständig.

¶Eigenständigkeit

Die Suite funktioniert in einem Projekt, in dem keiner der Engineering-Skills installiert ist: Planung, testgetriebene Umsetzung (ein Test, der das heutige Verhalten festhält, kommt vor jedem Umbau) und Review haben jeweils ein eigenes Verfahren der Suite, das genutzt wird, wenn das Projekt nichts Passendes anbietet. Ebenso ist keine Forge oder kein Remote kein Fehler: Der Branch wird vorbereitet, in einem Kommentar auf seinem Ticket genannt und dir übergeben.

¶Regeln und Prinzipien

Was einen Run ohne Ausnahme bindet, ist kurz und prüfbar. Was dem Urteil hilft – wann eine Migration Alt und Neu nebeneinander braucht, ob eine Änderung den Code leichter nachvollziehbar macht –, ist ein Prinzip: Die Suite wägt es ab, nennt es im Plan und darf mit Begründung davon abweichen.

¶Wo was in diesem Repo liegt

• skills/<skill>/SKILL.md – der Skill selbst, kurz gehalten; Details liegen in skills/<skill>/references/.
• Alles, was ein Skill zur Laufzeit braucht, liegt unter seinem eigenen references/. docs/ (Playbooks, diese Datei) ist für Menschen und wird nie mit den Skills ausgeliefert.
• fixtures/ und scripts/ – Beispielprojekte, um die Suite daran auszuprobieren, die Tests des Tooling-Baum-Parsers und die Skill-Validierungs-Checks (fixtures/README.md, CONTRIBUTING.md).