OmniSpec
Menú

OMNISPEC / 0.8.1

De la intención al software verificado.

La guía de Spec-Driven Development: arquitectura, contratos y ciclo de vida de tu agente. Documentación oficial de OmniSpec 0.8.1.

En esta guía
InstalarConocer los archivosRevisar una entrega

El Manifiesto SDD: De la Alucinación a la Certeza

Los agentes de Inteligencia Artificial son extraordinarios implementando funciones puntuales, pero sufren de tres problemas crónicos: amnesia de contexto entre sesiones, sobreingeniería prematura (*overengineering*) y modificación no controlada de código adyacente (*code slop*).

OmniSpec introduce el estándar de Desarrollo Guiado por Especificaciones (Spec-Driven Development / SDD): el repositorio es la fuente de la verdad duradera. Ningún agente escribe una sola línea de código sin antes acordar un contrato formal, un plan proporcional y criterios de aceptación verificables con evidencia ejecutable.

Un motor determinista con arquitectura Zero Runtime Dependencies (dependencies: {}) que garantiza soberanía sobre tu código, reduce más del 70% del consumo de tokens y blinda tu proyecto contra regresiones silenciosas.

Punto de Partida: Quickstart en 30 Segundos

OmniSpec requiere Node.js ≥22.19.0 (Node 22 LTS o Node 24 Current) o Bun 1.1+. No descarga dependencias ajenas ni modifica variables globales del sistema.

Abre una terminal en la carpeta de tu proyecto y ejecuta el comando insignia. El flag --yes de npm acepta obtener el paquete oficial publicado en el canal latest, mientras que OmniSpec despliega un asistente interactivo con teclado para seleccionar tu idioma y tus herramientas de IA preferidas.

¿Prefieres otro gestor o instalación permanente? OmniSpec es compatible de forma nativa con pnpm, Bun, Yarn Modern y CLI global.

npx --yes omni-spec init

pnpm dlx omni-spec init

bunx omni-spec init

Dos Modos de Entrada: Proyecto Nuevo o Existente

Proyecto Nuevo: Inicializa en una carpeta vacía y abre tu editor con tu agente favorito (Cursor, Claude Code, Antigravity, Copilot, Codex, etc.). Escribe en el chat /omni-init o la invocación indicada: el agente te ayudará a conceptualizar el stack, la arquitectura y tu primera especificación sin tocar código a ciegas.

Proyecto Existente: Ejecuta omni-spec init en la raíz. El motor inspecciona automáticamente tus manifiestos y herramientas (Astro, Next.js, React, Svelte, Vue, Python, Go, Rust, Java, etc.) y detecta tus scripts de prueba y compilación como candidatos de verificación (NOT_RUN), respetando rigurosamente tu código existente.

Para pipelines de CI o automatización desatendida, añade --yes como argumento de OmniSpec junto con las banderas deseadas:

npx --yes omni-spec init --agent claude --lang es

npx --yes omni-spec init --yes --agent cursor --ui-components shadcn

La Anatomía del Repositorio de la Verdad

OmniSpec organiza la gobernanza del proyecto de forma visible y versionable en Git bajo el directorio specs/, complementado con archivos raíz estandarizados:

Cada archivo tiene una responsabilidad estricta: CONSTITUTION.md dicta las normas innegociables de ingeniería; specs/project-context.md preserva la memoria duradera de decisiones arquitectónicas; manifest.json gobierna el estado estructurado leíble por máquina, y cada carpeta 001-nombre/ encapsula el contrato, diseño y evidencia del trabajo.

