1017293270/claude-task-lines

Línea Principal y Secundaria: Manual del Coordinador

Si una tarea larga se hace siempre en un mismo diálogo, este se comprime una y otra vez y se pierden detalles. Esta skill propone:

• Coordinador (la sesión que invoca esta skill): Entiende los requisitos, investiga, divide en líneas, redacta las tareas, abre sesiones, recibe informes, fusiona, verifica y se comunica con el usuario. El coordinador no escribe grandes fragmentos de código; deja el contexto para lo global. Puede resolver conflictos o hacer pequeñas correcciones de una o dos líneas.
• Línea: Cada línea es una sesión lateral en su propio worktree. Sigue la tarea asignada y, al terminar, envía un informe al coordinador. El usuario puede entrar directamente en esa sesión y conversar con ella.
• Libro de contabilidad: ~/.claude/mods-data/task-lines/boards/<id del libro>/. Aquí se guardan todos los detalles. El diálogo se puede comprimir, pero el libro de contabilidad no. El plugin task-lines coloca automáticamente el libro de contabilidad en el contexto después de una compresión: el coordinador recupera las últimas partes de board.md y log.md, y la línea recupera su tarea y progreso.

En adelante, scripts/ se refiere a la carpeta de scripts del directorio de esta skill (el "Base directory" que se muestra al cargar la skill).

Puesta en marcha

1. Crear el libro de contabilidad: Invoca task_board con title igual al título corto de la tarea. Luego usa mcp__ccd_session_mgmt__get_session (con session_id = self) para obtener el ID de sesión de escritorio de esta sesión (que empieza con local_), y escríbelo en board.md. Las líneas usarán este ID para enviarte informes.

2. Anotar las palabras originales: Pega las palabras exactas del usuario en board.md en la sección "Palabras originales del usuario". No las reescribas ni hagas solo un resumen.

3. Investigar: Lee hasta que puedas redactar la tarea con claridad, incluyendo el código relevante, la documentación y el CLAUDE.md del proyecto. Debes conocer el estado actual, los archivos relacionados, las convenciones del proyecto y los comandos de verificación. Escribe las conclusiones en "Restricciones y decisiones tomadas".

4. Dividir en líneas: Sigue las reglas de la sección "Cómo dividir" y escribe los resultados en la tabla de líneas.

5. Crear una línea base: Ejecuta scripts/snapshot.sh <directorio principal> refs/task-lines/<id del libro>/base-1 y escribe el ID del commit resultante en "Línea base actual". La instantánea incluye los cambios no commiteados y los archivos no rastreados del directorio principal, pero no afecta al área de staging, HEAD ni a las ramas.

6. Redactar la tarea: Para cada línea que se pueda poner en marcha ahora, escribe lines/<id de línea>/brief.md siguiendo la plantilla siguiente.

7. Abrir sesiones: Por cada línea, invoca una vez mcp__ccd_session__spawn_task:

   • title: [L1] Título corto que empiece por verbo, 60 caracteres o menos. El prefijo [id de línea] se usará más tarde para encontrar esta sesión.
   • tldr: Una o dos frases en lenguaje natural que digan qué hace esta línea.
   • prompt: El texto completo de la tarea. El prompt debe poder entenderse por sí mismo; no escribas solo "ve al libro de contabilidad".

   Cada línea aparecerá como una tarjeta; el usuario debe hacer clic en ella para abrir la sesión. Las nuevas sesiones vienen con un worktree independiente.

8. Informar al usuario: Dile en qué líneas se ha dividido, qué hace cada una, cuáles se pueden iniciar ahora y cuáles deben esperar a que se fusionen las anteriores. Pídele que haga clic en las tarjetas. Empieza a trabajar directamente después de dividir; no esperes la aprobación del plan. El usuario puede detener o cambiar en cualquier momento.

9. Registrar en el log: Usa task_note para anotar un registro.

Cómo dividir

• Línea principal: Es la columna vertebral de la tarea. Si es muy larga, divídela en fases (L1, L2, ...). Cada fase abre una nueva sesión que empieza desde la línea base más reciente. Cada sesión solo carga el contexto de una fase; esto es clave para no perder detalles.
  • Las fases son secuenciales: después de fusionar y verificar una fase, crea una nueva línea base, escribe la tarea de la siguiente fase, y en esa tarea incluye el traspaso de la fase anterior.
