g-ki/agent-skills

Entregar Proyecto

Ejecuta el backlog hasta completarlo en la rama main. Cada ticket se convierte en un PR, revisado por la automatización de revisión de GitHub del repositorio y por humanos. Tu trabajo es mantener el flujo de trabajo: iniciar tickets tan pronto como puedan comenzar, mantener cada PR saludable, actuar sobre los comentarios de revisión que valga la pena abordar, mantener las ramas apiladas rebasadas a medida que sus padres se fusionan, y mantener los estados de los tickets precisos.

Eres el orquestador. Lees el estado, decides, delegas y llevas la contabilidad. Los agentes escriben todo el código, resuelven conflictos y hacen push. Tú no editas código ni ejecutas rebases en este checkout, por lo que la carpeta principal del proyecto se mantiene limpia y cada cambio permanece trazable.

Entrada

$ARGUMENTS

• Archivo de tareas: el archivo local *.tasks.md de /task-breakdown (no rastreado, generalmente en una carpeta ignorada por git como .rfcs/). Si no se proporciona ninguno, búscalo allí y en docs/rfcs/; si existen varios, pregunta.
• --parallel N: número máximo de agentes trabajando a la vez, de todo tipo. Valor predeterminado: 3.
• --max-stack N: profundidad máxima de una pila de PRs. Valor predeterminado: 3. Pilas más profundas desbloquean más trabajo, pero multiplican los rebases cuando un padre cambia.
• --auto-merge: cuando un PR en main está pr-ready, habilita el auto-merge de GitHub en él (gh pr merge --auto con el método de fusión habitual del repositorio). GitHub aún aplica la protección de rama y las aprobaciones requeridas. Desactivado por defecto: los humanos fusionan.
• --once: ejecuta una sola pasada y luego sale. Úsalo para ejecutar la entrega en un horario, por ejemplo /loop 15m /deliver-project <archivo-de-tareas> --once, en lugar de mantener una sesión larga abierta.

Dónde reside el estado

• Tracker (Linear, Jira, GitHub Issues, …), para tickets que están publicados (tienen una clave Tracker: en el archivo de tareas). Es la fuente de verdad sobre si un ticket existe y es deseado: un ticket cancelado, eliminado o reasignado allí se omite. Mueve los issues del tracker a través de sus estados a medida que los tickets progresan, a menos que la integración de GitHub del tracker ya lo haga (verifica después de que se abra el primer PR y no luches contra ello).
• Archivo de tareas local, en la carpeta principal del proyecto. Es la fuente de verdad para el estado de la entrega, y eres su único escritor durante la ejecución: los agentes lo leen pero nunca lo editan. Estados: open → in progress → pr-draft → pr-open → pr-ready → pr-merged → done, más blocked y canceled con una razón. Los spikes van open → in progress → decision-proposed → decided → done. Mantén Branch / PR: (o Decision: para spikes) completados.
• GitHub, para el estado del PR: abierto, fusionado, comprobaciones, revisiones, capacidad de fusión. Una dependencia se fusiona cuando su PR se fusiona, independientemente de lo que diga cualquier archivo.
• Ramas identifican los PRs de esta ejecución: cada rama es <username>/<project-slug>/<task-branch>, por lo que los PRs de esta ejecución son los PRs del usuario cuya rama principal comienza con <username>/<project-slug>/. Así es como una ejecución reiniciada encuentra todo de nuevo.
• Registro de ejecución, <rfc-name>.run.md junto al archivo de tareas (local, no rastreado), para lo que no es un estado de ticket: agentes en ejecución, SHA de la cabeza del padre de cada rama apilada, IDs de comentarios manejados, rondas de retroalimentación, intentos de corrección de CI, escalaciones, seguimientos. Usa templates/run-log.md. Si se pierde, reconstrúyelo desde GitHub.

references/github.md tiene los comandos gh para leer el estado del PR, los hilos de revisión y las comprobaciones.

1. Prevuelo (solo primera pasada)

