Skip to content

Comandos ​

Esta es la referencia de los comandos con barra (/) de OpenSpec. Estos comandos se invocan en la interfaz de chat de tu asistente de codificación con IA (por ejemplo, Claude Code, Cursor, Devin Desktop).

Para patrones de flujo de trabajo y cuándo usar cada comando, consulta Flujos de trabajo. Para los comandos de CLI, consulta CLI.

Estas páginas utilizan /opsx:<comando> como el nombre canónico. Algunas herramientas lo escriben de manera diferente: Cursor y GitHub Copilot registran /opsx-propose, mientras que Codex utiliza $openspec-propose. Por lo tanto, consulta Cómo invocar para tu herramienta específica. Los archivos que genera OpenSpec ya utilizan la forma correcta.

Referencia rápida ​

Ruta rápida predeterminada (perfil core) ​

ComandoPropósito
/opsx:proposeCrear un cambio y generar artefactos de planificación en un solo paso
/opsx:exploreAnalizar ideas antes de comprometerse con un cambio
/opsx:applyImplementar tareas del cambio
/opsx:updateRevisar los artefactos de planificación de un cambio y mantener su coherencia
/opsx:syncFusionar especificaciones delta en las especificaciones principales
/opsx:archiveArchivar un cambio completado

Comandos de flujo de trabajo expandido (selección de flujo de trabajo personalizado) ​

ComandoPropósito
/opsx:newIniciar una nueva estructura base para un cambio
/opsx:continueCrear el siguiente artefacto basado en dependencias
/opsx:ffAvance rápido: crear todos los artefactos de planificación a la vez
/opsx:verifyValidar que la implementación coincida con los artefactos
/opsx:bulk-archiveArchivar múltiples cambios a la vez
/opsx:onboardTutorial guiado a través del flujo de trabajo completo

El perfil global predeterminado es core. Para habilitar los comandos de flujo de trabajo expandido, ejecuta openspec config profile, selecciona flujos de trabajo y luego ejecuta openspec update en tu proyecto.

Referencia de comandos ​

/opsx:propose ​

Crea un nuevo cambio y genera los artefactos de planificación en un solo paso. Este es el comando de inicio predeterminado en el perfil core.

Sintaxis:

text
/opsx:propose [change-name-or-description]

Argumentos:

ArgumentoObligatorioDescripción
change-name-or-descriptionNoNombre en formato kebab-case o descripción del cambio en lenguaje natural

Qué hace:

  • Crea openspec/changes/<change-name>/
  • Genera los artefactos necesarios antes de la implementación (para spec-driven: propuesta, especificaciones, diseño, tareas)
  • Se detiene cuando el cambio está listo para /opsx:apply

Ejemplo:

text
You: /opsx:propose add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     ✓ proposal.md
     ✓ specs/ui/spec.md
     ✓ design.md
     ✓ tasks.md
     Ready for implementation. Run /opsx:apply.

Consejos:

  • Úsalo para la ruta de extremo a extremo más rápida
  • Si deseas un control paso a paso de los artefactos, activa los flujos de trabajo ampliados y usa /opsx:new + /opsx:continue

/opsx:explore ​

Empieza aquí si tienes dudas. Explore es un compañero de reflexión sin riesgo: lee tu base de código, compara opciones y convierte una idea vaga en un plan concreto antes de que exista cualquier cambio. Viene incluido en el perfil predeterminado. Para el caso completo y más ejemplos, consulta la guía Explore First.

Reflexiona sobre ideas, investiga problemas y aclara requisitos antes de comprometerte con un cambio.

Sintaxis:

/opsx:explore [topic]

Argumentos:

ArgumentoObligatorioDescripción
topicNoLo que deseas explorar o investigar

Qué hace:

  • Abre una conversación exploratoria sin estructura requerida
  • Investiga la base de código para responder preguntas
  • Compara opciones y enfoques
  • Crea diagramas visuales para aclarar el pensamiento
  • Puede transicionar a /opsx:propose (predeterminado) o /opsx:new (flujo de trabajo ampliado) cuando los hallazgos se cristalizan

Ejemplo:

