regista 🎬

AI agent director for pi.

Automates the full development pipeline with agents: PO → QA → Dev → Reviewer → Done, governed by a formal state machine with deadlock detection, checkpoint/resume, and CI/CD-ready JSON output.

Filosofía

Regista no sabe nada de tu proyecto. No importa si usas Rust, Python, o lo que sea. Solo necesita tres cosas:

1. Dónde están tus historias de usuario (archivos .md)
2. Qué skills de pi actúan como PO, QA, Dev, Reviewer
3. La máquina de estados fija que gobierna las transiciones

Instalación

git clone https://github.com/dbareautopi/regista
cd regista
cargo build --release

El binario estará en target/release/regista.

Configuración

Crea un archivo .regista.toml en la raíz de tu proyecto, o ejecuta:

regista init                     # genera estructura completa
regista init --light             # solo .regista.toml
regista init --with-example      # incluye historia de ejemplo

Configuración de referencia:

[project]
stories_dir    = "product/stories"     # dónde están las historias
story_pattern  = "STORY-*.md"          # glob para encontrarlas
epics_dir      = "product/epics"       # opcional: para filtrar
decisions_dir  = "product/decisions"   # decisiones de los agentes
log_dir        = "product/logs"        # logs del orquestador

[agents]
product_owner = ".pi/skills/product-owner/SKILL.md"
qa_engineer   = ".pi/skills/qa-engineer/SKILL.md"
developer     = ".pi/skills/developer/SKILL.md"
reviewer      = ".pi/skills/reviewer/SKILL.md"

[limits]
max_iterations            = 10
max_retries_per_step      = 5
max_reject_cycles         = 3
agent_timeout_seconds     = 1800
max_wall_time_seconds     = 28800
retry_delay_base_seconds  = 10
groom_max_iterations      = 5     # bucle groom→validate→corregir
inject_feedback_on_retry  = true  # inyectar stderr en reintentos

[hooks]
# Comandos opcionales de verificación post-fase.
# Si fallan, se hace rollback automático.
post_qa       = "cargo check --tests"
post_dev      = "cargo build && cargo test && cargo clippy -- -D warnings"
post_reviewer = "cargo test"

[git]
enabled = true   # snapshots + rollback automáticos

Todos los campos tienen valores por defecto razonables. Un proyecto mínimo solo necesita definir [agents].

Formato de historias

Tus historias deben seguir este formato .md:

# STORY-001: Título de la historia

## Status
**Draft**

## Epic
EPIC-001

## Descripción
Como [rol], quiero [acción] para que [beneficio].

## Criterios de aceptación
- [ ] CA1: Descripción del criterio
- [ ] CA2: ...

## Dependencias       ← opcional
- Bloqueado por: STORY-000

## Activity Log       ← obligatorio
- 2026-04-30 | PO | Creada en Draft

Estados válidos

Draft · Ready · Tests Ready · In Progress · In Review · Business Review · Done · Blocked · Failed

Uso

Generar el backlog automáticamente

# Desde un documento de requisitos
regista groom product/spec.md

# Con límite de historias
regista groom product/spec.md --max-stories 8

# Regenerar desde cero
regista groom product/spec.md --replace

groom invoca al PO para descomponer la spec en historias, escribe los .md, y ejecuta un bucle de validación de dependencias hasta que el grafo esté limpio.

Validar el proyecto

# Chequeo pre-vuelo (config, historias, skills, dependencias, git)
regista validate

# Salida JSON para CI
regista validate --json

Pipeline completo

# Procesar todo el backlog
regista /ruta/a/tu/proyecto

# Una sola iteración (procesa una historia y sale)
regista /ruta/a/tu/proyecto --once

Simular antes de ejecutar

# Ver qué haría el orquestador sin invocar agentes
regista --dry-run

# Simular solo una iteración
regista --dry-run --once

# Simular con salida JSON
regista --dry-run --json

Salida JSON para CI/CD

# Reporte estructurado a stdout, logs a stderr
regista --json

# Solo el JSON, sin logs de progreso
regista --json --quiet

# Validar en CI y capturar reporte
regista validate --json && regista --json --once > report.json

Exit codes: 0 = éxito, 1 = error de configuración, 2 = hay historias Failed.

Checkpoint y reanudación

# El pipeline guarda su estado en .regista.state.toml tras cada iteración
regista

# Si se interrumpe, reanuda desde donde estaba
regista --resume

# Borrar el checkpoint manualmente
regista --clean-state

Filtros de historias

# Solo una historia concreta
regista /ruta/a/tu/proyecto --story STORY-007