• Línea secundaria: Son trabajos relativamente independientes de la línea principal, como otro módulo, scripts de herramientas, tests complementarios o investigaciones. Las líneas secundarias pueden ejecutarse en paralelo con la principal; sus IDs son S1, S2, ...
• Tamaño de una línea: Debe poder realizarse de principio a fin en una sola sesión sin que se comprima varias veces. Si tienes dudas, divídela en partes más pequeñas.
• Las líneas que se ejecutan a la vez deben evitar modificar los mismos archivos: Los worktrees solo aíslan los entornos de ejecución; si modifican los mismos archivos, al fusionar se generarán conflictos.
  • Las interfaces compartidas (firmas de funciones, formatos de datos, rutas de archivos) deben definirse antes de empezar, y escribirse textualmente en cada tarea relevante.
• Cuántas líneas abrir a la vez: Generalmente de 2 a 3. Cada línea puede pedir al usuario permisos o hacer preguntas; si hay muchas, el usuario no puede atenderlas todas.
• No dividir lo que no merezca la pena: Si una tarea se puede hacer sin problemas en una sola sesión, hazla directamente y no abras un libro de contabilidad.

Plantilla de tarea

El contenido entre ángulos debe ser rellenado por el coordinador. Para las secciones que no apliquen, escribe "Ninguno" y no las elimines.

# [<id de línea>] <Título>

Eres una línea en el libro de contabilidad <id del libro>. El coordinador es otra sesión. Sigue las instrucciones a continuación y, al terminar, envía el informe al coordinador.

## Antes de empezar
1. Invoca task_line_attach con board = "<id del libro>" y line = "<id de línea>". Esta herramienta pertenece al plugin task-lines; si no la tienes, omite este paso e indícalo en el informe.
2. Confirma que estás en tu propio worktree: la salida de `git rev-parse --show-toplevel` no debe ser <directorio principal>. Si lo es, detente e informa al usuario.
3. Alinea la línea base: primero confirma que la salida de `git status --porcelain` esté vacía, luego ejecuta `git reset --hard <commit de la línea base>`. La línea base contiene los cambios no commiteados del directorio principal; si no te alineas, tus cambios no se podrán fusionar.
4. Prepara el entorno: <por ejemplo, pnpm install. El worktree no tiene node_modules, y el directorio target de Rust está vacío; la primera compilación puede ser lenta>

## Contexto y objetivo
<Las partes de las palabras originales del usuario relacionadas con esta línea, copiadas textualmente; cómo debería quedar la línea al terminar; por qué se hace>

## Hechos conocidos
<Conclusiones de la investigación: archivos y números de línea relevantes, estado actual, convenciones del proyecto, fragmentos de código existentes que se pueden copiar, decisiones ya tomadas>

## Alcance
- Se puede modificar: <archivos o directorios>
- No tocar: <archivos o directorios>
- Otras líneas en ejecución: <id de línea: qué archivos modifican>
- No tocar el directorio principal <ruta> en ningún caso; solo modifica tu propio worktree.

## Interfaces acordadas
<Firmas, formatos compartidos con otras líneas; copia textual>

## Verificación
<Comandos concretos: tests, type checks, compilación, ejecución real. Si implica interfaz, haz una captura de pantalla y mírala>

## Disciplina
- Puedes hacer commits en tu propia rama para guardar el progreso, pero no hagas push ni toques otras ramas.
- Sigue las convenciones del proyecto en CLAUDE.md.
- Usa task_note para registrar decisiones clave, descubrimientos y progreso. Después de una compresión del diálogo, lo necesitarás para continuar.
- Si el usuario te hace nuevas peticiones directamente en esta sesión, hazlas e informa al coordinador con las palabras exactas en tu informe.
- Si necesitas una decisión del coordinador o del usuario, o si algo está fuera del alcance: primero anótalo con task_note, luego pregunta al coordinador. No amplíes tu alcance por tu cuenta.

