@kal-elsam/kairo-runtime 0.1.0

package/repo-template/.opencode/loops/ai-behavior-improvement.loop.md

@@ -0,0 +1,15 @@
+# Loop: AI Behavior Improvement
+
+## Input
+
+Failed eval, bad conversation, human feedback or production issue.
+
+## Cycle
+
+1. Classify failure.
+2. Identify prompt/tool/context/memory issue.
+3. Propose minimal change.
+4. Run relevant eval.
+5. Compare baseline.
+6. Accept/revert.
+7. Log learning.

package/repo-template/.opencode/loops/bug-repair.loop.md

@@ -0,0 +1,16 @@
+# Loop: Bug Repair
+
+## Input
+
+Bug report or failing test.
+
+## Cycle
+
+1. Reproduce bug.
+2. Isolate cause.
+3. Write regression test.
+4. Apply minimal fix.
+5. Run regression test.
+6. Repair up to 3 attempts.
+7. Run related suite.
+8. Document root cause.

package/repo-template/.opencode/loops/documentation-sync.loop.md

@@ -0,0 +1,13 @@
+# Loop: Documentation Sync
+
+## Input
+
+Code/spec/architecture change.
+
+## Cycle
+
+1. Detect stale docs.
+2. Update relevant docs.
+3. Check contradictions.
+4. Update decision log.
+5. Update Graphify/Engram notes if applicable.

package/repo-template/.opencode/loops/feature-development.loop.md

@@ -0,0 +1,25 @@
+# Loop: Feature Development
+
+## Input
+
+Approved spec in `docs/specs/`.
+
+## Cycle
+
+1. Select next task.
+2. Write failing test.
+3. Implement minimum change.
+4. Run related test.
+5. Repair up to 3 attempts.
+6. Run lint/typecheck/build if configured.
+7. Run evals if AI behavior changed.
+8. Review diff.
+9. Checkpoint.
+
+## Exit criteria
+
+- Tests pass.
+- Evals pass if applicable.
+- No critical review issues.
+- No scope creep.
+- Human approval if high impact.

package/repo-template/.opencode/skills/spec-complexity-classifier/SKILL.md

@@ -0,0 +1,10 @@
+# spec-complexity-classifier
+
+Read and follow:
+
+```txt
+docs/skills/spec-complexity-classifier.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.opencode/skills/spec-escalation-review/SKILL.md

@@ -0,0 +1,10 @@
+# spec-escalation-review
+
+Read and follow:
+
+```txt
+docs/skills/spec-escalation-review.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.opencode/skills/spec-intake/SKILL.md

