Cómo funciona SpecBox Engine

Pipeline completo de desarrollo spec-driven con orquestación multi-agente: agentes especializados, MCP tools, skills y quality gates.

4 comandos. Software verificado. Evidencia auditable.

Enmarcas el problema con /discovery (ICP + JTBD). Describes qué construir con /prd. El engine planifica con /plan. Implementa con /implement. Quality gates verifican cada paso. Self-healing corrige errores automáticamente. Tú revisas la PR.

Ejemplo real: de idea a PR en 4 pasos

Así funciona: 4 comandos, software verificado

$ /discovery "Sistema de reservas para restaurante"

Framing antes de construir...

┌─ ICP: dueño de restaurante sin equipo técnico

└─ JTBD: llenar mesas sin llamadas ni no-shows

→ icp_jtbd.md ✓ (insumo del PRD)

$ /prd "Sistema de reservas para restaurante"

Generando PRD...

┌─ US-001: Reservar mesa online

│ ├─ UC-001: Seleccionar fecha y hora (4 ACs)

│ └─ UC-002: Cancelar reserva (2 ACs)

└─ Quality Gate: PASS (12/12 ACs son específicos y medibles)

$ /plan

Analizando PRD (4 US, 12 UC, 38 AC)...

┌─ Fase 1: Database schema + RLS

├─ Fase 2: API (12 endpoints)

├─ Fase 3: UI (Stitch designs)

└─ Fase 4: E2E Playwright

Estimado: ~6h con SpecBox. Sin SpecBox: 3-5 días.

$ /implement

[Orchestrator] Creando rama feat/US-001

[AG-03] Migraciones: create_bookings_table ✓

[AG-01] Implementando UC-001 from Stitch design...

[AG-04] Tests: 24/24 passing, coverage 87%

[AG-08] Quality Gate: GO ✓

[AG-09] Acceptance: 12/12 AC ACCEPTED

→ PR #47 creada, lista para review

El Pipeline

$ /discovery

Framing del producto antes del PRD: identifica el ICP (cliente ideal) y extrae los JTBD (trabajos a resolver). Genera doc/discovery/<feature>/icp_jtbd.md, el insumo que orienta al /prd. Disponible desde v6.0.0.

$ /prd

Genera el Product Requirements Document con User Stories, Use Cases, y Acceptance Criteria. Definition Quality Gate valida que cada criterio sea específico, medible y testable.

$ /plan

Analiza el PRD, genera plan técnico con fases, componentes UI, y diseños Stitch. VEG genera directivas visuales adaptadas a la audiencia.

$ /implement

Autopilot: crea rama, ejecuta fases secuenciales, design-to-code, quality gates entre fases, acceptance testing, y PR automática.

Deep Dive — Todo lo que hay dentro

Agentes Especializados

Cada fase del pipeline tiene agentes con roles definidos. El Orquestador NUNCA escribe código — solo coordina, delega, y consolida.

Agent Skills

Comandos auto-descubribles que se activan cuando son relevantes. Cada skill es un workflow completo.

Herramientas de Automatización

Servidor MCP unificado. Backend-agnostic: funciona con Trello, Plane, o sin API externa.

Cada herramienta es una operación atómica que los agentes usan para gestionar tu proyecto: crear PRDs, ejecutar tests, mover tarjetas, verificar calidad, generar evidencia.

— MCP tools

·
…
·
…
·
…
·
…
·
…
·
…
·
…
·
…

Extensión para VS Code

Instala SpecBox Engine desde el Marketplace. Onboarding guiado, auto-update y sign-in con GitHub.

🧩
EmbedBuild.specbox-engine
v—
Ver en el Marketplace

Quality Gates

Controles que BLOQUEAN el pipeline si el trabajo no cumple. No son reparaciones: o se pasan, o no se avanza.

📐

Definition Quality Gate

En /prd: valida cada Acceptance Criteria por especificidad, medibilidad y testabilidad. Si el promedio no llega al umbral, rechaza el work item y propone mejoras.

🔍

Quality Audit · AG-08

En /implement: auditoría ISO/IEC 25010 (SQuaRE, 8 características). Veredicto GO / CONDITIONAL GO / NO-GO. Bloquea el merge si es NO-GO.

✅

Acceptance Gate · AG-09

En /implement: verifica que cada AC esté implementado, testeado y con evidencia. Veredicto ACCEPTED / CONDITIONAL / REJECTED por Use Case. Bloquea el merge si es REJECTED.

🧪

Lint + Tests bloqueantes

Hooks de pipeline (pre-commit-lint, spec-guard, e2e-gate) que impiden commit o merge con lint sucio o tests en rojo.

Self-Healing

Cuando una fase falla, el engine intenta repararse solo antes de pedir ayuda. Budget real: máx. ~8 auto-reparaciones por implementación y 2 intentos por fase; si 2 fases consecutivas fallan, se detiene.

1

Auto-fix

Nivel 1 — corrige lint, formato e imports automáticamente (p. ej. dart fix --apply, eslint --fix).

2

Patch

Nivel 2 — diagnostica y arregla la causa raíz: import faltante, tipo incorrecto, dependencia o path mal resuelto.

3

Rollback

Nivel 3 — rollback parcial: git stash, marca el checkpoint como fallido y reintenta la fase desde un estado limpio.

4

Intervención Humana

Nivel 4 — escala al desarrollador con diagnóstico (error_report.md) cuando la fase sigue fallando tras los reintentos.

Pipeline Integrity

Enforcement a nivel de hooks que hace imposible escribir código sin UC activo.

"El incidente embed-build (marzo 2026): un agente implementó 9 Use Cases sin el pipeline, dejando Trello vacío y sin trazabilidad. Ese fue el día que nacieron los HARD BLOCKS."

🛡️

spec-guard.sh bloquea Write/Edit en src/ sin UC activo

🚫

commit-spec-guard.sh bloquea commits en main/master

🎨

design-gate.sh bloquea UI sin diseños Stitch previos

💀

Anti-main guard: ERROR FATAL si se implementa en main

Multi-Backend

4 backends intercambiables con la misma interfaz (25 métodos). Migración bidireccional entre ellos.

📋
Trello Boards con US/UC/AC cards
✈️
Plane Cloud o self-hosted (CE)
📁
FreeForm JSON local, sin API externa
🐘
Native Postgres/Supabase, multi-tenant
☁️
SpecBox Cloud Panel web del ecosistema: observabilidad y gestión en cloud.specbox.build.

Servicios de Infraestructura

Patrones integrados para 5 servicios: cada uno con guías de configuración, best practices, y integración con el pipeline.

⚡ Supabase
🐘 Neon
💳 Stripe
🔥 Firebase
🔄 n8n

Stacks Soportados

💙 Flutter
⚛️ React
🐹 Go
🐍 Python
📜 Google Apps Script

Evolución del Engine

Cada versión es real y está en producción. Esto es lo último que ha cambiado.

v6.11.0 Self Update 2026-06-14 Versión actual
  • ▸ Chequeo de versión remota al arrancar
  • ▸ Diálogo accionable X→Y + comparación semver
  • ▸ Upgrade garantizado con verificación
  • ▸ Camino de divergencia con backup

¿Quieres SpecBox en tu equipo?

Escríbenos y te contamos cómo adoptarlo en tu flujo de trabajo.

jesus@embed.build
ver actividad →