Detente con un mensaje claro si falla alguno de estos:

1. El archivo de tareas es sólido: IDs, estados, dependencias existentes, criterios de aceptación, un Project slug:, sin ciclos de dependencia.
2. Tracker accesible: si algún ticket tiene una clave de tracker, el conector del tracker debe estar disponible, ya que lo necesitas para verificar cancelaciones y actualizar estados. Si no lo está, di qué conector habilitar y ofrece continuar usando solo el archivo local.
3. Repositorio listo: árbol de trabajo limpio, un remoto, gh autenticado con derechos de push y PR, y main compila y pasa las pruebas. Determina <username> (el prefijo de las ramas existentes del usuario, de lo contrario gh api user --jq .login) y el prefijo de rama.
4. Los agentes pueden trabajar sin supervisión: los agentes en segundo plano muestran cada solicitud de permiso en esta sesión, por lo que una solicitud detiene al equipo. Recomienda el modo automático o las reglas de permiso para git (incluyendo push --force-with-lease), gh, las pruebas, el lint y los comandos de compilación del repositorio, y el conector del tracker.
5. Skills disponibles: implement-task y spike-task están instalados donde los agentes puedan cargarlos, y task-breakdown está disponible para ti para refinar después de las decisiones.
6. Automatización de revisión: encuentra el flujo de trabajo de GitHub que revisa los PRs, y anota su nombre de comprobación y inicio de sesión del bot, para que sepas cuándo termina su revisión y qué comentarios son suyos.

Luego muestra el plan y obtén una confirmación: recuento de tickets, qué puede comenzar ahora y qué se apilará, paralelismo, profundidad máxima de pila, si el auto-merge está activado, y una nota honesta de que cada agente es una sesión completa y la ejecución usa un uso significativo. Después de eso, ejecuta sin supervisión.

2. Cada pasada

Haz esto en orden. Lo primero de la parte inferior de la pila es importante: la corrección o fusión de un padre cambia lo que sus hijos deben hacer.

a. Sincronizar

Haz fetch. Enumera los PRs de esta ejecución (por prefijo de rama) con estado, base, SHA de la cabeza, comprobaciones, decisión de revisión y capacidad de fusión. Actualiza los tickets publicados desde el tracker y omite los que fueron cancelados. Recopila los informes de los agentes que terminaron desde la última pasada (cada uno termina con un bloque RESULT). Reconciliar: si GitHub y el archivo de tareas no están de acuerdo, GitHub gana para el estado del PR; corrige el archivo.

b. Manejar fusiones

Para cada PR que se fusionó desde la última pasada: establece su ticket a pr-merged y mueve el issue del tracker a hecho a menos que la integración lo haya hecho. Establécelo a done una vez que el tracker muestre que está cerrado y cualquier paso de implementación en el ticket esté terminado. Cada PR apilado directamente sobre el fusionado necesita ser reajustado sobre main y su base cambiada a main: inicia un agente de reajuste por pila afectada (ver references/stacks.md; dale al agente su ruta absoluta, ${CLAUDE_SKILL_DIR}/references/stacks.md).

c. Avanzar decisiones

Los spikes bloquean los tickets detrás de ellos, y solo el usuario aprueba una decisión, porque las decisiones cambian el plan.

• Para cada spike en decision-proposed, asegúrate de que el usuario lo haya visto: ponlo en la parte superior de tu actualización con la pregunta, la recomendación y la confianza, los cambios propuestos al backlog en una línea y la ruta del registro de decisión. Pídele que lo apruebe, elija otra opción o extienda el spike. Mantén todo lo demás en movimiento mientras tanto.
• El usuario aprueba diciéndotelo en esta sesión, o entre pasadas --once estableciendo el spike a decided en el archivo de tareas (con la opción elegida anotada en el registro). Cuando un spike se convierte en decided: registra la aprobación en la línea Status: del registro de decisión, luego refina el backlog con los pasos de "Refinar después de un spike" del skill task-breakdown (la aprobación del usuario cubre la sincronización del tracker), y establece el spike a done. Sus dependientes se vuelven iniciables en el siguiente paso.
• Si el usuario elige extender el spike, establécelo de nuevo a open con la pregunta reducida en su campo Question:.

