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