@kal-elsam/kairo-runtime 0.1.0

package/repo-template/docs/ai/agent-workflow.md

@@ -0,0 +1,45 @@
+# Agent Workflow
+
+## Roles
+
+| Agente | Cuándo se activa | Responsabilidad |
+|---|---|---|
+| Harness Orchestrator | tareas complejas | Coordina estados |
+| Architect | arquitectura, capas, ADRs | Decide estructura |
+| Debugger | bugs, errores | Diagnóstico con evidencia |
+| Test Engineer | tests, cobertura | Diseña pruebas |
+| Eval Engineer | IA/agentes/prompts | Diseña evals |
+| Context Engineer | memoria/grafo | Administra contexto |
+| Reviewer | antes de merge/commit | Revisión técnica |
+
+## Feature
+
+```txt
+Harness Orchestrator
+→ Architect
+→ Test Engineer
+→ Eval Engineer si IA
+→ Implementation Agent
+→ Reviewer
+→ Human
+```
+
+## Bug
+
+```txt
+Debugger
+→ Test Engineer
+→ Implementation Agent
+→ Reviewer
+→ Human
+```
+
+## Handoff
+
+Cada agente entrega:
+
+- contexto leído
+- archivos analizados
+- decisión tomada
+- riesgos
+- siguiente acción sugerida

package/repo-template/docs/ai/api.md

@@ -0,0 +1,28 @@
+# API
+
+## Abstracción detectada
+
+- Capa: [API_LAYER]
+- Cliente HTTP: [HTTP_CLIENT]
+- Timeout estándar: 10000ms
+- Manejo de errores: [ERROR_HANDLING]
+
+## Endpoints internos
+
+[ENDPOINTS_DETECTED]
+
+## APIs externas
+
+[EXTERNAL_INTEGRATIONS]
+
+## Variables de entorno
+
+[ENV_VARS_DETECTED]
+
+## Reglas
+
+- No llamadas directas desde UI si existe capa de servicios.
+- Centralizar errores.
+- Validar request y response.
+- Documentar endpoint nuevo aquí.
+- Integration test para endpoint nuevo.

package/repo-template/docs/ai/architecture.md

@@ -0,0 +1,53 @@
+# Arquitectura del proyecto
+
+## Stack
+
+- Lenguaje: [LANGUAGE]
+- Framework: [FRAMEWORK]
+- Package manager: [PACKAGE_MANAGER]
+- Inicializado: [DATE]
+
+## Propósito
+
+[PROJECT_PURPOSE]
+
+## Estructura de carpetas
+
+```txt
+[REAL_TREE_MAX_DEPTH_3]
+```
+
+## Patrón de arquitectura
+
+- Patrón principal: [ARCHITECTURE_PATTERN]
+- Presentación: [UI_DIRECTORIES]
+- API: [API_DIRECTORIES]
+- Datos: [DATA_DIRECTORIES]
+- Tests: [TEST_DIRECTORIES]
+- Evals: [EVAL_DIRECTORIES]
+
+## Decisiones de arquitectura
+
+### ADR-001 — Stack inicial detectado
+
+**Estado:** aceptado  
+**Fecha:** [DATE]
+
+#### Contexto
+
+El proyecto usa [STACK].
+
+#### Decisión
+
+Mantener la arquitectura detectada salvo que una spec o ADR proponga cambio.
+
+#### Consecuencias
+
+Toda nueva capa debe respetar la estructura existente.
+
+## Reglas estrictas
+
+- No mezclar lógica de negocio con presentación.
+- No introducir dependencias sin ADR o justificación.
+- No crear nuevas capas sin documentarlas.
+- No romper contratos públicos sin migration plan.

package/repo-template/docs/ai/context-budget.md

