aapastech/claude-skill-session-backlog

Aapastech Session Backlog: nunca pierdas una tarea

Las sesiones largas y las indicaciones multitarea hacen que los asistentes de IA pierdan trabajo. Las solicitudes tempranas se desvanecen mientras un turno posterior profundiza en un detalle. Este skill soluciona eso con un backlog que vive en el propio ordenador del usuario. La memoria de la conversación no es la fuente de verdad; el backlog lo es. Una tarea que no está en el backlog no existe, y una tarea en el backlog no está terminada hasta que se marca como Hecha o Descartada.

Funciona con cualquier asistente o agente que pueda ejecutar comandos de shell en el ordenador del usuario o llamar a herramientas MCP. Cada sesión en ese ordenador, desde cualquier herramienta o modelo, comparte el mismo backlog.

Regla de privacidad: los datos de las tareas permanecen en el dispositivo que ejecuta el trabajo. Nunca copies el backlog a un servicio en la nube, una página alojada, un conector o un documento compartido. Si no se puede acceder a ningún dispositivo del usuario, utiliza el modo Offline (sección 9).

1. Encuentra el backlog y ejecuta el motor

Si tu lista de herramientas contiene herramientas backlog_* (el servidor MCP, sección 11), úsalas. Se corresponden uno a uno con los comandos siguientes y manejan la carpeta, la codificación y las actualizaciones por ti. Salta el resto de esta sección.

De lo contrario, el backlog es una carpeta que contiene bl.py (el motor), config.json, tasks/ (un archivo JSON por tarea), sessions/, board.html y BOARD.md. Búscala en este orden:

1. Una ubicación que el usuario te haya indicado, en sus preferencias, memoria o instrucciones del proyecto.
2. La variable de entorno BACKLOG_DIR, si está configurada.
3. ~/Documents/Aapastech-Backlog (la predeterminada).
4. ~/Documents/Claude-Backlog (el nombre de carpeta usado antes de v3; sigue usándolo si ahí es donde están las tareas del usuario).

Ejecutándolo. En este documento, bl <comando> es una abreviatura. Siempre escribe el comando completo; nunca lo almacenes en una variable de shell ($BL … falla en zsh, el shell predeterminado de macOS).

Shell	Comando
macOS / Linux (bash, zsh)	python3 ~/Documents/Aapastech-Backlog/bl.py <comando> …
Windows PowerShell	py -3 "$HOME\Documents\Aapastech-Backlog\bl.py" <comando> … (si falta py, prueba python)
Windows cmd	py -3 "%USERPROFILE%\Documents\Aapastech-Backlog\bl.py" <comando> …
Git Bash en Windows	py -3 ~/Documents/Aapastech-Backlog/bl.py <comando> …

bl where imprime la carpeta y la versión del motor que está usando. En Windows, Documents a menudo se mueve a OneDrive (%USERPROFILE%\OneDrive\Documents). Si ~\Documents no existe, búscalo allí y ofrece configurar BACKLOG_DIR para que cada sesión encuentre la misma carpeta.

Python. El motor necesita Python 3.8+ y nada más.

• macOS: la primera llamada a python3 en una Mac nueva puede abrir el diálogo "instalar herramientas de línea de comandos para desarrolladores" de Apple. Dile al usuario que es normal y seguro aceptar, o que instale Python desde python.org.
• Windows: Python normalmente no está instalado. Si py -3 y python fallan, pide al usuario que instale Python 3 desde python.org con "Agregar python.exe a PATH" marcado, o winget install Python.Python.3.12. No recurras a nada más.

2. Primera ejecución en un dispositivo (inicialización)

Si aún no existe un backlog:

