EscalaKit OS

EscalaKit OS convierte un repositorio en un entorno de trabajo guiado para personas y agentes de IA.

Ayuda a entender el proyecto, definir cómo se debe trabajar, preparar cada cambio antes de programarlo y exigir evidencia antes de darlo por terminado.

El resultado vive dentro del mismo repositorio. No necesitas un servidor, una cuenta adicional ni enviar el código del proyecto a EscalaKit.

El problema que resuelve

Cuando una persona o un agente entra a un proyecto nuevo, suele tener que descubrir por su cuenta:

• qué se está construyendo;
• qué decisiones ya se tomaron;
• qué reglas no se pueden romper;
• cómo debe diseñarse y verificarse un cambio;
• qué puede ejecutar un agente y qué necesita aprobación humana.

Esa información suele estar incompleta, dispersa o solo en la cabeza del equipo.

EscalaKit OS la convierte en contexto versionado, reglas comprobables y un flujo de trabajo común. Así, cada tarea empieza con la misma comprensión del proyecto y termina con evidencia revisable.

Qué hace

EscalaKit OS acompaña el trabajo en cinco momentos:

1. Entiende el proyecto. Puede entrevistar al equipo para iniciar un proyecto o analizar de forma segura un repositorio existente.
2. Genera el contexto. Crea una carpeta .sdd con el modelo del proyecto, sus reglas, interfaces, verificaciones y operación.
3. Prepara el cambio. Cada feature pasa por modelo, diagrama, especificación, diseño y tareas antes de llegar a implementación.
4. Delimita el trabajo de los agentes. Compila tareas con alcance, permisos, dependencias, presupuestos y aprobaciones explícitas.
5. Verifica el resultado. Usa gates y recibos para distinguir entre trabajo iniciado, trabajo comprobado y trabajo realmente listo.

Proyecto nuevo ──> onboarding ─────────────┐
                                           ├──> contexto .sdd
Proyecto existente ──> análisis ──> revisión ┘          │
                                                       v
                      modelo -> diagrama -> spec -> diseño -> tareas
                                                       │
                                                       v
                              ejecución controlada -> evidencia -> cierre

Para quién es

EscalaKit OS está pensado para:

• equipos que quieren adoptar desarrollo guiado por especificaciones;
• desarrolladores que trabajan con agentes de IA dentro de sus repositorios;
• responsables técnicos que necesitan límites, aprobaciones y trazabilidad;
• proyectos nuevos y repositorios existentes que necesitan ordenar su contexto.

Admite perfiles para aplicaciones web y móviles, APIs, CLIs, librerías, pipelines de datos, infraestructura, agentes de IA, contenido, procesos internos y proyectos personalizados.

Empieza en cinco minutos

Necesitas Node.js 22.14 o superior y menor que 27.

Puedes abrir el menú visual sin instalar nada globalmente:

npx @escala/escalakit-os

También puedes instalarlo y usar cualquiera de sus dos comandos:

npm install --global @escala/escalakit-os
escalakit-os
# o
escalaos-kit

Si empiezas un proyecto

Ejecuta el onboarding dentro del repositorio:

npx @escala/escalakit-os project new --lang es

EscalaKit te hará preguntas sobre el producto, la arquitectura, la seguridad, las integraciones y la forma de verificar el trabajo. Después generará el contexto .sdd específico para ese proyecto.

Para preparar la primera feature:

npx @escala/escalakit-os new mi-primera-feature
npx @escala/escalakit-os status

Si el proyecto ya existe

Empieza con un análisis de solo lectura:

npx @escala/escalakit-os analyze .

El análisis identifica el stack, los scripts, las pruebas, la integración continua, la estructura y las dependencias sin ejecutar el código del proyecto.

Luego puedes revisar sus conclusiones y preparar un plan de adopción antes de permitir cualquier cambio:

analyze -> reconcile -> adopt --plan -> aprobación humana -> adopt --apply

La adopción separa el diagnóstico, la decisión y la escritura. Los conflictos se muestran en lugar de sobrescribir archivos existentes.

Configuración SDD específica por proyecto

EscalaKit compila un contrato SddWorkspaceConfig versionado como fuente de verdad del sistema SDD base.

En un proyecto nuevo, el contrato se crea después de la entrevista, la normalización de respuestas, el ProjectModel completo y la configuración agéntica ligada.

En un repositorio existente, el contrato se crea únicamente desde el análisis de solo lectura, el perfil reconciliado, la policy efectiva y el contexto aprobados.

El contrato materializa propósito, alcance, dominio, ingeniería, gobierno, workflow, rules, profiles, interfaces, schemas, hooks, operaciones, verificación, templates, referencias y unknowns.

