634525fa21
- 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
94 lines
2.8 KiB
Markdown
94 lines
2.8 KiB
Markdown
# HOWTO — usar Orquestra
|
|
|
|
## 1) Requisitos
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
./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
|
|
|
|
```bash
|
|
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:
|
|
|
|
```text
|
|
/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:
|
|
|
|
```bash
|
|
python3 scripts/agent_status.py set --feature-id F-001 --stage build --agent implementer --state running --action "Implementing"
|
|
```
|
|
|
|
## 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
|
|
```
|
|
|
|
## 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.
|