├── CONSTITUTION.md              # Leyes de ingeniería inviolables
├── AGENTS.md                    # Directivas universales para agentes IA
├── CLAUDE.md                    # Sincronización gestionada para Claude Code
└── specs/
    ├── manifest.json            # Estado del proyecto y especificaciones activas
    ├── project-context.md       # Memoria destilada (MDD) y finops de contexto
    ├── checks.json              # Catálogo de quality gates automatizados
    ├── 001-feature-login/
    │   ├── spec.md              # Contrato EARS: propósito, alcance y criterios AC
    │   ├── plan.md              # Estrategia técnica y análisis de impacto
    │   ├── tasks.md             # Checklist atómico de implementación
    │   ├── acceptance.json      # Cobertura formal de criterios y evidencia
    │   └── verification.json    # Huella criptográfica y resultados de checks
    └── .omni/runtime/           # Motor determinista local (ignorado por Git)

CONSTITUTION.md: Las Leyes de Ingeniería

CONSTITUTION.md es el contrato ético y técnico que el agente de IA está obligado a acatar antes de proponer cualquier cambio. Aplica directivas innegociables:

Cirugía de Código (Minimal Touch): Prohibido reformatear o alterar código adyacente ajeno a la tarea. Fail-Fast Estricto: Prohibido envolver código en bloques try/catch defensivos que silencien excepciones devolviendo null. Cero Comentarios Tipo Loro: El código debe ser limpio y autoexplicativo.

Al actualizar OmniSpec con omni-spec update, tu constitución personalizada se preserva intacta y los cambios upstream se presentan como referencia comparativa.

Acto I: Explorar, Alinear y Aclarar

El ciclo de vida SDD comienza con alineación conversacional antes de redactar especificaciones formales:

omni-init: Reconoce el estado del proyecto, detecta herramientas, registra las capacidades reales de la sesión (renderizado visual, investigación web, herramientas de preguntas) y sella la línea base de contexto.

omni-discuss: Espacio dialéctico para explorar la necesidad, comparar enfoques técnicos y evaluar viabilidad sin escribir código prematuro.

omni-clarify: Detecta brechas de ambigüedad material mediante preguntas precisas. Si falta una decisión clave de producto o arquitectura, se resuelve y documenta aquí.

Acto II: Formalizar, Planificar y Desglosar

Una vez aclarada la intención, se establecen los contratos duraderos que guían la ejecución:

omni-specify: Redacta la especificación formal (spec.md) estructurando requerimientos y criterios de aceptación con sintaxis EARS (Easy Approach to Requirements Syntax). Cada criterio recibe un identificador único (ej. AC-01) y una tipificación clara (funcional, visual, accesibilidad, seguridad).

omni-plan: Conecta el diseño técnico con los criterios acordados, detallando cambios de interfaz, endpoints, contratos de datos y mitigación de riesgos.

omni-tasks: Desglosa el plan en un checklist de tareas atómicas e independientes, ordenadas secuencialmente para permitir implementación paso a paso.

Acto III: Implementar, Auditar y Converger

El último acto transforma los contratos en software funcional verificado con rigor científico:

omni-implement: Ejecuta la cirugía de código con enfoque minimalista, resolviendo tarea por tarea sin desviarse del alcance acordado.

omni-audit: Un subagente auditor independiente analiza la especificación y el código generado buscando trampas, checkboxes vacíos, comentarios de relleno o desviaciones constitucionales.

omni-converge: Reconcilia la evidencia ejecutable. verify ejecuta los quality gates y genera una huella criptográfica SHA-256 de los archivos; complete valida que todos los criterios estén cubiertos y no existan cambios espurios posteriores al snapshot.

Los Cuatro Arquetipos y Triaje Dinámico

En ingeniería de software no todo cambio es una 'Feature'. OmniSpec proporciona cuatro arquetipos con artefactos especializados:

feature (spec.md): Nueva funcionalidad o cambio de comportamiento. bugfix (bug.md, rca.md, fix.md): Diagnóstico estricto con reproducción, análisis de causa raíz (5 Whys) y prevención de regresiones. debt (audit.md, migration-plan.md): Reducción de deuda técnica o simplificación de dependencias. rfc (rfc.md): Registro duradero de decisiones arquitectónicas.