@@ -0,0 +1,10 @@
+# spec-intake
+
+Read and follow:
+
+```txt
+docs/skills/spec-intake.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.pi/README.md

@@ -0,0 +1,21 @@
+# Pi Adapter
+
+Pi is an optional CLI adapter.
+
+It is not governance-primary.
+
+## Source of truth
+
+- `AGENTS.md`
+- `docs/ai/`
+- `docs/skills/`
+- `docs/specs/`
+- `evals/`
+
+## Use
+
+Use Pi prompt templates and skills to execute the same SDD/TDD/evals/checkpoint workflows from terminal.
+
+## Rule
+
+If Pi instructions conflict with the universal core, the core wins.

package/repo-template/.pi/prompts/checkpoint.md

@@ -0,0 +1,11 @@
+# /checkpoint
+
+Run the checkpoint workflow.
+
+Read:
+
+- `AGENTS.md`
+- `docs/ai/git-workflow.md`
+- `docs/ai/harness.md`
+
+Review diff, run validation, report risks and do not commit without approval.

package/repo-template/.pi/prompts/loop-run.md

@@ -0,0 +1,10 @@
+# /loop-run
+
+Run a bounded loop.
+
+Read:
+
+- `docs/ai/loops.md`
+- `docs/ai/loop-policy.md`
+
+Define max attempts, validation and escalation before iterating.

package/repo-template/.pi/prompts/sdd-plan.md

@@ -0,0 +1,11 @@
+# /sdd-plan
+
+Create technical plan from an approved spec.
+
+Read:
+
+- `AGENTS.md`
+- `docs/ai/architecture.md`
+- `docs/specs/<feature-name>.spec.md`
+
+Do not implement code yet.

package/repo-template/.pi/prompts/sdd-spec.md

@@ -0,0 +1,13 @@
+# /sdd-spec
+
+Use the SDD workflow.
+
+Read:
+
+- `AGENTS.md`
+- `docs/ai/harness.md`
+- `docs/ai/spec-driven-development.md`
+
+Create or update `docs/specs/<feature-name>.spec.md`.
+
+Do not implement code yet.

package/repo-template/.pi/prompts/spec-escalate.md

@@ -0,0 +1,9 @@
+# spec-escalate
+
+Review whether the current spec must be upgraded.
+
+Read:
+
+- `docs/skills/spec-escalation-review.md`
+
+Stop implementation if risk exceeds the current spec level.

package/repo-template/.pi/prompts/spec-intake.md

@@ -0,0 +1,10 @@
+# spec-intake
+
+Run spec intake and create the right spec template.
+
+Read:
+
+- `docs/skills/spec-intake.md`
+- `docs/skills/spec-complexity-classifier.md`
+
+Do not implement yet.

package/repo-template/.pi/prompts/spec-size.md

@@ -0,0 +1,21 @@
+# spec-size
+
+Classify the requested task as basic, standard or complex.
+
+Read:
+
+- `docs/ai/spec-sizing.md`
+- `docs/ai/spec-intake.md`
+- `docs/ai/spec-escalation.md`
+
+Return:
+
+```txt
+Spec level:
+Score:
+Hard triggers:
+Reason:
+Template:
+Validation:
+Approval:
+```

package/repo-template/.pi/skills/adapter-parity/SKILL.md

@@ -0,0 +1,7 @@
+# adapter-parity Skill
+
+Use to verify adapter parity. Source: docs/ai/adapter-parity.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/checkpoint/SKILL.md

@@ -0,0 +1,7 @@
+# checkpoint Skill
+
+Use for checkpoint validation. Source: AGENTS.md and docs/ai/git-workflow.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/eval-design/SKILL.md

@@ -0,0 +1,3 @@
+# eval-design
+
+Read and follow `docs/skills/eval-design.md`. The universal core governs this adapter skill.

package/repo-template/.pi/skills/evals/SKILL.md

@@ -0,0 +1,7 @@
+# evals Skill
+
+Use for AI evals. Source: AGENTS.md and docs/ai/evals.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/loop-engineering/SKILL.md

@@ -0,0 +1,7 @@
+# loop-engineering Skill
+
+Use for bounded loops. Source: AGENTS.md and docs/ai/loops.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/maintainability-review/SKILL.md

@@ -0,0 +1,3 @@
+# maintainability-review
+
+Read and follow `docs/skills/maintainability-review.md`. The universal core governs this adapter skill.

package/repo-template/.pi/skills/quality-gate-review/SKILL.md

@@ -0,0 +1,3 @@
+# quality-gate-review
+
+Read and follow `docs/skills/quality-gate-review.md`. The universal core governs this adapter skill.

package/repo-template/.pi/skills/sdd/SKILL.md

@@ -0,0 +1,7 @@
+# sdd Skill
+
+Use for Spec-Driven Development. Source: AGENTS.md and docs/ai/spec-driven-development.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/spec-complexity-classifier/SKILL.md

@@ -0,0 +1,10 @@
+# spec-complexity-classifier
+
+Read and follow:
+
+```txt
+docs/skills/spec-complexity-classifier.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.pi/skills/spec-escalation-review/SKILL.md