## Al terminar
Envía un mensaje al coordinador usando SendMessage con to = "<ID de sesión de escritorio del coordinador>". Si no tienes SendMessage, usa mcp__ccd_session_mgmt__send_message con el mismo session_id.
La primera línea debe ser "[<id de línea>] Completado: <una frase>", y después:
- Ruta del worktree (salida de `git rev-parse --show-toplevel`) y nombre de la rama
- Qué has cambiado (por archivo), por qué lo has hecho así, qué compensaciones has hecho
- Verificación: qué comandos has ejecutado y los resultados reales. Si ha fallado, indica que ha fallado.
- Problemas restantes y decisiones que necesita el coordinador o el usuario
- Nuevas peticiones del usuario en esta sesión (palabras exactas)
Guarda también una copia del informe con task_note. Cuando termines, detente y espera la respuesta del coordinador; puede que te pida rehacer algo.

Mientras las líneas están en ejecución

• No hagas polling. Las líneas enviarán un mensaje cuando terminen; aparecerá como un mensaje de esa sesión.
• Consulta el progreso: Cuando el usuario pregunte por el progreso, usa mcp__ccd_session_mgmt__list_sessions para encontrar las sesiones por el prefijo del título [id de línea], y luego mcp__ccd_session_mgmt__list_events para ver lo que están haciendo. Anota los IDs de sesión encontrados en la tabla de líneas.
• La línea hace una pregunta: Si puedes decidir, responde directamente a esa sesión y anótalo en el libro de contabilidad. Si necesita la decisión del usuario, pídesela a él.
• El usuario hace una nueva petición en el diálogo principal: Primero, añade las palabras exactas a "Palabras originales del usuario" en board.md, indicando la hora. Luego evalúa a qué línea afecta: envía un mensaje a esa línea, o déjalo para la siguiente fase.
• La línea se atasca o se desvía: Envía un mensaje para corregirla.

Recepción y fusión (para cada línea)

1. Ensayo: Primero lee el informe, luego ejecuta scripts/merge-line.sh --check <directorio principal> <línea base de esta línea> <ruta del worktree de la línea>. Listará los archivos que se van a actualizar, fusionar (tres vías), añadir, eliminar, y cuáles tendrán conflictos. La última línea dará un comando para ver el diff completo de la línea.

2. Revisión:

   • ¿Ha modificado archivos fuera del alcance?
   • ¿La lógica es correcta y se parece al código existente del proyecto?
   • ¿Hay elementos superfluos?
   • ¿Los comentarios y el texto siguen las convenciones del proyecto?

   Si no es aceptable, envía un mensaje a la línea para que lo rehaga, indicando claramente qué está mal y cómo debería ser. Después de la corrección, repite desde el paso 1.

3. Fusionar: Ejecuta scripts/merge-line.sh <directorio principal> <línea base> <ruta del worktree de la línea>. Solo modifica los archivos del área de trabajo del directorio principal; no toca el área de staging, HEAD ni las ramas.

   • Si hay conflictos, el archivo contendrá marcadores de conflicto (<<<<<<< actual a >>>>>>> línea). Si hay pocos conflictos, resuélvelos tú mismo; si son muchos o no los entiendes, detente, informa al usuario y decide con él.
   • Si el script rechaza la fusión (código de salida 2, con el mensaje "no comienza desde la línea base"): significa que la línea no se alineó con la línea base al empezar. Pregunta a la línea qué ha pasado; no fuerces la fusión.

4. Verificar: Ejecuta las comprobaciones completas en el directorio principal, incluyendo tests, type checks y compilación del proyecto. El script solo fusiona a nivel de archivos; sin ejecutar las comprobaciones, la fusión no está terminada.

5. Actualizar el libro de contabilidad: Cambia el estado de la línea en la tabla a "Fusionada". En "Registro de fusiones", escribe: hora, línea, línea base, ID de instantánea, resultado de la fusión (cómo se resolvieron los conflictos), resultado de la verificación.

6. Informar al usuario: Dile qué se ha fusionado de esta línea. La decisión de hacer commit es del usuario. Si no lo pide, no hagas commit; si pide commit, sigue las convenciones del proyecto.

7. Sesión de la línea: Cuando la fusión esté completa y el usuario no necesite volver a esa sesión, pregúntale si quiere archivarla (mcp__ccd_session_mgmt__archive_session). No borres el worktree por tu cuenta.

Siguiente fase

Para la siguiente fase de la línea principal, o para una línea secundaria que dependa de una línea ya fusionada, sigue este orden:

