Harmonist : quand l'application du protocole devient une barrière mécanique

Le problème visé : une règle énoncée n'est pas une règle exécutée

Le README part d'un constat simple. Un assistant de codage peut être instruit de lancer la QA avant de fusionner, de ne pas utiliser de flottants pour l'argent, ou de faire relire tout code touchant l'authentification. Il peut acquiescer, puis passer à autre chose. Rien dans le prompt ne l'empêche d'oublier une étape.

Harmonist vise les équipes qui ont déjà ce genre de contraintes écrites noir sur blanc et qui constatent qu'elles ne sont pas toujours respectées. Le projet se présente comme une alternative à deux familles d'outils : les frameworks d'orchestration légers, où l'application des règles reste confiée au modèle, et les plateformes d'entreprise plus lourdes, qui demandent une infrastructure séparée. Le README cite LangChain, CrewAI, AutoGen et MetaGPT dans la première catégorie.

La cible est donc étroite : un développeur ou une petite équipe qui travaille dans un IDE compatible, qui a des règles de revue formalisées, et qui veut que ces règles soient vérifiées par un script plutôt que par la bonne volonté du modèle.

Ce que les hooks de fin de tour bloquent réellement

Le mécanisme central décrit dans le README tient dans un fichier : le hook stop, placé dans .cursor/hooks/. À chaque fin de tour, ce hook analyse les marqueurs de dispatch des sous-agents présents dans la session. Il vérifie si qa-verifier a été exécuté, si un relecteur obligatoire manque, et si session-handoff.md a été mis à jour. Si une de ces conditions n'est pas remplie, le hook renvoie un followup_message structuré et refuse de clore le tour.

Deux détails comptent plus que le principe. D'abord, loop_limit: 3 plafonne les tentatives. Un modèle qui boucle sur une condition qu'il ne peut pas satisfaire ne tourne pas indéfiniment. Ensuite, quand la limite est atteinte, le README indique qu'un incident est enregistré et remonté lors de la session suivante. Le blocage n'est donc pas silencieux : il laisse une trace.

Le point à retenir est que la vérification ne dépend pas de ce que le modèle déclare. Le hook inspecte la session, pas le résumé que le modèle en fait. C'est toute la différence avec une consigne écrite dans un prompt système.

La mémoire corrélée côté hook, pas côté modèle

Chaque entrée de mémoire porte un correlation_id de la forme <session_id>-<task_seq>. Le README précise que ces identifiants sont générés par les hooks au démarrage de session, selon le format <unix-seconds><pid4>, ce qui limite les collisions entre sessions parallèles. Le modèle lit l'identifiant actif via la ligne de commande. Il ne l'écrit jamais lui-même.

C'est une décision de conception défendable : la liaison entre une entrée state, une decision et un pattern issus de la même tâche n'est pas laissée à l'appréciation du modèle. Le README parle d'un ordonnancement « cryptographiquement ordonné » du point de vue du hook. La formulation est ambitieuse pour ce qui reste, en pratique, un identifiant généré localement. Ce n'est pas une signature ni une chaîne de confiance vérifiable par un tiers.

Le second garde-fou est plus concret. memory.py append est présenté comme le seul chemin d'écriture pris en charge. Chaque entrée est validée contre un schéma YAML décrit dans memory/SCHEMA.md, les doublons sont rejetés, et le corps est analysé à la recherche d'une trentaine de classes de secrets : clés d'accès AWS, jetons GitHub, jetons Stripe, webhooks Slack, comptes de service GCP, chaînes de connexion Azure, jetons de bots Telegram et Discord, UUID Heroku et Postmark, jetons génériques à forte entropie préfixés par secret:, et chaînes de connexion de base de données contenant des identifiants. Les marqueurs de substitution comme ${VAR} ou <NAME> désactivent l'analyse.

MANIFEST.sha256 : la vérification avant copie

Le contenu livré à l'exécution (agents/, hooks/, memory/, playbooks/, et les documents à la racine) est haché dans MANIFEST.sha256. Les configurations de CI et les métadonnées du dépôt sont explicitement exclues. upgrade.py vérifie le hachage de chaque source avant de la copier dans un projet. install_extras.py applique la même règle pour les installations ponctuelles de spécialistes.

L'exemple donné dans le README est parlant : un fichier security-reviewer.md modifié pour renvoyer approve sur tout serait refusé et n'entrerait jamais dans le projet. C'est le genre de contrôle qui manque à la plupart des catalogues de prompts distribués par copier-coller.

Il faut toutefois être précis sur ce que cela protège. La vérification porte sur l'intégrité du paquet au moment de la copie. Elle ne dit rien sur ce qui se passe ensuite : une fois les fichiers installés, un hook modifié localement ne sera pas détecté par ce même mécanisme, sauf à relancer une comparaison manuelle contre le manifeste.

Mise en route : ce que la documentation donne