@@ -0,0 +1,54 @@
+# Context Budget
+
+## Objetivo
+
+Evitar que los agentes carguen documentación innecesaria.
+
+## Siempre leer
+
+```txt
+AGENTS.md
+docs/ai/harness.md
+```
+
+## Leer por tarea
+
+| Tarea | Documentos |
+|---|---|
+| UI | `docs/ai/ui.md`, `docs/skills/ui-design.md` |
+| API | `docs/ai/api.md`, `docs/skills/api-design.md` |
+| DB | `docs/ai/data.md` si existe |
+| Testing | `docs/ai/testing.md`, `docs/ai/test-driven-development.md` |
+| IA/Evals | `docs/ai/evals.md`, `docs/skills/evals.md` |
+| Arquitectura | `docs/ai/architecture.md`, `docs/skills/architecture.md` |
+| Git/checkpoint | `docs/ai/git-workflow.md`, `docs/skills/git-workflow.md` |
+| Memoria | `docs/ai/memory.md` |
+| Graph | `docs/ai/context-graph.md`, `docs/skills/context-graph.md` |
+| Model selection | `docs/ai/model-policy.md`, `docs/ai/provider-routing.md` |
+| Tool adapter | `docs/ai/tool-adapters.md` |
+
+## Reglas
+
+- No leer todo si el cambio es trivial.
+- No cargar specs no relacionadas.
+- No cargar archivos grandes sin necesidad.
+- Reportar qué contexto fue usado.
+- Si falta contexto, pedir solo lo mínimo.
+
+## Adapter parity context rule
+
+Every adapter should use the same context budget.
+
+Adapters may load context differently, but should follow:
+
+```txt
+Always:
+- AGENTS.md
+- relevant docs/ai file
+
+Only when needed:
+- docs/skills
+- docs/specs
+- evals
+- adapter-specific instructions
+```

package/repo-template/docs/ai/context-graph.md

@@ -0,0 +1,39 @@
+# Context Graph
+
+## Objetivo
+
+Mapear arquitectura, módulos, entidades, flujos, tools y riesgos del proyecto usando Graphify, sin que el grafo se convierta en una segunda fuente de verdad.
+
+## Qué indexar con Graphify
+
+- Carpetas y módulos, y sus límites.
+- Dependencias entre módulos: imports, llamadas, contratos.
+- Entidades de dominio.
+- Endpoints y contratos de API.
+- Componentes UI y su árbol de composición.
+- Herramientas externas, MCPs e integraciones.
+- Agentes, skills y comandos definidos en el repo.
+- Specs (`docs/specs/`) y su relación con el código que implementan.
+- Tests y evals, y qué código o spec cubren.
+- Decisiones registradas en `docs/ai/decision-log.md`.
+
+## Cómo detectar dependencias y riesgos
+
+Señales a las que prestar atención en el grafo:
+
+| Señal | Riesgo | Acción |
+|---|---|---|
+| Dependencias circulares | Acoplamiento oculto, difícil de testear | Reportar y proponer ruptura del ciclo |
+| Nodo con fan-in muy alto ("god module") | Punto único de fallo, cambios riesgosos | Evaluar split o interfaz más estrecha |
+| Módulo huérfano, sin referencias | Código muerto o documentación desactualizada | Confirmar antes de borrar |
+| Nodo de alta centralidad sin tests/evals | Riesgo de regresión silenciosa | Priorizar cobertura antes de tocarlo |
+| Spec sin código asociado | Trabajo pendiente o spec abandonada | Verificar estado con el humano |
+| Código sin spec ni decisión asociada | Cambio no gobernado por el harness | Retrofit de spec si el cambio es significativo |
+
+## Reglas
+
+- Cada feature importante debe conectar spec → código → tests/evals → decisión.
+- El grafo se regenera desde código y docs; no se edita el grafo a mano.
+- Si el grafo y el código divergen, investigar el código primero: el grafo puede estar desactualizado.
+- El grafo ayuda a navegar y priorizar; no es fuente de verdad superior al repo.
+- No declarar un riesgo "resuelto" solo porque desapareció del grafo; verificarlo en el código y en los tests.

package/repo-template/docs/ai/conventions.md

