1d4eebca54
- TypeScript + Fastify skeleton under project/ (src/modules, shared, infrastructure, app) - scripts/check-module-boundaries.mjs enforcing module public-API rules (tested with fixtures) - GET /health endpoint, error envelope without stack leakage - specs/F-001-scaffold (SPEC/DESIGN/TASKS/TESTS), spec/tech.md dependency justification - 30-ticket MercadoDeVida roadmap in backlog/features.json, spec/roadmap.md - All gates approved: reviewer, security, qa; verify.sh green
162 lines
5.0 KiB
Markdown
162 lines
5.0 KiB
Markdown
# 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
|
|
|
|
```text
|
|
.
|
|
├── 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:
|
|
|
|
```bash
|
|
./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:
|
|
|
|
```text
|
|
.pi/extensions/orquestra-status/index.ts
|
|
.pi/extensions/orquestra-web-fetch.ts
|
|
```
|
|
|
|
Comando manual:
|
|
|
|
```bash
|
|
./scripts/pi_orquestra.sh
|
|
# dentro de Pi:
|
|
/orquestra-status
|
|
```
|
|
|
|
Fuente de verdad:
|
|
|
|
```bash
|
|
python3 scripts/agent_status.py show
|
|
python3 scripts/agent_status.py set ...
|
|
python3 scripts/agent_status.py reset
|
|
```
|
|
|
|
## 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
|