netheremp/baton-pass-netheremp

Baton Pass

Propósito: preservar la continuidad entre múltiples agentes con la menor cantidad de texto necesaria.

Esta es una utilidad de flujo de trabajo de bajo consumo de tokens, no una ceremonia de documentación.

Configuración rápida

Instalar en cada agente (una vez por máquina)

npx github:netheremp/baton-pass-netheremp install

Instala esta habilidad en ~/.claude y en cada directorio ~/.codex*. Luego:

• Claude Code (CLI + IDE): la habilidad se carga automáticamente; comandos /new-game, /save-state, /baton-pass, /foresight, /dragon-dance, /party-check, /hindsight
• Codex CLI: la habilidad se carga automáticamente; ejecútala explícitamente con $baton-pass
• Codex app de escritorio: la habilidad se carga automáticamente; usa /prompts:baton-pass en el compositor

Alternativas: /plugin marketplace add netheremp/baton-pass-netheremp (Claude Code) o /plugins → instalar (Codex).

Inicializar un repositorio para trabajo multi-agente

npx github:netheremp/baton-pass-netheremp init

Añade --track-state para confirmar el estado de traspaso en git (equipos que necesitan historial compartido). Por defecto es solo local (gitignorado).

Esto crea:

• baton-pass.config.json — donde el flujo de trabajo encuentra tus archivos de memoria
• baton-pass.state.json — estado de propiedad compartida ligero
• docs/agent-handoff.md — reglas específicas del repositorio para todos los agentes
• docs/current-state.md — lo que está sucediendo ahora mismo
• docs/next-task.md — quién es responsable del trabajo y qué viene después
• docs/progress.md — registro de sesión en ejecución (solo añadir)

init también coloca los comandos /move en el directorio .claude/commands/ del repositorio.

El Conjunto de Movimientos

• new-game = inicializar el flujo de trabajo en un repositorio nuevo
• save-state = pausar de forma segura sin transferir
• baton-pass = transferir el trabajo cuando los tokens están bajos o cambia la propiedad
• foresight = recibir o reanudar trabajo, verificar alineación y luego continuar
• dragon-dance = mejorar el flujo de trabajo solo cuando se ha aprendido una lección real
• party-check = inspeccionar quién actuó por última vez, quién debería actuar después y el estado actual del repositorio
• hindsight = auditar la cadena completa de traspasos: hitos reclamados, verificaciones realizadas, riesgos arrastrados, elementos nunca resueltos

Regla Principal

Por defecto, delta, no resumen.

No repitas el historial estable del proyecto a menos que el receptor no pueda continuar de forma segura sin él.

Cuándo Usar Cada Movimiento

new-game

Úsalo una vez al inicio del repositorio, o al introducir este flujo de trabajo en un repositorio que aún no tiene archivos de memoria compartidos.

save-state

Úsalo cuando:

• debas detenerte repentinamente
• estés pausando el trabajo para más tarde
• la propiedad no esté cambiando aún

save-state es un punto de control local, no una transferencia.

baton-pass

Úsalo cuando:

• los tokens estén bajos
• otro agente esté tomando el control
• necesites un paquete de continuidad transferible

baton-pass es un punto de control de transferencia.

foresight

Úsalo cuando:

• recibas un traspaso
• regreses después de un save-state
• tengas alguna duda de que el estado escrito aún coincida con el repositorio

dragon-dance

Úsalo solo cuando:

• el flujo de trabajo en sí haya aprendido algo
• el receptor haya encontrado desviación
• el traspaso haya omitido algo importante
• una nueva regla pueda prevenir claramente un desperdicio repetido

No actives dragon-dance por reflejo. No lo incluyas en cada sesión o baton-pass por defecto.

party-check

Úsalo cuando:

• hayas olvidado de quién es el turno
• múltiples agentes compartan el repositorio
• quieras el estado actual sin pagar por un foresight completo

