Instalación

kbspec es una CLI (kb) más las skills que leen Copilot y Claude. La CLI está hecha solo con la biblioteca estándar de Python: no hay pip install ni dependencias que aprobar. Lo demás que se instala son herramientas que la organización ya suele tener.

Requisitos

Obligatorios

Herramienta	Versión	Para qué
Python	3.9 o superior (3.12 recomendado)	La CLI kb. Las pruebas del framework corren en 3.9 y 3.12, en Linux y Windows
Git	2.x	Instalar, actualizar y todo el ciclo: ramas, worktrees, publicar la documentación
Node.js	20 o superior (22 LTS recomendado)	Instalar kb por npm y correr las pruebas E2E. El Playwright vigente pide 22
Un asistente	GitHub Copilot en VS Code, Claude Code, o los dos	El agente que conduce las fases. kbspec deja sus archivos para los dos

kb check dice en una tabla qué tiene la máquina y qué le falta. Con un Node viejo lo marca en rojo: el kb de npm muere dentro de Node antes de llegar a Python, y el error no dice por qué.

Recomendados

Herramienta	Versión	Para qué
Volta	la actual	Un Node por proyecto sin tocar el global: la app puede necesitar Node 16 y Playwright, 22. kb pruebas preparar lo usa si está
VS Code	1.132 o superior	El panel de kbspec, la ventana de agentes y kbspec Studio
Microsoft Edge o Chrome instalado	el del equipo	El navegador de las E2E. Si no hay, se usa el Chromium que baja Playwright

Opcionales (según lo que use el equipo)

Herramienta	Versión	Para qué
Playwright	1.63.0 — no se instala a mano	La versión que kbspec probó. La deja kb pruebas preparar en el proyecto E2E de cada app, con su package.json; una versión nueva se adopta cuando kbspec la prueba
CLI de GitHub Copilot	1.0.95 o superior	El lote de tareas en paralelo sin supervisión
SDK de Copilot	1.0.16	El corredor del lote con el SDK. Se instala con kb instalar --con-sdk
Azure CLI (az)	la actual	Work items y Pull Requests en Azure DevOps
GitHub CLI (gh)	la actual	Issues y Pull Requests en GitHub
pandoc	la actual	Solo para exportar el reporte de pruebas a Word o PDF. El HTML se genera sin él

Sistemas: Windows, macOS y Linux. En Windows, install.ps1; los comandos son los mismos.

Instalar

Elegí la vía que tenga tu organización. Las tres terminan igual.

Desde el repositorio de documentación del equipo (la recomendada)

Si quien administra kbspec ya lo repartió (kb distribuir), viaja en una rama del repositorio de documentación que el equipo ya tiene. En una máquina nueva:

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

Desde el paquete de una versión

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

Con el script (sin npm)

bash install.sh --from <url-del-repositorio>      # macOS / Linux

.\install.ps1 -From \\servidor\dev\kbspec         # Windows

Después, abrí una terminal nueva: el PATH recién instalado no existe en la que ya tenías abierta.

kb instalar: la puesta a punto de la máquina

Es un solo comando, el mismo la primera vez y después de cada versión. Detecta lo que hay, pregunta solo lo que no puede deducir y lo anota en ~/.kb/config, no en variables de entorno que se pierden al cerrar la terminal:

1. Node y Volta: los mira primero y dice cómo resolverlo si falta algo.
2. El repositorio de documentación: lo encuentra, lo clona o lo crea (kb init-docs). Es uno solo para todo el equipo: expedientes, inventario, fichas y configuración.
3. La carpeta de tu código: la raíz donde tenés clonados los repositorios.
4. Las skills en ~/.claude/skills.
5. Cada repositorio de código del inventario: lo prepara con kb init-repo (reglas para el agente, ganchos, servidor MCP, una regla por componente). Todo queda fuera de versión: no hace falta commitear nada en el código.
6. La base de conocimiento al día con esta versión: sin el manual de la plantilla en las fichas y con los índices regenerados. Ver Repartir y actualizar.
7. La medición del consumo y el panel de VS Code.

Con una sola raíz de documentación por máquina: si la cambiás, es con kb configuracion --raiz <ruta>, no con un export.

Que lo conduzca el agente

En el chat, /kb-instalar hace lo mismo conversando: corre kb check, trabaja sobre el estado real y pregunta solo lo que falta.

Comprobar

kb check

  ✓  python3          3.12.6                     obligatorio
  ✓  git              git version 2.50.1         para instalar y actualizar
  ✓  node             v22.20.0                   para `kb` por npm y las E2E
  ✓  volta            instalado                  recomendado
  ✓  kb en el PATH    ~/.local/bin/kb (3.189.0)  para usar `kb` sin python3
  ✓  documentación    main → origin/main         la rama del repositorio de documentación

Dos avisos que conviene resolver antes de seguir:

• «kb en el PATH … es la X y esta CLI es la Y»: hay dos instalaciones y la terminal usa la vieja. which -a kb (macOS/Linux) o where.exe kb (Windows) las muestra.
• «documentación … sin rama remota»: tu copia del repositorio de documentación no sigue a ninguna rama del servidor, así que git pull no trae lo del equipo.

kb check --json devuelve lo mismo en un objeto. Cuando listo es true, la máquina está. Lo que sigue es del equipo, una vez:

1. Cargar el inventario y las fichas: qué aplicaciones hay, de qué están hechas y dónde está su código.
2. Configurar las pruebas E2E de cada aplicación que las lleve.
3. Tu primer requerimiento.