feat(F-001): scaffold modular monolith skeleton with boundary checker
- 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
This commit is contained in:
93
HOWTO.md
Normal file
93
HOWTO.md
Normal file
@@ -0,0 +1,93 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user