orquestra/README.md

Orquestra — harness secuencial para Pi

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 trabajo asistido por agentes sin perder control:

• una feature a la vez
• estado persistente en disco
• evidencia auditable, nunca solo chat
• separación de roles
• gates obligatorios de revisión, seguridad y QA
• 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

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.

Los modelos por rol se definen en harness/model-routing.yml; el cambio de modelo ocurre antes de cada stage, nunca en paralelo.

Pipeline

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

No hay done si falta cualquier gate obligatorio; documenter.md no es requisito de cierre salvo que el cambio necesite documentación.

Evidencia obligatoria

Cada stage escribe 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>/documenter.md (opcional/condicional)
• work/artifacts/<feature>/leader-close.json

Respuesta estándar por stage:

• done -> <ruta>
• blocked -> <ruta>

Estructura mínima

.
├── AGENTS.md
├── README.md
├── harness/
│   ├── agents.matrix.yml
│   ├── workflow.stages.yml
│   ├── model-routing.yml
│   ├── policies/
│   └── contracts/
├── platforms/pi/
│   └── extensions/
│       ├── orquestra-status/
│       └── orquestra-web-fetch.ts
├── spec/
├── project/
├── backlog/features.json
├── work/
│   ├── current.md
│   ├── history.md
│   ├── runtime-status.json
│   └── artifacts/
└── scripts/
    ├── verify.sh
    ├── agent_status.py
    ├── new_ticket.py
    └── pi_orquestra.sh

Instalación y actualización segura

Desde el repo fuente de Orquestra:

./scripts/install.sh /path/to/project-repo

Para actualizar, volvé a ejecutar el mismo comando sobre el repo destino.

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/.

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.

Pi

Las extensiones Orquestra esperadas son:

.pi/extensions/orquestra-status/index.ts
.pi/extensions/orquestra-web-fetch.ts

Comando manual:

./scripts/pi_orquestra.sh
# dentro de Pi:
/orquestra-status

Fuente de verdad:

python3 scripts/agent_status.py show
python3 scripts/agent_status.py set ...
python3 scripts/agent_status.py reset

Verificación

./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