Extensiones y hooks

Sistema de extensiones

Las extensiones de Spec Kit permiten ampliar las capacidades del toolkit más allá de los slash commands y templates estándar. Una extensión puede añadir nuevos comandos, integrar herramientas externas, modificar el flujo de trabajo o incorporar validaciones adicionales al proceso SDD.

El sistema de extensiones funciona mediante catálogos: registros de extensiones disponibles que la CLI puede consultar para descubrir, instalar y gestionar extensiones en el proyecto.

Tipos de catálogos

Spec Kit maneja tres tipos de catálogos con diferentes propósitos:

Catálogo aprobado (catalog.json): contiene extensiones curadas y aprobadas por la organización. En un entorno empresarial, este catálogo actúa como la lista de extensiones permitidas. Si una extensión no está en este catálogo, no se puede instalar en proyectos que restrinjan las instalaciones al catálogo aprobado. Por defecto, este catálogo está vacío.

Catálogo community (catalog.community.json): contiene extensiones compartidas por la comunidad. Es un recurso de descubrimiento donde los desarrolladores pueden encontrar extensiones creadas por otros equipos. Las extensiones de este catálogo no están verificadas ni aprobadas, pero están disponibles para exploración.

Catálogos privados: catálogos internos de organizaciones que alojan extensiones propietarias. Se configuran mediante la variable de entorno SPECKIT_CATALOG_URL o mediante archivos de configuración del proyecto.

Los catálogos controlan tanto el descubrimiento (qué extensiones se pueden buscar) como la instalación (qué extensiones se pueden añadir al proyecto). Un catálogo puede permitir la búsqueda pero restringir la instalación.

Configuración de catálogos

La configuración de catálogos se define en el archivo .specify/extension-catalogs.yml del proyecto. Este archivo establece qué catálogos están activos, su prioridad y si permiten la instalación de extensiones:

catalogs:
  - name: "org-approved"
    url: "https://catalog.empresa.com/speckit/"
    priority: 1
    install_allowed: true
  - name: "community"
    url: "https://community.speckit.org/catalog/"
    priority: 3
    install_allowed: false

En este ejemplo, el catálogo de la organización tiene prioridad 1 (la más alta) y permite instalaciones. El catálogo community tiene prioridad 3 y solo permite búsqueda, no instalación. Esto garantiza que los desarrolladores pueden descubrir extensiones en la comunidad pero solo instalar las aprobadas por su organización.

Si el archivo extension-catalogs.yml no existe, la CLI utiliza un stack por defecto que busca en ambos catálogos estándar (aprobado y community) y restringe las instalaciones al catálogo aprobado.

Además del archivo de proyecto, existe un archivo de configuración a nivel de usuario en ~/.specify/extension-catalogs.yml que aplica a todos los proyectos del desarrollador.

Gestión de extensiones con la CLI

La CLI de Spec Kit proporciona comandos para gestionar extensiones:

• Listar catálogos activos:

specify extension catalogs

• Buscar extensiones en todos los catálogos activos:

specify extension search "jira"

• Instalar una extensión (respetando la restricción install_allowed):

specify extension add speckit-jira-sync

• Añadir un catálogo nuevo:

specify extension catalog add --name "internal" https://catalog.internal.com

• Eliminar un catálogo:

specify extension catalog remove "internal"

Sistema de hooks

El sistema de hooks de Spec Kit sigue el modelo de hooks de Git: scripts que se ejecutan automáticamente en puntos específicos del flujo SDD. A diferencia de las extensiones (que amplían funcionalidades), los hooks permiten automatizar acciones que el equipo necesita ejecutar de forma consistente en cada iteración del flujo.

Hooks disponibles

Spec Kit define cuatro hooks que se ejecutan en diferentes momentos del flujo de especificación:

flowchart TB
    PRE["pre-specify<br>Validacion y setup"] --> FEAT["prepare-feature-num<br>Numeracion personalizada"]
    FEAT --> BRANCH["Creacion de<br>branch y directorio"]
    BRANCH --> POST_CHECKOUT["post-checkout<br>Tareas post-branch"]
    POST_CHECKOUT --> WRITE["Escritura del<br>spec.md"]
    WRITE --> POST_SPEC["post-specify<br>Tareas de finalizacion"]

pre-specify: se ejecuta antes de iniciar el flujo de especificación. Su propósito principal es realizar validaciones previas y configurar el entorno. Un caso de uso habitual es verificar que el proyecto cumple con ciertos requisitos antes de crear una nueva feature (por ejemplo, que no hay features pendientes de merge, que el repositorio está limpio o que existen ciertos archivos de configuración).

prepare-feature-num: se ejecuta para personalizar la numeración de features. Por defecto, Spec Kit numera las features de forma secuencial (001, 002, 003...). Este hook permite reemplazar esa numeración con un valor externo, como el número de un ticket de Jira, un ID de GitHub Issue o cualquier otro esquema de numeración que el equipo utilice.

