lguidolin/ship-it

Ship It

Gestiona el ciclo de envío completo: preparar, confirmar, hacer push, abrir un PR, archivar registros de decisiones después de la fusión y limpiar.

Resumen

Cada cambio pasa por un branch y un PR. Nunca hagas push directamente a main. Esta skill maneja el ciclo de cierre completo, incluido el archivado de documentación posterior a la fusión.

Los mensajes de commit son documentación. El título del PR se convierte en el commit de squash-merge en main y aparece en el changelog. Hazlo bien en el momento de crear el PR.

Archiva después de la fusión, nunca antes. Las especificaciones y planes permanecen accesibles hasta que el PR se fusiona. Solo después de la fusión los convertimos en registros de decisiones compactos.

Cuándo usarla

• El usuario dice "push", "envíalo", "vamos a enviar", "abre un PR", "crea un PR"
• El usuario dice "fusionado", "está fusionado", "tira y limpia" después de que se haya abierto un PR
• El usuario ha completado la implementación y quiere finalizar
• Después de completar un plan donde el siguiente paso es enviar el trabajo

Cuándo NO usarla

• El usuario quiere explícitamente hacer push directamente a main (confirma primero que esto sea intencional)
• El repositorio no tiene un remoto configurado
• Los cambios son trabajo en progreso que el usuario aún no está listo para enviar
• El usuario solo quiere confirmar cambios sin enviar (usa conventional-commits-and-releases)

Proceso

Fase 0: Verificar y Detectar

Una suite roja nunca se convierte en PR. Ejecuta la suite de pruebas completa del proyecto primero. Si algo falla, informa de los fallos y detente — no confirmes, hagas push ni abras un PR. Esta regla es política del proyecto y no se delega.

La detección del entorno (repositorio normal vs. worktree con nombre vs. HEAD separado) y la determinación del branch base se delegan a superpowers:finishing-a-development-branch, que ya maneja los tres casos.

Comprueba la disponibilidad de la manera correcta: busca finishing-a-development-branch en tu propia lista de skills disponibles. Si aparece listada, se puede invocar. Si no aparece listada, no se puede — continúa con el plan de respaldo.

No investigues el sistema de archivos para encontrarla. ~/.claude/plugins/cache/ contiene todas las versiones que se han descargado, incluidos plugins que están instalados pero deshabilitados, y las skills pueden ser proporcionadas por mecanismos distintos al caché de plugins. Que exista una ruta en el caché no prueba que puedas invocar la skill.

Si está disponible — invócala para la verificación de pruebas, detección del entorno y determinación del branch base, luego detente antes de su menú de opciones.

La decisión de integración ya está tomada por la regla del proyecto y no es decisión del usuario revocarla aquí: este proyecto fusiona solo a través de un PR, porque el PR es lo que produce el despliegue de vista previa y lo que la CI controla. Su opción "fusionar de vuelta a <base> localmente" no está disponible. Su opción "mantener el branch como está" sigue siendo válida — es una decisión de aplazar, no de saltarse el control.

Si falta — recurre al plan de respaldo, sin perder nada que controle la corrección:

• Ejecuta la suite de pruebas directamente.
• Trata el upstream del branch, o main, como la base; confírmalo con el usuario antes de continuar.
• Omite la limpieza de worktree en la Fase 6; borra el branch normalmente.

Fase 1: Preparar y Confirmar Cambios

git status --short
git branch --show-current
git log --oneline @{upstream}..HEAD 2>/dev/null || echo "No upstream set"

Árbol de decisión:

• En main con cambios sin confirmar → crear branch, confirmar, push, PR
• En un branch de funcionalidad con cambios sin confirmar → confirmar, push, PR (o actualizar PR existente)
• En un branch de funcionalidad con commits sin enviar → push, PR (o actualizar PR existente)
• En un branch de funcionalidad con PR existente → push (el PR ya existe)

Si hay cambios sin staged:

• Pregunta al usuario si se deben incluir todos los cambios o archivos específicos
• Si los cambios abarcan varios temas, sugiere dividirlos

Redacta el mensaje de commit:

Tipo	Cuándo
feat	Nueva funcionalidad
fix	Corrección de errores
docs	Solo documentación
chore	Configuración, dependencias, herramientas
refactor	Reestructuración de código, sin cambio de comportamiento
test	Añadir o modificar pruebas
ci	Cambios en el flujo de CI/CD

Formato: <tipo>[ámbito opcional]: <descripción en imperativo>

Reglas:

• Modo imperativo ("añade", no "añadido" ni "añade")
• Primera palabra en minúsculas después de los dos puntos
• Sin punto al final
• Corto (50 caracteres o menos para el asunto)
• Describe qué hace el commit, no cómo

Presenta el mensaje de commit propuesto al usuario y confirma antes de confirmar.

Fase 2: Branch y Push

Si estás en main, crea un branch:

<tipo>/<descripción-corta>

Ejemplos:

• feat/login-oauth
• fix/manejo-respuesta-nula
• docs/permisos-flujo-release

Push:

git push -u origin $(git branch --show-current)

Fase 3: Abrir PR

Título del PR = mensaje de commit convencional (usado para squash-merge en main).

Estructura del cuerpo del PR:

## Qué cambió

