Harmonist: Agenten-Orchestrierung mit Hooks statt Prompt-Disziplin

Das Problem: Regeln, die nur im Prompt stehen

Jedes ernsthafte Engineering-Team hat Regeln, die nicht verhandelbar sind. Kein Floating-Point für Geldbeträge. QA vor dem Merge. Security-Review, bevor Authentifizierungscode angefasst wird. Ein Sprachmodell kann diese Regeln lesen und bestätigen. Es kann sie aber auch überspringen, ohne dass etwas den Ablauf unterbricht. Genau an dieser Lücke setzt Harmonist an. Das README formuliert es als Kontrast: Die meisten Frameworks vertrauen darauf, dass das Modell die Regeln befolgt, Harmonist lässt es nicht zu, dass es sie überspringt. Das ist keine Prompt-Formulierung, sondern eine Aussage über den Kontrollfluss. Adressat sind Teams und Einzelentwickler, die einen Coding-Assistenten mit Dateizugriff betreiben und festgestellt haben, dass Zusagen im Prompt keine ausreichende Garantie sind. Der Preis dafür ist, dass jede codeändernde Runde durch Prüfungen läuft, die auch dann greifen, wenn niemand sie angefordert hat.

Wie der stop-Hook einen Turn blockiert

Der Mechanismus sitzt in `.cursor/hooks/`. Der dortige `stop`-Hook liest Subagenten-Dispatch-Marker aus der Sitzung aus und prüft, ob der `qa-verifier` gelaufen ist, ob ein geforderter Reviewer fehlt und ob `session-handoff.md` aktualisiert wurde. Schlägt eine dieser Prüfungen fehl, gibt der Hook eine strukturierte `followup_message` zurück und verweigert den Abschluss des Turns. Das Modell erhält also nicht nur einen Hinweis, sondern einen Zustand, den es nicht wegdiskutieren kann. `loop_limit: 3` begrenzt die Wiederholungen. Nach Ausschöpfung wird ein Incident protokolliert und in der nächsten Sitzung sichtbar gemacht. Das ist ein Zustandsautomat auf der Festplatte, wie das README selbst formuliert, und kein Appell an die Vernunft des Modells. Die Grenze dieses Ansatzes liegt in der Abhängigkeit von der IDE: Der Hook muss vom jeweiligen Assistant ausgeführt werden, und die Dispatch-Marker müssen tatsächlich entstehen. Ohne diese Voraussetzung gibt es keine Erzwingung, sondern nur Dateien.

Memory als einziger Schreibpfad mit Schema und Secret-Scan

Erinnerungen an frühere Aufgaben sind in vielen Agenten-Setups freier Text, den das Modell selbst verfasst. Harmonist schränkt das ein. `memory.py append` ist laut README der einzige unterstützte Schreibpfad. Jeder Eintrag wird gegen ein YAML-Schema in `memory/SCHEMA.md` validiert, Duplikate werden abgewiesen, und der Textkörper wird auf rund 30 Klassen von Geheimnissen geprüft: AWS Access Keys, GitHub PATs, Stripe-Tokens, Slack-Webhooks, GCP-Service-Accounts, Azure Connection Strings, Telegram-Bot-Tokens, Discord-Tokens, Heroku- und Postmark-UUIDs im jeweiligen Kontext, generische High-Entropy-Tokens mit `secret:`-Präfix sowie Datenbankverbindungszeichenfolgen mit eingebetteten Zugangsdaten. Platzhalter in der Form `${VAR}` oder `<NAME>` unterdrücken den Scan, damit Vorlagen weiterhin geschrieben werden können. Die Korrelation zwischen Einträgen läuft über eine `correlation_id` der Form `<session_id>-<task_seq>`, die der Hook beim Sitzungsstart erzeugt (`<unix-seconds><pid4>`). Das Modell liest die aktive ID per CLI, schreibt sie aber nie selbst. Das ist eine bewusste Misstrauensentscheidung gegenüber dem Modell und der interessanteste Teil des Designs.

Installation und die Prüfung vor dem Kopieren

Die Installation läuft über Skripte im Repository. `upgrade.py` prüft jede Quelldatei per SHA256 gegen `MANIFEST.sha256`, bevor sie in ein Projekt kopiert wird. Alle zur Laufzeit ausgelieferten Inhalte sind dort gehasht: `agents/`, `hooks/`, `memory/`, `playbooks/` und die Dokumentation im Wurzelverzeichnis. CI-Konfigurationen und Repository-Metadaten sind ausgenommen, weil sie nur das Pack-Repository betreffen. Eine manipulierte `security-reviewer.md`, die alles genehmigt, wird abgewiesen und gelangt nicht ins Projekt. `install_extras.py` erbt diese Prüfung für nachträglich installierte Spezialisten. Für Agenten, die das Pack einbinden sollen, verweist das README auf `integration-prompt.md` und stellt klar, dass `AGENTS.template.md` nicht als aktive Regel im Pack-Ordner angewendet werden darf: Sie ist die Vorlage, aus der beim Integrieren die `AGENTS.md` des Zielprojekts wird. Diese Unterscheidung ist wichtig, weil eine Verwechslung die Regeln am falschen Ort aktiviert. Die genauen Aufrufe der Skripte stehen im Quick-Start-Abschnitt des README, der hier nicht vollständig vorliegt; verlässlich belegt sind die Dateinamen und der Prüfmechanismus, nicht die exakten Kommandozeilen.

193 Spezialisten und die Frage, wer sie pflegt