# Solo historias de una épica
regista /ruta/a/tu/proyecto --epic EPIC-001

# Rango de épicas (inclusivo)
regista /ruta/a/tu/proyecto --epics "EPIC-001..EPIC-003"

Archivo de configuración alternativo

regista /ruta/a/tu/proyecto --config mi-config.toml

Archivo de log personalizado

regista /ruta/a/tu/proyecto --log-file logs/debug.log

Modo daemon

# Lanzar en segundo plano
regista /ruta/a/tu/proyecto --detach

# Consultar si sigue corriendo
regista /ruta/a/tu/proyecto --status

# Ver el log en vivo (Ctrl+C para salir)
regista /ruta/a/tu/proyecto --follow

# Detener el daemon
regista /ruta/a/tu/proyecto --kill

Máquina de estados

Flujo feliz

Draft ──PO(groom)──→ Ready ──QA──→ Tests Ready ──Dev──→ In Review
                                                           │
                                                    Reviewer │
                                                           ▼
                       Done ←──PO(validate)── Business Review

Rechazos

In Review ──Reviewer──→ In Progress ──Dev(fix)──→ In Review
Business Review ──PO──→ In Review  (rechazo leve)
                 ──PO──→ In Progress (rechazo grave)

Transiciones automáticas (sin agente)

Feedback rico en reintentos

Cuando un agente falla, regista:

1. Guarda stdout/stderr en product/decisions/
2. En el reintento, inyecta el error en el prompt: «Tu intento anterior falló. Corrígelo.»
3. Esto aumenta la probabilidad de éxito en reintentos.

Configurable: inject_feedback_on_retry = false para desactivarlo.

Referencia completa de CLI

regista [PROJECT_DIR] [FLAGS]            # pipeline normal
regista validate [PROJECT_DIR] [FLAGS]   # validación pre-vuelo
regista init [PROJECT_DIR] [FLAGS]       # scaffolding de proyecto
regista groom <SPEC.md> [FLAGS]          # generación de historias

FLAGS (pipeline):
  --config <FILE>         Archivo de configuración alternativo
  --epics <RANGE>         Rango de épicas ("EPIC-001..EPIC-003")
  --epic <ID>             Una sola épica
  --story <ID>            Una sola historia
  --once                  Una iteración y salir
  --json                  Salida JSON a stdout
  --quiet                 Suprimir logs de progreso
  --dry-run               Simular sin invocar agentes
  --resume                Reanudar desde último checkpoint
  --clean-state           Borrar checkpoint
  --detach                Lanzar en segundo plano (daemon)
  --follow                Ver log en vivo del daemon
  --status                Consultar si el daemon sigue vivo
  --kill                  Detener el daemon
  --log-file <FILE>       Archivo de log (por defecto: stderr)

FLAGS (groom):
  --max-stories <N>       Máximo de historias (0 = sin límite)
  --replace               Regenerar desde cero (default: merge)
  --config <FILE>         Archivo de configuración alternativo

FLAGS (init):
  --light                 Solo .regista.toml, sin skills
  --with-example          Incluir historia y épica de ejemplo

FLAGS (validate):
  --json                  Salida JSON estructurada
  --config <FILE>         Archivo de configuración alternativo

Estructura del proyecto

regista/
├── src/
│   ├── main.rs                ← CLI, subcomandos, JSON output, exit codes
│   ├── config.rs              ← Config, carga TOML, defaults
│   ├── state.rs               ← Status, Actor, Transition
│   ├── story.rs               ← Story, parseo .md, set_status()
│   ├── dependency_graph.rs    ← Grafo, ciclos DFS, conteo inverso
│   ├── deadlock.rs            ← Detección de bloqueos + priorización
│   ├── agent.rs               ← pi con timeout, retry, feedback rico
│   ├── prompts.rs             ← Prompts para PO/QA/Dev/Reviewer
│   ├── orchestrator.rs        ← Loop principal, dry-run, checkpoint
│   ├── checkpoint.rs          ← Save/load/resume del estado
│   ├── validator.rs           ← Comando validate (pre-vuelo)
│   ├── init.rs                ← Comando init (scaffolding)
│   ├── groom.rs               ← Comando groom (generar backlog)
│   ├── hooks.rs               ← Comandos post-fase
│   ├── git.rs                 ← Snapshots + rollback
│   └── daemon.rs              ← Modo daemon (detach/follow/status/kill)
└── roadmap/                   ← Documentos de diseño de features futuras

Tests

cargo test   # 104 tests, 0 fallos, 0 warnings

Licencia

MIT