@@ -0,0 +1,34 @@
+# Convenciones de código
+
+## Nombrado
+
+- Archivos: [DETECTED]
+- Variables: camelCase
+- Funciones: camelCase
+- Clases/componentes: PascalCase
+- Constantes: UPPER_SNAKE_CASE
+- Tests: [DETECTED]
+
+## Imports
+
+Orden recomendado:
+
+1. Librerías externas
+2. Módulos internos
+3. Tipos
+4. Estilos
+
+Alias detectados:
+
+```txt
+[ALIASES]
+```
+
+## Reglas
+
+- No usar `any` sin comentario justificando.
+- No crear funciones largas sin extraer lógica.
+- No anidar más de 3 niveles sin refactor.
+- No poner lógica de negocio en archivos de presentación.
+- No dejar código muerto, comentado o duplicado.
+- Preferir módulos pequeños, cohesionados y testeables.

package/repo-template/docs/ai/decision-log.md

@@ -0,0 +1,5 @@
+# Decision Log
+
+| Date | Decision | Context | Impact |
+|---|---|---|---|
+| [DATE] | Use AGENTS.md as universal source | Multi-agent compatibility | Reduces duplicated instructions |

package/repo-template/docs/ai/enforcement.md

@@ -0,0 +1,63 @@
+# Enforcement
+
+## Objetivo
+
+Evitar que el harness sea solo documentación.
+
+El harness opera en tres niveles:
+
+```txt
+1. Guidance      -> AGENTS.md, docs/ai, docs/skills
+2. Constraints   -> permissions, hooks, trust policy, model routing
+3. Enforcement   -> CI gates, evals, tests, secret scan, dependency review
+```
+
+## Regla central
+
+```txt
+If it is important, it must be enforceable.
+If it cannot be enforced, it must be reviewed.
+If it cannot be reviewed, it must not be automated.
+```
+
+## Controles mínimos
+
+- lint
+- format check
+- typecheck
+- unit tests
+- integration tests cuando apliquen
+- E2E smoke test cuando aplique
+- AI evals cuando hay comportamiento IA
+- secret scanning
+- dependency review
+- license policy
+- build check
+- checkpoint review antes de merge
+
+## Enforcement map
+
+| Riesgo | Control |
+|---|---|
+| Código basura | lint, typecheck, tests, review |
+| Scope creep | specs, diff limit, checkpoint |
+| Bugs recurrentes | regression tests obligatorios |
+| IA degradada | evals con baseline |
+| Skill maliciosa | trust policy + allowlist |
+| Secretos | secret scan + pre-commit |
+| Dependencias inseguras | dependency review |
+| Arquitectura degradada | architecture review + ADR |
+| Loops infinitos | loop policy + max attempts |
+| Costos altos | model routing + usage logs |
+
+## Spec sizing enforcement
+
+Agents must classify spec complexity before implementation.
+
+```txt
+basic    -> low-risk local task
+standard -> normal feature/change
+complex  -> architecture/security/data/AI/infra/cross-system/high-risk
+```
+
+Hard-trigger work must be complex and cannot proceed as a basic spec.

package/repo-template/docs/ai/eval-strategy.md

@@ -0,0 +1,42 @@
+# Eval Strategy
+
+## Tipos de evals
+
+```txt
+evals/golden/       -> casos esperados de comportamiento
+evals/tool-calls/   -> tool/function calling correctness
+evals/schema/       -> JSON/schema/output contracts
+evals/regression/   -> bugs o fallos previos
+evals/loop-regression/ -> loops acotados y escalación
+```
+
+## Evals mínimos por proyecto IA
+
+- 20-50 golden cases iniciales
+- casos negativos
+- casos de edge behavior
+- casos de tool-calling
+- casos de seguridad/prompt injection básicos
+- casos de regresión por bugfix
+
+## Métricas
+
+| Métrica | Target |
+|---|---:|
+| schema validity | 100% |
+| critical eval pass rate | 100% |
+| golden eval pass rate | >= 95% |
+| regression eval pass rate | 100% |
+| tool-call correctness | >= 95% |
+| no unsafe action | 100% |
+| no hallucinated tool | 100% |
+
+## Release rule
+
+No promover cambios IA si:
+
+- falla una eval crítica
+- cae el baseline sin justificación
+- no hay dataset suficiente
+- no hay rollback
+- no hay aprobación humana para producción

package/repo-template/docs/ai/evals.md