Der Katalog umfasst laut README 193 kuratierte Spezialisten in 16 Kategorien, nicht eine generische Coder-Rolle. Die Badge im Repository nennt 193, die Kurzbeschreibung des Projekts spricht von 186. Diese Abweichung zwischen zwei Angaben desselben Projekts ist ein Hinweis darauf, dass die Zahl sich mit dem Katalog bewegt und keine stabile Kennzahl ist. Für die Bewertung ist das zweitrangig. Entscheidend ist die Pflegefrage: Jede Agentendefinition ist Inhalt, der bei Änderungen im Manifest neu gehasht werden muss, sonst schlägt die Prüfung beim nächsten Upgrade fehl. Ein Team, das eigene Spezialisten ergänzt, übernimmt damit einen Teil der Release-Buchhaltung. Das ist kein Fehler des Designs, sondern die direkte Folge der Integritätsprüfung. Wer viele eigene Rollen pflegt, zahlt diesen Aufwand bei jedem Update erneut.

Wann Harmonist das falsche Werkzeug ist

Die Erzwingung hängt an Hooks, die von der IDE ausgeführt werden. Läuft der Assistant in einer Umgebung ohne Hook-Unterstützung oder ohne die Fähigkeit, Shell- und Python-Skripte an definierten Punkten des Turns aufzurufen, bleibt von der Mechanik nur die Dokumentation übrig. Ebenso problematisch ist der Fall, in dem der Workflow gar keine Subagenten-Dispatches erzeugt: Die Marker, die der stop-Hook auswertet, entstehen dann nicht, und die Prüfung läuft ins Leere oder blockiert ohne Grundlage. Auch für sehr kleine Änderungen ist der Apparat schwer: Wer eine Zeile in einer Konfigurationsdatei korrigiert, durchläuft dieselbe Kette aus Reviewer-Prüfung, Handoff-Aktualisierung und Incident-Protokollierung. Das README positioniert Harmonist gegen schwere Enterprise-Plattformen mit separater Laufzeit und Datenbank. Der Preis dafür ist, dass die Disziplin in Dateien und Hooks liegt, die ein Team selbst verstehen und warten muss.

Abgrenzung zu LangChain, CrewAI und AutoGen

Das README nennt LangChain, CrewAI, AutoGen und MetaGPT als Vertreter eines anderen Ansatzes: Sie liefern Orchestrierungsprimitive, überlassen die Durchsetzung aber dem Prompt, sodass das Modell sein eigenes Protokoll überschreiben kann. Der Unterschied liegt nicht im Funktionsumfang, sondern im Ort der Kontrolle. Bei diesen Frameworks ist die Regel Teil des Kontexts, den das Modell sieht. Bei Harmonist ist sie ein Skript, das den Turn blockiert. Daraus folgen unterschiedliche Fehlerbilder: Dort kann eine Regel stillschweigend ausgelassen werden, hier kann ein Hook einen Turn festhalten, obwohl die Arbeit inhaltlich fertig ist. Ein weiterer Unterschied ist die Abhängigkeitsbasis. Harmonist gibt an, nur mit der Standardbibliothek von Python ab 3.9 auszukommen, ohne Laufzeit und ohne Datenbank. Das senkt die Installationshürde, verlagert aber die Komplexität in die Shell- und Python-Skripte, die das Team selbst lesen muss.

Lizenz, Wartung und was vor der Übernahme zu prüfen ist

Harmonist steht unter MIT. Das erlaubt Weitergabe und Anpassung, verlangt aber, den Lizenztext beizubehalten. Wer das Pack in ein eigenes Produkt einbettet, sollte die Lizenzhinweise der mitgelieferten Dateien prüfen; eine Rechtsberatung ersetzt das nicht. Die Wartungslage lässt sich aus den veröffentlichten Versionen ablesen: v1.1.0 am 8. Juni 2026, v1.2.0 und v1.2.3 am 9. Juni 2026. Drei Releases innerhalb von zwei Tagen deuten auf eine Phase intensiver Änderungen hin. Für Nutzer bedeutet das, das Manifest und die eigene Anpassung im Blick zu behalten, weil ein Upgrade die SHA256-Prüfung gegen die ausgelieferten Dateien ausführt. Vor der Einführung sind drei Dinge konkret zu klären: ob die verwendete IDE den stop-Hook ausführt, ob der eigene Workflow die Dispatch-Marker erzeugt, die der Hook auswertet, und ob `memory/SCHEMA.md` zu den Feldern passt, die das Team tatsächlich festhalten will. Diese drei Punkte entscheiden, ob Harmonist Regeln durchsetzt oder nur beschreibt.

Redaktionelles Fazit

Wer mit Cursor, Claude Code oder einem vergleichbaren Assistant arbeitet und Review- sowie Memory-Schritte nicht der Disziplin des Modells überlassen will, findet hier einen prüfbaren Mechanismus. Wer nur einen einzelnen Chat pro Aufgabe nutzt oder keine Hooks konfigurieren kann, sollte es nicht einführen: Der Aufwand entsteht erst durch die Dispatch-Marker und die stop-Logik. Vor der Übernahme ist zu klären, ob die eigene IDE-Hook-Konfiguration den stop-Hook unterstützt, ob der eigene Workflow die Marker für Subagenten-Dispatches überhaupt erzeugt und ob ein fehlgeschlagener Hook in der Praxis nicht den gesamten Turn blockiert.

Offizielle Quellen

1. GammaLabTechnologies/harmonist on GitHub
2. License: MIT
3. Project website
4. README
5. Releases