1. Crea la carpeta ~/Documents/Aapastech-Backlog (o la ubicación elegida por el usuario).
2. Copia scripts/bl.py de la carpeta de este skill en ella. Es un único archivo Python solo con la biblioteca estándar que incluye el tablero.
3. Haz al usuario una pregunta breve: qué nombre mostrar para las tareas que esperan por él, y en qué áreas se encuadra su trabajo (3–8 áreas, p. ej., clientes, productos, administración, personal). Sugiere áreas basándote en lo que ya sepas de él. Luego ejecuta: bl init --owner "<nombre>" --areas "Area1,Area2,…,Personal,AI-Ops" Agrega --title "<Título del tablero>" si quieren un nombre de tablero propio (por defecto "Aapastech Backlog").
4. Diles la ubicación del tablero: file://…/Aapastech-Backlog/board.html. Ofrece abrirlo (bl board --open) y sugiere que fijen la pestaña.
5. Sugiere que hagan el skill permanente, p. ej., en las preferencias personales o el archivo de instrucciones de su asistente: "Carga siempre el skill de session-backlog al inicio de cada sesión y antes de cualquier tarea que implique trabajo."

Actualizaciones: si bl version imprime una versión inferior a scripts/bl.py de este skill (busca VERSION = "…"), copia el nuevo bl.py sobre el antiguo. Los datos de las tareas y la configuración no se modifican.

3. Identidad de sesión (una vez por sesión)

Elige un identificador de sesión estable y reutilízalo en cada llamada:

• Si tu plataforma asigna una URL o ID a la sesión, úsalo y pasa la URL como --url.
• De lo contrario: <superficie>-<AAAAMMDD-HHMM> usando la hora de inicio de la sesión, p. ej., desktop-20261018-1652, code-20261018-0910, api-20261018-1200, sched-20261019-0600.

bl session --id <SID> --label "<Superficie> · <tema principal>" --surface code|desktop|cloud|api|scheduled [--url <enlace>]

Esto imprime las tareas abiertas de esta sesión más las tareas no reclamadas o obsoletas de otras sesiones. Menciona las tareas vencidas o que esperan al usuario en una línea. No vuelques toda la lista.

4. El bucle de turno (cada turno con trabajo)

A. Vuelve a leer primero. Al inicio de cada turno después del primero, ejecuta bl open --session <SID>. Haz esto especialmente cuando la indicación sea una inmersión profunda en una subtarea. Este paso evita que se olvide otro trabajo. Nunca lo saltes.

B. Captura antes de trabajar. Cada nueva solicitud se captura en un lote antes de comenzar cualquier trabajo. Esto incluye comentarios como "también…", "recuérdame…", "luego…", "no olvides…". Escribe el lote en un archivo JSON con tu herramienta de escritura de archivos, luego pasa la ruta. Un archivo funciona en cualquier shell; canalizar JSON a través de echo falla en shells de Windows y distorsiona el texto que no es ASCII.

[
 {"title":"Rediseñar página de precios","area":"Producto","eta":"1h","priority":"P1",
  "source":"indicación 16:52: rehacer página de precios","next":"Obtener copia actual",
  "children":[{"title":"Auditar copia actual","eta":"10m"},
              {"title":"Borrador de 2 diseños","eta":"30m"},
              {"title":"Publicar diseño elegido","eta":"20m"}]},
 {"title":"Responder a proveedor","area":"Admin","eta":"15m","status":"waiting_user","next":"El usuario debe confirmar cantidad"}
]

bl batch --session <SID> <ruta-al-archivo.json> (coloca el archivo en tu espacio temporal o de trabajo, no en el proyecto del usuario).

Reproduce la captura en una línea compacta para que el usuario pueda corregirla:

Capturado: T-0042 Página de precios (1h) → T-0043 auditoría (10m), T-0044 diseños (30m), T-0045 publicar (20m); T-0046 Respuesta a proveedor (esperando por ti).

Primero verifica bl list y actualiza una tarea existente en lugar de crear un duplicado. Agrega "parent":"T-0042" (o --parent T-0042 en bl add) para poner una subtarea bajo una tarea existente.

C. Reclama, luego trabaja. Ejecuta bl claim <ID> --session <SID> [--eta 20m] antes de comenzar cada tarea. Si el reclamo es rechazado porque otra sesión activa lo posee, déjalo en paz. Los reclamos están bloqueados, por lo que dos sesiones nunca pueden ganar uno a la vez. Trabaja en paralelo cuando sea posible. La sesión orquestadora actualiza el backlog para sus subagentes, pasando a cada subagente su ID de tarea.