@@ -0,0 +1,44 @@
+# AI Evals
+
+## Objetivo
+
+Validar comportamiento de IA, agentes, prompts, tool calling, RAG y flujos conversacionales.
+
+## Cuándo crear evals
+
+- Prompt de producción.
+- Agente conversacional.
+- Tool calling.
+- Clasificación.
+- Generación de contenido.
+- RAG.
+- Workflow multi-step.
+- Cambio de modelo o proveedor.
+- Cambio de memoria/contexto.
+
+## Tipos de eval
+
+| Tipo | Objetivo |
+|---|---|
+| Golden dataset | Casos esperados conocidos |
+| Prompt regression | Evitar degradación de prompts |
+| Tool-call correctness | Verificar herramienta correcta y argumentos |
+| Schema adherence | Respuesta cumple contrato |
+| Safety checks | Evitar acciones inseguras |
+| Conversation flows | Validar flujos multi-turn |
+| Cost/latency | Controlar costo y tiempo |
+| Hallucination checks | Evitar invenciones |
+
+## Estructura
+
+```txt
+evals/
+├── golden-datasets/
+├── prompt-regression/
+├── tool-calling/
+└── conversation-flows/
+```
+
+## Regla
+
+Si un cambio puede alterar comportamiento IA, debe tener eval o justificación explícita de por qué no aplica.

package/repo-template/docs/ai/git-workflow.md

@@ -0,0 +1,35 @@
+# Git workflow
+
+## Pipeline pre-commit
+
+1. Diff review.
+2. Secrets check.
+3. Linter: `[LINT_COMMAND]`
+4. Formatter: `[FORMAT_COMMAND]`
+5. Type check: `[TYPE_CHECK_COMMAND]`
+6. Tests: `[TEST_COMMAND]`
+7. Build: `[BUILD_COMMAND]`
+8. Commit conventional.
+
+## Conventional Commits
+
+```txt
+tipo(scope): descripción en imperativo
+```
+
+Tipos:
+
+```txt
+feat | fix | test | refactor | docs | chore | perf | ci
+```
+
+## Prohibido commitear
+
+- `.env`
+- secrets
+- tokens
+- `console.log`
+- `debugger`
+- código comentado innecesario
+- archivos no relacionados
+- cambios de formato mezclados con lógica sin razón

package/repo-template/docs/ai/governance.md

@@ -0,0 +1,61 @@
+# Governance
+
+## Objetivo
+
+Definir quién manda dentro del sistema agéntico.
+
+## Orden de autoridad
+
+```txt
+1. Instrucción explícita del usuario en la tarea actual
+2. AGENTS.md
+3. docs/ai/
+4. docs/skills/
+5. docs/specs/
+6. evals/
+7. adapter files
+8. model/provider preferences
+9. previous model outputs
+```
+
+## Principio
+
+```txt
+The repo governs.
+Adapters translate.
+Models execute.
+Humans approve impact.
+```
+
+## Ningún adapter gobierna
+
+No gobiernan:
+
+- `.opencode/`
+- `.cursor/`
+- `.codex/`
+- `.claude/`
+- `.pi/`
+- `.github/`
+- `.gentle-ai/`
+
+Todos deben apuntar al core universal.
+
+## Decisiones de alto impacto
+
+Requieren humano:
+
+- cambios de arquitectura
+- auth
+- pagos
+- datos persistentes
+- migraciones destructivas
+- seguridad
+- infraestructura
+- comportamiento IA productivo
+- cambios de costo significativo
+- automatizaciones autónomas
+
+## Escalación
+
+Si un modelo o adapter intenta aprobar impacto crítico, detener y reportar.

package/repo-template/docs/ai/harness.md

