refactor: complete bootstrap of ARNES agent harness framework
- 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.
This commit is contained in:
rikrdo
167
HOWTO.md
167
HOWTO.md
@@ -1,145 +1,58 @@
|
||||
# HOWTO — Cómo usar ARNES Framework
|
||||
# HOWTO (breve) — iniciar ARNES en proyecto nuevo o ya empezado
|
||||
|
||||
Guía rápida para arrancar proyectos nuevos usando este framework.
|
||||
|
||||
---
|
||||
|
||||
## Fórmula base (siempre igual)
|
||||
|
||||
1. **Crear repo nuevo**
|
||||
2. **Copiar ARNES Framework dentro del repo**
|
||||
3. **Configurar spec + backlog**
|
||||
4. **Ejecutar verificación**
|
||||
5. **Empezar implementación por features (una a la vez)**
|
||||
|
||||
---
|
||||
|
||||
## 1) Crear repo
|
||||
## 1) Proyecto nuevo (greenfield)
|
||||
|
||||
```bash
|
||||
mkdir mi-proyecto
|
||||
cd mi-proyecto
|
||||
mkdir mi-proyecto && cd mi-proyecto
|
||||
git init
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2) Copiar framework
|
||||
|
||||
Desde tu copia local de ARNES:
|
||||
|
||||
```bash
|
||||
cp -R /ruta/a/arnes/* .
|
||||
cp -R /ruta/a/arnes/.[!.]* . 2>/dev/null || true
|
||||
```
|
||||
|
||||
> Si usas plantilla remota, clónala y copia su contenido al repo nuevo.
|
||||
|
||||
---
|
||||
|
||||
## 3) Personalizar proyecto
|
||||
|
||||
Edita mínimo:
|
||||
|
||||
- `README.md` (contexto del proyecto)
|
||||
- `spec/product.md` (qué construir)
|
||||
- `spec/tech.md` (stack y límites técnicos)
|
||||
- `spec/acceptance.md` (criterios de aceptación)
|
||||
- `backlog/features.json` (features iniciales en `pending`)
|
||||
- `harness/agents.matrix.yml` (roles/permisos)
|
||||
- `harness/workflow.stages.yml` (flujo y gates)
|
||||
|
||||
---
|
||||
|
||||
## 4) Elegir plataforma (pi.dev u opencode)
|
||||
|
||||
Usa el adaptador correspondiente:
|
||||
|
||||
- `platforms/pi/`
|
||||
- `platforms/opencode/`
|
||||
|
||||
El núcleo del framework no cambia; solo cambian prompts/hooks/permisos de plataforma.
|
||||
|
||||
---
|
||||
|
||||
## 5) Inicializar estado de trabajo
|
||||
|
||||
Verifica que existan y estén limpios:
|
||||
|
||||
- `work/current.md`
|
||||
- `work/history.md`
|
||||
- `work/artifacts/`
|
||||
|
||||
Pon solo **1 feature activa** (`in_progress`) como máximo.
|
||||
|
||||
---
|
||||
|
||||
## 6) Ejecutar verificación inicial
|
||||
|
||||
```bash
|
||||
# copiar contenido de arnes-fork aquí
|
||||
./scripts/start.sh
|
||||
./scripts/verify.sh
|
||||
python3 scripts/agent_status.py show
|
||||
```
|
||||
|
||||
Si falla, **no empezar implementación** hasta dejar todo en verde.
|
||||
Después:
|
||||
- Edita `backlog/features.json` (`project`, `description`).
|
||||
- Crea tu primera feature `pending` (puedes usar `starter-pack/backlog.features.bootstrap.json`).
|
||||
- Empieza el ciclo SDD (una feature a la vez).
|
||||
|
||||
---
|
||||
|
||||
## 7) Ciclo operativo por feature
|
||||
## 2) Proyecto ya empezado (brownfield)
|
||||
|
||||
Orden obligatorio:
|
||||
Copia al repo existente solo el core ARNES:
|
||||
- `harness/`
|
||||
- `spec/`
|
||||
- `backlog/`
|
||||
- `work/`
|
||||
- `scripts/`
|
||||
- `platforms/`
|
||||
- `AGENTS.md`, `CHECKPOINTS.md`
|
||||
|
||||
1. `leader` orquesta
|
||||
2. `architect` define/ajusta diseño
|
||||
3. `implementer` implementa + tests
|
||||
4. `reviewer` gate técnico
|
||||
5. `security` gate seguridad
|
||||
6. `qa` gate funcional
|
||||
7. `leader` cierra si todo está aprobado
|
||||
Luego ejecuta:
|
||||
|
||||
Reglas clave:
|
||||
- una feature a la vez
|
||||
- evidencia en disco (`work/artifacts/<feature>/...`)
|
||||
- nadie marca `done` si falta un gate
|
||||
```bash
|
||||
./scripts/start.sh
|
||||
./scripts/verify.sh
|
||||
python3 scripts/agent_status.py show
|
||||
```
|
||||
|
||||
Y añade checks del dominio en:
|
||||
- `scripts/verify.local.sh` (opcional)
|
||||
|
||||
---
|
||||
|
||||
## 8) Cierre de feature
|
||||
Crear ticket nuevo (leader/triager, EN caveman):
|
||||
```bash
|
||||
python3 scripts/new_ticket.py
|
||||
```
|
||||
|
||||
Antes de pasar a `done`:
|
||||
Modelo por tarea:
|
||||
- Config base en `harness/models.profiles.yml`
|
||||
- Reglas en `harness/policies/model-routing.md`
|
||||
|
||||
- `verify.sh` en verde
|
||||
- review aprobado
|
||||
- security aprobado
|
||||
- qa aprobado
|
||||
- resumen en `work/history.md`
|
||||
|
||||
---
|
||||
|
||||
## 9) Manejo de pérdida de contexto (memoria)
|
||||
|
||||
Si una sesión se corta:
|
||||
|
||||
1. leer `work/current.md`
|
||||
2. revisar `backlog/features.json`
|
||||
3. abrir artefactos de la feature activa
|
||||
4. ejecutar `./scripts/verify.sh`
|
||||
5. continuar desde “Próximo paso”
|
||||
|
||||
---
|
||||
|
||||
## 10) Checklist rápido de arranque
|
||||
|
||||
- [ ] Repo creado
|
||||
- [ ] Framework copiado
|
||||
- [ ] Specs escritas
|
||||
- [ ] Backlog definido
|
||||
- [ ] Matriz de agentes configurada
|
||||
- [ ] Workflow de stages configurado
|
||||
- [ ] Verificación inicial OK
|
||||
- [ ] Primera feature en `pending`
|
||||
|
||||
---
|
||||
|
||||
## Comando mental (resumen)
|
||||
|
||||
**Crear repo → copiar framework → definir spec/backlog → verificar → ejecutar pipeline de 6 agentes con gates obligatorios.**
|
||||
## Reglas operativas mínimas
|
||||
- Máximo una feature en `in_progress`.
|
||||
- `done` requiere gates `review/security/qa` aprobados.
|
||||
- Evidencia siempre en `work/artifacts/<feature_id>/`.
|
||||
- Si `verify.sh` falla, no se cierra la feature.
|
||||
|
||||
Reference in New Issue
Block a user