¿Qué es OpenSpec? Instalación y flujos de trabajo

OpenSpec es un framework ligero de desarrollo guiado por especificaciones (Spec-Driven Development). Añade una capa de acuerdo entre tú y tu asistente de programación con IA: primero se escribe qué hay que construir, se revisa el plan y solo después se escribe código, en lugar de dejar los requisitos únicamente en el historial del chat. Tiene licencia MIT, es compatible con más de 30 herramientas de programación con IA y el propio flujo de trabajo de HagiCode se basa en él. Esta página es el camino más corto para instalarlo y ejecutar un primer cambio completo; las guías completas se mantienen en un sitio aparte.

Conceptos clave

OpenSpec se construye sobre cinco ideas:

1. Las especificaciones (specs) son la fuente de la verdad. Describen cómo se comporta el sistema ahora, viven en openspec/specs/, se organizan por dominio y se componen de requisitos y escenarios.
2. Un cambio (change) es una unidad de trabajo. Para añadir, modificar o eliminar comportamiento, creas una carpeta dentro de openspec/changes/ que reúne la propuesta, el diseño, la lista de tareas y las ediciones de las especificaciones de ese trabajo.
3. Las especificaciones delta describen solo lo que cambia. Dentro de un cambio no reescribes la especificación completa, sino que escribes ADDED, MODIFIED y REMOVED, y por eso funciona bien para editar sistemas existentes.
4. Los artefactos se apoyan unos en otros. proposal (por qué) → specs (qué) → design (cómo) → tasks (pasos) → implementación. Son facilitadores, no barreras, y puedes volver a cualquiera de ellos.
5. Archivar devuelve el cambio a la verdad. Cuando el trabajo termina, las especificaciones delta se fusionan con las principales y la carpeta del cambio pasa a changes/archive/ con la fecha.

Instalación

Necesitas Node.js 20.19.0 o superior (para otros componentes de HagiCode se recomienda 24 o superior; consulta Instalación de Node.js).

npm install -g @fission-ai/openspec@latest
openspec --version

En macOS y Linux también puedes usar Homebrew: brew install openspec. pnpm, yarn (1.x) y bun también pueden instalarlo de forma global, pero OpenSpec sigue ejecutándose sobre Node.js.

Después entra en el directorio de tu proyecto e inicialízalo:

cd your-project
openspec init

La inicialización pregunta qué herramientas de IA usas y genera para ellas archivos de skills o de comandos. Para omitir las preguntas, usa openspec init --tools claude,cursor; los ID de las herramientas están en Herramientas compatibles.

Tu primer cambio completo

Los comandos con barra se escriben en el chat de tu asistente de IA, no en la terminal:

/opsx:explore            # ¿aún no lo tienes claro? La IA lee el código y sopesa opciones
/opsx:propose add-dark-mode   # crea la carpeta del cambio: proposal, specs, design, tasks
/opsx:apply              # implementa la lista de tareas
/opsx:archive            # archiva; las especificaciones delta se fusionan con las principales

/opsx:propose crea openspec/changes/add-dark-mode/ con proposal.md, specs/, design.md y tasks.md. Las especificaciones son Markdown sencillo, sin sintaxis especial:

## ADDED Requirements

### Requirement: Theme selection
The app SHALL let users switch between light and dark themes,
defaulting to the system preference.

#### Scenario: User toggles dark mode
- **WHEN** the user clicks the theme toggle
- **THEN** the app switches to dark mode and persists the choice

Las escribe la IA y tú revisas el plan antes de que se escriba cualquier código. El perfil predeterminado incluye propose, explore, apply, update, sync y archive. Para el flujo ampliado (new, continue, ff, verify, bulk-archive y más), elígelo con openspec config profile y aplícalo con openspec update.

Los nombres de los comandos varían ligeramente según el asistente

/opsx:propose es la forma canónica. En Cursor y GitHub Copilot es /opsx-propose, en Amazon Q es @opsx-propose y en Codex es $openspec-propose. openspec init muestra la forma correcta para las herramientas que elegiste.

Actualización

npm install -g @fission-ai/openspec@latest   # actualiza el paquete
openspec update                              # refresca los archivos de instrucciones de IA en cada proyecto

Si lo instalaste con Homebrew, usa brew upgrade openspec.

Problemas frecuentes

• openspec: command not found: el directorio global de npm no está en el PATH. Ejecuta npm prefix -g; en macOS y Linux añade al PATH el subdirectorio bin/ de ese directorio, y en Windows el propio directorio.
• «Requires Node.js 20.19.0 or higher»: comprueba la versión con node --version y actualiza Node.js.
• /opsx:propose no aparece en el chat: asegúrate de escribirlo en el asistente y no en la terminal, ejecuta openspec update para regenerar los archivos y reinicia el asistente. Las herramientas que solo admiten skills, como Codex, necesitan la forma $openspec-propose.
• La inicialización no configuró tu herramienta: ejecuta openspec init de nuevo o pasa --tools.

Documentación completa

Abrir la documentación de OpenSpec en español

• Instalar OpenSpec
• Primeros pasos
• Flujos de trabajo
• Solución de problemas

Lecturas adicionales

• Si dudas entre OpenSpec y Spec Kit de GitHub, lee Spec Kit frente a OpenSpec.
• La práctica de HagiCode sobre OpenSpec: Optimizar la eficacia de cada fase de OpenSpec con diferentes Agentes: Resumen de la práctica de HagiCode y MonoSpecs ¿Qué es y por qué se dice que es una actualización y extensión de OpenSpec.