post-checkout: se ejecuta después de crear la rama Git de la feature. Es útil para tareas de configuración que dependen de que la rama exista, como crear directorios adicionales, copiar archivos base o ejecutar scripts de setup específicos de la feature.

post-specify: se ejecuta después de completar la especificación. Se utiliza para acciones de notificación y registro, como enviar un mensaje a Slack informando de que una nueva feature ha sido especificada, actualizar un dashboard de progreso o crear una entrada en un sistema de seguimiento.

Ubicación y activación de hooks

Los hooks se almacenan en el directorio .specify/scripts/ con la extensión .sample para indicar que son plantillas inactivas:

.specify/scripts/
  bash/
    pre-specify.sh.sample
    prepare-feature-num.sh.sample
    post-checkout.sh.sample
    post-specify.sh.sample
  powershell/
    pre-specify.ps1.sample
    prepare-feature-num.ps1.sample
    post-checkout.ps1.sample
    post-specify.ps1.sample

Para activar un hook, se elimina la extensión .sample del archivo:

cd .specify/scripts/bash/
mv pre-specify.sh.sample pre-specify.sh
chmod +x pre-specify.sh

En Windows con PowerShell:

cd .specify\scripts\powershell\
Rename-Item pre-specify.ps1.sample pre-specify.ps1

Un hook activo se ejecuta automáticamente cada vez que el flujo SDD alcanza su punto de ejecución. Si el hook devuelve un código de salida distinto de cero, el flujo se detiene y muestra el error.

Soporte cross-platform

El sistema de hooks soporta Bash y PowerShell de forma simultánea para equipos con desarrolladores en diferentes sistemas operativos. La CLI detecta automáticamente el sistema operativo y ejecuta el hook correspondiente:

• En Linux/macOS: ejecuta los scripts de bash/.
• En Windows: ejecuta los scripts de powershell/.

La opción --script de specify init determina qué variante de scripts se genera:

specify init mi-proyecto --ai claude --script sh
specify init mi-proyecto --ai claude --script ps

En un equipo mixto, ambas variantes pueden coexistir en el mismo repositorio. Cada desarrollador activa los hooks de su plataforma y la CLI ejecuta la variante correcta.

Ejemplo: numeración con GitHub Issues

Un caso de uso concreto del hook prepare-feature-num es obtener el número de feature desde un GitHub Issue. En lugar de usar la numeración secuencial de Spec Kit, el equipo quiere que cada feature se numere con el ID del issue asociado.

Hook en Bash:

#!/bin/bash
ISSUE_NUMBER=$1
if [ -z "$ISSUE_NUMBER" ]; then
  echo "Error: issue number required"
  echo "Usage: specify --feature-num <issue-number>"
  exit 1
fi
echo "$ISSUE_NUMBER"

Hook en PowerShell:

param([string]$FeatureNum)
if (-not $FeatureNum) {
  Write-Error "Issue number required"
  Write-Error "Usage: specify -FeatureNum <issue-number>"
  exit 1
}
Write-Output $FeatureNum

Con este hook activo, la invocación del slash command /speckit.specify utiliza el parámetro --feature-num (en Bash) o -FeatureNum (en PowerShell) para recibir el número externo:

specify --feature-num 42

Esto crea la feature en specs/042-nombre-feature/ en lugar de usar el siguiente número secuencial disponible.

Ejemplo: notificación a Slack

Un hook post-specify puede enviar una notificación automática al canal de Slack del equipo cada vez que se completa una especificación:

#!/bin/bash
FEATURE_DIR=$1
FEATURE_NAME=$(basename "$FEATURE_DIR")

curl -X POST "$SLACK_WEBHOOK_URL" \
  -H "Content-Type: application/json" \
  -d "{\"text\": \"Nueva spec creada: $FEATURE_NAME\"}"

Este tipo de automatización elimina la necesidad de que el desarrollador notifique manualmente al equipo, y crea un registro cronológico de las features especificadas.

Hooks y extensiones en el flujo SDD

Los hooks y las extensiones cumplen funciones complementarias dentro del ecosistema de Spec Kit:

| Aspecto | Hooks | Extensiones | |---|---|---| | Propósito | Automatizar acciones en puntos fijos del flujo | Ampliar funcionalidades del toolkit | | Activación | Automática (por punto del flujo) | Manual (instalación con CLI) | | Complejidad | Scripts simples, una acción concreta | Paquetes con lógica más elaborada | | Persistencia | Por proyecto, en .specify/scripts/ | Por proyecto, gestionadas con catálogos | | Cross-platform | Bash + PowerShell nativos | Depende de la extensión |

Un equipo que empieza con SDD puede no necesitar ni hooks ni extensiones durante los primeros proyectos. El flujo estándar con los slash commands por defecto cubre la mayoría de las necesidades. Los hooks y extensiones se incorporan cuando el equipo identifica automatizaciones recurrentes que justifican la inversión en configuración.

Los hooks son ideales para automatizaciones ligeras y específicas del proyecto. Las extensiones son más adecuadas para funcionalidades reutilizables entre múltiples proyectos.