D. Actualiza sobre la marcha. bl update <ID> --session <SID> --log "decisión / hallazgo" [--next "…"] [--output <ruta o enlace>] [--status blocked|waiting_user|ready]

• Registra las decisiones del usuario con sus propias palabras.
• Cada archivo o enlace que produzcas va en --output.
• Esperar al usuario significa --status waiting_user --next "<exactamente lo que necesitas>".

E. Cierra honestamente. Ejecuta bl done <ID> --session <SID> --log "entregado …" --output … solo después de haber verificado el resultado. Una tarea padre no puede cerrarse mientras sus subtareas estén abiertas. Para abandonar una tarea, ejecuta bl drop <ID> --session <SID> --reason "…". Nunca elimines nada.

F. Pie de página. Termina cada respuesta que haya implicado trabajo con la salida de una línea de bl footer --session <SID> [--exclude <IDs recién informados>].

5. Áreas

Cada tarea de nivel superior recibe un área de config.json (bl areas las lista). Las subtareas heredan el área de su padre. Elige la que mejor se ajuste. Agrega una nueva área (bl areas --add "Nombre") solo cuando aparezca claramente una nueva línea de trabajo continua, y menciónalo cuando lo hagas. bl areas --rename ANTIGUO NUEVO renombra un área en la configuración y en cada tarea.

6. ETA (cada tarea tiene una)

• La ETA es el tiempo real para que el asistente termine, asumiendo trabajo en paralelo. Suele ser de 5 a 60 minutos, a veces horas y raramente días. Formato: 10m, 45m, 2h, 1h30m, 1d.
• Incluye el tiempo para verificar el resultado.
• La cuenta regresiva comienza en el reclamo o la creación. El tablero marca las tareas vencidas en rojo.
• Cuando superes el tiempo, vuelve a estimar de inmediato: --eta 1h --eta-reason "…". Nunca dejes que una tarea pase desapercibida.
• Para una tarea waiting_user, la ETA es el tiempo para terminar después de que el usuario responda.

7. Reglas entre sesiones

• Un reclamo permanece activo mientras su sesión siga actualizando la tarea. Después de 24 horas sin tocar, se vuelve obsoleto, y cualquier sesión puede tomarlo (la toma se registra).
• Nunca uses --force en un reclamo activo sin la aprobación del usuario.
• Antes de que termine un período largo de trabajo, deja cada tarea reclamada con un --next que una nueva sesión pueda retomar en frío. Libera el trabajo no terminado con --status ready --log "liberado: <estado>".
• Para "qué está abierto", "dónde estamos" o "qué hizo la otra sesión", responde desde bl list (--all, --area X, --session Y), no desde la memoria de conversación.
• El backlog pertenece a un solo dispositivo. Las sesiones en otros dispositivos, o en la nube, lo usan solo a través de un enlace a ese dispositivo.
• Si un comando dice que una tarea está ocupada, otra sesión la está escribiendo en ese instante. Reintenta una vez después de un momento.

8. Cuándo omitir la captura

Omite la captura solo para una pregunta puntual que se responda completamente en la misma respuesta. Captura todo lo demás: cualquier cosa que tenga un entregable, cualquier cosa que abarque más de un turno, y cualquier cosa diferida. En caso de duda, captúralo.

9. Modo offline (ningún dispositivo del usuario accesible)

1. Refleja las tareas en la lista de tareas propia de tu plataforma si tiene una, o en una lista de verificación en tu respuesta si no.
2. Pon en cola cada operación bl.py prevista, un objeto JSON por línea, en backlog-pending.jsonl en tu espacio temporal (nunca en el proyecto del usuario): {"cmd":"add","args":{…},"at":"<iso>"}.
3. Dile al usuario una vez: "Tu ordenador no está accesible, por lo que las actualizaciones del backlog están en cola y se sincronizarán cuando vuelva a estar disponible."
4. Reintenta el dispositivo en cada turno. Una vez que esté accesible, reproduce la cola en orden y ejecuta bl open.
5. Si la sesión termina antes de la sincronización, la última respuesta debe listar las tareas no sincronizadas en su totalidad.

10. El tablero

