arnes/README.md

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

Framework para construir aplicaciones con agentes autónomos, con control estricto de calidad, seguridad y trazabilidad.

Convención recomendada: el código real del proyecto vive dentro de project/. Cada proyecto real debe vivir en su propio repo git, distinto del repo fuente de ARNES. 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)
10. publish (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
• work/artifacts/<feature>/publish.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

.
├── project/                 # código real del proyecto
│   └── README.md
├── README.md
├── AGENTS.md
├── CHECKPOINTS.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── models.profiles.yml
│   ├── policies/
│   └── contracts/
├── spec/
│   ├── product.md
│   ├── tech.md
│   ├── acceptance.md
│   ├── sdd/
│   └── bdd/
├── backlog/
│   └── features.json
├── work/
│   ├── current.md
│   ├── history.md
│   ├── runtime-status.json
│   └── artifacts/
├── scripts/
│   ├── start.sh
│   ├── new_ticket.py
│   ├── agent_status.py
│   └── verify.sh
├── defaults/
│   └── flask-skeleton/
└── platforms/

---

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

• Instalar ARNES en repo externo: ./scripts/install_into_repo.sh /path/to/project-repo
• Ejecuta wizard: ./scripts/start.sh
• Crear ticket: python3 scripts/new_ticket.py
• Publicar ticket: python3 scripts/publish_ticket.py --feature-id F-001
• Guía breve: HOWTO.md
• Starter pack: starter-pack/README.md
• Adaptación del template: TEMPLATE.md
• Índice de docs: docs/README.md
• Layout del repo: docs/repository-layout.md
• Referencia de scripts: docs/scripts-reference.md
• Manual Skeleton (uso + mejoras): docs/skeleton-manual.md

Tipos de tarea / ticket

python3 scripts/new_ticket.py soporta estos tipos:

• feature: nueva capacidad
• fix: corrección de comportamiento roto
• bug: incidencia reportada o defecto claro
• chore: trabajo interno, refactor, setup, mantenimiento

Además guarda campos estructurados:

• problem
• goal
• scope_in
• scope_out
• priority
• risk
• acceptance

Convención recomendada:

• usar feature para trabajo nuevo visible
• usar fix o bug para reparación
• usar chore para cambios internos sin valor funcional directo

Próximos pasos sugeridos

1. Instalar/copiar ARNES en un repo de proyecto real distinto del repo fuente.
2. Definir el backlog inicial del proyecto real.
3. Configurar overlay opcional (AGENTS.local.md, scripts/verify.local.sh).
4. Ejecutar ./scripts/verify.sh y python3 scripts/agent_status.py show.
5. Empezar la primera feature pending con pipeline completo y terminar con commit+push del ticket.