party-check es el movimiento en sesión. Desde una terminal simple (sin agente, sin tokens) ejecuta baton-pass status — imprime la misma lectura de propiedad más la cadena de traspasos reciente, y baton-pass status --json proporciona salida legible por máquina para scripts y hooks.

hindsight

Úsalo cuando:

• un hito o funcionalidad importante esté completo y quieras un registro limpio
• algo parezca incorrecto y necesites rastrear qué se reclamó realmente versus lo que se hizo
• un nuevo agente se esté uniendo y necesite una imagen completa del historial, no solo el último traspaso
• un foresight haya encontrado una desviación severa y necesites entender desde cuándo comenzó
• el proyecto esté siendo revisado, entregado a un humano o archivado

No ejecutes hindsight después de cada traspaso. Es una auditoría, no un punto de control rutinario.

Qué Debe Escribir Cada Movimiento

save-state

Salida mínima:

• tarea actual
• detenido en
• archivos tocados
• próxima acción inmediata
• bloqueador o riesgo

baton-pass

Salida mínima:

• objetivo
• hecho
• tareas (si se usa un plan de tareas — lista cada tarea con estado: hecho / en progreso / pendiente)
• archivos
• árbol de trabajo (nombre de rama y ruta del árbol de trabajo si se usan git worktrees)
• verificado
• desviaciones (decisiones tomadas durante la sesión que difieren del plan original)
• entorno (requisitos previos que el próximo agente debe confirmar: servicios en ejecución, variables .env configuradas, BD de pruebas, etc.)
• siguiente
• riesgos
• próximo agente

Disciplina de confirmación:

• Confirma antes de transferir, o documenta por qué no.
• Nunca entregues un árbol de trabajo sucio sin nombrar el estado no confirmado explícitamente.
• Si no se ejecutó la verificación, dilo — no impliques que pasó.

Por qué importan las tareas, el árbol de trabajo, las desviaciones y el entorno: La memoria de la sesión se pierde en la transferencia. Si estás a mitad de un plan de 20 tareas, el próximo agente no puede reconstruir qué tareas están hechas solo a partir del registro de git — escribe el estado explícitamente. Si estás trabajando dentro de un árbol de trabajo, el próximo agente necesita la ruta exacta. Si solucionaste algo de manera diferente a lo que decía el plan, escríbelo — el próximo agente volverá a leer el plan y lo hará mal de nuevo. Si el entorno debe estar en un estado específico (base de datos en ejecución, .env configurado), nómbralo — un agente nuevo encontrará el mismo bloqueador sin esa información.

foresight

Salida mínima:

• alineado o no
• si no está alineado, qué estaba desactualizado o faltaba
• siguiente paso corregido solo si es necesario

Si la desviación es grave (el traspaso afirma que se hizo el trabajo pero el repositorio muestra lo contrario), escribe un informe estructurado de desviación antes de continuar:

• lo que se reclamó
• lo que realmente muestra el repositorio
• lo que debe rehacerse
• si esta desviación justifica un dragon-dance

dragon-dance

Salida mínima:

• problema
• impacto
• mejora
• nueva convención

party-check

Salida mínima:

• estado
• último movimiento
• último agente
• próximo agente
• actualizado en
• breve resumen

hindsight

Salida mínima:

• alcance de la auditoría (cadena completa o rango acotado)
• tabla de la cadena de traspasos (de → a, fecha, resumen del objetivo)
• hitos reclamados por agente con estado de verificación
• vacíos de verificación (reclamos hechos sin evidencia)
• riesgos arrastrados a través de traspasos
• desviaciones encontradas a través de traspasos
• elementos abiertos nunca resueltos
• veredicto de auditoría: limpio, vacíos encontrados, riesgos no resueltos o se requiere acción

Fuentes a verificar:

• docs/progress.md — registro completo de sesiones
• docs/next-task.md — historial de estado de turno
• baton-pass.state.json — estado programático
• git log — mensajes de confirmación y fechas
• cualquier archivo de traspaso o save-state guardado referenciado en progress