Triaje Dinámico (Fit v2): Permite ajustar la ceremonia al tamaño real del problema. Usa create --light para cambios quirúrgicos de 1 a 3 archivos (omite plan y tareas pesadas), y escala a standard o full automáticamente cuando aumenta el riesgo o la ambigüedad.

Artesanía de Software y Matriz de 4 Estados de UI

OmniSpec 0.8 erradica los clichés visuales y malos hábitos de los modelos de IA mediante el protocolo Zero-Slop Guard:

Cero Clichés de IA: Prohibidos los degradados azul/púrpura genéricos, resplandores difusos artificiales y el anidamiento excesivo de tarjetas con sombras (*card-itis*). Se prioriza la jerarquía visual limpia mediante tipografía y whitespace deliberado.

Matriz Obligatoria de 4 Estados: Toda vista interactiva debe contemplar explícitamente: 1. Loading (skeletons contextuales con CLS = 0), 2. Empty (explicación clara con llamada a la acción), 3. Error (mensaje comprensible con reintento), y 4. Protected (estado sin permisos o restringido).

Soporte nativo para kits modernos de componentes (shadcn, radix, headlessui, preline, flyonui) vía --ui-components y la guía de diseño del sistema en omni-spec guide design.

Perfiles de Dominio Regulados

Los perfiles inyectan controles de seguridad, privacidad y mejores prácticas específicas para sectores de alta exigencia técnica y regulatoria.

No imponen bases de datos ni arquitecturas forzadas para todos los proyectos; son revisiones de aplicabilidad que el agente evalúa en diálogo con el desarrollador. Puedes declarar un perfil con --profile o explorarlo durante el onboarding.

Tu Agente Favorito: 10 Adaptadores Estandarizados

OmniSpec no te ata a un único modelo o entorno. Genera instrucciones nativas y compatibles con la documentación oficial de los principales agentes de desarrollo:

Antigravity: Workspace skills en .agents/skills/ y subagente auditor en .agents/agents/omni-auditor.md. Claude Code: Skills en .claude/skills/ y sincronización gestionada en CLAUDE.md. Cursor: Skills en .cursor/skills/ y reglas de proyecto. Codex: Skills en .agents/skills/ con invocación $omni-init en AGENTS.md. Copilot, Kilo, OpenCode y Gemini CLI: Adaptadores específicos por host. Generic: Modo universal por prompts para cualquier terminal o LLM.

Google Antigravity
Instala nueve skills y la definición del auditor. El host debe confirmar su descubrimiento; un archivo instalado no demuestra que el auditor se haya ejecutado.
Inicio: /omni-init
.agents/skills/omni-*/SKILL.md + .agents/agents/omni-auditor.md
OpenCode
Menciona @omni-init en el prompt interactivo o deja que el agente active la skill según la tarea.
Inicio: @omni-init
.opencode/skills/omni-*/SKILL.md + AGENTS.md
Claude Code
Prepara las skills del proyecto para trabajar con Claude Code. Conserva contexto y especificaciones; las capacidades y permisos dependen de la sesión.
Inicio: /omni-init
.claude/skills/omni-*/SKILL.md + AGENTS.md
Cursor
Distribuye las skills y una regla de proyecto. Las reglas guían al agente; no son un bloqueo del sistema de archivos.
Inicio: /omni-init
.cursor/skills/omni-*/SKILL.md + .cursor/rules/omni-spec.mdc
VS Code / GitHub Copilot
Instala skills e instrucciones del repositorio. La invocación depende del soporte Agent Skills de tu host.
Inicio: /omni-init (Agent Skills)
.agents/skills/omni-*/SKILL.md + .github/copilot-instructions.md
Codex
Usa el selector de skills o $omni-init. Si no aparece, lee la ruta de la skill que muestra el instalador.
Inicio: $omni-init
.agents/skills/omni-*/SKILL.md + AGENTS.md
Kilo
Incluye skills y comandos Markdown en las rutas de Kilo. El descubrimiento real se comprueba en el editor.
Inicio: /omni-init
.kilo/skills/omni-*/SKILL.md + .kilo/commands/omni-*.md
Gemini CLI
Incluye skills y comandos TOML para Gemini CLI. No presupone las herramientas disponibles en tu sesión.
Inicio: /omni-init
.gemini/skills/omni-*/SKILL.md + .gemini/commands/omni-*.toml
Otra herramienta / Generic
Conserva nueve prompts completos para herramientas sin integración elegida. No registra comandos nativos.
Inicio: Lee specs/commands/omni-init.md
specs/commands/omni-*.md