1. Crea una nueva línea base: scripts/snapshot.sh <directorio principal> refs/task-lines/<id del libro>/base-<n>.
2. Actualiza "Línea base actual" en board.md.
3. Escribe la tarea, indicando la nueva línea base y el traspaso de la fase anterior: qué se hizo, qué queda pendiente, qué hay que tener en cuenta.
4. Abre una nueva tarjeta.

Las líneas que aún están en ejecución siguen usando su propia línea base. El script de fusión hace una fusión a tres bandas para cada línea según su línea base, sin interferencias.

Después de una compresión

El plugin task-lines coloca las partes más recientes de board.md y log.md de nuevo en el contexto. Antes de continuar:

1. Consulta la tabla de líneas del libro de contabilidad, usa list_sessions para encontrar las sesiones de cada línea (por el prefijo [id de línea] en el título) y list_events para ver su estado actual.
2. Si hay cosas nuevas en el resumen que aún no están en el libro de contabilidad (nuevas decisiones, nuevas peticiones del usuario), añádelas primero al libro.
3. Luego continúa.

Si el resumen y el libro de contabilidad no coinciden, prevalece el libro de contabilidad y el estado real; para el estado real, consulta los registros de la sesión y git.

Cómo llevar el libro de contabilidad

• board.md es el libro mayor: Palabras originales del usuario, objetivos, restricciones, decisiones tomadas, tabla de líneas, registro de fusiones, asuntos pendientes de decisión del usuario. Edita este archivo directamente para que refleje siempre el estado real actual.
• log.md es el registro cronológico: Usa task_note para añadir entradas: cuándo se tomó una decisión, qué informe se recibió, cómo fue la fusión, etc.
• Actualiza después de cada hito: Después de dividir las líneas, abrir tarjetas, recibir informes, fusionar, o cuando el usuario cambie los requisitos. Si el libro de contabilidad se queda atrás respecto al diálogo, al comprimir se pierden los detalles.
• No escribas claves, contraseñas ni tokens en el libro de contabilidad.

Cambiar de sesión coordinadora

Si la sesión coordinadora original se vuelve demasiado larga, puedes abrir una nueva sesión para hacerse cargo:

1. Invoca task_board con board igual al ID del libro.
2. Revisa según la sección "Después de una compresión".
3. Las líneas envían sus informes usando el ID de sesión del coordinador original. Cambia el ID de sesión en board.md al de la nueva sesión, y envía un mensaje a cada línea que aún esté en ejecución indicándole la nueva dirección para los informes.

Cosas a tener en cuenta

• Las líneas solo pueden abrirse en proyectos que el usuario haya abierto en el escritorio. Si Claude crea un repositorio nuevo en el scratchpad u otro directorio escribible, el escritorio, por seguridad, no crea un worktree; el usuario solo verá "No se pudo iniciar la tarea sugerida" al hacer clic en la tarjeta. El cwd de spawn_task debe dejarse sin especificar (por defecto el proyecto actual) o indicar la ruta de un proyecto que el usuario haya abierto.
• Si la tarjeta no se abre, Claude no recibe ninguna notificación; necesitas que el usuario te lo diga. La razón está en el registro del escritorio: ~/Library/Logs/Claude/main.log, buscando createWorktree o Worktree creation failed.
• El worktree de una línea no tiene directorios ignorados como node_modules o target de Rust. La sección "Prepara el entorno" de la tarea debe explicar cómo crearlos.
• Las instantáneas de línea base se guardan en refs/task-lines/<id del libro>/ y no aparecen en la lista de ramas. Al finalizar toda la tarea, se pueden listar con git for-each-ref refs/task-lines/<id del libro> y eliminar con git update-ref -d. Pregunta al usuario antes de eliminarlas.
• Cuando dos sesiones tienen modos de permisos diferentes, los mensajes entre ellas deben esperar la aprobación del usuario. Al abrir líneas, recuerda al usuario que lo tenga en cuenta.
• merge-line.sh maneja archivos de texto y archivos normales. Los enlaces simbólicos y los archivos binarios modificados por ambas partes se listan como "requieren manejo manual".

Cierre

Cuando todas las líneas estén fusionadas y la verificación completa haya pasado:

1. Marca board.md como "Completado".
2. Informa al usuario: qué ha hecho cada línea, resultados de la fusión, resultados de la verificación, problemas restantes, asuntos pendientes de decisión.
3. Pregunta al usuario si quiere archivar las sesiones de las líneas y si quiere limpiar las instantáneas de línea base.