netheremp/baton-pass-netheremp

Baton Pass

Objectif : préserver la continuité entre plusieurs agents avec le minimum de texte nécessaire.

C'est un utilitaire de workflow à faible consommation de jetons, pas une cérémonie de documentation.

Configuration rapide

Installer sur chaque agent (une fois par machine)

npx github:netheremp/baton-pass-netheremp install

Installe cette compétence dans ~/.claude et chaque répertoire personnel ~/.codex*. Ensuite :

• Claude Code (CLI + IDE) — la compétence se charge automatiquement ; /new-game /save-state /baton-pass /foresight /dragon-dance /party-check /hindsight
• Codex CLI — la compétence se charge automatiquement ; exécutez-la explicitement avec $baton-pass
• Application de bureau Codex — la compétence se charge automatiquement ; /prompts:baton-pass dans le compositeur

Alternatives : /plugin marketplace add netheremp/baton-pass-netheremp (Claude Code) ou /plugins → installer (Codex).

Initialiser un dépôt pour le travail multi-agent

npx github:netheremp/baton-pass-netheremp init

Ajoutez --track-state pour versionner l'état de transfert (équipes ayant besoin d'historique partagé). Par défaut, local uniquement (ignoré par git).

Ceci crée :

• baton-pass.config.json — où le workflow trouve vos fichiers mémoire
• baton-pass.state.json — état de propriété partagé léger
• docs/agent-handoff.md — règles spécifiques au dépôt pour tous les agents
• docs/current-state.md — ce qui se passe actuellement
• docs/next-task.md — qui possède le travail et ce qui vient ensuite
• docs/progress.md — journal de session en cours (ajout seulement)

init dépose également les commandes slash /move dans .claude/commands/ du dépôt.

L'ensemble des mouvements

• new-game = initialiser le workflow dans un dépôt vierge
• save-state = mettre en pause en toute sécurité sans transférer
• baton-pass = transférer le travail lorsque les jetons sont faibles ou que la propriété change
• foresight = recevoir ou reprendre le travail, vérifier l'alignement, puis continuer
• dragon-dance = améliorer le workflow uniquement lorsqu'une véritable leçon a été apprise
• party-check = inspecter qui a agi en dernier, qui devrait agir ensuite, et l'état actuel du dépôt
• hindsight = auditer la chaîne complète des transferts — jalons revendiqués, vérifications effectuées, risques portés, éléments jamais résolus

Règle fondamentale

Par défaut, delta, pas de récapitulatif.

Ne répétez pas l'historique stable du projet à moins que le récepteur ne puisse pas continuer en toute sécurité sans cela.

Quand utiliser chaque mouvement

new-game

À utiliser une fois au démarrage du dépôt, ou lors de l'introduction de ce workflow dans un dépôt qui n'a pas encore de fichiers mémoire partagés.

save-state

À utiliser lorsque :

• vous devez vous arrêter soudainement
• vous mettez le travail en pause pour plus tard
• la propriété ne change pas encore

save-state est un point de contrôle local, pas un transfert.

baton-pass

À utiliser lorsque :

• les jetons sont faibles
• un autre agent prend le relais
• vous avez besoin d'un package de continuité transférable

baton-pass est un point de contrôle de transfert.

foresight

À utiliser lorsque :

• vous recevez un témoin
• vous revenez après un save-state
• il y a un doute que l'état écrit corresponde toujours au dépôt

dragon-dance

À utiliser uniquement lorsque :

• le workflow lui-même a appris quelque chose
• le récepteur a trouvé une dérive
• le témoin a omis quelque chose d'important
• une nouvelle règle empêcherait clairement des gaspillages répétés

Ne déclenchez pas dragon-dance par réflexe. Ne l'incluez pas dans chaque session ou baton-pass par défaut.

party-check

À utiliser lorsque :

• vous avez oublié à qui est le tour
• plusieurs agents partagent le dépôt
• vous voulez l'état actuel sans payer le coût d'un foresight complet

