Qué hace

solveos-cli lleva el ciclo completo Plan → Build → Ship a tu asistente de código con IA:

• 14 slash commands para cada paso del ciclo
• 7 agentes especializados — planner, researcher, executor, validators, reviewer, debugger
• Gates de calidad opcionales — investigación, validación de plan, validación de build, revisión
• Ejecución paralela por waves para builds complejos
• Estado en Markdown — todos los artefactos viven en .solveos/, sin bases de datos ni cuentas en la nube

Runtimes compatibles

Instalación

Requisitos previos: Node.js >= 20.0.0 y uno de los runtimes compatibles instalado.

Instalar globalmente:

npm i solveos-cli@latest

O ejecutar sin instalar:

npx solveos-cli@latest

El instalador detecta automáticamente tu runtime. Usa --runtime <nombre> para forzar uno específico.

Rutas por runtime

Verificar instalación

Después de instalar, ejecuta /solveos-status en tu asistente. Debería mostrar:

Cycle 1 | State: INIT | No brief yet

Inicio rápido

1. Inicializar

/solveos-new

Crea el directorio .solveos/. Si ya existe, conserva tu configuración y estado actuales.

2. Planificar

/solveos-plan

El agente planner te guía por 8 preguntas del Plan Brief: Problema, Audiencia, Objetivo, Apetito, Restricciones, Criterios de éxito, Hipótesis central y Agujeros de conejo. Guardado en .solveos/BRIEF.md.

3. Construir

/solveos-build

El agente executor lee el Plan Brief y divide el trabajo en waves — grupos de tareas que pueden ejecutarse en paralelo.

4. Lanzar

/solveos-ship

Confirma el cierre del ciclo y archiva los artefactos en .solveos/history/cycle-N/.

El ciclo

El ciclo completo tiene 11 estados:

INIT -> RESEARCHING -> PLANNING -> VALIDATING_PLAN -> BUILDING ->
  VALIDATING_BUILD -> REVIEWING_PRE -> READY_TO_SHIP -> SHIPPED ->
  REVIEWING_POST -> CYCLE_COMPLETE

La ruta mínima (sin gates):

INIT -> PLANNING -> BUILDING -> READY_TO_SHIP -> SHIPPED -> CYCLE_COMPLETE

Usa /solveos-next en cualquier estado para ver qué está disponible. Usa /solveos-status para ver dónde estás.

Gates

Los gates son checkpoints de calidad opcionales. Cada uno puede activarse o desactivarse en .solveos/config.json.

Gate de investigación

Úsalo cuando el dominio es poco familiar o necesitas explorar opciones antes de comprometerte con un plan.

/solveos-research "¿Qué librerías de autenticación funcionan con nuestro stack?"

Genera un resumen de investigación en .solveos/research/. El agente researcher realiza investigación acotada — tiene una pregunta definida y se detiene cuando la responde.

Gate de validación del plan

Úsalo para planes de alto impacto, con muchas incógnitas, o cuando se necesita alineación.

/solveos-validate-plan

Verifica tres preguntas clave: ¿El plan resuelve el problema declarado? ¿Es factible dentro del apetito? ¿Los criterios de éxito son específicos y falsificables? Si hay brechas, refina y valida de nuevo (hasta plan_validation_max_passes veces, por defecto 3).

Gate de validación del build

Úsalo antes de lanzar cualquier cosa no trivial.

/solveos-validate-build

Verifica cada criterio de éxito contra el output real del build. Reporta aprobado/reprobado por criterio, desviación de alcance y problemas conocidos.

Gate de revisión

Pre-ship: juicio holístico "¿deberíamos lanzar esto?". Post-ship: medición de resultados y feed-forward.

/solveos-review

El comando detecta si estás pre-ship o post-ship según el estado actual. La revisión post-ship genera feed-forward items — nuevos problemas, alcance diferido, hipótesis incorrectas — que alimentan /solveos-new-cycle.

Escalado de rigor

Referencia de comandos

Agentes

Configuración

La configuración vive en .solveos/config.json:

{
  "mode": "interactive",
  "gates": {
    "research": true,
    "plan_validation": true,
    "build_validation": true,
    "review_pre_ship": true,
    "review_post_ship": true
  },
  "plan_validation_max_passes": 3,
  "granularity": "standard",
  "domain": "software",
  "runtime": "auto",
  "hooks": {
    "context_monitor": true,
    "context_monitor_threshold": 60,
    "brief_anchor": true,
    "brief_anchor_interval": 10
  }
}

Hooks

• Context monitor — Avisa cuando la longitud de la conversación se acerca al límite del contexto (al 60% y 80%). Sugiere lanzar sub-agentes.
• Brief anchor — Vuelve a mostrar periódicamente los criterios de éxito y los elementos fuera de alcance del Plan Brief para prevenir la desviación. Se activa cada N llamadas a herramientas (por defecto: 10).

Estructura del proyecto

.solveos/
  config.json          # Configuración
  STATE.md             # Estado del ciclo actual (legible por humanos)
  BRIEF.md             # Plan Brief del ciclo actual
  research/            # Resúmenes de investigación
  validations/         # Logs de validación de plan y build
  reviews/             # Revisiones pre-ship y post-ship
  history/             # Ciclos archivados
  notes/               # Notas libres

El directorio .solveos/ está diseñado para incluirse en el control de versiones — da visibilidad al equipo sobre el proceso de planificación y revisión.

Tips para Plan Briefs efectivos

1. Sé específico en los Criterios de éxito. "La feature funciona" no es falsificable. "Los usuarios pueden crear, editar y eliminar ítems vía la API" sí lo es.
2. Define un Apetito realista. El apetito da forma a la solución. Si escribes "2 horas" pero el plan requiere una migración de base de datos, habrá fricción.
3. Nombra tus Agujeros de conejo. Reconocer las incógnitas de antemano significa que no te sorprenderán cuando aparezcan.
4. Usa Fuera de alcance de forma agresiva. El modo de falla más común es la expansión del alcance. Escribe lo que NO estás haciendo.
5. Una Hipótesis central por plan. Si tienes múltiples hipótesis riesgosas, considera investigarlas primero.

Preguntas frecuentes

¿Puedo usar solveos-cli sin un asistente de código con IA?
No. solveos-cli instala slash commands y agentes que se ejecutan dentro de un asistente de código con IA. No tiene su propio runtime de CLI.

¿Funciona con múltiples runtimes a la vez?
Sí. Ejecuta npx solveos-cli@latest --runtime <nombre> para cada uno. El directorio de estado .solveos/ es compartido.

¿Dónde vive el estado?
Todo está en .solveos/ como archivos markdown y JSON. Sin bases de datos, sin cuentas en la nube, sin telemetría.

¿Cómo reseteo un ciclo atascado?
Usa /solveos-archive para archivar o abandonar el ciclo actual, luego /solveos-new para empezar de nuevo.

¿Qué pasa si salto todos los gates?
El ciclo sigue funcionando. Los gates saltados quedan registrados en .solveos/STATE.md para que puedas ver qué se omitió.

¿Puedo agregar comandos o agentes personalizados?
Sí. Agrega archivos markdown al directorio de comandos/agentes de tu runtime. solveos-cli no sobreescribirá archivos que no haya creado.

Código fuente

Open source bajo licencia MIT.