La fuente de verdad queda en .sdd/config.json.

El manifest liga su ruta y digest.

Constitution, knowledge, decisions, glossary, flow, runbooks y demás vistas Markdown conservan el mismo digest para detectar drift.

Los hooks pre-commit y pre-push se generan como plantillas ejecutables, locales, sin red y opt-in.

EscalaKit nunca los instala automáticamente dentro de .git/hooks.

Los schemas locales se copian desde un catálogo allowlisted de contratos publicados por la misma versión del paquete.

escalakit-os check valida binding, digest, schema, catálogo, tipo de archivo, budget, modo de hooks, drift de schemas y ausencia de placeholders.

Los proyectos legacy sin manifest.sdd conservan compatibilidad hasta una adopción explícita.

Configuración agéntica específica por proyecto

EscalaKit ya no instala una plantilla genérica de agentes. Compila un contrato AgenticWorkspaceConfig versionado y provider-neutral a partir del contexto real del proyecto.

En un proyecto nuevo, la configuración se genera después de terminar la entrevista, normalizar las respuestas y persistir un ProjectModel completo. El tipo de proyecto, los datos, las integraciones, la seguridad, la operación y la verificación determinan los roles especializados y sus rutas.

En un repositorio existente, la configuración solo se prepara después del análisis de solo lectura, la reconciliación humana y la aprobación del plan de adopción. Las señales observadas del stack, pruebas, CI, infraestructura, riesgos y políticas determinan qué roles adicionales hacen falta. Las incertidumbres quedan visibles y producen estado review_required o blocked, en vez de convertirse en permisos inventados.

El contrato mantiene un modelo conservador:

• ejecución por un solo agente como valor predeterminado;
• delegación y fan-out desactivados hasta que exista una decisión explícita;
• herramientas y datos con política deny-by-default;
• grants solicitados que describen intención, pero no conceden autoridad;
• budgets, stop conditions, handoffs, memoria y evaluaciones verificables;
• aprobación humana y contratos de runtime como autoridad efectiva para cada mutación.

La fuente de verdad agéntica queda en .sdd/agentic/config.json. Los documentos humanos se derivan del mismo digest para evitar que AGENTS.md, el router, los roles y las políticas describan sistemas distintos.

SddWorkspaceConfig y AgenticWorkspaceConfig son contratos separados y ligados.

El primero gobierna el contexto y la superficie SDD.

El segundo gobierna roles, routing, herramientas, memoria, handoffs y evaluaciones.

CLI interactivo y modo scriptable

Al ejecutar EscalaKit OS sin argumentos, una terminal compatible abre un menú para navegar por:

• Proyecto;
• Workflow SDD;
• Agentes;
• Automatización;
• Workspace;
• Runtime y operaciones;
• Diagnóstico.

Las acciones que modifican el repositorio muestran una vista previa y solicitan confirmación. La misma funcionalidad está disponible mediante comandos y salida JSON para automatización y CI. La navegación es keyboard-first y no depende del color para comunicar estados.

Si la terminal no es compatible, EscalaKit usa una salida lineal. También ofrece modos para lectores de pantalla, movimiento reducido, ASCII y ausencia de color. Los temas de alto contraste siguen la configuración de la terminal.

CI=1 npx @escala/escalakit-os status
NO_COLOR=1 npx @escala/escalakit-os status
ASCII_ONLY=1 npx @escala/escalakit-os status
REDUCED_MOTION=1 npx @escala/escalakit-os status
SCREEN_READER=1 npx @escala/escalakit-os status

La guía de uso y compatibilidad está en CLI interactiva.

Qué queda en el repositorio

El onboarding crea un sistema de contexto local y versionable:

.sdd/
├── config.json          # Fuente de verdad del workspace SDD base
├── project-model.json   # Qué es el proyecto y de dónde salió cada decisión
├── agentic/config.json  # Roles, rutas, límites, herramientas y políticas compiladas
├── constitution.md      # Principios que no deben romperse
├── flow.md              # Fases, transiciones, gates, receipts y recuperación
├── decisions.md         # Decisiones iniciales y sus consecuencias
├── glossary.md          # Lenguaje del sistema y del dominio
├── knowledge/           # Contexto, dominio y referencias con provenance
├── rules/               # Reglas compiladas para este proyecto
├── profiles/            # Selección, agentes, operación y verificación
├── interfaces/          # Contratos de entrada y salida
├── schemas/             # Contratos locales allowlisted de la versión
├── hooks/               # Hooks ejecutables, seguros y opt-in
├── templates/           # Contratos completos para features y decisiones
├── verification/        # Cómo se demuestra que el trabajo funciona
├── operations/          # Cómo operar, recuperar y revertir cambios
├── agents/              # Cómo se asigna trabajo especializado
└── features/            # Expediente y estado de cada feature