party-check est le mouvement en session. Depuis un terminal simple (pas d'agent, pas de jetons), exécutez baton-pass status — il affiche la même lecture de propriété ainsi que la chaîne récente des transferts, et baton-pass status --json produit une sortie lisible par machine pour les scripts et les hooks.

hindsight

À utiliser lorsque :

• un jalon ou une fonctionnalité majeure est terminé et vous voulez un enregistrement propre
• quelque chose semble anormal et vous devez retracer ce qui a été réellement revendiqué par rapport à ce qui a été fait
• un nouvel agent arrive et a besoin d'une vue d'ensemble complète de l'historique, pas seulement du dernier transfert
• un foresight a trouvé une dérive sévère et vous devez comprendre jusqu'où elle a commencé
• le projet est en cours de révision, remis à un humain ou archivé

N'exécutez pas hindsight après chaque transfert. C'est un audit, pas un point de contrôle de routine.

Ce que chaque mouvement doit écrire

save-state

Sortie minimale :

• tâche en cours
• arrêté à
• fichiers touchés
• prochaine action immédiate
• blocage ou risque

baton-pass

Sortie minimale :

• objectif
• fait
• tâches (si vous utilisez un plan de tâches — listez chaque tâche avec son statut : fait / en cours / en attente)
• fichiers
• worktree (nom de branche et chemin du worktree si vous utilisez des git worktrees)
• vérifié
• écarts (décisions prises en milieu de session qui diffèrent du plan initial)
• environnement (prérequis que le prochain agent doit confirmer : services en cours d'exécution, variables d'environnement définies, bases de données de test, etc.)
• suite
• risques
• prochain agent

Discipline de commit :

• Committez avant de transférer, ou documentez pourquoi.
• Ne transférez jamais un arbre de travail sale sans nommer explicitement l'état non commité.
• Si la vérification n'a pas été exécutée, dites-le — n'impliquez pas qu'elle a réussi.

Pourquoi les tâches, worktree, écarts et environnement sont importants : La mémoire de session est perdue lors du transfert. Si vous êtes à mi-chemin d'un plan de 20 tâches, le prochain agent ne peut pas reconstruire quelles tâches sont terminées à partir du seul journal git — écrivez le statut explicitement. Si vous travaillez dans un worktree, le prochain agent a besoin du chemin exact. Si vous avez corrigé quelque chose différemment du plan, écrivez-le — le prochain agent relira le plan et le refera de la mauvaise manière. Si l'environnement doit être dans un état spécifique (base de données en cours d'exécution, .env rempli), nommez-le — un agent frais rencontrera le même blocage sans cela.

foresight

Sortie minimale :

• aligné ou non
• si non aligné, ce qui était obsolète ou manquant
• prochaine étape corrigée uniquement si nécessaire

Si la dérive est sévère (le témoin prétend que le travail a été fait mais le dépôt montre le contraire), écrivez un rapport de dérive structuré avant de continuer :

• ce qui a été revendiqué
• ce que le dépôt montre réellement
• ce qui doit être refait
• si cette dérive justifie un dragon-dance

dragon-dance

Sortie minimale :

• problème
• impact
• amélioration
• nouvelle convention

party-check

Sortie minimale :

• état
• dernier mouvement
• dernier agent
• prochain agent
• mis à jour à
• résumé court

hindsight

Sortie minimale :

• périmètre d'audit (chaîne complète ou plage limitée)
• tableau de la chaîne des transferts (de → à, date, résumé de l'objectif)
• jalons revendiqués par agent avec statut de vérification
• lacunes de vérification (revendications faites sans preuve)
• risques reportés d'un transfert à l'autre
• dérive constatée d'un transfert à l'autre
• éléments ouverts jamais résolus
• verdict d'audit : clean, gaps found, risks unresolved ou action required

Sources à vérifier :

• docs/progress.md — journal complet de session
• docs/next-task.md — historique de l'état de tour
• baton-pass.state.json — état programmatique
• journal git — messages de commit et dates
• tous les fichiers de transfert ou de sauvegarde référencés dans le journal

Procédure de réception pour foresight

Vérifiez uniquement le minimum nécessaire pour éviter les erreurs :

• objectif actuel de l'utilisateur
• état de l'arbre de travail
• dernier(s) commit(s)
• current-state
• next-task
• dernière entrée de progress
• fichiers nommés dans l'état sauvegardé ou le transfert
• statut de la liste de tâches si un plan était en cours

Ensuite, décidez :

• si aligné, continuez
• si non aligné, corrigez le transfert et continuez
• si le non-alignement révèle une leçon réutilisable, exécutez dragon-dance

Découverte de compétence entre agents

Lorsque les compétences sont installées localement dans un projet (dans .claude/commands/ ou via installation de plugin dans le dépôt), Codex et les autres agents qui récupèrent le dépôt trouveront les mêmes définitions de compétence. Les fichiers de compétence voyagent avec le dépôt.

Ce que les compétences ne TRANSPORTENT PAS à travers une limite de session :

• L'état des tâches des gestionnaires de tâches en mémoire (les listes TaskCreate sont perdues à la fin de la session)
• L'état d'exécution des sous-agents (quelles boucles de révision sont terminées, quels agents ont été exécutés)
• L'état de l'environnement (quels services sont en cours d'exécution, quelles variables d'environnement sont définies)

Le baton-pass doit écrire tout cela explicitement. Les compétences disent aux agents comment travailler ; le témoin leur dit où en sont les choses.

Modèle d'état

Utilisez le fichier d'état partagé pour suivre :

• état actuel
• dernier mouvement
• dernier agent
• prochain agent
• heure de mise à jour
• résumé

États recommandés :

• active
• paused
• handed-off
• claimed
• blocked

Vocabulaire de vérification

Utilisez un langage cohérent pour que les récepteurs sachent exactement ce qui a été vérifié.

• passed — exécuté localement, sortie confirmée propre
• passed outside sandbox — exécuté localement mais pas dans l'environnement CI/build
• not run — [reason] — ignoré, indiquez la raison
• expected to pass, unverified — non exécuté, mais présumé correct

N'écrivez jamais passed quand vous voulez dire expected to pass, unverified. Cette seule ambiguïté cause le plus de rework lors des transferts.

État de tour

Le bloc d'état de tour dans next-task est le principal signal de propriété lisible par un humain. baton-pass.state.json le reflète pour une utilisation programmatique.

Lorsque vous mettez à jour l'un, mettez à jour l'autre. S'ils sont en désaccord, next-task prévaut.

Valeurs state recommandées dans les deux :

• active — quelqu'un travaille actuellement
• paused — arrêté en toute sécurité, le même agent reprendra
• handed-off — transféré, en attente que le récepteur le réclame
• claimed — le récepteur a exécuté foresight et continue
• blocked — ne peut pas continuer, la raison doit être dans next-task

Anti-patrons

Évitez :

• d'utiliser baton-pass pour chaque petit point de contrôle
• d'utiliser dragon-dance alors que rien n'a été appris
• de réécrire tous les fichiers mémoire pour un travail trivial
• de transformer foresight en audit complet du dépôt à chaque fois
• d'exécuter hindsight après chaque transfert — c'est un audit, pas une étape de routine
• de répéter tout le projet au lieu du delta
• d'écrire passed quand vous voulez dire expected to pass, unverified
• de transférer avec un arbre de travail sale sans nommer l'état non commité
• d'omettre le statut des tâches lorsque vous êtes à mi-chemin d'un plan numéroté
• d'omettre le chemin du worktree lorsque le travail est dans un git worktree
• d'omettre les prérequis d'environnement qu'un agent frais ne connaîtrait pas

Meilleur flux pratique

Pause :

• save-state
• plus tard foresight

Transfert :

• baton-pass
• le récepteur exécute foresight

Amélioration :

• dragon-dance uniquement si foresight a exposé un problème de workflow significatif

Vérifier la propriété du tour :

• party-check

Auditer la chaîne complète :

• hindsight
• si des lacunes ou des risques non résolus sont trouvés, exécutez dragon-dance