board.html se regenera en cada escritura y se actualiza automáticamente cada 30 segundos. Muestra:

• carriles por área, con las columnas Por hacer / En progreso / Bloqueado / Esperando a / Hecho
• la ETA y la cuenta regresiva en cada tarjeta, con las tareas vencidas en rojo
• qué sesión creó, trabajó y completó cada tarea
• un enlace para ver el registro completo y las salidas

BOARD.md es el mismo tablero en texto.

Cuando el usuario pida verlo ("muestra mi backlog", "abre el tablero", "¿qué está abierto?"):

• En el ordenador que contiene el backlog, ejecuta bl board --open para abrirlo en su navegador predeterminado.
• Si no se puede acceder a un navegador en ese ordenador (p. ej., un chat en el teléfono), pega un breve resumen de bl list agrupado por área, con las tareas vencidas y las que esperan al usuario primero.
• El tablero es un archivo local. Nunca se publica, sube ni comparte.

11. Notas de plataforma

• Clientes MCP (cualquier asistente o marco de agente). scripts/backlog_mcp.py es un servidor MCP de solo biblioteca estándar sobre stdio que expone backlog_session, backlog_open, backlog_add, backlog_claim, backlog_update, backlog_done, backlog_drop, backlog_list, backlog_show, backlog_footer, backlog_board, backlog_init y backlog_where. Regístralo con el comando python3 (Windows py, args -3 <ruta>) y argumentos <ruta a backlog_mcp.py>, opcionalmente con la variable de entorno BACKLOG_DIR. Ejecuta el mismo bl.py, por lo que las rutas de shell y MCP comparten un solo backlog.
• Agentes basados en API. Un modelo llamado a través de una API no tiene acceso por sí mismo a los archivos del usuario. El desarrollador ejecuta el servidor MCP (o bl.py detrás de su propia herramienta) en la máquina que posee el backlog y le da esas herramientas al modelo. Los sandboxes de código alojados son temporales, por lo que un backlog allí se pierde cuando el sandbox termina; no lo mantengas allí.
• Sesiones de Claude desktop / cloud / teléfono vinculadas al ordenador del usuario (herramientas de dispositivo como device_bash, device_request_folder_access, device_commit_files; cárgalas a través de tu búsqueda de herramientas si están aplazadas). La carpeta del backlog o su padre (p. ej., ~/Documents) debe ser una carpeta conectada; si no lo es, llama a device_request_folder_access una vez con el motivo "para mantener tu backlog de tareas en este ordenador". Luego ejecuta comandos a través de device_bash usando la ruta conectada (p. ej., python3 $HOME/mnt/Documents/Aapastech-Backlog/bl.py …). Para instalar bl.py a través del puente, prepara el archivo y confírmalo en el dispositivo (device_commit_files).
• Claude Code / Codex / Cursor / otros agentes de codificación ejecutan el motor directamente en su shell, según la tabla de la sección 1.

Referencia de comandos

bl init    [--owner NOMBRE] [--areas "A,B,C"] [--title T]       configuración inicial / cambiar propietario, áreas o título del tablero
bl version                                                    versión del motor
bl where                                                      carpeta del backlog, versión del motor, enlace al tablero
bl areas   [--add NOMBRE …] [--rename ANTIGUO NUEVO]           listar / agregar / renombrar áreas
bl session --id SID --label L --surface S [--url U]           registrar una sesión; imprime tareas abiertas
bl open    --session SID                                      tareas abiertas de esta sesión + no reclamadas
bl batch   --session SID archivo.json|-                        agregar muchas ("children" anidados = subtareas)
bl add     --session SID --title T --area A --eta 20m [--parent ID] [--status S] [--next N] [--priority P1]
bl claim   ID --session SID [--eta 20m] [--force]
bl update  ID --session SID [--status S] [--eta E --eta-reason R] [--next N] [--log L] [--output O] [--area A] [--title T]
bl done    ID --session SID [--log L] [--output O] [--force]
bl drop    ID --session SID --reason R
bl list    [--all] [--area A] [--session SID] [--json]
bl show    ID
bl footer  --session SID [--exclude <IDs recién informados>]
bl board   [--open]
bl where