ainova-systems/intelligence-dev-packs

Inicializar el sustrato de documentación guiada por especificaciones

Montar la base de conocimiento compartida del repositorio — la capa que tanto humanos como agentes leen — para que el resto del paquete de especificaciones (spec-create, spec-execute) tenga un lugar donde escribir. Seguro y aditivo: no se elimina nada, los borradores se marcan como inferidos hasta confirmación, y el propietario aprueba antes de que algo sea autoritativo.

Resolver la estructura objetivo (aprender, luego perfilar, luego predeterminar) — nunca imponer

1. Aprender del proyecto primero. Si el repositorio ya tiene una estructura de documentación (docs/, Documentation/, una regla de documentación, documentación de características emparentada), adóptala — busca primero, lee dos documentos emparentados, imita no inventes. Una estructura existente madura prevalece sobre la predeterminada; no reestructures lo que ya funciona.
2. Perfilar fija rutas cuando sean ambiguas: specs_dir, features_dir, rules_dir, decisions_dir, spec_grouping.
3. Predeterminado para proyectos nuevos = el árbol de documentación priorizada para IA (ver references/docs-tree.md): docs/ con model.md, glossary.md, rules/R-NNN-*.md, features/<feature>.md, specs/NNN-<feature>/{requirements,plan,tasks}.md, decisions/NNNN-*.md, architecture/, guides/, _inbox/.

El modelo por capas (lo que posee este skill)

Ordenado por la fuerza con que cada una restringe a un agente: un agente sigue una verificación ejecutable de manera más fiable que texto en prosa.

• Capa A - restricciones ejecutables (configuraciones de lint/límites/pruebas de contrato, tests/): la más fuerte. Fuera del alcance aquí — configúralo por separado.
• Capa B - reglas legibles por máquina y conocimiento de arquitectura (reglas como contratos rules/R-NNN, mapa de dependencias, registro de decisiones). spec-init crea estos documentos; el enrutador de entrada del agente (AGENTS.md) sigue siendo propiedad del motor de sincronización — este skill solo asegura que apunte al árbol de documentación, nunca lo sobrescribe.
• Capa C - base de conocimiento compartida (modelo, glosario, documentación de características, especificaciones, arquitectura, guías). spec-init crea y siembra esta capa.

Pasos

1. Inventariar la documentación existente: cada *.md, exportación de wiki, diagrama, nota dispersa. Clasificar cada una como modelo / glosario / comportamiento-característica / flujo / decisión / arquitectura / guía / no clasificada.
2. Andamiar el árbol resuelto — crear solo lo que falta (carpetas + un índice docs/README.md). Nunca sobrescribir un documento existente.
3. Migrar de forma segura - cuarentena primero. Mover todo el contenido preexistente, no clasificado o heredado a _inbox/ (la cuarentena) para que solo la nueva estructura se lea como autoritativa, luego reclasificar un elemento a la vez con revisión del propietario: notas de "cómo funciona X" -> features/, diagramas de flujo -> architecture/diagrams/, decisiones -> decisions/. Nada se elimina; la reclasificación es uno a uno, nunca masiva automática.
4. Redactar los documentos núcleo a partir del código, marcados como confirmado / inferido: el modelo de dominio (model.md) y el glosario (glossary.md) a partir de tipos y nombres de campos; líneas base de comportamiento de características (features/) a partir del comportamiento real del código hoy + criterios de aceptación EARS; el mapa de dependencias a partir de importaciones reales; reglas de negocio numeradas candidatas (rules/R-NNN) que el código ya impone.
5. Aplicar el principio de nomenclatura. Todo bajo la raíz de documentación es kebab-case en minúsculas; las series ordenadas usan prefijos rellenos con ceros (NNNN- ADRs, NNN- especificaciones); un concepto, un nombre, sin sinónimos. Los únicos archivos en mayúsculas son AGENTS.md y README.md en la raíz (los estándares externos requieren esos nombres).
6. Puerta del propietario. Presentar el árbol andamiado, el contenido de _inbox/ pendiente de reclasificación y los documentos redactados. Nada es autoritativo hasta que el propietario confirme cada borrador; todo permanece como inferido hasta entonces.

Verificar

• El árbol resuelto existe; el índice lo lista; cada archivo preexistente está reclasificado o en _inbox/ (ninguno perdido); cada documento redactado está marcado como confirmado/inferido; AGENTS.md no fue sobrescrito.

Alcance / traspaso

• Crear una especificación de cambio dentro de specs/ andamiada — spec-create.
• Restricciones ejecutables de Capa A (lint, límites, pruebas de contrato) — fuera del alcance; configurar por separado.
• Mantener la documentación sincronizada con el código posteriormente — spec-audit-docs.

CRÍTICO

• Nunca eliminar ni sobrescribir documentación existente — poner en cuarentena en _inbox/, reclasificar uno a uno, revisado por el propietario.
• Nunca imponer el árbol predeterminado sobre una estructura de proyecto que funciona — aprender y adoptar primero.
• Advertencia honesta que declarar en la salida: esto fija solo lo que ya está estructurado en el código. Las reglas de negocio que viven en configuraciones, filas de base de datos o extensiones registradas en tiempo de ejecución son invisibles para la redacción estática — señalarlas para pruebas funcionales o migración gradual al código; nunca inventar una regla que el código no muestre.