Workspaces Kanban Hermes : scratch, dossier partagé ou worktree ?

Tu crées une tâche dans Kanban Hermes. Tu tapes hermes kanban create, tu remplis le titre, l’assignee, et là, une option que tu n’as pas encore regardée de près : --workspace. Scratch, dir, worktree. Trois mots, trois comportements radicalement différents.

Si tu choisis au hasard, tu vas le sentir passer. Un workspace scratch pour une tâche dont tu voulais garder les fichiers ? Ils disparaissent à la complétion. Un worktree pour une tâche sans dépôt git ? Ça plante. Un dossier partagé que tu croyais protégé contre les accès concurrents ? Mauvaise surprise.

Je te montre ce que chaque option fait vraiment, pour que tu choisisses en connaissance de cause.

Communauté Kavyro

Le vrai sujet n’est pas d’ajouter un agent de plus.

Si tu veux construire un système d’agents utile, il te faut surtout une structure claire, de bons arbitrages et des retours terrain. C’est exactement ce qu’on partage dans Kavyro.

Cas concrets
Arbitrages utiles
Questions réelles
Accès gratuit

Rejoindre la communauté

Tu arrives avec ton sujet, tu repars avec plus de clarté.

Scratch : le workspace jetable

C’est le mode par défaut. Quand tu ne specifies rien, Kanban crée un dossier temporaire dans ~/.hermes/kanban/workspaces/<id>/. Le worker bosse dedans, produit ce qu’il doit produire, et quand la tâche passe en done, le dossier est nettoyé automatiquement.

Ce que ça implique concrètement :

• Aucun fichier ne survit à la tâche. Si le worker a généré un rapport, un script, un fichier de config, tout disparaît.
• Le worker reçoit $HERMES_KANBAN_WORKSPACE qui pointe vers ce dossier. Il n’a pas besoin de savoir où il est, il travaille dedans.
• Aucune configuration nécessaire. C’est le choix zero-setup.

Quand c’est le bon choix : tâches de recherche, analyse ponctuelle, vérification rapide, tout ce qui produit un résultat dans le summary ou le metadata de kanban_complete plutôt que dans des fichiers à conserver.

Exemple : tu demandes à un worker de vérifier si tes 14 skills sont à jour. Il lit, il compare, il te répond dans le summary. Aucun fichier à garder. Scratch est parfait.

Quand ça coince : si la tâche suivante a besoin des fichiers produits par celle-ci. Ou si tu veux inspecter ce qui a été généré après coup. Scratch est volontairement éphémère.

Dir : le dossier partagé persistant

Tu le déclares avec --workspace dir:<path>. Le chemin peut être absolu ou relatif. Exemple : dir:../tenants/project-data/.

Contrairement à scratch, le dossier n’est jamais nettoyé automatiquement. Les fichiers restent là après la complétion. Plusieurs tâches peuvent pointer vers le même dossier.

Ce que ça change :

• Les fichiers survivent. Tu peux enchaîner des tâches qui lisent les sorties des précédentes.
• Tu peux utiliser un dossier qui existe déjà, avec des données déjà présentes.
• Le worker voit le même $HERMES_KANBAN_WORKSPACE, mais cette fois il pointe vers un endroit durable.
• Tu peux configurer un workspace par défaut pour tout le board avec kanban.default_workdir dans config.yaml.

Quand c’est le bon choix : tâches de production de contenu, génération de rapports, extraction de données, tout ce qui produit des artefacts que d’autres tâches ou toi-même allez réutiliser.

Exemple : un worker extrait des données, les écrit dans dir:../data/extractions/. Le worker suivant lit ces fichiers pour produire une synthèse. Sans dir, tu devrais tout faire dans la même tâche ou bidouiller des transferts.

Piège à connaître : dir:<path> ne gère pas la concurrence. Si deux workers écrivent dans le même dossier en même temps, le comportement n’est pas documenté. Kanban est conçu pour du single-host, pas pour de la coordination multi-processus sur un système de fichiers partagé. On en parle plus bas.

Worktree : le git worktree isolé

Tu le déclenches avec --workspace worktree ou --workspace worktree:<path>. Kanban exécute git worktree add pour créer un worktree isolé avec sa propre branche. Le worker bosse dans ce worktree, commit si nécessaire, et le worktree est nettoyé après complétion.

Ce que ça apporte :

• Isolation totale : le worker a sa branche dédiée, il ne pollue pas ta branche courante.
• Le workspace est un vrai dépôt git. Le worker peut commit, push, créer une PR.
• Nettoyage automatique comme scratch, mais avec la puissance de git derrière.
• La branche est nommée de façon déterministe : soit tu la specifies avec --branch, soit Kanban la génère.

