3ff9b70e4c
- Add complete agent harness structure with 8 roles (leader, triager, architect, implementer, reviewer, security, qa, documenter) - Implement strict workflow with 9 stages and mandatory gates - Add comprehensive verification script and runtime status tracking - Create artifact-based evidence system with contracts and schemas - Add agent policy matrix with permissions and anti-cheat rules - Include test suite (44 tests passing) and CI-ready structure - Add documentation: README, HOWTO, CHECKPOINTS, templates - Configure model routing policies and token-aware task assignment - Add BDD/SDD specification guides and feature templates - Include starter pack for quick project onboarding All verification checks pass. Framework ready for production use.
202 lines
5.5 KiB
Markdown
202 lines
5.5 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.
|
|
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
|
|
|
|
```text
|
|
.
|
|
├── 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.
|