zyrocli

ZyroCLI — Orquestador Autónomo para Desarrollo Asistido por IA

Pipeline SDD completo (F0→F4) · Memoria Causal · Seguridad por Fase · Auto-instalable

🆕 v3.1.0

• Nueva TUI interactiva con Bubble Tea — menú principal, instalación guiada, configuración de modelos
• Detección de GPU cross-platform — Linux (nvidia-smi/lspci/ROCm), macOS (sysctl/system_profiler), Windows (nvidia-smi/WMI)
• Ruteo de modelos por agente — cada skill SDD puede usar un modelo LLM distinto, configurable vía /zyro-model en OpenCode
• Boomerang Phase Skip — cada macro-fase ejecuta solo los pasos necesarios: F0-F2 sin Git/Quality, F3 completa, F4 sin Think. Hasta ~40% menos pasos que v2.
• Persistencia de configuración en ~/.zyro/config.yaml

📋 Tabla de Contenidos

• ✨ ¿Qué hace ZyroCLI?
• 🧠 ¿Por qué existe?
• 🔄 Dos Ciclos, Un Sistema: SDD + Boomerang
• 🏗️ Arquitectura
• 🚀 Instalación
• ⚡ Quick Start
• 📚 Documentación
• 🛡️ Seguridad
• ✅ Estado del Proyecto

ZyroCLI es un orquestador que ejecuta un pipeline de desarrollo de software usando agentes de IA sobre OpenCode. No es un chat, no es un IDE — es un ingeniero de software automatizado que planifica, especifica, diseña, implementa y verifica usando agentes especializados.

✨ ¿Qué hace ZyroCLI?

🧠 ¿Por qué existe?

El desarrollo asistido por IA tiene un problema fundamental: cada sesión empieza en blanco. El agente no recuerda decisiones anteriores, repite errores, y no tiene contexto del proyecto.

ZyroCLI resuelve esto con 4 innovaciones basadas en investigación técnica:

1. Memoria Causal (en lugar de chat stateless)

Basado en el concepto de engram (traza física de memoria, Semon 1904). Cada decisión, error y preferencia se almacena como un nodo Fact en un grafo causal con relaciones como CAUSED, PRECEDES, CONTRADICTS. Antes de cada fase, el agente recibe automáticamente el contexto relevante. Después de cada fase, se extraen nuevos hechos y se resuelven contradicciones.

Por qué: Los LLMs no tienen memoria persistente. HelixDB (grafos + vectores) permite búsqueda semántica y navegación causal que SQLite no puede ofrecer.

Investigación →

2. Agent-as-Validator (el agente opina, Go ejecuta)

El agente Python nunca escribe en la base de datos. Devuelve un AgentDecision validado con Pydantic, y el orquestador Go decide si ejecutarlo. Esto evita que el agente se salte fases o corrompa el estado global.

Por qué: Un agente autónomo sin restricciones puede inventar herramientas, modificar estado o ejecutar acciones no autorizadas. Separar "opinar" de "ejecutar" es un patrón probado (verificar y validar).

Investigación →

3. Seguridad por Fase (Boundari)

Cada fase del pipeline tiene una política Boundari que define qué herramientas puede usar el agente. F0 solo lectura, F3 escritura intensiva con approval para comandos peligrosos. Las políticas están escritas en YAML y se cargan dinámicamente.

Por qué: No todas las fases tienen los mismos permisos. Un agente en fase de investigación no debería poder ejecutar código. Boundari aplica el principio de mínimo privilegio.

Investigación →

4. Búsqueda Híbrida + Embeddings Locales

La memoria causal se consulta con búsqueda híbrida (vector ANN + BM25 + RRF fusion). Los embeddings se generan localmente con Ollama + nomic-embed-text (768d, GPU vía Vulkan). Si no hay embeddings, cae a BM25 puro (degradación graceful).

Por qué: La búsqueda semántica permite encontrar hechos conceptualmente similares aunque usen palabras diferentes. El modelo nomic-embed-text ofrece buen balance calidad/velocidad para búsqueda semántica local.

Investigación →

🔄 Dos Ciclos, Un Sistema: SDD + Boomerang

ZyroAgentCLI opera con dos ciclos anidados que no debes confundir:

🟦 SDD — Macro-ciclo de producto (F0→F4)

El ciclo visible para el humano. Cada fase produce un artefacto:

