feat: Orquestra - sequential orchestration runtime
- Context isolation: fresh Pi process per stage (run_stage.py) - Gate enforcement: blocks close without approved gates - Auto commit/push on feature close (close_feature.py) - Write restrictions: only allowed directories (ALLOWED_WRITE_DIRS) - Pi extension: orquestra-status with /orquestra-stage command - Documentation: context-handoff.md, updated README - Scripts: agent_status.py, verify.sh, install.sh updated
This commit is contained in:
rikrdo
170
HOWTO.md
170
HOWTO.md
@@ -1,145 +1,93 @@
|
||||
# HOWTO — Cómo usar ARNES Framework
|
||||
# HOWTO — usar Orquestra
|
||||
|
||||
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) Requisitos
|
||||
|
||||
```bash
|
||||
mkdir mi-proyecto
|
||||
cd mi-proyecto
|
||||
git init
|
||||
command -v pi
|
||||
command -v python3
|
||||
```
|
||||
|
||||
---
|
||||
Si `pi` no existe, no instales Orquestra todavía.
|
||||
|
||||
## 2) Copiar framework
|
||||
## 2) Instalar en un proyecto
|
||||
|
||||
Desde tu copia local de ARNES:
|
||||
Desde el repo fuente de Orquestra:
|
||||
|
||||
```bash
|
||||
cp -R /ruta/a/arnes/* .
|
||||
cp -R /ruta/a/arnes/.[!.]* . 2>/dev/null || true
|
||||
./scripts/install.sh /path/to/project-repo
|
||||
```
|
||||
|
||||
> Si usas plantilla remota, clónala y copia su contenido al repo nuevo.
|
||||
Para actualizar, ejecutá el mismo comando otra vez sobre el repo destino.
|
||||
|
||||
---
|
||||
La instalación es safe-update:
|
||||
- crear archivos faltantes
|
||||
- conservar o mergear archivos existentes
|
||||
- crear `project/` si falta y no pisar su contenido
|
||||
- no pisar progreso en `project/`, `work/`, `backlog/`, `spec/` ni `work/artifacts/`
|
||||
|
||||
## 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
|
||||
## 3) Verificar
|
||||
|
||||
```bash
|
||||
./scripts/verify.sh
|
||||
```
|
||||
|
||||
Si falla, **no empezar implementación** hasta dejar todo en verde.
|
||||
Debe comprobar:
|
||||
- estructura mínima
|
||||
- `project/` existente
|
||||
- ausencia de archivos de producto/código en la raíz (`*.py`, `*.js`, `*.ts`, `*.go`, `*.rs`, `*.java`, `*.php`, `*.rb`); usá `project/`
|
||||
- Pi instalado
|
||||
- extensión project-local permitida
|
||||
- sin `.pi/subagents/` ni `.pi/subagents.json`
|
||||
- extensiones Orquestra requeridas
|
||||
- backlog válido
|
||||
- runtime status válido
|
||||
|
||||
---
|
||||
## 4) Ejecutar desde Pi
|
||||
|
||||
## 7) Ciclo operativo por feature
|
||||
```bash
|
||||
cd <repo-instalado>
|
||||
./scripts/pi_orquestra.sh
|
||||
```
|
||||
|
||||
Orden obligatorio:
|
||||
Ese launcher usa `pi --no-extensions` y carga solo `orquestra-status` + `orquestra-web-fetch`, así Pi arranca limpio con las extensiones del proyecto.
|
||||
|
||||
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
|
||||
Después de abrir o recargar Pi:
|
||||
|
||||
Reglas clave:
|
||||
- una feature a la vez
|
||||
- evidencia en disco (`work/artifacts/<feature>/...`)
|
||||
- nadie marca `done` si falta un gate
|
||||
```text
|
||||
/orquestra-status
|
||||
```
|
||||
|
||||
---
|
||||
## 5) Flujo secuencial
|
||||
|
||||
## 8) Cierre de feature
|
||||
1. `leader` selecciona una feature pending.
|
||||
2. `architect` diseña si hace falta.
|
||||
3. `implementer` implementa y escribe `implementer.md`.
|
||||
4. `reviewer` escribe `reviewer.json`.
|
||||
5. `security` escribe `security.json`.
|
||||
6. `qa` escribe `qa.json`.
|
||||
7. `documenter` escribe `documenter.md` solo si cambiaron docs/API/contratos/comportamiento user-facing.
|
||||
8. `leader` cierra con `leader-close.json` y `work/history.md`.
|
||||
|
||||
Antes de pasar a `done`:
|
||||
Un stage empieza solo cuando el anterior terminó con artefacto en disco; `document` es opcional/condicional y no bloquea el cierre por defecto.
|
||||
|
||||
- `verify.sh` en verde
|
||||
- review aprobado
|
||||
- security aprobado
|
||||
- qa aprobado
|
||||
- resumen en `work/history.md`
|
||||
## 6) Dónde va el código de producto
|
||||
|
||||
---
|
||||
El código del producto vive en `project/`. No escribas archivos de producto/código en la raíz del repo.
|
||||
|
||||
## 9) Manejo de pérdida de contexto (memoria)
|
||||
En Pi, las herramientas `write` y `edit` solo pueden modificar `project/` o `tests/` cuando `work/runtime-status.json` tiene una feature activa con `stage=build`, `agent=implementer` y `state=running`. Prepará el stage con:
|
||||
|
||||
Si una sesión se corta:
|
||||
```bash
|
||||
python3 scripts/agent_status.py set --feature-id F-001 --stage build --agent implementer --state running --action "Implementing"
|
||||
```
|
||||
|
||||
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”
|
||||
## 7) Estado visible
|
||||
|
||||
---
|
||||
```bash
|
||||
python3 scripts/agent_status.py show
|
||||
python3 scripts/agent_status.py set --feature-id F-001 --stage build --agent implementer --state running --action "Implementing"
|
||||
python3 scripts/agent_status.py reset
|
||||
```
|
||||
|
||||
## 10) Checklist rápido de arranque
|
||||
## Regla corta
|
||||
|
||||
- [ ] 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.**
|
||||
Pi instalado → Orquestra instalado sin pisar progreso → producto dentro de `project/` → `verify.sh` verde → `./scripts/pi_orquestra.sh` desde raíz → stages secuenciales con evidencia en disco.
|
||||
|
||||
Reference in New Issue
Block a user