text
You: /opsx:explore

AI:  What would you like to explore?

You: How should we handle authentication for the mobile app?

AI:  Let me investigate your current auth setup...
     [Analyzes codebase]

     I see you're using session-based auth for the web app.
     For mobile, we have three main options:

     1. JWT tokens (stateless, works offline)
     2. OAuth2 (if you need third-party login)
     3. Extend current sessions (simpler, but requires connectivity)

     Your API already has CORS configured. Which direction interests you?

You: Let's go with JWT. Can we start a change for that?

AI:  Ready when you are. Run /opsx:propose add-jwt-auth to begin.

Consejos:

  • Úsalo cuando los requisitos no estén claros o necesites investigar
  • No se crean artefactos durante la exploración
  • Es útil para comparar múltiples enfoques antes de decidir
  • Puede leer archivos y buscar en la base de código

/opsx:new ​

Inicia un nuevo andamiaje de cambio. Crea la carpeta del cambio y espera a que generes los artefactos con /opsx:continue o /opsx:ff.

Este comando forma parte del conjunto de flujos de trabajo ampliados (no incluido en el perfil predeterminado core).

Sintaxis:

/opsx:new [change-name] [--schema <schema-name>]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoNombre para la carpeta del cambio (se solicitará si no se proporciona)
--schemaNoEsquema de flujo de trabajo a usar (predeterminado: desde la configuración o spec-driven)

Qué hace:

  • Crea el directorio openspec/changes/<change-name>/
  • Crea el archivo de metadatos .openspec.yaml en la carpeta del cambio
  • Muestra la primera plantilla de artefacto lista para su creación
  • Solicita el nombre del cambio y el esquema si no se proporcionan

Qué crea:

openspec/changes/<change-name>/
└── .openspec.yaml    # Change metadata (schema, created date)

Ejemplo:

You: /opsx:new add-dark-mode

AI:  Created openspec/changes/add-dark-mode/
     Schema: spec-driven

     Ready to create: proposal
     Use /opsx:continue to create it, or /opsx:ff to create all artifacts.

Consejos:

  • Usa nombres descriptivos: add-feature, fix-bug, refactor-module
  • Evita nombres genéricos como update, changes, wip
  • El esquema también se puede configurar en la configuración del proyecto (openspec/config.yaml)

/opsx:continue ​

Crea el siguiente artefacto en la cadena de dependencias. Crea un artefacto a la vez para un progreso incremental.

Sintaxis:

