ARNES Framework (agnóstico) — Diseño v0.1

Framework para construir aplicaciones con agentes autónomos, con control estricto de calidad, seguridad y trazabilidad. Compatible por diseño con pi.dev y opencode mediante adaptadores.

---

Objetivo

Permitir que agentes implementen features de forma autónoma sin perder control:

• una feature a la vez
• evidencia en disco (no en chat)
• gates obligatorios de revisión, seguridad y QA
• cierre solo con validación completa

---

Principios

1. Vendor-neutral: núcleo independiente de herramienta.
2. Estado persistente: todo vive en archivos versionables.
3. No confianza ciega: “funciona” debe demostrarse con evidencia ejecutable.
4. Separación de roles: quien implementa no aprueba.
5. Anti-trampa por diseño: no se puede marcar done saltando gates.

---

Matriz de agentes (6)

1. leader

   • Orquesta etapas y handoffs.
   • No implementa código de producto.

2. architect

   • Define/ajusta diseño técnico y contratos.
   • Puede editar documentación y diseño.

3. implementer

   • Implementa una sola feature + tests.
   • No puede aprobar ni cerrar.

4. reviewer

   • Revisión técnica vs arquitectura/convenios.
   • No edita código, solo aprueba/rechaza.

5. security

   • Gate de seguridad: secretos, dependencias, SAST básico, hardening checks.
   • No edita código.

6. qa

   • Gate de calidad funcional: aceptación, integración/E2E, regresión.
   • No edita código.

---

Flujo de trabajo (pipeline)

1. intake (leader)
2. design (architect)
3. build (implementer)
4. review_gate (reviewer) ✅
5. security_gate (security) ✅
6. qa_gate (qa) ✅
7. close (leader)

Regla: no hay done si cualquier gate falla.

---

Anti-trampa (control estricto)

Reglas de autorización

• Solo leader puede mover in_progress -> done.
• implementer no puede editar archivos de estado final de cierre.
• reviewer/security/qa no pueden editar código de producto.

Evidencia obligatoria por etapa

Cada agente escribe artefactos en disco:

• work/artifacts/<feature>/implementer.md
• work/artifacts/<feature>/reviewer.md
• work/artifacts/<feature>/security.md
• work/artifacts/<feature>/qa.md

Respuesta de agente siempre: done -> <ruta> o blocked -> <ruta>.

Gates ejecutados fuera del agente

• Verificación disparada por harness/scripts (no por “declaración” del agente).
• Si gate falla, estado vuelve a blocked o permanece in_progress.

Trazabilidad y auditoría

• work/history.md append-only.
• Checklist de cierre firmado por etapa (aprobado/rechazado + evidencia).
• Cualquier missing evidence = cierre denegado.

---

Estructura propuesta

.
├── README.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── policies/
│   │   ├── security.md
│   │   ├── quality.md
│   │   └── governance.md
│   └── contracts/
│       ├── handoff.md
│       └── evidence.schema.json
├── spec/
│   ├── product.md
│   ├── tech.md
│   └── acceptance.md
├── backlog/
│   └── features.json
├── work/
│   ├── current.md
│   ├── history.md
│   └── artifacts/
└── scripts/
    └── verify.sh

---

Manejo de pérdidas de memoria (context loss)

Sí: el framework está diseñado para eso.

Mecanismos:

1. Estado en disco (work/current.md, backlog/features.json).
2. Bitácora append-only (work/history.md).
3. Handoffs explícitos por archivo, no por chat.
4. Protocolo de reentrada al iniciar sesión:
   • leer work/current.md
   • leer feature activa
   • ejecutar verificación base
   • continuar desde “próximo paso”

Si se pierde contexto del modelo, el sistema se puede reconstruir desde archivos.

---

Adaptadores de plataforma

• platforms/pi/: prompts, hooks, permisos, comandos compatibles con pi.dev.
• platforms/opencode/: prompts, hooks, permisos, comandos compatibles con opencode.

El núcleo no cambia; solo el adaptador.

---

Criterios de éxito del framework

• No se puede cerrar una feature sin 3 gates en verde (review/security/qa).
• Evidencia completa y auditable por feature.
• Reentrada robusta tras reinicio o pérdida de contexto.
• Portabilidad entre pi.dev y opencode sin rediseñar el núcleo.

---

Próximos pasos sugeridos

1. Definir agents.matrix.yml completo (permisos exactos por rutas).
2. Definir workflow.stages.yml con transiciones válidas.
3. Diseñar features.json con estados y criterios de aceptación.
4. Especificar scripts/verify.sh (lint/test/security/qa gates).
5. Crear adaptadores platforms/pi y platforms/opencode.