PRE-F0: Alineación →  Alignment + Domain Model (grill-me, triage, improve-arch)
F0: Investigación  →  Patrones, Librerías, Skills
F1: Especificación →  PRD con deep modules (to-prd)
F2: Diseño + Tasks →  Design + Tareas atómicas
F3: Implementación →  Código + Tests
F4: Archive        →  Documentación final + Handoff

Cuándo usarlo: cuando planificas un feature o fix completo.
Quién lo gobierna: el humano + el scheduler Go.

🟠 Boomerang — Micro-ciclo de ejecución (dentro de cada fase)

Cada macro-fase ejecuta una combinación distinta de pasos. La Phase Skip Matrix elimina los innecesarios:

           MEMORY  THINK  DELEGATE  GIT CHECK  QUALITY  SAVE
PRE-F0  │   ✅      ✅      ✅        —          —       ✅
F0      │   ✅      ✅      ✅        —          —       ✅
F1      │   ✅      ✅      ✅        —          —       ✅
F2      │   ✅      ✅      ✅        —          —       ✅
F3      │   ✅      ✅      ✅        ✅         ✅      ✅
F4      │   ✅      —       ✅        ✅         —       ✅

Por qué: F0-F2 son fases de investigación y diseño — no requieren validar git ni calidad de código. F3 es implementación y necesita control de cambios + tests. F4 es cierre y solo necesita git + archive. Esto reduce el overhead del Boomerang hasta ~40% versus ejecutar los 6 pasos siempre.

Quién lo gobierna: el orquestador Go — nunca el agente Python.

📊 Benchmark v2 — Comparativa justa (24 runs, 3 sesiones)

Ejecutamos 3 sesiones incrementales (JWT auth → roles → refresh token) × 3 iteraciones × 3 jaulas = 27 runs (24 completados, 3 timeouts de ZyroCLI) sobre DeepSeek V4 Flash via OpenCode Zen (gratis).

🏆 Ganadores por métrica

⚠️ Comparación justa: ZyroCLI completó 6/9 runs (3 timeouts en sesiones 2-3 por el overhead del Boomerang). Las celdas con "—" indican N < 2, datos insuficientes para promedio.

🔧 Boomerang: lo hecho y lo pendiente

✅ Implementado en v3.1.0 (Phase Skip Matrix) Cada macro-fase ejecuta solo los pasos que necesita (ver matriz arriba). Esto reduce el overhead del Boomerang en fases de investigación y diseño hasta ~40%.

⏳ Pendiente (Smart Boomerang dinámico) Inspeccionar el estado en vivo del repo para decidir si un paso corre o no:

• Si no hay cambios en git → saltar GitStep (incluso en F3)
• Si no hay tareas delegadas → saltar DelegateStep
• Si no hay hechos nuevos → saltar SaveStep

Objetivo: reducir el overhead de ~2.5× a ~1.3× respecto a OpenCode plano. La especificación técnica está en sdd/fase1-skip-matrix/.

✅ Conclusión honesta

Los benchmarks de abajo corresponden a v2, previo al Phase Skip Matrix. La matriz implementada en v3.1.0 ya reduce el overhead, pero el Smart Boomerang dinámico está pendiente para reducirlo aún más.

1. ZyroCLI produce mejor calidad — único que genera tests (27-82% cobertura) y código modular.
2. ZyroCLI gasta menos tokens input que gentle-ai (−35%) y comparable a Plain (−2%).
3. ZyroCLI es 2.5× más lento — el Boomerang tiene overhead real. Para tareas chicas, no conviene.
4. Plain es óptimo para tareas rápidas (1-2 archivos, sin tests). Rápido, barato, pero deuda técnica.
5. gentle-ai es consistente pero caro en tokens (+31% input vs Plain). No genera tests.
6. Costo no es factor — DeepSeek V4 Flash es gratis. Con GPT-4/Claude, la historia sería otra.

📁 Datos crudos y reportes

📊 Charts

Tokens totales por jaula y sesión

Distribución de tokens input vs output

Turns por sesión

• 📊 Datos crudos — Plain
• 📊 Datos crudos — gentle-ai
• 📊 Datos crudos — ZyroCLI

🔬 Metodología

