/session-handoff compacta una sesión entera de agente en un archivo, para que una sesión nueva retome exactamente donde esta se detuvo, como si la ventana de contexto se hubiera agrandado en vez de reiniciarse. El sucesor no es un lector al que se le cuenta el trabajo de otro: es esta misma sesión, con una ventana nueva. Todo lo que necesita para actuar tiene que estar en disco, direccionable y ser cierto cuando lo lea.
Nota que la ventana se llena, o que el trabajo sigue más allá de esta sesión.
Todas, en orden. Una vacía se escribe como none con su razón.
Bajo .session/handoffs/, con el número que sigue en el linaje.
Recién con el archivo completo. Solo, si hay runtime; si no, una línea para pegar.
Un handoff mueve la sesión entera a su propio sucesor. Cada vecino de esta tabla mueve otra cosa, y tiene su propia puerta.
| Se parece a | En realidad es | Se usa |
|---|---|---|
| Pasarle una tarea acotada a otra sesión y supervisarla | Orquestación: una tarea sale, el trabajo vuelve | /orca-orchestration |
| Despachar un subagente para una pieza de trabajo | Un ejecutor con briefing, adentro de ESTA sesión | AGENTS.md §3, briefing-template.md |
| Retomar el pipeline de una historia después de una pausa | Estado de una skill, por ticket | /sprint-development fase 0, session-management.md |
| Recordar una decisión para el mes que viene | Un hecho durable entre sesiones, del proyecto | Engram (mem_save), un ADR o el tracker |
| Achicar la ventana y seguir | La compactación del harness: con pérdida, no direccionable, no la controlas | Nada que hacer |
| Pasar la SESIÓN entera a su sucesor | Esta skill | /session-handoff |
El humano ve que la ventana se llena, lo dice, y la skill corre. Sin polling, sin recordatorios, sin gastar tokens adivinando.
La respuesta, con citas, está en references/auto-trigger.md. Veredicto: parcialmente factible, y el manual sigue siendo el disparo principal.
Una sección sin nada que decir se escribe con una línea none y su razón. Una omitida y una olvidada se ven idénticas, y el sucesor no puede preguntar cuál pasó. El orden no es decorativo: se lee de arriba abajo con apuro, así que abre con lo único que hay que hacer y cierra con lo que siempre es cierto.
| § | Sección | Qué guarda | Qué evita |
|---|---|---|---|
| 0 | Tu PRIMERA tarea | Una tarea, no un menú. Los criterios del dueño citados, numerados, sin parafrasear. Los de una historia se citan por ruta del PBI sincronizado. | Un sucesor que redecide lo que ya estaba decidido, y elige distinto |
| 1 | Identidad y autoridad | Qué delegó el dueño y qué se reservó; harness, worktree, trailers; la estrategia de git y la política de push con sus valores resueltos de git_strategy:, no el nombre de la clave | Volver a preguntar algo delegado, o asumir un permiso que no existe |
| 2 | Qué se construyó | Un párrafo por unidad de trabajo, con SHAs, PRs, deploys y rutas. Pusheado o local, mergeado o abierto, desplegado o solo compilado | Rehacer trabajo que ya estaba terminado |
| 3 | Decisiones, cada una con su porqué | Alternativas descartadas, la razón, y quién decidió. Lo arquitectónico cita su ADR | Revertir una elección deliberada creyendo que fue un descuido |
| 4 | Gotchas y observaciones | Lo aprendido a los golpes, cada uno marcado measured o read, con la versión para la que vale | Pagar dos veces el mismo costo. Es la sección más valiosa y la que más flaca sale |
| 5 | Skills, herramientas y MCPs | Una tabla con la columna Load next session? respondida fila por fila con una razón | Recargar todo y quemar la ventana nueva, o no cargar nada y adivinar sintaxis |
| 6 | Archivos a leer, en orden | Lista numerada, rutas absolutas, para qué sirve cada uno. Los progress.md de skills, antes que el código que describen | Que el sucesor tenga que buscar lo que el predecesor ya encontró |
| 7 | Estado vivo que heredas | La sección perecedera. Ver frescura | Actuar sobre un mundo que ya no existe. Aquí es donde los handoffs se rompen |
| 8 | Trabajo pendiente, por prioridad | Ítems con letra, en el orden del dueño, con el próximo paso exacto. Separa lo decidido de lo que espera una decisión | Empezar por el ítem interesante en vez del importante |
| 9 | Convenciones que le importan al dueño | Cómo se presentan decisiones, qué se anuncia, idioma, registro, memoria. Cierra con el umbral al que el sucesor escribe su propio handoff | Reaprender preferencias equivocándose primero. Y un linaje que muere |
Recorre capture-contract.md sección por sección y llena templates/handoff.md.
Antes de escribir: lista el directorio de handoffs y re-verifica todo lo que va a §7.
Cuándo: el disparo es tuyo.
Un nombre para la sesión, si la identidad dice unknown.
Un markdown en inglés, gitignorado, desechable por diseño.
Lo durable no va aquí: va a Engram, al repo o al tracker, y el handoff lo cita.
Las conjeturas del predecesor sobre lo que va a encontrar el sucesor son útiles, y son lo primero que se vuelve viejo. Por eso cada afirmación lleva su etiqueta.
Todo lo que sigue en movimiento: PRs abiertos y sus checks, deploys sin confirmar READY para el SHA pusheado, subagentes o comandos en segundo plano, transiciones de Jira en vuelo, migraciones escritas sin aplicar, sesiones reanudables.
# forma de un ítem de §7 (templates/handoff.md) - **staging deploy**: `PERISHABLE`, measured <HH:MM>. Ids: `<sha>` `<deployment-id>`. Re-verify: `<the exact command>`. Then: <what to do with each outcome>.
<<PRIMARY_ROOT>> se resuelve igual desde el primario y desde cada worktree (.agents/README.md, sección "Checkout roots"). Nunca se deriva de pwd.
# la ruta <<PRIMARY_ROOT>>/.session/handoffs/<predecessor-session-name>-handoff-NN.md # cómo se resuelve PRIMARY_ROOT dirname "$(git rev-parse --path-format=absolute --git-common-dir)" # el linaje se lee en la lista de archivos: el nombre del sucesor es el basename sin extensión <base> <base>-handoff-01 <base>-handoff-01-handoff-02
Un handoff escrito adentro de un worktree muere con el worktree. Y dos worktrees del mismo linaje contarían NN cada uno desde su propio directorio vacío.
Si alguno quedó por error en el .session/ de un worktree, lo rescata bun run worktree:audit --rescue antes de que el worktree se vaya.
Listando <<PRIMARY_ROOT>>/.session/handoffs/. Dos dígitos desde 01, contados en todo el linaje. Nunca se asume. Dos handoffs con el mismo número son un linaje que no se puede leer.
Del valor session= de la línea AGENT IDENTITY: que inyecta el hook (la misma etiqueta que llevan los trailers de commit), con espacios y paréntesis cambiados por -. Si dice unknown, la IA te pide un nombre en vez de inventarlo.
Los nombres largos son el punto: un linaje que no se lee es un linaje que no se audita.
.session/ está ignorado. Un handoff describe el estado de una sesión, no es un registro del proyecto: commitearlo pondría una foto que se pudre bajo control de versiones.
El orden no se invierte: un sucesor que arranca primero lee un archivo que todavía no existe. Corre en el mismo worktree que el predecesor (<<REPO_ROOT>>) y en el mismo harness. Solo el archivo vive en el primario.
# el binario pelado: sus MCPs leen .env por el loader de .env claude # o: opencode · codex, el mismo harness del predecesor # el primer prompt, idéntico en los dos caminos Read `<absolute path to the handoff>` top to bottom and continue that session exactly where it stopped.
| Handoff (esta skill) | Orquestación (/orca-orchestration) | |
|---|---|---|
| Qué se mueve | La sesión entera | Una tarea acotada |
| El predecesor | Termina | Sigue trabajando y supervisa |
| Canal después | Ninguno, por diseño | Buzón, preguntas, respuestas |
| Objetos del runtime | Una terminal | Run, task, dispatch, worker |
Viven en el bloque ## Compact Rules y en "Hard rules" de la skill; las compactas son las que viajan a los subagentes por .agents/skills/REGISTRY.md.
No tiene modos: una sola corrida, tres pasos. Alcanza con nombrarla, o con frases como "hagamos el handoff", "pasa el contexto a otra sesión" o "hand this session over".
La barra de la skill, sin argumentos.
Sin barra: nombras la skill en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
Es chica a propósito: el artefacto pesado es el markdown que produce, y todo el contrato vive en references/capture-contract.md.
Para delegar una tarea acotada y supervisarla mientras sigues. Sus verbos de terminal y sus trampas son los que usa el lanzamiento con runtime.
Su fase 0 retoma una historia desde .session/sprint-development/<KEY>/progress.md. El handoff apunta a ese archivo, no lo copia.
Los hechos que sobreviven a la sesión van ahí. El handoff los cita; el predecesor cierra con mem_session_summary.