Actualizar y repartir

Cuando sale una versión nueva

Tres actores, en este orden. Ninguno tiene que editar un archivo a mano.

1. Quien administra kbspec: repartirla

kb distribuir --push

Publica el paquete en la rama kbspec/instalador del repositorio de documentación y deja instalador/VERSION.json con la versión y sus notas. Desde ahí, kb version, kb check y el panel avisan a cada desarrollador. (Detalle más abajo, en Repartir.)

2. Cada desarrollador: actualizar su máquina

kb actualizar

Hace git pull del repositorio de documentación, verifica la huella del paquete, lo instala y corre kb instalar, que:

pone al día las skills en ~/.claude/skills;
vuelve a preparar cada repositorio de código del inventario (kb init-repo): reglas del agente, ganchos, servidor MCP, la regla de cada componente. Todo fuera de versión: no queda nada para commitear en el código;
pone al día la configuración sembrada que nadie tocó (CHECKLISTS.md, PERFILES.md…) y avisa la que el equipo personalizó y el framework mejoró;
pone al día la base de conocimiento: saca de las fichas y del inventario el manual que versiones anteriores copiaban adentro —solo el texto que kbspec publicó, idéntico— y regenera el índice de las apps que ya tienen mapa. No lee código y no publica nada;
instala el panel y deja la medición activada.

Sin kb distribuir en el medio, lo mismo es:

npm install -g kabatasoft-kbspec-<versión>.tgz
kb instalar

Después: Reload Window en VS Code (el panel y los ganchos nuevos) y una sesión nueva del agente —el servidor MCP que ya estaba corriendo sirve la versión vieja hasta que se reinicia—.

3. El equipo, una vez: la base de conocimiento

Lo que kb instalar deja cambiado en el repositorio de documentación es igual en todas las máquinas: lo publica una persona, después de mirarlo.

kb apps actualizar --ver      # qué cambia en fichas e inventario, sin escribir
kb apps actualizar            # lo escribe (lo mismo que hizo kb instalar) y verifica el inventario
git diff aplicaciones/        # revisarlo: solo se va prosa de plantilla
kb publicar-base              # para el equipo

Y lo que pide la versión según sus notas (kb version las muestra). Las más comunes:

Si las notas dicen…	Correr
que cambió el mapa o el índice	`kb mapa construir <APP>` por cada app, y `kb publicar-base`
que una semilla de la configuración mejoró y la personalizaste	`kb configuracion diff <ARCHIVO>`: traer lo que sirva y `--resellar`
que cambió el kit de pruebas E2E	`kb pruebas preparar --app <APP> --actualizar-kit` y `kb pruebas validar --app <APP>`
que cambió la ficha	`kb apps verificar` y `kb arquitectura --aplicar`

Para comprobar que quedó todo:

kb check                    # la máquina, la versión en el PATH, la rama de la documentación
kb configuracion probar     # lo que no va a funcionar como está escrito
kb apps verificar           # el inventario y las fichas contra el código

Repartir

kbspec se instala con npm install -g <paquete>.tgz. Hacer llegar ese archivo a cada desarrollador por fuera —un correo, un recurso compartido— tiene un problema que no es técnico: nadie sabe quién quedó en qué versión, y de una versión nueva se entera el que pregunta.

El repositorio de documentación ya está clonado en todas las máquinas, ya vive en Azure DevOps con los permisos del equipo y ya se le hace git pull todos los días. Es el canal que existe.

Quien administra kbspec, una vez por versión

kb distribuir --push

Hace dos cosas:

Publica el paquete en una rama del mismo repositorio — kbspec/instalador — con una etiqueta kbspec-v<version>. Esa rama no la clona nadie: existe para que npm la instale.
Deja en el repositorio de documentación un instalador/VERSION.json (unos cientos de bytes) con la versión, la huella y las notas, y un LEEME.md que explica qué hacer.

Sin --push imprime los tres comandos de git para que los corras vos. Con --con-tgz además deja el .tgz en el árbol de la documentación, para un equipo que prefiera instalar desde el archivo — por omisión no, porque son 2 MB por versión en una rama que clonan todos.

Se niega si el .vsix del panel no corresponde al código: repartir un panel viejo que dice el número nuevo es peor que no repartir nada — quien lo instala mira la versión, ve que coincide y busca el problema en cualquier otro lado.

Se guardan los últimos dos paquetes en el árbol; el historial de git conserva los demás. Cada versión pesa unos 2 MB.

Cada desarrollador

kb actualizar

git pull del repositorio de documentación, compara la versión repartida con la instalada, verifica la huella, npm install -g y kb instalar. Un comando.

Si el binario no llegó con el pull, o la huella no coincide, no instala nada y dice por qué. kb actualizar --revisar solo mira.

Y avisa solo

kb version, kb check y el panel de VS Code leen ese mismo VERSION.json y avisan cuando el equipo repartió algo más nuevo, con las notas de la versión. Sin red: es un archivo del repositorio que el desarrollador ya tiene. El panel lo dice una vez por versión, con un botón que corre kb actualizar en una terminal.

La primera vez, en una máquina nueva

Sin clonar nada antes — una línea:

npm install -g "git+https://dev.azure.com/ORG/Proyecto/_git/Repo#kbspec/instalador"
kb instalar

npm clona esa rama con las credenciales que git ya tiene. Después, kb instalar:

pregunta dónde está tu carpeta de CÓDIGO fuente;
clona la documentación del equipo adentro, en una carpeta llamada documentacion (ese nombre siempre, aunque el repositorio se llame de otra forma), desde la rama kbspec/documentacion;
deja anotadas las dos rutas en ~/.kb/config y configura la máquina.

Sabe de qué repositorio salió porque kb distribuir se lo graba en el paquete: npm no guarda la URL de origen, así que la guarda kbspec.

De ahí en adelante, kb actualizar.