• 3 sesiones incrementales: Sesión 1 = JWT auth, Sesión 2 = roles, Sesión 3 = refresh token
• 3 iteraciones por jaula × sesión = 27 runs total (24 completados)
• Modelo: DeepSeek V4 Flash vía OpenCode Zen (gratis, sin API key)
• Medición exacta: opencode export para tokens, go test -cover para cobertura, gocyclo para complejidad
• Timeout: 900s por run (15 min)
• Fecha: 2026-06-17

🏗️ Arquitectura

Humano ──→ ZyroCLI (Go) ──→ OpenCode (Agentes IA)
              │                     │
              ├── HelixDB (grafos)  ├── PydanticAI (Agent-as-Validator)
              ├── Boundari (seguridad) ├── Boomerang (ciclo 6 pasos)
              └── Memoria Causal    └── Skills (patrones, librerías, etc.)

🚀 Instalación

# Opción 1: Go install (requiere Go 1.26+)
go install github.com/yechua-silva/zyrocli@latest
zyrocli install

# Opción 2: binary directo (recomendado)
curl -sSL https://github.com/yechua-silva/zyrocli/releases/latest/download/install.sh | bash
zyrocli install

# Opción 3: compilar desde fuente
git clone https://github.com/yechua-silva/zyrocli
cd zyrocli
make build
sudo cp ./zyrocli /usr/local/bin/

zyrocli install configura skills, MCP tools y OpenCode globalmente. Después corré zyrocli doctor para verificar que todo funcione.

⚡ Quick Start

# 1. Instalar
zyrocli install

# 2. Crear un handoff con la descripción de tu proyecto
cat > handoff.yaml << 'EOF'
project:
  name: mi-app
  description: API REST en Go con autenticación JWT
  technologies:
    - Go
    - PostgreSQL
    - JWT
EOF

# 3. Inicializar el proyecto
zyrocli init handoff.yaml

📚 Documentación

🛡️ Seguridad

ZyroCLI aplica el principio de mínimo privilegio en cada fase del pipeline:

F0 (Investigación) → solo lectura de código y web
F1 (Especificación) → lectura + escritura de documentos .md
F2 (Diseño) → escritura de planos .md .yaml
F3 (Implementación) → escritura de código + ejecución controlada
F4 (Cierre) → solo lectura, archive con approval

✅ Estado del Proyecto

• Pipeline F0-F4: Completo e integrado con Boomerang
• Memoria Causal: 6 tipos de Facts, 7 aristas causales, curva de Ebbinghaus
• Embeddings: Ollama + nomic-embed-text (768d, GPU vía Vulkan) + fallback BM25
• Seguridad: Boundari con políticas YAML por fase
• Tests: 455 tests, 100% passing
• Distribución: npm, GitHub Releases, go install

Créditos

Skills y Metodología

• Matt Pocock — Creador de las skills grill-with-docs, to-prd, grill-me, domain-model, triage, improve-codebase-architecture, to-issues y /handoff. Su framework de skills para desarrollo asistido por IA es la base metodológica de nuestro pipeline SDD v2. mattpocock/skills (135K ⭐)
• samber/cc-skills-golang — Skills de documentación y testing Go que usamos para mantener la calidad del código de ZyroCLI.
• obra/superpowers — Framework de Subagent-Driven Development que inspiró nuestro modelo de agentes especializados. (232K ⭐)
• github/awesome-copilot — Skills complementarias de PRD y especificación técnica.

MCP Tools y Ecosistema

• HelixDB — Base de datos de grafos + vectores que usamos como memoria causal. Motor de persistencia de todo el pipeline.
• Neuledge Context — Paquete de documentación offline para librerías, integrado en nuestras herramientas MCP.
• OpenCode — Runtime de agentes que ejecuta nuestros 16 skills especializados.
• Boundari — Seguridad por fase con políticas de mínimo privilegio.
• Bubble Tea — Framework TUI que usamos para la interfaz interactiva de ZyroCLI.

Lenguajes y Herramientas

• Go — Lenguaje principal del orquestador.
• Python (PydanticAI) — Lenguaje de los agentes MCP con validación tipada.
• Ollama + nomic-embed-text — Embeddings locales para búsqueda semántica.

📬 Contacto

Sígueme en mis redes para estar al tanto de nuevas herramientas, artículos y proyectos:

• 🌐 GitHub: github.com/yechua-silva
• 📝 Dev.to: dev.to/yechuasilva
• 💼 LinkedIn: linkedin.com/in/yechua-silva

Feedback

• DEV.to: Publicacion y discusión

Licencia

MIT