Quand c’est le bon choix : toute tâche qui touche du code. Refactoring, fix, feature, review automatique, génération de tests. Si le worker doit produire un diff ou une PR, worktree est l’option naturelle.

Exemple : tu assignes une tâche « corrige le bug de pagination » à un profile dev. Worktree lui donne une branche isolée, il corrige, il commit, il te met le diff dans le summary. Tu review, tu merge. Rien n’a touché ta branche principale.

Prérequis : il faut un dépôt git existant. Si tu lances un worktree hors d’un dépôt, ça échoue. Et si ton dépôt est volumineux, le git worktree add peut prendre quelques secondes.

Les risques du dossier partagé

dir:<path> est pratique, mais il a une limite importante qu’il faut regarder en face.

Ce que ça veut dire en pratique :

• Si tu enchaînes des tâches séquentiellement (la B attend que la A soit done), dir:<path> fonctionne très bien. La tâche B lit ce que A a écrit, aucun risque.
• Si deux tâches indépendantes pointent vers le même dossier et tournent en parallèle, tu es en terrain non documenté. Ça peut marcher, ça peut casser. Tu n’as aucune garantie.
• Pour du partage safe entre tâches, le pattern recommandé est de faire dépendre les tâches les unes des autres (via parents dans kanban_create). La tâche enfant ne démarre que quand la parente est terminée. Le dossier partagé devient un simple support de passage de fichiers, pas un espace de travail concurrent.

Autre point d’attention : dir:<path> n’est jamais nettoyé. Si tu crées 50 tâches qui écrivent dans le même dossier sans nettoyer derrière, tu vas accumuler. Ce n’est pas grave, mais c’est à toi de gérer le ménage.

Comment choisir en 30 secondes

Tu te poses trois questions, dans l’ordre :

1. Est-ce que la tâche touche du code dans un dépôt git ? → Worktree.
2. Est-ce que les fichiers produits doivent survivre à la tâche ? → Dir.
3. Sinon ? → Scratch.

Critère	Scratch	Dir	Worktree
Durée de vie des fichiers	Tâche terminée = supprimés	Persistant	Tâche terminée = nettoyé
Partage entre tâches	Non	Oui (lecture, séquentiel)	Non (isolé)
Git intégré	Non	Non	Oui (branche dédiée)
Nettoyage automatique	Oui	Non	Oui
Setup requis	Aucun	Chemin à fournir	Dépôt git existant
Usage type	Recherche, analyse, vérification	Production de contenu, rapports, données	Code, refactoring, PR, tests

Quelques cas concrets pour fixer les idées :

• Tu veux qu’un worker audite tes skills et te fasse un rapport dans le summary → Scratch. Pas de fichier à garder.
• Tu fais produire un jeu de données par un worker, puis un autre worker doit générer des graphiques à partir de ces données → Dir. Les fichiers doivent survivre entre les deux tâches.
• Tu veux qu’un worker corrige un bug et te propose une PR → Worktree. Il lui faut une branche git isolée.
• Tu as un dossier partagé où plusieurs workers écrivent des logs → Dir, mais en séquentiel seulement. Si les workers tournent en parallèle, tu prends un risque.

Ce que tu ne peux pas faire avec ces workspaces

Deux limites à garder en tête :

Pas de coordination multi-host. Kanban est single-host par conception. Si tu as deux machines qui tournent des workers, elles ne partagent pas le même kanban.db, et un dir:<path> sur un filesystem réseau n’est pas protégé par Kanban.

Pas de locking. Aucun des trois workspaces ne fournit de mécanisme de verrouillage. Si tu as besoin que deux workers ne se marchent pas dessus, le seul mécanisme fiable est la dépendance entre tâches (parents/enfants).

Ces limites ne sont pas des défauts. Elles viennent du fait que Kanban est un ordonnanceur de tâches, pas un système de fichiers distribué. Le workspace est un répertoire de travail, pas une base de données partagée.

Mettre ça en place sans se planter

Si tu utilises déjà Kanban pour des tâches simples, tu es probablement en scratch sans le savoir, et c’est très bien. Le moment où tu veux passer à dir ou worktree, c’est quand tu commences à enchaîner des tâches qui produisent des fichiers.

Mon conseil : commence par configurer un kanban.default_workdir dans ton config.yaml si la majorité de tes tâches partagent un même dossier. Comme ça, tu n’as pas à y penser à chaque create. Et pour les tâches de code, passe en worktree explicitement.

Si tu veux qu’on regarde ta config ensemble et qu’on mette en place un workflow Kanban adapté à tes tâches de code ou de prod, tu peux faire une demande directement sur la page du Second Cerveau.

Réserve ta place dans le Second Cerveau →