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 (8)

1. leader

   • Orquesta etapas y handoffs.
   • Da órdenes internas en English caveman.

2. triager

   • Convierte requests en tickets claros.
   • Escribe tickets en English caveman.

3. architect

   • Define/ajusta diseño técnico y contratos.

4. implementer

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

5. reviewer

   • Gate técnico.

6. security

   • Gate de seguridad.

7. qa

   • Gate funcional.

8. documenter

   • Documenta fix/feature/bug y actualiza docs.

---

Flujo de trabajo (pipeline)

1. triage_translate (leader/triager)
2. intake (leader)
3. design (architect)
4. build (implementer)
5. review_gate (reviewer) ✅
6. security_gate (security) ✅
7. qa_gate (qa) ✅
8. documentation_gate (documenter) ✅
9. 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.json
• work/artifacts/<feature>/security.json
• work/artifacts/<feature>/qa.json
• work/artifacts/<feature>/leader-close.json

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

---

Estado runtime visible

• Estado en tiempo real: work/runtime-status.json
• CLI: python3 scripts/agent_status.py show|set|reset

Overlays por proyecto (sin contaminar el core)

• Reglas locales: AGENTS.local.md (opcional)
• Checks locales: scripts/verify.local.sh (opcional)
• El template base sigue agnóstico.

Lenguaje y modelos

• Política de lenguaje: harness/policies/language.md (English caveman interno)
• Routing de modelos: harness/models.profiles.yml
• Reglas de routing: harness/policies/model-routing.md

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.

---

Inicio rápido

• Ejecuta wizard: ./scripts/start.sh
• Crear ticket: python3 scripts/new_ticket.py
• Guía breve: HOWTO.md
• Starter pack: starter-pack/README.md
• Adaptación del template: TEMPLATE.md
• Manual Skeleton (uso + mejoras): docs/skeleton-manual.md

Próximos pasos sugeridos

1. Definir el backlog inicial del proyecto real.
2. Configurar overlay opcional (AGENTS.local.md, scripts/verify.local.sh).
3. Ejecutar ./scripts/verify.sh y python3 scripts/agent_status.py show.
4. Empezar la primera feature pending con pipeline completo.