@kal-elsam/kairo-runtime 0.1.0

package/repo-template/docs/ai/spec-driven-development.md

@@ -0,0 +1,124 @@
+# Spec-Driven Development
+
+## Cuándo crear una spec
+
+Crear spec para:
+
+- nueva feature
+- cambio de flujo
+- endpoint nuevo
+- integración externa
+- cambio de modelo de datos
+- refactor estructural
+- automatización agéntica
+- prompt/agente de producción
+
+No es obligatorio para cambios triviales de copy, estilos menores o fixes pequeños, salvo riesgo alto.
+
+## Ubicación
+
+```txt
+docs/specs/<feature-name>.spec.md
+```
+
+## Plantilla
+
+```md
+# Spec: [Nombre]
+
+## Objetivo
+
+## Contexto
+
+## Alcance
+
+## No alcance
+
+## Criterios de aceptación
+
+- [ ] Comportamiento observable
+- [ ] Caso de error
+- [ ] Validación técnica
+
+## Diseño técnico
+
+### Capas afectadas
+
+- UI:
+- API:
+- DB:
+- Servicios:
+- Jobs:
+- Agentes:
+- Evals:
+
+### Contratos
+
+#### Request
+
+```json
+{}
+```
+
+#### Response
+
+```json
+{}
+```
+
+## Estados y errores
+
+| Caso | Resultado esperado |
+|---|---|
+| Happy path | |
+| Error externo | |
+| Input inválido | |
+| Sin permisos | |
+
+## Testing
+
+- Unit:
+- Integration:
+- E2E:
+- Regression:
+
+## Evals
+
+- Dataset:
+- Prompt regression:
+- Tool calling:
+- Safety:
+
+## Riesgos
+
+## Plan de implementación
+```
+
+## Reglas
+
+- La spec debe ser suficientemente clara para que otro agente implemente.
+- Los criterios de aceptación deben convertirse en tests/evals.
+- Si cambia la implementación, actualizar la spec.
+- Si la spec contradice arquitectura, resolver antes de codificar.
+
+## Spec sizing requirement
+
+Before writing a spec, classify it as:
+
+```txt
+basic
+standard
+complex
+```
+
+Use:
+
+```txt
+docs/ai/spec-sizing.md
+docs/specs/templates/basic-spec.md
+docs/specs/templates/standard-spec.md
+docs/specs/templates/complex-spec.md
+```
+
+Do not force complex SDD on tiny safe tasks.
+Do not use basic specs for high-risk or high-ambiguity tasks.

package/repo-template/docs/ai/spec-escalation.md

@@ -0,0 +1,44 @@
+# Spec Escalation
+
+## Objective
+
+Define when to upgrade a spec level during work.
+
+## Upgrade from basic to standard when
+
+- more than 3 files are affected
+- behavior is broader than expected
+- tests require integration setup
+- state management is touched
+- API contract is touched
+- ambiguity appears
+- the agent needs to make design choices
+
+## Upgrade from standard to complex when
+
+- architecture boundaries are touched
+- auth/security/privacy appears
+- database migration appears
+- production AI behavior appears
+- a new vendor/tool/MCP appears
+- rollback becomes hard
+- multiple systems/services are affected
+- failure modes are not obvious
+- human approval becomes necessary
+
+## Stop conditions
+
+Stop implementation and escalate if:
+
+```txt
+The current spec level no longer matches risk.
+The agent is making architecture decisions not captured in the spec.
+The implementation requires changing the original scope.
+The task touches hard-trigger areas.
+```
+
+## Downgrade
+
+Downgrading requires explicit review.
+
+Do not silently downgrade from complex to standard/basic.

package/repo-template/docs/ai/spec-intake.md

@@ -0,0 +1,46 @@
+# Spec Intake
+
+## Objective
+
+Capture enough information to classify and start the right level of spec.
+
+## Intake questions
+
+Ask or infer:
+
+```txt
+What is the requested change?
+What problem does it solve?
+Who is affected?
+What files/modules are likely affected?
+Does it touch UI, API, DB, auth, infra, AI, tools or payments?
+Is there existing behavior to preserve?
+How will success be validated?
+What could break?
+How easy is rollback?
+```
+
+## Intake output
+
+Every feature/task starts with:
+
+```txt
+Spec level:
+Reason:
+Hard triggers:
+Ambiguity:
+Blast radius:
+Validation needed:
+Human approval needed:
+Next action:
+```
+
+## Avoid over-questioning
+
+If the task is simple and low-risk, infer missing details and create a basic spec.
+
+If the task is high-risk, stop and require more explicit scope or human approval.
+
+## Classification first
+
+Do not implement before classifying the spec level.

