/handoff — Transfert de travail entre outils
Aucun outil de codage IA ne peut lire le transcript d'un autre : Claude Code verrouille les sessions dans ~/.claude/projects/<munged-cwd>/<uuid>.jsonl, Codex/OpenCode dans leurs propres stockages, Antigravity dans des .pb chiffrés. La seule chose portable entre les outils est un document autonome. Cette compétence écrit ce document — votre objectif actuel, vos décisions, et les modifications non commitées EXACTES — pour que tout autre agent IA puisse reprendre là où vous vous êtes arrêté, sans que vous ayez à réexpliquer quoi que ce soit.
Utilisez cette compétence quand l'utilisateur manque de tokens, veut changer d'outil en cours de tâche, se déplace vers une autre machine, ou dit "handoff" / "continue elsewhere" / "plus de tokens".
Cette compétence est autonome : elle fonctionne avec seulement git + un shell. Elle appelle specweave handoff comme accélérateur optionnel quand ce binaire est sur le PATH (haute fidélité, conscient des incréments) — mais elle n'a aucune dépendance stricte à l'installation de SpecWeave.
Décision : quelle voie emprunter
command -v specweave >/dev/null 2>&1 && echo "ACCELERATEUR" || echo "AUTONOME"
- ACCELERATEUR (
specweavesur PATH) → exécutez le moteur, affichez sa sortie. Allez en Chemin A. - AUTONOME (pas de
specweave) → construisez le document vous-même avecgit+ un court entretien. Allez en Chemin B.
Les deux chemins émettent le même format de document et le même prompt de collage (voir le modèle canonique ci-dessous), donc un transfert est continuable dans n'importe quel outil quel que soit le chemin qui l'a produit.
Chemin A — Accélérateur (specweave sur PATH)
Exécutez le moteur, en transmettant tout contexte court que vous pouvez fournir à moindre coût :
specweave handoff [incrementId] [--reason "..."] [--summary "..."] [--next "..."] [--gotcha "..."] [--decision "..."] [--inline]
Ensuite, affichez sa sortie standard textuellement, dans l'ordre (ne réorganisez ni ne paraphrasez) :
- chemin absolu du document en texte brut (EN PREMIER), 2. lien cliquable en markdown, 3. chemin du
.diff, - prompt de reprise dans un bloc de code, 5. conseils "trouver votre session source" par outil.
Terminé. Le moteur a géré la détection de l'espace de travail, l'analyse des tâches/CA, la capture git, le dump du diff complet, le nettoyage des secrets et le rendu.
Chemin B — Autonome (pas de specweave)
Construisez un document compatible au niveau octet en utilisant uniquement le shell.
B1. Capturer l'état git (gratuit — pas de tokens)
ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
mkdir -p "$ROOT/.handoff"
printf '*\n' > "$ROOT/.handoff/.gitignore" # ne jamais laisser le handoff ou son diff entrer dans git
BRANCH="$(git -C "$ROOT" rev-parse --abbrev-ref HEAD 2>/dev/null || echo '(pas de git)')"
SHA="$(git -C "$ROOT" rev-parse --short HEAD 2>/dev/null || echo '(aucun commit)')"
STATUS="$(git -C "$ROOT" status --porcelain 2>/dev/null)"
STAT="$(git -C "$ROOT" diff --stat 2>/dev/null)"
# Toutes les modifications non commitées → fichier .diff (arbre de travail + index), artefact de fidélité clé
{ git -C "$ROOT" diff HEAD 2>/dev/null; git -C "$ROOT" diff --cached 2>/dev/null; } > "$ROOT/.handoff/handoff.diff"
B2. Entretien en cinq questions (uniquement les champs non dérivables)
Demandez à l'utilisateur (limitez-vous à ~5 chaînes courtes — peu coûteuses même en cas d'épuisement des tokens) :
- raison — pourquoi effectuez-vous le transfert ? (ex. "plus de tokens")
- résumé — une ligne : où en sommes-nous ?
- prochaine étape — l'étape suivante exacte.
- piège — y a-t-il quelque chose que le prochain agent NE doit PAS faire / doit savoir ?
- décisions — décisions clés déjà prises (séparées par des points-virgules).
B3. Nettoyage des secrets (avant l'écriture — SUR le texte libre ET le diff)
Remplacez les correspondances par [REDACTED-<type>] et comptez par motif. Motifs (12) :
sk-, ghp_, gho_, ghs_, AKIA, ASIA, -----BEGIN, vsk_, xox[bap]-, Bearer , password=, api_key=.
# nettoyer le diff capturé sur place, ex. :
sed -i.bak -E \
-e 's/sk-[A-Za-z0-9_-]+/[REDACTED-sk]/g' \
-e 's/gh[pos]_[A-Za-z0-9_-]+/[REDACTED-gh-token]/g' \
-e 's/(A[KS]IA[0-9A-Z]{16})/[REDACTED-aws-key]/g' \
-e 's/vsk_[A-Za-z0-9_-]+/[REDACTED-vsk]/g' \
-e 's/xox[bap]-[A-Za-z0-9-]+/[REDACTED-slack]/g' \
-e 's/Bearer [A-Za-z0-9._-]+/Bearer [REDACTED-bearer]/g' \
-e 's/(password=)[^[:space:]]+/\1[REDACTED-password]/g' \
-e 's/(api_key=)[^[:space:]]+/\1[REDACTED-api_key]/g' \
"$ROOT/.handoff/handoff.diff" && rm -f "$ROOT/.handoff/handoff.diff.bak"
Le nettoyage est heuristique — une liste de rédactions vide n'est PAS une garantie que le fichier est propre.
B4. Écrire le document
Écrivez le modèle canonique ci-dessous dans $ROOT/.handoff/HANDOFF.md, en remplissant les champs capturés + de l'entretien.
Sentinel de propriété : si un fichier ./HANDOFF.md racine existe déjà et NE contient PAS le marqueur Doc format v1, c'est un fichier étranger — ne l'ÉCRASEZ PAS ; écrivez dans .handoff/HANDOFF.md à la place (ce qui est le comportement par défaut ici de toute façon).
B5. Afficher la sortie — chemin absolu en premier, dans cet ordre
- Le chemin absolu de
.handoff/HANDOFF.mden texte brut. - Un lien cliquable en markdown vers celui-ci.
- Le chemin absolu de
.handoff/handoff.diff. - Le prompt de collage dans un bloc de code (voir ci-dessous).
- Les conseils "trouver votre session source" par outil.
Modèle de document de transfert canonique (EN LIGNE — source unique de vérité)
Affichez ces sections dans cet ordre exact, en terminant par le marqueur de pied de page Doc format v1. Les espaces réservés entre crochets sont remplis avec l'état git capturé + l'entretien. Cela reflète le handoff-doc-format.ts de specweave, donc un document produit ici est compatible au niveau octet avec un document produit par la CLI.
# Transfert de travail[: <titre si connu>]
- Chemin du doc : <CHEMIN_ABSOLU_DOC>
- Lien du doc : [<CHEMIN_ABSOLU_DOC>](<CHEMIN_ABSOLU_DOC>)
- Fichier diff : <CHEMIN_ABSOLU_DIFF>
- Généré le : <HORODATAGE_ISO>
- Espace de travail : <RACINE> (non-SpecWeave)
- Git : branche `<BRANCHE>` @ `<SHA>`
## Là où je me suis arrêté
**Raison du transfert :** <raison>
**Résumé :** <résumé>
_Aucun incrément SpecWeave actif — il s'agit d'un transfert git + entretien._
## Fait / En attente
_Aucun état de tâche/CA d'incrément disponible._
## Décisions clés et pièges
- <décision 1>
- <décision 2>
**Piège :** <piège>
## Fichiers modifiés
**NON COMMITÉS** — commitez, stashz, ou continuez à éditer AVANT de faire quoi que ce soit de destructeur.
<git status --porcelain>
<git diff --stat>
Diff complet non commité : `<CHEMIN_ABSOLU_DIFF>` — lisez-le ou exécutez `git apply --check` dessus pour voir les modifications exactes.
## Prochaines étapes exactes
<prochaine_étape>
## Comment reprendre
Si le chemin du document ci-dessus N'existe PAS sur la machine sur laquelle vous lisez ceci, ARRÊTEZ-VOUS et demandez à l'utilisateur de coller le transfert — n'improvisez pas de contexte.
Pour récupérer le transcript ORIGINAL (optionnel), trouvez votre session source par outil :
### Claude Code
- Trouver la session : ls ~/.claude/projects/<munged-cwd>/ (munge : chaque caractère non alphanumérique → "-", les suites NON réduites ; ex. /Users/antonabyzov/Projects/github/specweave-umb/.claude-worktrees/x → -Users-antonabyzov-Projects-github-specweave-umb--claude-worktrees-x)
- Reprendre : `claude -r <uuid>`
### Codex
- Trouver la session : ls ~/.codex/sessions/ (le dossier le plus récent = session la plus récente)
- Reprendre : `codex resume <uuid> (ou : codex resume --last)`
### OpenCode
- Trouver la session : opencode sessions list
- Reprendre : `opencode -s <id> (forme longue : opencode --session <id>)`
### Gemini CLI
- Trouver la session : exécutez /chat list dans la session Gemini pour voir les tags sauvegardés
- Reprendre : `/chat resume <tag>`
### Antigravity
- Trouver la session : ouvrez le Gestionnaire d'Agents Antigravity et sélectionnez le fil de tâche précédent
- Reprendre : `reprendre le fil depuis le Gestionnaire d'Agents Antigravity`
### Aider
- Trouver la session : aider conserve .aider.chat.history.md dans la racine du dépôt
- Reprendre : `aider --restore-chat-history`
## Rédactions
- <N> chaînes `<type>` masquées
_Le nettoyage est heuristique (regex de base). Une liste de rédactions vide n'est PAS une garantie que ce fichier est propre — vérifiez avant de partager ou de commiter._
---
<!-- Doc format v1 -->
Notes sur le modèle :
- S'il n'y a aucune modification non commitée, remplacez le corps de Fichiers modifiés par
_Arbre de travail propre — aucune édition non commitée._(ou_Pas un dépôt git — aucun diff capturé._quand il n'y a pas de git). - S'il n'y a aucune décision, le corps Décisions clés est
_Aucune décision enregistrée._; omettez la ligne Piège : quand aucun piège n'a été donné. - Le corps Rédactions est
_Aucune chaîne de type token détectée._quand rien n'a été masqué. - Le marqueur de pied de page
<!-- Doc format v1 -->est obligatoire et doit être la dernière ligne — c'est le sentinel de propriété.
Prompt de collage
Par défaut (fichier accessible) :
Reprenez mon travail. Lisez le document de transfert à : <CHEMIN_ABSOLU_DOC>
Si ce chemin n'existe PAS sur cette machine, ARRÊTEZ-VOUS et demandez-moi de coller le transfert — n'improvisez pas de contexte.
Les modifications non commitées exactes se trouvent dans : <CHEMIN_ABSOLU_DIFF>
--inline (machine distante, fichier inaccessible) : incorporez le corps COMPLET du document entre des marqueurs pour qu'il voyage dans le prompt lui-même :
Reprenez mon travail en utilisant le transfert autonome ci-dessous.
Ceci est un document de transfert complet — traitez tout ce qui se trouve entre les marqueurs comme la vérité de référence. S'il fait référence à un chemin `.diff` qui n'existe pas sur cette machine, demandez-moi de coller le diff.
DÉBUT TRANSFERT
<document de transfert complet rendu, incluant le pied de page Doc format v1>
FIN TRANSFERT
Sécurités par défaut
- Le document + diff sont ignorés par git par défaut (
.handoff/.gitignore=*) et jamais auto-commités. N'affichez pas d'indicegit add. - Le nettoyage des secrets s'exécute sur le texte libre et le diff avant toute écriture.
- Le nettoyage est heuristique — conseillez à l'utilisateur de vérifier avant de partager ou de commiter.