Le README place en tête un avertissement destiné aux agents : lire integration-prompt.md et exécuter ses étapes, et ne pas appliquer AGENTS.template.md comme règle active à l'intérieur du dossier du pack, puisque ce fichier est le modèle qui deviendra le AGENTS.md du projet utilisateur pendant l'intégration.

Les exigences annoncées sont Python 3.9 ou plus récent et des dépendances limitées à la bibliothèque standard. Le badge du dépôt indique 193 agents, alors que la description du dépôt et le texte du README mentionnent 186 puis 193 selon les endroits. Cette divergence entre les chiffres est un point à vérifier soi-même dans agents/index.json avant de se fier à un décompte.

Le README renvoie à une section Quick start et à une section Key scripts, mais le contenu fourni ici s'arrête avant de les détailler. Les commandes exactes d'installation ne figurent donc pas dans le matériel dont je dispose, et je ne vais pas les inventer. Ce que l'on peut affirmer : l'intégration passe par integration-prompt.md, l'écriture en mémoire passe par memory.py append, et la mise à jour du paquet passe par upgrade.py.

La limite structurelle : un framework qui suppose un IDE

Toute la mécanique de blocage repose sur des hooks d'IDE. Le README cite Cursor, Claude Code, Copilot, Windsurf et Aider parmi les assistants pris en charge. Si votre environnement d'exécution principal est un pipeline d'intégration continue sans assistant exposant un hook de fin de tour, le contrôle central de Harmonist ne s'applique pas. Les scripts restent utilisables, mais la barrière disparaît.

Il y a un second coût, moins visible. Le catalogue compte près de 200 définitions d'agents, et leur intégrité est vérifiée par un manifeste de hachages. Chaque modification d'un agent livré implique de régénérer ce manifeste, sans quoi upgrade.py refusera la copie. C'est le prix de la vérification, et il faut le compter en maintenance.

Enfin, le blocage lui-même peut devenir un obstacle. Un hook qui refuse de clore un tour parce que session-handoff.md n'a pas été mis à jour arrête aussi les sessions exploratoires où aucun changement de code n'a été produit. Le README ne décrit pas de mode permettant de désactiver sélectivement cette vérification.

Face à LangChain ou CrewAI : deux endroits différents pour la confiance

La comparaison la plus utile n'est pas une question de fonctionnalités mais de lieu où l'on place la confiance. LangChain et CrewAI fournissent des primitives d'orchestration : chaînes, agents, outils, gestion d'état. La conformité au protocole reste une affaire de prompt et de code appelant. Rien n'empêche structurellement un agent de sauter une étape de revue.

Harmonist déplace la confiance vers des scripts qui s'exécutent à des moments définis du cycle de session. L'orchestration elle-même est plus rudimentaire : pas de graphe d'exécution, pas de gestion d'état distribuée, pas de runtime. Le README assume ce choix en revendiquant l'absence de runtime, de base de données et de verrouillage fournisseur.

Le revers est symétrique. Un projet qui a besoin d'enchaînements conditionnels complexes entre agents trouvera davantage d'outils dans les frameworks d'orchestration. Un projet dont le problème principal est qu'une règle de revue saute régulièrement trouvera dans Harmonist un mécanisme que les autres n'ont pas.

Licence et coût de mise à jour

Le dépôt est publié sous licence MIT, ce qui autorise la modification et la redistribution avec conservation de l'avis de licence. Le README ne signale pas de clause additionnelle ni de restriction sur l'usage commercial. Je ne donne pas d'avis juridique : pour un usage en entreprise, la vérification du fichier LICENSE et des conditions de votre organisation reste nécessaire.

Le rythme de publication est soutenu. Trois versions apparaissent dans les données fournies : v1.1.0 le 8 juin 2026, puis v1.2.0 et v1.2.3 le 9 juin 2026, la dernière quelques secondes après une poussée sur main. Un tel enchaînement sur une seule journée suggère des correctifs rapprochés plutôt qu'un cycle de publication espacé.

Concrètement, cela signifie que le manifeste de hachages bouge souvent. Si vous modifiez localement des agents ou des hooks, chaque mise à jour du paquet vous demandera de réconcilier vos changements avec le nouveau MANIFEST.sha256 avant que upgrade.py n'accepte de copier quoi que ce soit.

Conclusion éditoriale

Harmonist convient aux équipes qui ont déjà des règles de revue non négociables et qui acceptent de les faire porter par des hooks plutôt que par le prompt. Il ne convient pas à un usage en CI sans IDE compatible, ni aux projets qui ne veulent pas maintenir un catalogue d'agents à jour. Avant d'adopter, vérifiez deux choses concrètes : que votre assistant expose bien un hook de fin de tour, et que le contenu de MANIFEST.sha256 correspond à ce que upgrade.py s'apprête à copier dans votre projet.

Sources officielles

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