package/repo-template/docs/ai/spec-sizing.md

@@ -0,0 +1,207 @@
+# Spec Sizing
+
+## Objective
+
+Classify the required depth of a spec before implementation.
+
+The goal is to avoid two failure modes:
+
+```txt
+Over-specification: wasting time with complex SDD for tiny tasks.
+Under-specification: allowing risky work to proceed with vague instructions.
+```
+
+## Spec levels
+
+```txt
+basic
+standard
+complex
+```
+
+## Basic spec
+
+Use for low-risk, well-understood, localized work.
+
+Examples:
+
+- small UI copy change
+- styling adjustment
+- small isolated component behavior
+- simple bug with clear reproduction
+- simple utility function
+- small test addition
+- documentation update
+
+Allowed when:
+
+- no architecture change
+- no API contract change
+- no database change
+- no auth/security change
+- no payment/billing change
+- no AI behavior change
+- no production migration
+- low ambiguity
+- low blast radius
+
+Required sections:
+
+```txt
+Goal
+Scope
+Files likely affected
+Acceptance criteria
+Validation
+```
+
+## Standard spec
+
+Use for normal product/engineering work.
+
+Examples:
+
+- new frontend feature
+- new form or workflow
+- API endpoint without critical data impact
+- integration with existing service
+- non-critical refactor
+- medium bug spanning multiple files
+- state management change
+- component library change
+
+Allowed when:
+
+- moderate ambiguity
+- moderate number of files
+- test strategy needed
+- contracts may be touched but not critical
+- rollback is straightforward
+
+Required sections:
+
+```txt
+Problem
+Goal
+Non-goals
+User flow / system flow
+Scope
+Technical plan
+Acceptance criteria
+Test plan
+Risks
+Rollback
+```
+
+## Complex spec
+
+Use for high-risk, ambiguous or architectural work.
+
+Examples:
+
+- architecture changes
+- auth/authorization/session changes
+- payments/billing
+- database schema or migrations
+- production AI behavior
+- agent/tool/MCP permissions
+- security-sensitive logic
+- infrastructure/deployment changes
+- cross-service workflows
+- large refactors
+- multi-agent orchestration
+- data consistency changes
+- irreversible or hard-to-rollback changes
+
+Required sections:
+
+```txt
+Context
+Problem
+Goals
+Non-goals
+Stakeholders
+System boundaries
+Current architecture
+Proposed architecture
+Alternatives considered
+Decision / ADR link
+Data model / contracts
+Failure modes
+Security/privacy review
+Test strategy
+Eval strategy if AI-related
+Migration plan
+Observability
+Rollback plan
+Rollout plan
+Risk register
+Human approvals
+Acceptance criteria
+Implementation phases
+```
+
+## Complexity scoring
+
+Score each dimension from 0 to 2.
+
+| Dimension | 0 | 1 | 2 |
+|---|---|---|---|
+| Ambiguity | clear | some unknowns | unclear/open-ended |
+| Blast radius | 1 file/module | multiple modules | cross-system |
+| Architecture impact | none | local pattern | system boundary/design |
+| Data impact | none | non-critical data | persistent/critical data |
+| Security/privacy | none | minor | auth/secrets/privacy |
+| AI behavior | none | prompt-only/internal | production behavior/tools |
+| Testability | simple | needs integration | needs evals/E2E/contracts |
+| Rollback | trivial | moderate | hard/destructive |
+| Dependency impact | none | minor package | new service/vendor/MCP |
+| User impact | invisible/internal | normal UX | critical flow/revenue |
+
+## Decision
+
+```txt
+0-3 points    -> basic spec
+4-9 points    -> standard spec
+10+ points    -> complex spec
+Any hard trigger -> complex spec
+```
+
+## Hard triggers for complex spec
+
+Always complex if the task touches:
+
+- auth
+- authorization
+- payments
+- billing
+- secrets
+- production database migration
+- destructive data changes
+- infrastructure
+- CI/CD release gates
+- production AI behavior
+- MCP/tool permissions
+- cross-service contracts
+- architecture boundaries
+- compliance/legal/privacy
+- anything difficult to rollback
+
+## Escalation
+
+A spec can be upgraded at any time.
+
+```txt
+basic -> standard
+standard -> complex
+```
+
+A spec can be downgraded only after review.
+
+## Rule
+
+```txt
+Start with the smallest safe spec.
+Escalate as soon as risk or ambiguity increases.
+Never use a basic spec for critical work.
+```

