245 lines
6.9 KiB
Markdown
245 lines
6.9 KiB
Markdown
# 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
|
|
|
|
```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.
|