@@ -0,0 +1,10 @@
+# spec-escalation-review
+
+Read and follow:
+
+```txt
+docs/skills/spec-escalation-review.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.pi/skills/spec-intake/SKILL.md

@@ -0,0 +1,10 @@
+# spec-intake
+
+Read and follow:
+
+```txt
+docs/skills/spec-intake.md
+```
+
+Use the universal core as source of truth.
+Do not implement before classifying the spec level.

package/repo-template/.pi/skills/tdd/SKILL.md

@@ -0,0 +1,7 @@
+# tdd Skill
+
+Use for Test-Driven Development. Source: AGENTS.md and docs/ai/test-driven-development.md.
+
+## Rule
+
+This is an adapter skill. The universal core wins.

package/repo-template/.pi/skills/trust-review/SKILL.md

@@ -0,0 +1,3 @@
+# trust-review
+
+Read and follow `docs/skills/trust-review.md`. The universal core governs this adapter skill.

package/repo-template/AGENT.md

@@ -0,0 +1,8 @@
+Este archivo es un puntero de compatibilidad.
+
+Fuente universal: `AGENTS.md`.  
+Fuente técnica: `docs/ai/`.  
+Skills operativos: `docs/skills/`.
+
+No agregues reglas largas aquí.  
+Actualiza la fuente correspondiente.

package/repo-template/AGENTS.md

@@ -0,0 +1,165 @@
+# AGENTS.md
+
+> Fuente universal para agentes de IA trabajando en este proyecto.
+
+## Proyecto
+
+- **Nombre:** [PROJECT_NAME]
+- **Propósito:** [PROJECT_PURPOSE]
+- **Stack:** [STACK]
+- **Package manager:** [PACKAGE_MANAGER]
+- **Arquitectura detectada:** [ARCHITECTURE_PATTERN]
+
+## Primera ley
+
+La fuente de verdad siempre gana sobre el instinto, la memoria externa o la conveniencia del adapter.
+
+Antes de escribir código:
+
+1. Leer este archivo.
+2. Leer el documento relevante en `docs/ai/` (ver `docs/ai/context-budget.md`).
+3. Seguir `docs/ai/harness.md`.
+4. Usar SDD para cambios significativos (`docs/ai/spec-driven-development.md`).
+5. Usar TDD para cambios de comportamiento (`docs/ai/test-driven-development.md`).
+6. Usar evals para comportamiento IA (`docs/ai/evals.md`).
+7. Si falta documentación, crearla o actualizarla antes de implementar.
+
+## Context budget
+
+No leas toda la documentación por defecto.
+
+Siempre leer:
+
+```txt
+AGENTS.md
+docs/ai/harness.md
+```
+
+Lectura por tarea: `docs/ai/context-budget.md`
+
+## Harness obligatorio
+
+Todo cambio no trivial sigue:
+
+```txt
+Requirement → Spec → Plan → Tests failing first → Implementation → Validation → Review → Human approval
+```
+
+Detalle: `docs/ai/harness.md`
+
+## Comandos
+
+```bash
+# Install
+[INSTALL_COMMAND]
+
+# Dev
+[DEV_COMMAND]
+
+# Lint
+[LINT_COMMAND]
+
+# Format
+[FORMAT_COMMAND]
+
+# Type check
+[TYPE_CHECK_COMMAND]
+
+# Test
+[TEST_COMMAND]
+
+# Build
+[BUILD_COMMAND]
+```
+
+## Pipeline pre-commit
+
+Seguir `docs/ai/git-workflow.md`. No commitear si el pipeline falla.
+
+## Límites absolutos
+
+- No instalar dependencias sin confirmación explícita.
+- No modificar `.env`, CI/CD, infra o deploy sin avisar.
+- No borrar tests sin justificación.
+- No crear patrones nuevos sin documentarlos.
+- No mezclar lógica de negocio con UI.
+- No hacer llamadas directas desde UI a servicios externos si existe capa de abstracción.
+- No declarar éxito parcial como éxito total.
+
+## Engram / Graphify
+
+- Engram indexa memoria y decisiones (`docs/ai/memory.md`).
+- Graphify mapea arquitectura y riesgos (`docs/ai/context-graph.md`).
+- Si memoria o grafo contradice el repo, el repo gana.
+- Decisiones importantes en `docs/ai/decision-log.md` o ADR.
+
+## Universal-first adapters
+
+Este repo no depende de una sola herramienta.
+
+```txt
+Core:     AGENTS.md, docs/ai/, docs/skills/, docs/specs/, evals/
+Adapters: .cursor/, .codex/, .claude/, .github/, .gemini/, .gentle-ai/, .opencode/, .pi/, CLAUDE.md, GEMINI.md
+```
+
+Todo adapter lee `AGENTS.md` primero, como constitución común, antes de cualquier archivo propio. Si un adapter contradice `AGENTS.md`, gana `AGENTS.md`.
+
+Leer: `docs/ai/tool-adapters.md`, `docs/ai/adapter-parity.md`, `docs/ai/governance.md`
+
+Si los adapters discrepan:
+
+```txt
+Current user instruction → AGENTS.md → docs/ai/ → docs/skills/ → adapter file → model output
+```
+
+## Temas avanzados
+
+Leer solo cuando aplique:
+
+| Tema | Documentos |
+|---|---|
+| Model routing | `docs/ai/model-policy.md`, `docs/ai/provider-routing.md` |
+| Loop engineering | `docs/ai/loops.md`, `docs/ai/loop-policy.md`, `docs/ai/loop-observability.md` |
+| Enforcement | `docs/ai/enforcement.md`, `docs/ai/quality-gates.md`, `docs/ai/trust-policy.md`, `docs/ai/eval-strategy.md`, `docs/ai/maintainability-gates.md` |
+| Spec sizing | `docs/ai/spec-sizing.md`, `docs/ai/spec-intake.md`, `docs/ai/spec-escalation.md` |
+| Gentle AI / OpenCode | `docs/ai/tool-adapters.md` |
+
+Reglas de loops (resumen):
+
+```txt
+No autonomous loop without boundaries.
+No repair loop without max attempts.
+No learning loop without evals.
+No production loop without observability.
+No critical loop without human approval.
+```
+
+Reglas de enforcement (resumen):
+
+```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.
+```
+
+## Fuente de verdad
+
+| Archivo | Propósito |
+|---|---|
+| `AGENTS.md` | Constitución universal |
+| `docs/ai/harness.md` | Flujo agéntico |
+| `docs/ai/architecture.md` | Arquitectura |
+| `docs/ai/conventions.md` | Convenciones |
+| `docs/ai/testing.md` | Testing |
+| `docs/ai/evals.md` | AI evals |
+| `docs/ai/spec-driven-development.md` | SDD |
+| `docs/ai/test-driven-development.md` | TDD |
+| `docs/ai/agent-workflow.md` | Roles y handoffs |
+| `docs/ai/memory.md` | Engram |
+| `docs/ai/context-graph.md` | Graphify |
+| `docs/skills/` | Procedimientos operativos |
+| `docs/specs/` | Specs vivas |
+
+## Regla final
+
+El agente puede proponer, implementar y validar, pero la decisión de impacto arquitectónico pertenece al humano.

package/repo-template/CLAUDE.md

@@ -0,0 +1,9 @@
+This file is a compatibility pointer.
+
+Universal source: `AGENTS.md`  
+Technical source: `docs/ai/`  
+Operational skills: `docs/skills/`  
+Specs: `docs/specs/`  
+Evals: `evals/`
+
+Do not add long rules here. Update the source files instead.

package/repo-template/GEMINI.md

@@ -0,0 +1,9 @@
+This file is a compatibility pointer.
+
+Universal source: `AGENTS.md`  
+Technical source: `docs/ai/`  
+Operational skills: `docs/skills/`  
+Specs: `docs/specs/`  
+Evals: `evals/`
+
+Do not add long rules here. Update the source files instead.

package/repo-template/docs/ai/adapter-parity.md

@@ -0,0 +1,135 @@
+# Adapter Parity
+
+## Objetivo
+
+Garantizar que el harness no dependa de una sola herramienta.
+
+OpenCode, Cursor, Codex, Claude, Gemini, Pi y otros agentes deben poder operar sobre el mismo core universal.
+
+## Regla principal
+
+```txt
+No adapter is primary by authority.
+An adapter can be primary only by workflow preference.
+The core universal remains the governance layer.
+```
+
+## Core universal
+
+La fuente real siempre es:
+
+```txt
+AGENTS.md
+docs/ai/
+docs/skills/
+docs/specs/
+evals/
+```
+
+## Adapters
+
+| Adapter | Rol | Autoridad |
+|---|---|---|
+| OpenCode | Runtime CLI, Gentle AI + DeepSeek, loops | No superior |
+| Cursor | IDE, edición interactiva, rules, commands, subagents | No superior |
+| Codex | Ejecución puntual, specs, tests, reviews, skills | No superior |
+| Claude | Reasoning fuerte, arquitectura, review, debugging complejo | No superior |
+| Gemini | Alternativa de reasoning/modelo | No superior |
+| Pi | CLI alternativo/harness experimental | No superior |
+| GitHub Copilot | Asistencia IDE/PR | No superior |
+
+## Capability parity matrix
+
+| Capability | OpenCode | Cursor | Codex | Claude | Pi |
+|---|---|---|---|---|---|
+| Leer core universal | `AGENTS.md` | `AGENTS.md` | `AGENTS.md` | `CLAUDE.md` pointer | `AGENTS.md` |
+| SDD | `.opencode/agents`, loops | `.cursor/commands`, subagents | `.codex/skills/sdd` | `.claude/skills/sdd` | `.pi/prompts/sdd-*` |
+| TDD | agents/loops | commands/rules | `.codex/skills/tdd` | `.claude/skills/tdd` | `.pi/skills/tdd` |
+| Evals | agents/loops | commands/rules | `.codex/skills/evals` | `.claude/skills/evals` | `.pi/skills/evals` |
+| Loop Engineering | `.opencode/loops` | `loop-*` commands | loop skill/prompt | loop skill/agent | prompt templates |
+| Checkpoint | checkpoint agent | `/checkpoint` | checkpoint skill | checkpoint skill | `/checkpoint` |
+| Model routing | model-router agent | docs/rules | skill/prompt | skill/prompt | model-routing skill |
+| Review | checkpoint/reviewer | `/review` | review prompt/skill | reviewer agent | `/review` |
+| Human approval | policy | policy | policy | policy | policy |
+
+## Adapter responsibilities
+
+Each adapter must:
+
+1. Read the universal core.
+2. Avoid duplicating long instructions.
+3. Avoid contradicting `AGENTS.md`.
+4. Support SDD/TDD/evals/checkpoint in its native way.
+5. Report limitations when it cannot support a capability.
+6. Escalate high-impact decisions.
+
+## When an adapter cannot implement a capability
+
+Use this fallback order:
+
+```txt
+1. Use AGENTS.md instruction directly.
+2. Use docs/skills/ procedure.
+3. Use natural-language prompt.
+4. Use another adapter.
+5. Ask human for approval.
+```
+
+## OpenCode positioning
+
+OpenCode may be the user's primary execution runtime.
+
+That means:
+
+```txt
+OpenCode is workflow-primary.
+OpenCode is not governance-primary.
+```
+
+## Cursor positioning
+
+Cursor may be the user's primary IDE.
+
+That means:
+
+```txt
+Cursor is IDE-primary.
+Cursor is not governance-primary.
+```
+
+## Codex positioning
+
+Codex may be used for focused implementation, reviews and remote/CLI tasks.
+
+That means:
+
+```txt
+Codex is execution/review-capable.
+Codex is not governance-primary.
+```
+
+## Claude positioning
+
+Claude may be used for strong reasoning.
+
+That means:
+
+```txt
+Claude is reasoning/review-strong.
+Claude is not governance-primary.
+```
+
+## Final rule
+
+If adapters disagree, do not choose the most convenient adapter.
+
+Apply precedence:
+
+```txt
+Current user instruction
+→ AGENTS.md
+→ docs/ai/
+→ docs/skills/
+→ adapter file
+→ model output
+```