package/repo-template/docs/ai/test-driven-development.md

@@ -0,0 +1,35 @@
+# Test-Driven Development
+
+## Regla central
+
+Antes de implementar cambios de comportamiento, escribir el test que define el comportamiento esperado.
+
+## Por tipo de tarea
+
+| Tarea | Test obligatorio |
+|---|---|
+| Función nueva | Unit test |
+| Bug fix | Regression test que falla primero |
+| Endpoint nuevo | Integration test happy path + errores |
+| Flujo de usuario | E2E test |
+| Refactor | Tests existentes deben seguir pasando |
+| Cambio IA | Eval o prompt regression |
+
+## Proceso
+
+```txt
+1. Identificar comportamiento esperado
+2. Escribir test/eval que falla
+3. Confirmar que falla por la razón correcta
+4. Implementar mínimo necesario
+5. Ejecutar test/eval
+6. Ejecutar suite completa
+7. Refactorizar si aplica
+```
+
+## Prohibiciones
+
+- No mockear lógica de negocio propia.
+- No borrar tests para hacer pasar el pipeline.
+- No cambiar assertions para ocultar un bug.
+- No usar snapshots como sustituto de comportamiento crítico.

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

@@ -0,0 +1,28 @@
+# Estrategia de testing
+
+## Estado actual
+
+- Tests configurados: [TESTING_EXISTS]
+- Herramientas detectadas: [TESTING_TOOLS]
+- Herramientas propuestas: [TESTING_PROPOSED]
+- Comando: [TEST_COMMAND]
+- Cobertura mínima recomendada: 80% líneas y branches
+
+## Por tipo de tarea
+
+| Tarea | Test requerido |
+|---|---|
+| Función nueva | Unit |
+| Endpoint nuevo | Integration |
+| Bug fix | Regression |
+| Flujo UI | E2E |
+| Refactor | Suite existente verde |
+| Cambio IA | Eval/prompt regression |
+
+## Reglas
+
+- Factories en `tests/factories/` si aplica.
+- Mocks solo para dependencias externas.
+- Regression test antes del fix.
+- No borrar tests sin justificación.
+- No cambiar assertions para ocultar bugs.

package/repo-template/docs/ai/tool-adapters.md

