El inventario y las fichas

El inventario (aplicaciones/INVENTARIO.md, en el repositorio de documentación) es lo que le dice a kbspec y al agente qué aplicaciones hay, de qué están hechas y dónde está cada parte. De ahí salen:

en qué repositorios se crea la rama de un requerimiento (kb ramas);
qué ficha de arquitectura y qué estándares lee el agente (kb contexto);
qué comandos corre kb pruebas y qué evidencia exige el Pull Request;
con qué se arma el mapa del código y su índice (kb mapa construir).

Recién instalado trae filas de ejemplo. Hay que cargar las del equipo una vez.

Las tres palabras

Palabra	Qué es	¿Tiene carpeta?
Aplicación	Cómo le dice el usuario al producto: `OPERACIONES`, `CARTERA`	No
Componente	Una unidad desplegable: un proyecto Angular, una API .NET, un repositorio de scripts	Sí: es lo único que tiene ruta
Módulo	Un área de negocio: `RO`, `Cobros`. Puede atravesar varios componentes (su front y su API)	No

Si tiene carpeta propia, es un componente. El manual completo, con cómo se resuelve un nombre informal («el host», «el backend de ro»): kb apps guia.

1. Cargar el inventario

Lo más simple es conversando: /kb-configurar en el chat (o el botón Configurar kbspec del panel) escanea la carpeta de tus aplicaciones, propone cada una con lo que puede inferir y pregunta solo lo que falta. Está en Configurar conversando. Una aplicación que todavía no existe también se da de alta ahí (/kb-configurar app nueva).

En una terminal, parado en la carpeta que contiene los repositorios de código:

kb apps descubrir

Es una conversación y va en el orden del negocio: cuál es el punto de entrada del usuario (la aplicación), cuáles proyectos del workspace son sus módulos —los propone leyendo angular.json, las soluciones .sln y los manifiestos— y qué componentes usa por detrás. Anota cada componente con su repositorio, que es lo que decide cuántas ramas necesita un requerimiento. No escribe nada sin confirmación; si el inventario ya existe, entra en modo revisión y ofrece completar lo que falte.

Sin conversación —un pipeline, un script—, o para un alta puntual:

kb apps detectar <raíz-del-código> --aplicar      # propone y escribe lo que encuentra

kb apps agregar --codigo OPS-RO-API --nombre "API del área RO" --tipo Backend \
    --aplicacion OPERACIONES --modulo RO --ruta raiz/OPS_RO_API \
    --repositorio ops-ro --consume "API-CORE,API-SEG"

kb apps aplicacion OPERACIONES --modulos "RO,Continuidad" \
    --componentes "OPS-HOST,OPS-RO-WEB,OPS-RO-API"

kb apps editar OPS-RO-WEB --consume "OPS-RO-API,API-CORE"

Las rutas son lógicas. El primer segmento (raiz/) es una etiqueta, no una carpeta: la copia de cada desarrollador puede estar en D:\proyectos o en ~/repos, y kbspec la encuentra sola. Nunca se guarda una ruta absoluta.

2. Comprobar que se lee bien

kb apps                       # el inventario como lo entiende kbspec
kb apps "el backend de ro"    # resuelve un nombre informal al código canónico
kb alcance                    # (con un expediente abierto) qué componentes y ramas toca

Si kb apps "<nombre>" devuelve varias candidatas, falta un alias o el módulo. Un apodo se declara solo cuando no se deduce del nombre: una sigla interna, un nombre viejo.

3. Las fichas de arquitectura

Cada aplicación (o componente con stack propio) tiene su ficha en aplicaciones/<APP>/arquitectura.md. Guarda solo datos: comandos, usuarios de prueba, cómo se entra, decisiones. Cómo se llena cada sección lo dice kb ficha guia <sección>.

kb ficha sembrar OPERACIONES          # la arranca con lo que dice el código: proyectos, versiones, comandos
kb arquitectura --aplicar             # compara cada ficha con el código y le escribe proyectos y comandos reales
kb ficha cosechar OPERACIONES --aplicar   # capas y patrones, desde el CLAUDE.md/AGENTS.md del equipo (como cita)

Lo que queda para una persona:

clasificacion: en el encabezado (público, interno, confidencial, restringido). Decide qué modelos pueden trabajar con ese código según la política de IA.
verified: con quién la revisó y cuándo. Sin eso, kb contexto la lee «con cautela».
Lo que el código no dice: por qué se decidió algo, qué no se toca, las trampas.

4. El mapa y el índice

kb mapa construir OPERACIONES

Lee la copia local de cada componente —Angular, .NET, SQL, WebForms, ASP clásico, Java, PHP, SSIS— y arma el mapa del código: qué pantalla llama a qué API, qué comando maneja qué caso, qué entidad usa qué tabla. Tarda segundos y escribe al lado de la ficha:

indice-<APP>.md: componentes, áreas y pantallas, y quién depende de quién;
indice/<COMPONENTE>.md: áreas con las APIs que consumen y dónde va cada tipo de archivo, con uno real a imitar.

El índice se genera, no se edita, y vence con el código: kb contexto lo da por bueno aunque la ficha no esté confirmada. Con él el agente puede pedir una receta en vez de recorrer carpetas:

kb mapa receta OPERACIONES comando OPS-RO-API     # los archivos de un comando nuevo, con uno real a imitar
kb mapa vecindario OPERACIONES <archivo>          # qué toca un archivo y quién depende de él

5. El inventario contra el código

kb apps verificar OPERACIONES

Cruza el inventario con los mapas: lo que cada componente consume de verdad y la columna «Consume» no dice, lo declarado que el código no muestra, rutas que no existen, un componente de base de datos sin un solo .sql, y lo que le falta a cada ficha. Con --aplicar suma a «Consume» lo que el código muestra (nunca quita).

6. Los contratos de las APIs

kb contratos sembrar API-SEG               # del OpenAPI que el código ya tiene (NSwag, swagger.json)
kb contratos buscar API-SEG usuarios por rol   # una operación, no el contrato entero

No hace falta levantar el servicio. Si el spec del disco no coincide con los controllers —está viejo o es de otro servicio—, no lo siembra y lo dice.

7. La guía funcional

La ficha dice cómo está hecha la aplicación; la guía funcional dice cómo se usa, en el idioma del negocio —módulos, pantallas, cálculos, cómo se hace cada cosa—, y es lo que contesta kb preguntar. Se arma con kb funcional <APP> sembrar: está en La guía funcional y el asistente.

8. Publicar para el equipo

Todo esto vive en el repositorio de documentación:

kb publicar-base

Los demás lo reciben con git pull o kb abrir --sync. Y kb init-repo —que corre kb instalar en cada repositorio de código— deja una regla por componente para Claude Code y Copilot, que se carga solo al tocar archivos de esa carpeta.