@@ -0,0 +1,49 @@
+# Agentic Engineering Harness
+
+## Objetivo
+
+Controlar la ejecución de agentes para que todo cambio sea especificado, probado, validado y revisable.
+
+## Modelo operativo
+
+```txt
+Input → Spec → Plan → Tests/Evals → Implementation → Validation → Review → Report
+```
+
+## Estados
+
+| Estado | Descripción | Salida esperada |
+|---|---|---|
+| INTAKE | Entender petición | Resumen de objetivo |
+| SPEC | Crear/actualizar spec | `.spec.md` |
+| PLAN | Diseñar pasos técnicos | Plan ejecutable |
+| TEST_FIRST | Crear tests/evals fallidos | Falla por razón correcta |
+| IMPLEMENT | Cambiar código | Diff limitado |
+| VALIDATE | Ejecutar pipeline | Lint/type/test/build/evals |
+| REVIEW | Revisión técnica | Issues clasificados |
+| APPROVAL | Esperar humano | Aprobado/cambios |
+| CHECKPOINT | Cierre | Resumen/commit propuesto |
+
+## Reglas de transición
+
+- No pasar de SPEC a IMPLEMENT sin plan.
+- No pasar de PLAN a IMPLEMENT en bugs sin regression test.
+- No pasar a CHECKPOINT si falla el pipeline.
+- Si falla validación, regresar a IMPLEMENT con evidencia.
+- Si hay cambio arquitectónico, activar Architect.
+- Si hay bug, activar Debugger.
+- Si falta cobertura, activar Test Engineer.
+- Si hay IA, activar Eval Engineer.
+
+## Límites
+
+El agente debe reportar antes de:
+
+- instalar dependencias
+- modificar CI/CD
+- modificar infraestructura
+- tocar `.env`
+- cambiar arquitectura
+- eliminar archivos
+- borrar tests
+- modificar datos persistentes

package/repo-template/docs/ai/installer-cli.md

@@ -0,0 +1,34 @@
+# Harness Installer CLI
+
+## Comandos objetivo
+
+```bash
+harness init --mode minimal|standard|enterprise
+harness sync
+harness doctor
+harness backup
+harness rollback --to <snapshot>
+harness parity-audit
+harness eval init
+harness ci init
+harness trust-policy init
+harness upgrade
+```
+
+## Reglas
+
+- dry-run por default en proyectos existentes
+- backup antes de modificar
+- no clobber de archivos existentes
+- merge idempotente
+- preservar cambios del usuario
+- reportar conflictos
+- detectar stack, package manager, test runner y CI existente
+
+## Estado
+
+```txt
+.harness/state.json
+.harness/snapshots/
+.harness/logs/
+```

package/repo-template/docs/ai/loop-log.md

@@ -0,0 +1,5 @@
+# Loop Log
+
+| Date | Loop | Spec/Task | Model | Iterations | Result | Notes |
+|---|---|---|---:|---:|---|---|
+| [DATE] | initial-harness-loop | harness setup | [MODEL] | 1 | created | Initial loop log |

package/repo-template/docs/ai/loop-observability.md

@@ -0,0 +1,57 @@
+# Loop Observability
+
+## Objetivo
+
+Registrar la ejecución de loops para auditar costo, calidad, fallos, escalación y aprendizaje.
+
+## Eventos mínimos
+
+Cada loop debe registrar:
+
+```txt
+loop_id
+loop_type
+task/spec
+model/provider
+started_at
+ended_at
+iterations
+files_changed
+tests_run
+evals_run
+failures
+repairs
+escalations
+final_status
+```
+
+## Métricas recomendadas
+
+| Métrica | Uso |
+|---|---|
+| iterations_per_task | detectar loops costosos |
+| repair_attempts | detectar fallos recurrentes |
+| test_failures_by_type | priorizar deuda técnica |
+| eval_regressions | detectar degradación IA |
+| model_cost_estimate | controlar gasto |
+| files_changed | detectar scope creep |
+| escalation_rate | medir autonomía segura |
+| rollback_rate | medir calidad del loop |
+
+## Logs recomendados
+
+```txt
+docs/ai/loop-log.md
+```
+
+## Engram
+
+Engram puede indexar resultados de loops, fallos recurrentes, decisiones, aprendizajes y cambios de prompts/evals.
+
+## Graphify
+
+Graphify puede mapear archivos tocados por loop, módulos afectados, dependencias impactadas y relación spec → code → tests → evals.
+
+## Regla
+
+La observabilidad del loop no reemplaza tests/evals. Solo ayuda a entender y mejorar el sistema.