rikrdo/orquestra
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
orquestra/HOWTO.md
rikrdo 634525fa21 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
2026-08-17 07:39:03 +02:00

2.8 KiB
Raw Permalink Blame History

HOWTO — usar Orquestra

1) Requisitos

command -v pi
command -v python3

Si pi no existe, no instales Orquestra todavía.

2) Instalar en un proyecto

Desde el repo fuente de Orquestra:

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

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) Verificar

./scripts/verify.sh

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

cd <repo-instalado>
./scripts/pi_orquestra.sh

Ese launcher usa pi --no-extensions y carga solo orquestra-status + orquestra-web-fetch, así Pi arranca limpio con las extensiones del proyecto.

Después de abrir o recargar Pi:

/orquestra-status

5) Flujo secuencial

  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.

Un stage empieza solo cuando el anterior terminó con artefacto en disco; document es opcional/condicional y no bloquea el cierre por defecto.

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.

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:

python3 scripts/agent_status.py set --feature-id F-001 --stage build --agent implementer --state running --action "Implementing"

7) Estado visible

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

Regla corta

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.