# 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//implementer.md` - `work/artifacts//reviewer.json` - `work/artifacts//security.json` - `work/artifacts//qa.json` - `work/artifacts//leader-close.json` - `work/artifacts//publish.json` Respuesta de agente siempre: `done -> ` o `blocked -> `. ### 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 ```text . ├── 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.