[Descripción específica de adiciones/modificaciones/eliminaciones]

## Por qué

[Motivación — ¿qué problema resuelve esto?]

Crea usando la CLI de gh:

gh pr create --title "<mensaje de commit convencional>" --body "<cuerpo del PR>"

Si gh no está disponible, proporciona la URL del PR desde la salida de git push o constrúyela.

Verifica que el entorno de vista previa se haya levantado. Si el proyecto despliega vistas previas por PR, espera ese flujo de trabajo y confirma que el entorno sea accesible antes de entregar el PR:

gh pr checks --watch

Si la vista previa falla al desplegar, infórmalo y detente. Un PR que nadie puede revisar no está enviado.

Donde termina esta skill. ship-it finaliza su conciencia de despliegue en la vista previa. La promoción a staging y producción no es su trabajo — pertenece a la skill de entrega del proyecto (cloud-delivery-aks, o su equivalente). Las Fases 4-6 a continuación son higiene de git y documentación, no despliegue.

Fase 4: Esperar la Fusión

Después de crear el PR, pregunta: "Avísame cuando esté fusionado y me encargaré de la limpieza y el archivado."

Espera la confirmación del usuario (por ejemplo, "fusionado", "hecho", "está fusionado").

Fase 5: Post-Fusión — Archivar Registros de Decisiones

Las especificaciones y planes son detallados por diseño — buenos para un humano que lee el historial, costosos cada vez que Claude carga uno. Convertirlos en registros de decisiones compactos mantiene las decisiones esenciales baratas de leer mientras la narrativa completa permanece en disco, archivada, sin costar nada hasta que alguien la abre deliberadamente.

Solo después de que el PR se fusiona, verifica si hay especificaciones/planes sin convertir:

ls docs/superpowers/specs/ 2>/dev/null
ls docs/superpowers/decisions/ 2>/dev/null

La skill recording-decisions incluye dos ayudantes para esto. Localízalos — la skill puede estar instalada en el proyecto o globalmente:

for base in .claude/skills ~/.claude/skills; do
  d="$base/recording-decisions/scripts"
  [ -d "$d" ] && echo "$d" && break
done

Si se encuentra, $d/doc-archive.sh lista las especificaciones no convertidas e imprime un prompt de conversión, y $d/index-rebuild.sh regenera el índice. Si no se encuentra, haz el mismo trabajo manualmente usando los pasos a continuación — son autocontenidos.

Si existen especificaciones/planes no convertidos:

1. Pregunta al usuario: "Encontré especificaciones/planes que pueden corresponder a este trabajo. ¿Quieres que los convierta en registros de decisiones compactos y archive los originales?"

2. Si sí, para cada especificación:

   • Lee el contenido de la especificación
   • Genera un registro de decisión con frontmatter YAML:

     ---
     title: <extraído de la especificación>
     date: <desde el nombre del archivo de especificación>
     component: <inferido del contenido>
     status: implemented
     supersedes: null
     dependencies: [<inferido>]
     ---
     

   • Escribe ~30-50 líneas capturando: decisiones clave, interfaces, restricciones
   • Guarda en docs/superpowers/decisions/<fecha>-<tema>.md
   • Mueve la especificación original a docs/superpowers/archive/specs/
   • Mueve el plan correspondiente a docs/superpowers/archive/plans/

3. Reconstruye el índice maestro — regenera docs/superpowers/index.md a partir del frontmatter de cada registro de decisión, agrupado en una tabla de Decisiones Activas (componente, título, fecha, dependencias) y una tabla de Reemplazadas (componente, título, reemplazada por). Ejecuta $d/index-rebuild.sh si lo localizaste arriba; de lo contrario, escribe el archivo directamente.

4. Confirma los cambios de archivado:

   git add docs/superpowers/
   git commit -m "docs: archivar especificaciones y actualizar índice de decisiones"
   git push
   

Fase 6: Limpieza

git checkout main
git pull
git branch -d <nombre-del-branch>
git push origin --delete <nombre-del-branch> 2>/dev/null || true
git fetch --prune

Verifica el estado limpio:

git branch --show-current
git log --oneline -3

Si el trabajo ocurrió en un git worktree, delega el desmontaje a superpowers:finishing-a-development-branch (su limpieza basada en procedencia — sabe qué worktrees posee y deja intactos los gestionados externamente). Si esa skill no está disponible, elimina el worktree manualmente con git worktree remove <ruta> y confírmalo primero con el usuario.

Principios Clave

• Una suite roja nunca se convierte en PR — verifica antes que nada (Fase 0)
• Nunca hagas push a main directamente — siempre branch + PR. El PR es el despliegue de vista previa y el control de CI; una fusión local se salta ambos. Esto anula cualquier flujo de trabajo que ofrezca fusionar localmente como opción.
• El envío termina en la vista previa — la fusión, el archivado y la limpieza son higiene; la promoción a staging y producción es trabajo de otra skill
• Commits convencionales — el título del PR es la entrada del changelog
• Archivar solo después de la fusión — las especificaciones permanecen accesibles durante la revisión
• Los registros de decisiones son compactos — ~30-50 líneas, indexados en YAML, optimizados para LLMs
• Limpia completamente — sin branches obsoletos ni referencias de seguimiento