EscalaKit también puede generar instrucciones como AGENTS.md y preparar PR Review Agent para GitHub o Azure DevOps. La instalación del agente usa versiones fijas, mantiene los secretos fuera del repositorio y deja visibles los permisos y gates requeridos.

Un ejemplo del flujo diario

# Ver el estado y los bloqueos actuales
npx @escala/escalakit-os status

# Crear el expediente de una feature
npx @escala/escalakit-os new importar-transacciones

# Verificar si la especificación cumple sus gates
npx @escala/escalakit-os check --phase spec

# Explicar un bloqueo concreto
npx @escala/escalakit-os explain gate GATE-SPEC-MODEL

# Avanzar después de una aprobación
npx @escala/escalakit-os advance \
  --to design \
  --actor owner \
  --justification "Especificación aprobada"

Las fases avanzan en orden:

intent -> discovery -> spec -> design -> tasks -> build -> verify -> ship

EscalaKit no considera una fase completa solo porque existan archivos. Los gates revisan contenido, decisiones, evidencias y la cadena de recibos.

Capacidades principales

| Necesidad | Capacidad | | --- | --- | | Crear contexto para un proyecto nuevo | Onboarding adaptado al tipo de proyecto y sus riesgos | | Entender un repositorio existente | Análisis local y de solo lectura | | Corregir inferencias del análisis | Reconciliación con decisiones humanas | | Adoptar EscalaKit sin sobrescribir trabajo | Plan y aplicación transaccional con rollback | | Configurar el SDD para el proyecto real | Contrato base compilado desde entrevista o evidencia aprobada | | Configurar agentes para el proyecto real | Contrato agéntico compilado desde onboarding o análisis aprobado | | Preparar una feature | Workflow SDD diagram-first | | Coordinar varios repositorios | Workspace y grafo de impacto de solo lectura | | Asignar trabajo a un agente | Contratos y briefs con mínimo privilegio | | Automatizar acciones repetibles | Motor local, idempotente y gobernado | | Revisar una ejecución | Estado, recibos y bundles de soporte redactados | | Detectar cambios posteriores | Baseline y reconciliación de drift |

Usa escalakit-os --help para ver todos los comandos y ejemplos disponibles. Los consumidores automatizados deben usar --json para obtener contratos estables.

Límites importantes

EscalaKit OS no es un generador autónomo que recibe una idea y publica un producto sin supervisión.

• analyze no ejecuta scripts, builds ni pruebas del repositorio inspeccionado.
• Un resultado inferido no se convierte en verdad hasta que una persona lo revisa.
• La documentación y la memoria no conceden permisos a un agente.
• Las acciones sensibles requieren políticas y aprobaciones explícitas.
• El runtime gobernado ejecuta tareas de agentes, no comandos arbitrarios del proyecto analizado.
• Los gates locales no demuestran por sí solos que una aplicación fue validada en producción.

Estas restricciones son parte del producto. Su objetivo es hacer que la automatización sea útil sin volver invisible el riesgo.

Seguridad y privacidad

El flujo principal es local-first. EscalaKit no incluye telemetría remota habilitable y los bundles de soporte redactan rutas, contenidos y secretos.

La instalación de PR Review Agent nunca guarda API keys en argumentos, archivos, logs, recibos ni mensajes de error. Las credenciales se configuran en el proveedor de CI correspondiente.

La instalación automática de skills remotas está deshabilitada. EscalaKit solo recomienda las skills adecuadas para el tipo y los riesgos del proyecto.

Documentación avanzada

• Adopción de un repositorio existente
• Resolución de conflictos
• Recuperación después de un fallo
• Rollback
• Detección y reconciliación de drift
• Respuesta a incidentes
• Publicación segura del paquete npm

Los contratos públicos versionados están en lib/schemas. Las APIs reutilizables están expuestas desde lib.

Desarrollo local

npm install
npm test
npm run verify:ga
npm run verify:project-new-ga
npm pack --dry-run

Todo archivo .js del repositorio debe tener 100 líneas o menos. El comando npm test verifica esa regla antes de ejecutar la suite funcional.

Estado del paquete

La versión pública actual es @escala/[email protected].

El repositorio fuente es privado y el paquete en npm es público. Las releases usan publicación por etapas, aprobación humana y verificación de integridad.