@@ -0,0 +1,186 @@
+# Tool Adapters
+
+## Objetivo
+
+Definir cómo cada herramienta consume el core harness sin duplicar reglas.
+
+## Constitución común
+
+Todo adapter — Cursor, Codex, Claude, Gemini, GitHub Copilot, OpenCode, Gentle AI, Pi — lee `AGENTS.md` primero, antes de cualquier archivo específico del adapter.
+
+```txt
+AGENTS.md is the constitution.
+Adapter files are translations, never replacements.
+If an adapter file and AGENTS.md disagree, AGENTS.md wins.
+```
+
+Ningún adapter puede:
+
+- Declarar una regla que no exista en `AGENTS.md` o `docs/ai/` como si fuera gobernanza propia.
+- Saltarse SDD, TDD, evals o aprobación humana porque su formato nativo no lo soporta bien.
+- Tratar su propia sintaxis, rules, skills o prompts, como más autoritativa que el core.
+
+## Core universal
+
+La fuente principal siempre es:
+
+```txt
+AGENTS.md
+docs/ai/
+docs/skills/
+docs/specs/
+evals/
+```
+
+## Cursor adapter
+
+Rutas:
+
+```txt
+.cursor/rules/
+.cursor/commands/
+.cursor/agents/
+.cursor/skills/
+```
+
+Uso:
+
+- reglas persistentes
+- comandos de workflow
+- subagentes especializados
+- skills nativas de Cursor
+
+No debe contradecir `AGENTS.md`.
+
+## Codex adapter
+
+Rutas:
+
+```txt
+AGENTS.md
+.codex/skills/
+```
+
+Uso:
+
+- Codex App
+- Codex CLI
+- skills reutilizables para SDD/TDD/evals/checkpoint
+
+Codex debe leer `AGENTS.md` como fuente universal.
+
+## Claude adapter
+
+Rutas:
+
+```txt
+CLAUDE.md
+.claude/agents/
+.claude/skills/
+.claude/commands/
+```
+
+Uso:
+
+- subagentes de arquitectura/review/debugging
+- skills de workflow
+- comandos reutilizables
+
+`CLAUDE.md` debe ser puntero delgado salvo necesidad explícita.
+
+## Gemini adapter
+
+Rutas:
+
+```txt
+GEMINI.md
+.gemini/
+```
+
+Uso:
+
+- puntero delgado a `AGENTS.md`
+- comandos o contexto específico si la herramienta lo requiere
+
+## GitHub Copilot adapter
+
+Rutas:
+
+```txt
+.github/copilot-instructions.md
+.github/instructions/
+```
+
+Uso:
+
+- instrucciones compactas
+- no duplicar reglas largas
+- apuntar al core
+
+## Gentle AI adapter
+
+Gentle AI usa el core como fuente de verdad y puede ejecutar:
+
+```bash
+/sdd-init
+gentle-ai skill-registry refresh
+gentle-ai doctor
+```
+
+Debe alinearse con:
+
+```txt
+docs/ai/spec-driven-development.md
+docs/ai/test-driven-development.md
+docs/ai/evals.md
+docs/skills/
+```
+
+## Engram / Graphify adapter
+
+- Engram indexa memoria y decisiones.
+- Graphify indexa grafo contextual.
+- Ninguno reemplaza el repo.
+- Si hay contradicción, gana el repo.
+
+## OpenCode adapter
+
+Rutas:
+
+```txt
+.opencode/
+.opencode/agents/
+.opencode/loops/
+opencode.json.sample
+```
+
+Uso:
+
+- runtime principal CLI
+- ejecución con Gentle AI + DeepSeek
+- agentes por proyecto
+- loops acotados
+- plan/build separation
+- escalación por permisos y límites de pasos
+
+Reglas:
+
+- OpenCode ejecuta, pero `AGENTS.md` gobierna.
+- `Plan` debe preferirse para análisis sin cambios.
+- `Build` puede implementar con permisos controlados.
+- Subagentes se invocan con `@agent-name`.
+- Loops deben respetar `docs/ai/loop-policy.md`.
+
+## Adapter parity rule
+
+No adapter is primary by authority.
+
+```txt
+OpenCode can be primary by workflow preference.
+Cursor can be primary by IDE preference.
+Codex can be primary by task execution.
+Claude can be primary by reasoning task.
+But AGENTS.md remains governance-primary.
+```
+
+Read `docs/ai/adapter-parity.md` before adding or changing adapters.

package/repo-template/docs/ai/trust-allowlist.md

@@ -0,0 +1,5 @@
+# Trust Allowlist
+
+| Name | Type | Source | Version/Ref | Permissions | Reviewer | Date | Notes |
+|---|---|---|---|---|---|---|---|
+| local-harness-core | docs/skills | repo-local | current | read/write repo docs | owner | YYYY-MM-DD | Core harness skills |

package/repo-template/docs/ai/trust-policy.md

@@ -0,0 +1,41 @@
+# Trust Policy for Skills, Tools and Packages
+
+## Regla central
+
+```txt
+No untrusted skill, tool, package or MCP server may run with write, network or shell permissions.
+```
+
+## Trust levels
+
+| Trust level | Descripción | Permisos |
+|---|---|---|
+| trusted-local | creado y revisado por el equipo | mínimo necesario |
+| trusted-vendored | congelado en repo con revisión | mínimo necesario |
+| trusted-official | fuente oficial verificada | mínimo necesario |
+| experimental | probado en sandbox | read-only por default |
+| untrusted | no revisado | deny |
+
+## Deny by default
+
+Bloquear por defecto:
+
+- scripts descargados dinámicamente
+- paquetes no fijados
+- skills con instrucciones ocultas
+- skills con shell/network sin justificación
+- tools que modifiquen auth/secrets/infra
+- MCPs no revisados
+- prompts que pidan ignorar AGENTS.md
+
+## Review checklist
+
+- [ ] objetivo claro
+- [ ] no contiene instrucciones ocultas
+- [ ] no pide exfiltrar información
+- [ ] no pide ignorar políticas
+- [ ] no ejecuta shell sin permiso
+- [ ] no accede a red sin permiso
+- [ ] permisos mínimos
+- [ ] versión/ref fija
+- [ ] reviewer humano