d. Mantener PRs abiertos saludables

Trabaja a través de los PRs abiertos, desde la parte inferior de cada pila primero. Mantén como máximo un agente por rama o pila a la vez, para que nadie reajuste una rama mientras alguien más la está arreglando. Mientras haya trabajo pendiente en un PR, su ticket está pr-open.

1. El padre se movió. Si el padre de un PR apilado recibió nuevas confirmaciones (su SHA de cabeza difiere del registrado para el hijo), reajusta el hijo sobre la nueva cabeza del padre.
2. Conflictos con la base. Si GitHub informa que el PR está en conflicto, o desactualizado donde la protección de rama requiere estar actualizado, reajústalo. No reajustes solo porque main se movió; vuelve a activar CI y revisión para nada.
3. CI fallando. Lee los registros de fallos. Si parece inestable o no relacionado con el PR (infraestructura, una prueba que el PR no toca y que también falla en main), vuelve a ejecutar los trabajos fallidos una vez. Si el PR lo causó, inicia un agente de retroalimentación con el fallo como elemento. Después de dos intentos de corrección fallidos, establece el ticket blocked y escala.
4. Comentarios de revisión. Espera hasta que la comprobación de la automatización de revisión haya terminado. Luego clasifica cada hilo de revisión y comentario no resuelto que aún no hayas manejado (sección 3), e inicia un agente de retroalimentación por PR con los elementos a abordar y las respuestas a publicar.
5. Listo. Comprobaciones verdes, automatización de revisión terminada, sin comentarios no abordados: establece el ticket pr-ready. Si su base es main y --auto-merge está activado, habilita el auto-merge; de lo contrario, enuméralo como listo para fusión humana en tu actualización.

e. Iniciar nuevos tickets

Llena los espacios de agente libres con tickets que puedan comenzar. Spikes primero, ya que bloquean otro trabajo; luego tickets de ruta crítica.

• Spikes pueden comenzar cuando están open y sus dependencias están hechas. Inicia un agente de spike con el aviso en references/agent-prompts.md y establece el ticket a in progress. Los spikes nunca obtienen un PR y nada se apila sobre ellos.
• Un ticket puede comenzar cuando está open, no cancelado en el tracker, cada spike del que depende está done, y cada otra dependencia está fusionada o tiene un PR abierto con comprobaciones verdes y sin cambios solicitados, con todas las dependencias no fusionadas en una sola línea de pila. Basa la rama en la rama de la dependencia no fusionada superior, o en main si todas están fusionadas. No excedas --max-stack.
• Si dos dependencias no fusionadas están en pilas diferentes, espera hasta que una se fusione.
• No ejecutes dos tickets a la vez cuyos Files: se superpongan.

Decide el nombre de la rama (<username>/<project-slug>/<task-branch>, con la clave del tracker en task-branch cuando esté publicado), establece el ticket a in progress (y el issue del tracker también, a menos que la integración lo haga), e inicia el implementador con el aviso en references/agent-prompts.md: un agente de propósito general, en segundo plano, con isolation: "worktree" establecido en la llamada del Agent, nombrado como impl-T-04. Cuando informe un PR, establece el ticket a pr-open y registra la rama y el PR.

f. Informar y esperar

Si algo cambió, dale al usuario una breve actualización: PRs abiertos, fusionados, reajustados, comentarios abordados, qué espera a los humanos y nuevas escalaciones. Mantente en silencio cuando no haya cambiado nada.

Con --once, sal aquí. De lo contrario, espera unos 5–10 minutos antes de la siguiente pasada, usando las herramientas de programación o monitoreo de la sesión (por ejemplo, un Monitor en un comando de sondeo gh) en lugar de dormir en un bucle. Despierta temprano cuando un agente termine.

3. Clasificar comentarios de revisión

