rikrdo/orquestra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Orquestra - sequential orchestration runtime

Browse Source 
- 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
2026-08-17 07:39:03 +02:00
parent 622e5df382
commit 634525fa21
28 changed files with 2296 additions and 284 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
README.md
View File

@@ -1,170 +1,161 @@
# ARNES Framework (agnóstico) — Diseño v0.1
# Orquestra — harness secuencial para Pi
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.
Orquestra es un harness in-house para instalar en cualquier repo de proyecto y ejecutarlo desde Pi con control de estado, evidencias y gates.
---
No instala subagentes. El flujo es secuencial: termina un rol/stage, se escribe su artefacto, recién ahí empieza el siguiente.
## Requisitos
- `pi` instalado y disponible en `PATH` antes de ejecutar Orquestra.
- `python3` disponible para scripts del harness.
- Ejecutar Pi desde la raíz del proyecto.
- Arrancar con `./scripts/pi_orquestra.sh` para usar `pi --no-extensions` y cargar solo extensiones Orquestra.
- Extensiones Pi project-local declaradas: `orquestra-status` y `orquestra-web-fetch.ts`.
> Nota honesta: abrir `pi` directo puede cargar extensiones globales. Para Pi limpio, usá `./scripts/pi_orquestra.sh`.
## Objetivo
Permitir que agentes implementen features de forma autónoma **sin perder control**:
Permitir trabajo asistido por agentes sin perder control:
- una feature a la vez
- evidencia en disco (no en chat)
- estado persistente en disco
- evidencia auditable, nunca solo chat
- separación de roles
- gates obligatorios de revisión, seguridad y QA
- cierre solo con validación completa
- documentación opcional cuando cambian docs/API/contratos/comportamiento user-facing
- código de producto dentro de `project/` (nunca archivos de código en la raíz)
- cierre solo con `./scripts/verify.sh` en verde
---
## Roles secuenciales
## Principios
1. `leader` — selecciona feature, orquesta, cierra.
2. `architect` — diseño/contratos cuando haga falta.
3. `implementer` — cambia código y tests, no aprueba.
4. `reviewer` — gate técnico.
5. `security` — gate de seguridad.
6. `qa` — gate funcional/aceptación.
7. `documenter` — documentación opcional cuando aplique.
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.
Los modelos por rol se definen en `harness/model-routing.yml`; el cambio de modelo ocurre antes de cada stage, nunca en paralelo.
---
## Pipeline
## Matriz de agentes (6)
1. `intake` → `leader`
2. `design` → `architect` opcional
3. `build` → `implementer`
4. `review_gate` → `reviewer`
5. `security_gate` → `security`
6. `qa_gate` → `qa`
7. `document` → `documenter` opcional/condicional
8. `close` → `leader`
1. **leader**
- Orquesta etapas y handoffs.
- No implementa código de producto.
No hay `done` si falta cualquier gate obligatorio; `documenter.md` no es requisito de cierre salvo que el cambio necesite documentación.
2. **architect**
- Define/ajusta diseño técnico y contratos.
- Puede editar documentación y diseño.
## Evidencia obligatoria
3. **implementer**
- Implementa una sola feature + tests.
- No puede aprobar ni cerrar.
4. **reviewer**
- Revisión técnica vs arquitectura/convenios.
- No edita código, solo aprueba/rechaza.
5. **security**
- Gate de seguridad: secretos, dependencias, SAST básico, hardening checks.
- No edita código.
6. **qa**
- Gate de calidad funcional: aceptación, integración/E2E, regresión.
- No edita código.
---
## Flujo de trabajo (pipeline)
1. `intake` (leader)
2. `design` (architect)
3. `build` (implementer)
4. `review_gate` (reviewer) ✅
5. `security_gate` (security) ✅
6. `qa_gate` (qa) ✅
7. `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:
Cada stage escribe en disco:
- `work/artifacts/<feature>/implementer.md`
- `work/artifacts/<feature>/reviewer.md`
- `work/artifacts/<feature>/security.md`
- `work/artifacts/<feature>/qa.md`
- `work/artifacts/<feature>/reviewer.json`
- `work/artifacts/<feature>/security.json`
- `work/artifacts/<feature>/qa.json`
- `work/artifacts/<feature>/documenter.md` (opcional/condicional)
- `work/artifacts/<feature>/leader-close.json`
Respuesta de agente siempre: `done -> <ruta>` o `blocked -> <ruta>`.
Respuesta estándar por stage:
- `done -> <ruta>`
- `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
## Estructura mínima
```text
.
├── AGENTS.md
├── README.md
├── harness/
│ ├── agents.matrix.yml
│ ├── workflow.stages.yml
│ ├── model-routing.yml
│ ├── policies/
│ │ ├── security.md
│ │ ├── quality.md
│ │ └── governance.md
│ └── contracts/
│ ├── handoff.md
│ └── evidence.schema.json
├── platforms/pi/
│ └── extensions/
│ ├── orquestra-status/
│ └── orquestra-web-fetch.ts
├── spec/
│ ├── product.md
│ ├── tech.md
│ └── acceptance.md
├── backlog/
│ └── features.json
├── project/
├── backlog/features.json
├── work/
│ ├── current.md
│ ├── history.md
│ ├── runtime-status.json
│ └── artifacts/
└── scripts/
└── verify.sh
├── verify.sh
├── agent_status.py
├── new_ticket.py
└── pi_orquestra.sh
```
---
## Instalación y actualización segura
## Manejo de pérdidas de memoria (context loss)
Desde el repo fuente de Orquestra:
Sí: el framework está diseñado para eso.
```bash
./scripts/install.sh /path/to/project-repo
```
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”
Para actualizar, volvé a ejecutar el mismo comando sobre el repo destino.
Si se pierde contexto del modelo, el sistema se puede reconstruir desde archivos.
Regla base:
- crear si falta
- conservar o mergear si existe
- nunca pisar `work/`, `backlog/`, `spec/` ni artefactos ya producidos
---
Archivos del harness actualizables: `AGENTS.md`, `README.md`, `HOWTO.md`, `CHECKPOINTS.md`, `harness/`, `scripts/`, `platforms/pi/`.
Datos del proyecto: `project/`, `work/`, `backlog/`, `spec/`.
## Adaptadores de plataforma
El instalador crea `project/` si falta y no pisa su contenido. Los archivos de producto/código (`*.py`, `*.js`, `*.ts`, `*.go`, `*.rs`, `*.java`, `*.php`, `*.rb`) son inválidos en la raíz del repo; `./scripts/verify.sh` falla si los encuentra. Durante una sesión Pi, escribir en `project/` o `tests/` requiere una feature activa con `stage=build`, `agent=implementer` y `state=running` en `work/runtime-status.json`.
- `platforms/pi/`: prompts, hooks, permisos, comandos compatibles con pi.dev.
- `platforms/opencode/`: prompts, hooks, permisos, comandos compatibles con opencode.
## Pi
El núcleo no cambia; solo el adaptador.
Las extensiones Orquestra esperadas son:
---
```text
.pi/extensions/orquestra-status/index.ts
.pi/extensions/orquestra-web-fetch.ts
```
## Criterios de éxito del framework
Comando manual:
- 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.
```bash
./scripts/pi_orquestra.sh
# dentro de Pi:
/orquestra-status
```
---
Fuente de verdad:
## Próximos pasos sugeridos
```bash
python3 scripts/agent_status.py show
python3 scripts/agent_status.py set ...
python3 scripts/agent_status.py reset
```
1. Definir `agents.matrix.yml` completo (permisos exactos por rutas).
2. Definir `workflow.stages.yml` con transiciones válidas.
3. Diseñar `features.json` con estados y criterios de aceptación.
4. Especificar `scripts/verify.sh` (lint/test/security/qa gates).
5. Crear adaptadores `platforms/pi` y `platforms/opencode`.
## Verificación
```bash
./scripts/verify.sh
```
Comprueba:
- estructura mínima
- `pi` instalado
- launcher limpio `scripts/pi_orquestra.sh`
- extensiones requeridas: `orquestra-status` y `orquestra-web-fetch`
- ausencia de subagentes project-local
- precondiciones de stage en `agent_status.py`
- extensiones project-local no declaradas
- backlog y gates
- `work/runtime-status.json`
- `project/` existente y sin archivos de producto/código en la raíz
- suite del proyecto si existe