Procedimiento de Recepción para foresight

Verifica solo el mínimo necesario para evitar pasos en falso:

• objetivo actual del usuario
• estado del árbol de trabajo
• confirmaciones más recientes
• current-state
• next-task
• entrada más reciente de progress
• archivos nombrados en el estado o traspaso guardado
• estado de la lista de tareas si había un plan en progreso

Luego decide:

• si está alineado, continúa
• si está desalineado, corrige el traspaso y continúa
• si la desalineación revela una lección reutilizable, ejecuta dragon-dance

Descubrimiento de Habilidades Entre Agentes

Cuando las habilidades están instaladas localmente en el proyecto (en .claude/commands/ o mediante instalación de plugin en el repositorio), Codex y otros agentes que recojan el repositorio encontrarán las mismas definiciones de habilidades. Los archivos de habilidades viajan con el repositorio.

Qué habilidades NO se transfieren a través de un límite de sesión:

• Estado de tareas de gestores de tareas en memoria (las listas de TaskCreate se pierden cuando la sesión termina)
• Estado de ejecución de subagentes (qué bucles de revisión se completaron, qué agentes se ejecutaron)
• Estado del entorno (qué servicios están en ejecución, qué variables .env están configuradas)

El traspaso debe escribir todo esto explícitamente. Las habilidades le dicen a los agentes cómo trabajar; el traspaso les dice dónde están las cosas.

Modelo de Estado

Usa el archivo de estado compartido para rastrear:

• estado actual
• último movimiento
• último agente
• próximo agente
• hora de actualización
• resumen

Estados recomendados:

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

Vocabulario de Verificación

Usa un lenguaje consistente para que los receptores sepan exactamente qué se verificó.

• passed — se ejecutó localmente, la salida confirmó que es correcto
• passed outside sandbox — se ejecutó localmente pero no en el entorno de CI/construcción
• not run — [reason] — se omitió, indica la razón
• expected to pass, unverified — no se ejecutó, pero se cree correcto

Nunca escribas passed cuando quieras decir expected to pass, unverified. Esa única ambigüedad causa la mayor parte del retrabajo en los traspasos.

Estado de Turno

El bloque de Estado de Turno en next-task es la señal principal de propiedad legible por humanos. baton-pass.state.json lo refleja para uso programático.

Al actualizar uno, actualiza ambos. Si alguna vez discrepan, next-task tiene prioridad.

Valores de state recomendados en ambos:

• active — alguien está trabajando ahora
• paused — se detuvo de forma segura, el mismo agente reanudará
• handed-off — transferido, esperando que el receptor lo reclame
• claimed — el receptor ha ejecutado foresight y está continuando
• blocked — no se puede continuar, la razón debe estar en next-task

Anti-patrones

Evita:

• usar baton-pass para cada punto de control insignificante
• usar dragon-dance cuando no se aprendió nada
• reescribir todos los archivos de memoria para trabajo trivial
• convertir foresight en una auditoría completa del repositorio cada vez
• ejecutar hindsight después de cada traspaso — es una auditoría, no un paso rutinario
• repetir todo el proyecto en lugar del delta
• escribir passed cuando quieras decir expected to pass, unverified
• transferir con un árbol de trabajo sucio sin nombrar el estado no confirmado
• omitir el estado de las tareas cuando se está a mitad de un plan numerado
• omitir la ruta del árbol de trabajo cuando se trabaja dentro de un git worktree
• omitir los requisitos previos del entorno que un agente nuevo no conocería

Mejor Flujo Práctico

Pausa:

• save-state
• luego foresight

Transferencia:

• baton-pass
• el receptor ejecuta foresight

Mejora:

• dragon-dance solo si foresight expuso un problema significativo en el flujo de trabajo

Verificar la propiedad del turno:

• party-check

Auditar la cadena completa:

• hindsight
• si se encuentran vacíos o riesgos no resueltos, ejecuta dragon-dance