Herdr Multiagent : Workflow des agents de codage parallèles

--- name: herdr-multiagent description: Exécuter plusieurs agents de codage en parallèle sous Herdr : décomposition en étapes, un git worktree, environnement isolé, panneau et brief fichier par agent, surveillance d'état, revue, fusion. Le kind enfant est lu depuis `herdr pane current` (.result.pane.agent) et correspond à l'orchestrateur (omp, opencode, claude, codex, kimi, ...). Nécessite HERDR_ENV=1. --- # Travail multi-agents via Herdr Playbook : décomposer les tâches d'un projet en étapes indépendantes, assigner chaque étape à un agent séparé dans son propre git worktree et panneau herdr, fournir un brief fichier, surveiller et accepter le résultat. Compétence indépendante de l'agent : kind des enfants = kind de l'orchestrateur. Si vous lancez la compétence depuis opencode - les enfants seront opencode ; depuis omp - omp ; depuis claude - claude. Ne remplacez jamais le kind de l'orchestrateur de mémoire et ne choisissez pas un kind « populaire ». ## 0. Prérequis ```bash test "${HERDR_ENV:-}" = 1 # sans cela - stop, nous ne sommes pas dans Herdr ``` Si la vérification échoue - dire à l'utilisateur que la session n'est pas sous Herdr, et s'arrêter. Ne pas gérer un Herdr externe depuis l'extérieur. Les commandes de base des panneaux/agents - dans la compétence standard Herdr (`herdr --skill`). Le binaire installé fait autorité pour la syntaxe ; en cas de doute, lisez `herdr agent`, `herdr pane`, `herdr integration`, ne devinez pas. ## 1. Déterminer son propre kind - avant toute action ```bash herdr pane current --current ``` Le champ `.result.pane.agent` - c'est le kind de l'orchestrateur, c'est aussi la valeur pour `--kind` des enfants : ```bash KIND=$(herdr pane current --current | jq -r '.result.pane.agent') # sans jq : KIND=$(herdr pane current --current | sed -E 's/.*"agent":"([^"]+)".*/\1/' | head -1) echo "$KIND" ``` Vide ou `unknown` - demander à l'utilisateur avec quel kind lancer les enfants. Dans la suite du texte, `$KIND` - c'est la valeur obtenue, pas un littéral. Vérifier l'intégration Herdr ↔ ce kind (elle fournit `agent list/wait/prompt`) : ```bash herdr integration status | grep -i "$KIND" ``` - `current` - ok. - `not installed` - `herdr integration install "$KIND"`. L'intégration n'est prise en compte que par les **nouvelles** sessions, donc l'installer AVANT de lancer les enfants ; l'orchestrateur lui-même restera invisible pour `agent list` - c'est normal, il n'a pas besoin d'être surveillé. - kind absent de la liste `herdr integration install` (par exemple `amp`, `cline`, `kiro`, `maki`) - pas de surveillance structurelle, on travaille avec le fallback §7 (`pane read` + git). Ce n'est pas un bloqueur. Enregistrer et annoncer à l'utilisateur : « kind des enfants = $KIND ». ## 2. Décomposition - l'étape principale, ne vous précipitez pas - Lisez le plan/spécification du projet et l'état actuel (`git log`, tests, `git worktree list`). - Divisez le travail restant en étapes avec des **zones de fichiers non chevauchantes**. Deux agents sur le même package - seulement délibérément et avec un ordre explicite (après, pas en parallèle). - Les modifications additives de fichiers communs (config, lock) sont autorisées - les écrire dans les briefs « uniquement de manière additive, sans changer les signatures » ; les conflits de fusion seront résolus par l'orchestrateur. - Fixez la matrice « étape → fichiers que l'on PEUT / NE PEUT PAS toucher ». Avant le lancement : tout ce qui est prêt dans main est commité, l'arbre est propre. ## 3. Worktree + environnement isolé par agent ```bash git worktree add ../<proj>-s<N> -b stage-<N>-<name> ``` Piège des projets Python : le venv partagé importe le code D'AUTRUI (installation editable du dépôt principal). Pour chaque worktree - son propre venv : ```bash cd ../<proj>-s<N> && python -m venv .venv \ && ./.venv/Scripts/python.exe -m pip install -q -e "./api[dev]" ``` Installer plusieurs venv séquentiellement dans une seule commande en arrière-plan (cache pip partagé). Stack JS : ses propres `node_modules` dans chaque worktree (`npm ci`). Si l'orchestrateur a un hook d'encapsulation de commandes (rtk et similaires) : le chemin relatif vers l'interpréteur (`../.venv/Scripts/python.exe`) dans le brief via un tel hook ne se résout pas (« command not found »). Dans le brief et les prompts - uniquement des chemins ABSOLUS vers python/npm du worktree concerné. ## 4. Briefs - par fichiers, pas en ligne de commande `<repo>/.briefs/stage-<N>.md` (non suivi). Structure du brief : - **contexte** : quoi lire en premier (spécification, contrat, fichiers clés), ce qui est déjà fait ; - **tâche** : exigences concrètes avec références aux points de la spécification ; - **limites** : fichiers autorisés/interdits, « ne sors pas du worktree », « NE PAS faire de push » ; - **acceptation** : commandes exactes de tests/linter (avec le chemin absolu vers l'interpréteur du worktree), « les anciens tests restent verts », commit dans sa propre branche, rapport final. Le brief ne doit pas présumer un kind d'agent spécifique : n'y écrivez pas « lance omp/skill/... » - écrivez l'objectif, les limites et les commandes d'acceptation. L'enfant décidera lui-même avec quels de ses propres outils le faire. Prompt à l'agent court : « Lis le fichier <brief> et exécute-le jusqu'au bout ». ## 5. Panneaux : créer, puis NOMMER immédiatement Disposition recommandée - main-left : panneau de l'orchestrateur à gauche sur toute la hauteur, tous les enfants en colonne à droite les uns sous les autres. Si l'utilisateur a des plugins de disposition conçus pour main-left, tout autre schéma cassera sa vue. Si l'utilisateur demande explicitement une autre disposition - exécutez-la. Premier enfant - `split --current --direction right`, les autres - `split --pane <enfant précédent> --direction down` DANS la colonne de droite. NE PAS diviser le panneau de l'orchestrateur et ne pas diviser les panneaux des agents vers la droite - uniquement une chaîne down dans la colonne de droite. ```bash herdr pane split --current --direction right --cwd "<worktree1>" --no-focus herdr pane split --pane <agent1-pane> --direction down --cwd "<worktree2>" --no-focus ``` ID du nouveau panneau - depuis le JSON `.result.pane.pane_id`. Ne pas toucher au focus de l'utilisateur (`--no-focus`). Le nom de l'enfant est donné à l'étape 6 via `agent start`, plus pour la clarté `herdr pane rename <pane_id> "s<N>-<name>"`. ## 6. Lancement de l'enfant de son propre kind Chemin standard - `agent start`, il valide aussi que l'agent attendu est bien monté dans le panneau : ```bash herdr agent start s1-<name> --kind "$KIND" --pane <pane_id> -- <drapeaux-d'autonomie> ``` Le nom doit correspondre à `[a-z][a-z0-9_-]{0,31}` et être unique parmi les agents vivants. ### Drapeaux d'autonomie L'enfant travaille sans humain, sinon il s'arrêtera sur une approbation. Le drapeau dépend du CLI, pas de Herdr. Confirmés : | kind | lancement | |---|---| | `omp` | `-- --yolo` | | `claude` | `-- --dangerously-skip-permissions` (ou `--permission-mode bypassPermissions`) | | `opencode` | `-- --auto` | Pour tout autre kind (codex, gemini, kimi, cursor, copilot, droid, kilo, grok, hermes, qodercli, mastracode, pi, …) - NE PAS inventer de drapeau. Déterminer l'exécutable canonique et lire son aide : ```bash herdr agent start --help # dans la description de --kind est indiqué l'exécutable canonique <exécutable> --help | grep -iE "permission|approve|yolo|auto|dangerous|allow" ``` Drapeau non trouvé → vérifier s'il existe un mode d'autonomie dans la config du CLI (par exemple `~/.omp/agent/config.yml: tools.approvalMode: yolo`, `~/.claude/settings.json: permissions`, `opencode.json: permission`), et prévenir l'utilisateur que l'enfant peut s'arrêter sur des approbations - visibles comme état `blocked` (§7). ### Si `agent start` échoue par timeout Bug connu sur Windows dans les panneaux PowerShell : `agent start` envoie un `Start-Process` corrompu → timeout. Contournement - lancer le CLI dans le panneau directement : ```bash herdr pane run <pane_id> "<exécutable> <drapeaux-d'autonomie>" sleep 3 && herdr pane read <pane_id> --lines 15 # on attend le prompt du CLI herdr agent rename <pane_id> s1-<name> # si herdr a reconnu l'agent ``` Si après cela `herdr agent explain <pane_id>` ne donne pas d'agent reconnu - la surveillance structurelle pour ce panneau est indisponible, on travaille avec le fallback §7. ### Distribution du brief PAS via `pane run` : l'Entrée est avalée pendant que le TUI rend l'insertion. En deux étapes avec pause : ```bash herdr pane send-text <pane_id> "Lis le fichier <chemin absolu vers le brief> - c'est ton brief. Exécute-le entièrement jusqu'au bout (code, tests, linter, commit dans ta branche), puis donne un rapport final." sleep 5 && herdr pane send-keys <pane_id> Enter ``` Alternative standard, quand l'intégration est installée et `agent start` a fonctionné : ```bash herdr agent prompt s1-<name> "Lis le fichier <brief> et exécute-le jusqu'au bout" --wait --timeout 300000 ``` Vérifier avec `pane read` que le brief est PARTI : input vide, l'agent travaille. ## 7. Surveillance - via l'intégration, PAS cron ```bash herdr agent list # statuts de tous les enfants herdr agent wait s1-<name> --until idle --timeout 1800000 herdr agent prompt s1-<name> "<texte>" # ajouter une instruction à un agent en cours herdr agent read s1-<name> --lines 40 ``` Sémantique des états : `idle` - prêt pour l'entrée et son onglet a été vu dans l'UI ; `done` - même idle après un travail en arrière-plan invisible (la lecture via CLI ne marque pas l'onglet comme vu) ; `blocked` - herdr a reconnu l'UI d'approbation/question, l'enfant ATTEND un humain ; `unknown` - l'agent existe, mais pas de classification, ce n'est PAS un signe de fin. Cycle de l'orchestrateur : `agent wait` un par un ou par événement → acceptation (§8). `blocked` → `agent read`, comprendre la question, répondre via `agent prompt` ou demander à l'utilisateur. Silence suspect → `pane read <pane_id>`. Timeout de `wait` modéré (~30 min) et réarmé à chaque déclenchement : les très grandes valeurs partent en « timed out ». Fallback, quand l'intégration pour `$KIND` est indisponible ou `agent explain` n'a pas reconnu l'enfant : `herdr pane read <pane_id> --lines 60` périodique + `git log/status` dans le worktree. Cron - seulement en dernier recours et obligatoirement supprimé à la fin. Interruption de session de l'enfant : le travail dans le worktree est conservé. Relance - avec le même CLI et son drapeau de continuation (vérifier dans `--help`) : `omp --resume`, `claude --continue`, `opencode --continue`. Puis prompt : « Session interrompue. Vérifie git status, termine le brief <fichier> jusqu'au bout ». ## 8. Acceptation et fusion - Chaque branche : tests + linter dans son worktree, revue `git diff main...<branche> --stat`. - Ne pas accepter le rapport final de l'enfant sur parole - vérifier les commandes d'acceptation soi-même. - Fusion dans main - uniquement avec confirmation de l'utilisateur ; les chevauchements additifs à résoudre manuellement. - Après la fusion : `git worktree remove` ; branches - selon accord avec l'utilisateur. - Libérer les panneaux des enfants, sans toucher au panneau de l'utilisateur.