Para cada comentario o hilo no manejado, decide una de cuatro cosas y registra el ID del comentario como manejado:

• Abordar cuando apunta a un defecto real: un error, un criterio de aceptación omitido o débilmente probado, un riesgo de seguridad o pérdida de datos, una convención del repositorio rota o una solicitud clara y concreta de un revisor humano.
• Seguimiento cuando es válido pero fuera del alcance del ticket (nuevo comportamiento, refactorización más amplia). No lo construyas. Anótalo en el registro de ejecución y en el informe final como un ticket candidato, y haz que el agente de retroalimentación responda en una línea que está rastreado como seguimiento.
• Rechazar cuando un comentario automatizado es un falso positivo, una cuestión de gusto o pide estructura adicional que el ticket no necesita, ya que agregarlo desharía el enfoque de cambio más pequeño. Haz que el agente de retroalimentación responda con una línea de razonamiento. Solo rechaza comentarios automatizados de esta manera.
• Escalar cuando un revisor humano pide algo que de otro modo rechazarías, o los revisores no están de acuerdo, o el comentario cuestiona el diseño en sí. No discutas con humanos en los hilos; llévaselo al usuario con el enlace del comentario.

Limita la revisión automatizada a tres rondas de retroalimentación por PR. Si la automatización de revisión sigue planteando nuevos elementos después de eso, escala en lugar de hacer un bucle.

4. Cuando un agente informa

• done: el PR de un implementador está abierto, o se ha hecho push del trabajo de retroalimentación o reajuste. Actualiza el estado del ticket y el registro de ejecución; verifica el PR nuevamente en la próxima pasada.
• decision-proposed (spike): establece el spike a decision-proposed, completa Decision: con la ruta del registro y plantéalo al usuario (paso 2c).
• inconclusive (spike): también establece decision-proposed y plantéalo como no concluyente con el siguiente paso recomendado por el agente (un spike más estrecho, o un valor predeterminado reversible para continuar).
• already-met: verifica la afirmación contra el código y los criterios. Si se sostiene, dile al usuario que el ticket se puede cerrar como ya hecho; si no, reanuda el agente con SendMessage diciendo qué falta.
• needs-split o blocked: establece el ticket blocked con la razón, registra una escalación con las notas del agente y la división propuesta, y continúa con otro trabajo. No apliques divisiones tú mismo.
• Sin bloque RESULT, o un bloqueo: reanuda el agente una vez con SendMessage; si eso también falla, escala.

5. Detener y finalizar

Deja de iniciar nuevo trabajo, deja que los agentes en ejecución terminen e informa cuando:

• cada ticket está pr-merged o done (éxito), o
• nada puede moverse sin un humano (todo lo que queda está esperando revisión, fusiones, decisiones o escalaciones). Di exactamente qué espera a quién; una ejecución posterior, o la siguiente pasada --once, reanuda desde allí, o
• main está rojo después de una fusión. Inicia un agente para arreglarlo como un ticket no planificado (registrado como tal) y retén nuevos tickets hasta que main esté verde nuevamente, o
• el usuario te dice que te detengas.

El informe final cubre: tickets fusionados del total, PRs abiertos y qué espera cada uno, decisiones pendientes de aprobación, candidatos de seguimiento de la revisión, correcciones no planificadas y escalaciones con la decisión que necesita cada una.

Reglas para la ejecución

• Nunca hagas push a main, fusiones nada tú mismo ni apruebes PRs. Fusionar pertenece a los humanos, o al auto-merge de GitHub con --auto-merge.
• Haz force-push solo con --force-with-lease, y solo a las ramas de esta ejecución (el prefijo de rama).
• Nunca edites criterios de aceptación, marques un ticket como fusionado que no lo está, ni cierres PRs, ramas o issues del tracker que esta ejecución no creó o posee.
• Nunca hagas commit de archivos RFC, notas, tareas o registro de ejecución; permanecen locales.
• Solo el usuario cambia el plan: aprobar divisiones

...

[truncado para traducción]