/opsx:continue [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio continuar (se infiere del contexto si no se proporciona)

Qué hace:

  • Consulta el grafo de dependencias de artefactos
  • Muestra qué artefactos están listos y cuáles están bloqueados
  • Crea el primer artefacto disponible
  • Lee los archivos de dependencia para obtener contexto
  • Muestra qué se vuelve disponible después de la creación

Ejemplo:

You: /opsx:continue

AI:  Change: add-dark-mode

     Artifact status:
     ✓ proposal    (done)
     ◆ specs       (ready)
     ◆ design      (ready)
     ○ tasks       (blocked - needs: specs, design)

     Creating specs...

     [Reads proposal.md, creates specs based on requirements]

     ✓ Created openspec/changes/add-dark-mode/specs/ui/spec.md

     Now available: design
     Run /opsx:continue to create the next artifact.

Consejos:

  • Úsalo cuando quieras revisar cada artefacto antes de continuar
  • Es útil para cambios complejos donde deseas tener control
  • Varios artefactos pueden volverse disponibles simultáneamente
  • Puedes editar los artefactos creados antes de continuar

/opsx:ff ​

Avanza rápidamente en la creación de artefactos. Crea todos los artefactos de planificación de una vez.

Sintaxis:

/opsx:ff [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio avanzar rápidamente (se infiere del contexto si no se proporciona)

Qué hace:

  • Crea todos los artefactos en orden de dependencia
  • Rastrea el progreso mediante una lista de tareas
  • Se detiene cuando todos los artefactos apply-required están completos
  • Lee cada dependencia antes de crear el siguiente artefacto

Ejemplo:

You: /opsx:ff add-dark-mode

AI:  Fast-forwarding add-dark-mode...

     ✓ Creating proposal.md
     ✓ Creating specs/ui/spec.md
     ✓ Creating design.md
     ✓ Creating tasks.md

     All planning artifacts complete!
     Ready for implementation. Run /opsx:apply to begin.

Consejos:

  • Úsalo cuando tengas una imagen clara de lo que estás construyendo
  • Más rápido que /opsx:continue para cambios sencillos
  • Aún puedes editar los artefactos después
  • Es útil para funciones pequeñas a medianas

/opsx:apply ​

Implementa las tareas del cambio. Trabaja a través de la lista de tareas, escribiendo código y marcando elementos como completados.

Sintaxis:

/opsx:apply [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio implementar (se infiere del contexto si no se proporciona)

Qué hace:

  • Lee tasks.md y identifica tareas incompletas
  • Trabaja las tareas una por una
  • Escribe código, crea archivos y ejecuta pruebas según sea necesario
  • Marca las tareas como completadas con casillas [x]

Ejemplo:

You: /opsx:apply

AI:  Implementing add-dark-mode...

     Reading tasks.md:
     - [ ] 1.1 Create ThemeContext
     - [ ] 1.2 Add CSS custom properties
     - [ ] 1.3 Implement localStorage persistence

     Working on 1.1: Create ThemeContext...
     [Creates src/context/ThemeContext.tsx]

     ✓ 1.1 Complete

     Working on 1.2: Add CSS custom properties...
     [Updates src/styles/globals.css]

     ✓ 1.2 Complete
     ...

Consejos:

  • Puede reanudar donde lo dejaste si se interrumpe
  • Úsalo para cambios en paralelo especificando el nombre del cambio
  • El estado de finalización se rastrea en las casillas de tasks.md

/opsx:update ​

Revisa los artefactos de planificación existentes de un cambio y los mantiene coherentes entre sí. Solo artefactos de planificación: nunca edita código.

Sintaxis:

text
/opsx:update [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio actualizar (se infiere del contexto si no se proporciona)

Qué hace:

  • Lee los artefactos del cambio mediante openspec status --change <name> --json
  • Aplica la revisión solicitada, o revisa los artefactos en busca de contradicciones si no se especificó una
  • Armoniza los demás artefactos existentes en cualquier dirección (una edición de diseño puede repercutir en la propuesta)
  • Confirma cada edición contigo antes de escribirla, un artefacto a la vez
  • Termina recomendando el siguiente paso: /opsx:continue (artefactos faltantes), /opsx:apply (llevar un plan revisado al código) o /opsx:archive (todo listo)

Ejemplo:

text
You: /opsx:update add-dark-mode - we're storing the theme in a cookie now, not localStorage

AI:  Reading add-dark-mode artifacts...

     The design references localStorage in two places; tasks 1.3 covers
     localStorage persistence; the proposal doesn't mention storage.

     Proposed revisions:
     1. design.md - swap localStorage decision for cookie storage
     2. tasks.md - reword task 1.3 to cookie persistence

     Apply revision 1? (design.md)

Consejos:

  • No creará artefactos faltantes: eso es /opsx:continue
  • Si el cambio ya fue implementado, continúa con /opsx:apply para que el código coincida con el plan revisado
  • Si tu revisión cambia la intención del cambio, empieza de nuevo con un cambio nuevo (consulta When to Update vs. Start Fresh)

/opsx:verify ​

Valida que la implementación coincida con los artefactos del cambio. Verifica completitud, corrección y coherencia.

Sintaxis:

/opsx:verify [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio verificar (se infiere del contexto si no se proporciona)

Qué hace:

  • Verifica tres dimensiones de calidad de implementación
  • Busca evidencia de implementación en la base de código
  • Informa sobre problemas categorizados como CRITICAL, WARNING o SUGGESTION
  • No bloquea el archivo, pero muestra los problemas

Dimensiones de verificación:

DimensiónQué valida
CompletitudTodas las tareas completadas, todos los requisitos implementados, escenarios cubiertos
CorrecciónLa implementación coincide con la intención de la especificación, casos límite manejados
CoherenciaLas decisiones de diseño reflejadas en el código, patrones consistentes

Ejemplo:

You: /opsx:verify

AI:  Verifying add-dark-mode...

     COMPLETENESS
     ✓ All 8 tasks in tasks.md are checked
     ✓ All requirements in specs have corresponding code
     ⚠ Scenario "System preference detection" has no test coverage

     CORRECTNESS
     ✓ Implementation matches spec intent
     ✓ Edge cases from scenarios are handled
     ✓ Error states match spec definitions

     COHERENCE
     ✓ Design decisions reflected in code structure
     ✓ Naming conventions consistent with design.md
     ⚠ Design mentions "CSS variables" but implementation uses Tailwind classes

     SUMMARY
     ─────────────────────────────
     Critical issues: 0
     Warnings: 2
     Ready to archive: Yes (with warnings)

     Recommendations:
     1. Add test for system preference detection
     2. Update design.md to reflect Tailwind usage, or refactor to use CSS variables

Consejos:

  • Ejecútalo antes de archivar para detectar discrepancias a tiempo
  • Las advertencias no bloquean el archivo, pero indican posibles problemas
  • Es útil para revisar el trabajo de la IA antes de confirmar
  • Puede revelar desviaciones entre los artefactos y la implementación

/opsx:sync ​

Comando opcional. Fusiona las especificaciones delta de un cambio en las especificaciones principales. El archivo solicitará sincronizar si es necesario, por lo que generalmente no necesitas ejecutarlo manualmente.

Sintaxis:

/opsx:sync [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio sincronizar (se infiere del contexto si no se proporciona)

Qué hace:

  • Lee las especificaciones delta de la carpeta del cambio
  • Analiza las secciones ADDED/MODIFIED/REMOVED/RENAMED
  • Fusiona los cambios en el directorio principal openspec/specs/
  • Preserva el contenido existente no mencionado en la delta
  • No archiva el cambio (permanece activo)

Ejemplo:

text
You: /opsx:sync

AI:  Syncing add-dark-mode delta specs...

     Reading: openspec/changes/add-dark-mode/specs/ui/spec.md
     Target:  openspec/specs/ui/spec.md

     Changes to apply:
     ✓ ADDED: Theme Selection requirement (2 scenarios)
     ✓ ADDED: Accessibility requirement (1 scenario)

     Merging...
     ✓ openspec/specs/ui/spec.md updated

     Change remains active. Run /opsx:archive when ready to complete.

Cuándo usarlo manualmente:

Escenario¿Usar sync?
Cambio de larga duración, deseas las especificaciones en el principal antes de archivarSí
Múltiples cambios en paralelo necesitan las especificaciones base actualizadasSí
Deseas previsualizar/revisar la fusión por separadoSí
Cambio rápido, yendo directo al archivoNo (el archivo lo gestiona)

Consejos:

  • La sincronización es inteligente, no es copiar y pegar
  • Puede agregar escenarios a requisitos existentes sin duplicarlos
  • El cambio permanece activo después de la sincronización (no se archiva)
  • La mayoría de los usuarios nunca necesitará llamarlo directamente: el archivo lo solicita si es necesario

/opsx:archive ​

Archiva un cambio completado. Finaliza el cambio y lo mueve a la carpeta de archivo.

Sintaxis:

/opsx:archive [change-name]

Argumentos:

ArgumentoObligatorioDescripción
change-nameNoQué cambio archivar (se infiere del contexto si no se proporciona)

Qué hace:

  • Verifica el estado de finalización de los artefactos
  • Verifica la finalización de tareas (avisa si están incompletas)
  • Ofrece sincronizar las especificaciones delta si aún no se han sincronizado
  • Mueve la carpeta del cambio a openspec/changes/archive/YYYY-MM-DD-<name>/
  • Preserva todos los artefactos como registro de auditoría

Ejemplo:

text
You: /opsx:archive

AI:  Archiving add-dark-mode...

     Artifact status:
     ✓ proposal.md exists
     ✓ specs/ exists
     ✓ design.md exists
     ✓ tasks.md exists (8/8 tasks complete)

     Delta specs: Not yet synced
     → Sync now? (recommended)

You: Yes

AI:  ✓ Synced specs to openspec/specs/ui/spec.md
     ✓ Moved to openspec/changes/archive/2025-01-24-add-dark-mode/

     Change archived successfully.

Consejos:

  • El archivo no bloqueará por tareas incompletas, pero emitirá una advertencia
  • Las especificaciones delta pueden sincronizarse durante el archivo o antes
  • Los cambios archivados se preservan para el historial
  • Usa /opsx:verify primero para detectar problemas

/opsx:bulk-archive ​

Archiva múltiples cambios completados a la vez. Gestiona conflictos de especificaciones entre cambios.

Sintaxis:

/opsx:bulk-archive [change-names...]

Argumentos:

ArgumentoObligatorioDescripción
change-namesNoCambios específicos a archivar (se solicitará seleccionar si no se proporcionan)

Qué hace:

  • Lista todos los cambios completados
  • Valida cada cambio antes de archivar
  • Detecta conflictos de especificaciones entre cambios
  • Resuelve conflictos verificando lo que realmente está implementado
  • Archiva en orden cronológico

Ejemplo:

You: /opsx:bulk-archive

AI:  Found 3 completed changes:
     - add-dark-mode (8/8 tasks complete)
     - fix-login-bug (3/3 tasks complete)
     - update-footer (2/2 tasks complete)

     Checking for spec conflicts...
     ⚠ add-dark-mode and update-footer both touch specs/ui/

     Inspecting codebase to resolve...
     Both changes are implemented. Will merge in chronological order:
     1. add-dark-mode (created Jan 20)
     2. update-footer (created Jan 22)

     Archive all 3 changes?

You: Yes

AI:  ✓ Archived add-dark-mode
     ✓ Archived fix-login-bug
     ✓ Archived update-footer
     Specs merged: add-dark-mode → update-footer

Consejos:

  • Es útil para flujos de trabajo en paralelo
  • La resolución de conflictos es agéntica (verifica la base de código)
  • Los cambios se archivan en orden de creación
  • Solicita confirmación antes de sobrescribir contenido de especificaciones

/opsx:onboard ​

Introducción guiada a través del flujo de trabajo completo de OpenSpec. Un tutorial interactivo que usa tu base de código real.

Sintaxis:

/opsx:onboard

Qué hace:

  • Recorre un ciclo completo de flujo de trabajo con narración
  • Escanea tu base de código en busca de oportunidades reales de mejora
  • Crea un cambio real con artefactos reales
  • Implementa trabajo real (cambios pequeños y seguros)
  • Archiva el cambio completado
  • Explica cada paso a medida que ocurre

Fases:

  1. Bienvenida y análisis de la base de código
  2. Búsqueda de una oportunidad de mejora
  3. Creación de un cambio (/opsx:new)
  4. Redacción de la propuesta
  5. Creación de especificaciones
  6. Redacción del diseño
  7. Creación de tareas
  8. Implementación de tareas (/opsx:apply)
  9. Verificación de la implementación
  10. Archivo del cambio
  11. Resumen y próximos pasos

Ejemplo:

You: /opsx:onboard

AI:  Welcome to OpenSpec!

     I'll walk you through the complete workflow using your actual codebase.
     We'll find something small to improve, create a proper change for it,
     implement it, and archive it.

     Let me scan your codebase for opportunities...

     [Analyzes codebase]

     I found a few things we could work on:
     1. Add input validation to the contact form
     2. Improve error messages in the auth flow
     3. Add loading states to async buttons

     Which interests you? (or suggest something else)

Consejos:

  • Es ideal para nuevos usuarios que aprenden el flujo de trabajo
  • Usa código real, no ejemplos de juguete
  • Crea un cambio real que puedes conservar o descartar
  • Toma entre 15 y 30 minutos completarlo

Sintaxis de comandos según la herramienta de IA ​

Diferentes herramientas de IA utilizan una sintaxis de comandos ligeramente diferente. Usa el formato que coincida con tu herramienta:

Archivo de comandos de tu herramientaEjemplo de sintaxisHerramientas de ejemplo
.../commands/opsx/<id>.*/opsx:propose, /opsx:applyClaude Code, Gemini CLI, Crush
.../opsx-<id>.*/opsx-propose, /opsx-applyCursor, Devin Desktop, Copilot (IDE), Trae, Oh My Pi
none — solo habilidades/openspec-propose, /openspec-apply-changeCodeArts, ForgeCode, Hermes, MiniMax Code, Mistral Vibe, Zed Agent, .agents compartidos
none — Kimi Code/skill:openspec-proposeKimi Code
none — Codex CLI$openspec-proposeCodex

Devin Desktop vs Devin Local: los archivos .devin/workflows/opsx-*.md le dan a Devin Desktop /opsx-propose. Devin Local no tiene flujos de trabajo — usa las habilidades que OpenSpec escribe en .devin/skills/, por ejemplo /openspec-propose, que funcionan en ambos agentes.

La intención es la misma en todas las herramientas, pero la forma en que se presentan los comandos puede diferir según la integración. Cómo invocar lista cada herramienta compatible; esta tabla solo muestra ejemplos de cada forma.

Nota: Los comandos de GitHub Copilot (.github/prompts/*.prompt.md) solo están disponibles en extensiones de IDE (VS Code, JetBrains, Visual Studio). GitHub Copilot CLI no admite actualmente archivos de prompt personalizados — consulta Herramientas compatibles para obtener detalles y soluciones alternativas.


Comandos heredados ​

Estos comandos utilizan el flujo de trabajo más antiguo "todo de una vez". Siguen funcionando, pero se recomiendan los comandos OPSX.

ComandoQué hace
/openspec:proposalCrea todos los artefactos de una vez (propuesta, especificaciones, diseño, tareas)
/openspec:applyImplementa el cambio
/openspec:archiveArchiva el cambio

Cuándo usar comandos heredados:

  • Proyectos existentes que usan el flujo de trabajo antiguo
  • Cambios simples donde no necesitas creación incremental de artefactos
  • Preferencia por el enfoque de todo o nada

Migración a OPSX: Los cambios heredados pueden continuarse con comandos OPSX. La estructura de artefactos es compatible.


Solución de problemas ​

"Cambio no encontrado" ​

El comando no pudo identificar en qué cambio trabajar.

Soluciones:

  • Especifica el nombre del cambio explícitamente: /opsx:apply add-dark-mode
  • Verifica que la carpeta del cambio exista: openspec list
  • Verifica que estás en el directorio correcto del proyecto

"No hay artefactos listos" ​

Todos los artefactos están completos o bloqueados por dependencias faltantes.

Soluciones:

  • Ejecuta openspec status --change <name> para ver qué está bloqueando
  • Comprueba si existen los artefactos requeridos
  • Crea primero los artefactos de dependencia faltantes

"Esquema no encontrado" ​

El esquema especificado no existe.

Soluciones:

  • Lista los esquemas disponibles: openspec schemas
  • Verifica la ortografía del nombre del esquema
  • Crea el esquema si es personalizado: openspec schema init <name>

Comandos no reconocidos ​

La herramienta de IA no reconoce los comandos de OpenSpec.

Soluciones:

  • Asegúrate de que OpenSpec esté inicializado: openspec init
  • Regenera las habilidades: openspec update
  • Verifica que exista el directorio .claude/skills/ (para Claude Code)
  • Reinicia tu herramienta de IA para detectar nuevas habilidades

Artefactos que no se generan correctamente ​

La IA crea artefactos incompletos o incorrectos.

Soluciones:

  • Añade contexto del proyecto en openspec/config.yaml
  • Añade reglas por artefacto para una guía específica
  • Proporciona más detalles en tu descripción de cambio
  • Usa /opsx:continue en lugar de /opsx:ff para tener más control

Próximos pasos ​

  • Workflows - Patrones comunes y cuándo usar cada comando
  • CLI - Comandos de terminal para gestión y validación
  • Customization - Crea esquemas y flujos de trabajo personalizados