Plugin Oficial para Google Antigravity

Además del modo workspace local, los desarrolladores en Google Antigravity pueden instalar el Plugin Global Oficial (paquete autónomo de ~540 KB).

El plugin proporciona inyección permanente de constitución (trigger: always_on) y un subagente auditor aislado (omni-auditor) disponible en cualquier proyecto sin duplicar archivos. Inicializa proyectos vinculados al plugin ejecutando omni-spec init --agent plugin.

npx --yes omni-spec plugin install

npx --yes omni-spec plugin status

npx --yes omni-spec init --agent plugin

Quality Gates y Evidencia Ejecutable

En OmniSpec, la palabra del agente no es suficiente: el cierre exige evidencia empírica. specs/checks.json cataloga los comandos de prueba y verificación por módulo con timeout y directorio de trabajo.

acceptance.json vincula cada criterio de aceptación a un comando ejecutado o a una observación manual fundamentada. verify ejecuta los checks y sella una huella criptográfica SHA-256 de los archivos; complete valida la integridad total y rechaza el cierre si hubo modificaciones posteriores o criterios pendientes.

La evidencia declarada permanece separada de los resultados ejecutados en máquina, garantizando máxima fidelidad técnica.

Bajo el Capó: Concurrencia e Integridad Atómica

specs/manifest.lock/ implementa un mecanismo de exclusión mutua basado en el algoritmo de panadería de Lamport para serializar escrituras concurrentes de estado entre procesos y subagentes.

Las operaciones de disco utilizan reemplazos atómicos con reintentos exponenciales (fs-retry.mjs) diseñados para mitigar bloqueos transitorios en entornos Windows causados por antivirus o sincronizadores en la nube.

Una arquitectura limpia de dependencias que asegura que OmniSpec funcione sin fricción tanto en estaciones de trabajo locales como en pipelines de CI/CD.

Actualizar una instalación

Ejecuta primero el diagnóstico desde la raíz del proyecto. Revisa la propuesta de actualización antes de aplicarla. init prepara una instalación; no migra otra versión.

npx --yes omni-spec doctor

npx --yes omni-spec update --dry-run

Si la propuesta corresponde a lo que buscas, ejecuta npx --yes omni-spec update. Conserva una copia de tus cambios y revisa los conflictos que indique el CLI; no uses --force como solución automática.

Si algo no funciona

  • La skill no aparece. Abre la raíz del proyecto, reinicia la herramienta y pide al agente que lea la ruta que imprimió el instalador. Consulta las rutas de cada integración.
  • La instalación se interrumpió. Ejecuta doctor y revisa update --dry-run. Una salida con error puede dejar escritura parcial.
  • Hay otra versión o instalación global. Comprueba qué CLI y qué instrucciones está leyendo el agente. El plugin global de Antigravity se gestiona por separado.
  • Un check falla o expira. Lee el comando, la carpeta de trabajo y su salida. Corrige la causa y repite la verificación; un fallo no cuenta como evidencia de aprobación.
  • No se puede copiar. Usa la acción «Seleccionar comando» y copia con el teclado. El contenido permanece visible para poder recuperarlo.

Consultar documentación de la versión en GitHub

Novedades