Solución de problemas

Correcciones concretas para problemas concretos. Cada entrada nombra un síntoma, explica la causa probable en una frase y te da la solución. Si no ves tu problema aquí, la FAQ puede ayudar, y el Discord definitivamente lo hará.

Instalación y configuración

openspec: command not found

El CLI no está instalado, o tu shell no puede encontrarlo. Instálalo globalmente y verifica:

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

Si se instaló pero aún no se encuentra, es probable que el directorio bin global de npm no esté en tu PATH. Ejecuta npm prefix -g para ver dónde viven los paquetes globales: en macOS y Linux los binarios están en el directorio bin/, y en Windows están directamente en él. Asegúrate de que esa ruta esté en tu PATH. (npm bin -g se eliminó en npm 9.)

Si usaste la instalación asistida por IA, este es el punto de traspaso esperado: ese prompt le indica a tu asistente que te muestre el cambio de PATH en lugar de editar por sí mismo tus archivos de inicio del shell.

"Requires Node.js 20.19.0 or higher"

OpenSpec se ejecuta en Node 20.19.0+. Verifica tu versión y actualiza si es necesario:

node --version

Si usas bun para instalar OpenSpec, ten en cuenta que OpenSpec aún se ejecuta en Node, por lo que necesitas Node 20.19.0+ disponible en tu PATH independientemente. Consulta Instalación.

openspec init no configuró mi herramienta de IA

Init pregunta qué herramientas configurar. Si omitiste tu herramienta o quieres añadir otra, simplemente ejecútalo de nuevo, o usa la forma no interactiva:

openspec init --tools claude,cursor

La lista completa de IDs de herramientas está en Herramientas Soportadas. Usa --tools all para todo, --tools none para omitir la configuración de herramientas.

Los comandos no aparecen

Si /opsx:propose (o el equivalente de tu herramienta) no aparece o no hace nada, revisa esta lista. Están ordenados de más rápido de comprobar a menos.

1. Puede que estés en el lugar equivocado. Los comandos de barra van en el chat de tu asistente de IA, no en tu terminal. Si escribiste /opsx:propose en tu shell, ese es el problema. Consulta Cómo Funcionan los Comandos.

2. Regenera los archivos. Desde la raíz de tu proyecto:

   openspec update

   Esto reescribe los archivos de skill y de comando para cada herramienta que hayas configurado.

   Los archivos de instrucción provienen del CLI instalado, por lo que un CLI desactualizado informa que todo está al día sin escribir nunca los flujos de trabajo más nuevos. openspec update ahora comprueba eso y ofrece actualizar: acepta la oferta si la ves.

3. Reinicia tu asistente. La mayoría de las herramientas escanean habilidades y comandos al inicio. Una ventana nueva a menudo lo resuelve.

4. Confirma que los archivos existen. Para Claude Code, verifica que .claude/skills/ contenga carpetas openspec-*. Otras herramientas usan sus propios directorios, todos listados en Herramientas Soportadas.

5. Verifica que inicializaste este proyecto. Las habilidades se escriben por proyecto. Si clonaste un repositorio o cambiaste de carpeta, ejecuta openspec init (o openspec update) allí.

6. Confirma que tu herramienta soporta archivos de comando. Codex, CodeArts, ForgeCode, Hermes, Kimi Code, Mistral Vibe, Zed Agent y el objetivo compartido .agents no reciben archivos de comando opsx-* generados; usan invocaciones basadas en skills en su lugar, así que /opsx nunca autocompletará para ellos. Escribe $openspec-propose en Codex, /skill:openspec-propose en Kimi Code y /openspec-propose en el resto. El objetivo compartido .agents es neutral al proveedor, por lo que /openspec-propose es la forma común, no una garantizada: si tu asistente no responde a ello, consulta sus propios documentos sobre cómo invoca una skill. Amazon Q sí recibe archivos de comando, pero los carga en su biblioteca de prompts en lugar de su menú de barra: escribe @opsx-propose allí, no /opsx. La forma de cada herramienta está listada en Cómo Invocar.

Trabajando con cambios

"Change not found"

El comando no pudo determinar qué cambio querías. Nómbralo explícitamente, o verifica qué existe:

openspec list                    # ver cambios activos
/opsx:apply add-dark-mode        # nombrar el cambio en el chat

También confirma que estás en el directorio correcto del proyecto.

"No artifacts ready"

Cada artefacto ya está creado o bloqueado esperando una dependencia. Mira qué está bloqueando:

openspec status --change <name>

Luego crea primero la dependencia que falta. Recuerda el orden: la propuesta habilita las specs y el diseño; las specs y el diseño juntos habilitan las tareas.

openspec validate informa advertencias o errores

La validación revisa tus specs y cambios para detectar problemas estructurales. Lee el mensaje: nombra el archivo y el problema.

openspec validate <name>           # validar un elemento
openspec validate --all            # validar todo
openspec validate --all --strict   # comprobaciones más estrictas, bueno para CI
openspec validate --archived       # fallar si los cambios archivados tienen tareas sin comprobar

Las causas comunes son una sección requerida faltante (como una spec sin escenarios) o un encabezado de delta mal formado. Corrige el archivo y vuelve a ejecutar. La referencia del CLI documenta el formato de salida.

Un mensaje merece su propia nota:

MODIFIED "<requirement>" omite escenario(s) que la spec actual aún tiene: "<scenario>"

Un requisito MODIFIED reemplaza todo el bloque de requisito, por lo que debe incluir cada escenario que sobreviva al cambio, no solo los que editaste. Copia los escenarios nombrados desde openspec/specs/<capability-path>/spec.md de vuelta al delta, preservando los directorios de dominio en la ruta. Esto suele aparecer en un cambio más antiguo después de que el cambio de otra persona añadiera un escenario al mismo requisito: archivar rechaza ese cambio de cualquier manera, y la validación ahora lo dice antes de que lo implementes.

La IA creó artefactos incompletos o incorrectos

La IA no tenía suficiente contexto. Algunas palancas ayudan:

• Añade contexto del proyecto en openspec/config.yaml para que tu stack y convenciones se inyecten en cada solicitud. Consulta Personalización.
• Añade rules: por artefacto para obtener orientación que solo aplique, por ejemplo, a las specs.
• Da una descripción más detallada cuando propongas.
• Usa el /opsx:continue expandido para crear un artefacto a la vez y revisar cada uno, en lugar de /opsx:ff que los hace todos a la vez.

El archivo no termina, o advierte sobre tareas incompletas

El archivo no bloqueará por tareas incompletas, pero te advierte, porque archivar normalmente significa que el trabajo está hecho. Si las tareas quedan a propósito (estás presentando un cambio parcial), procede. De lo contrario, termina las tareas primero. Archivar también ofrecerá sincronizar tus specs delta en las specs principales si aún no las has sincronizado; di que sí a menos que tengas una razón para no hacerlo.

"User force closed the prompt with 0 null"

Algo ejecutó openspec archive donde nada puede responder una pregunta: un agente de IA llamándolo desde una herramienta, un trabajo de CI o cualquier shell con stdin cerrado. Archive pide hasta tres confirmaciones, y una que no se puede responder solía fallar con ese mensaje crudo.

Pasa --yes para responderlas de antemano:

openspec archive <change-name> --yes

Mantén cualquier bandera que ya estuvieras pasando: --skip-specs y --no-validate cambian lo que hace archive, así que una re-ejecución con solo --yes no es el mismo comando. Las versiones actuales nombran la bandera por ti e imprimen una línea Fix: que puedes pegar. Si pretendías elegir de una lista, pasa el nombre del cambio explícitamente: el selector también necesita una respuesta.

Si en cambio ejecutaste archive con su salida redirigida a un archivo o capturada por una herramienta y sí canalizaste una respuesta (printf 'y\n' | openspec archive …), las versiones anteriores escribían códigos de escape de terminal en esa captura mientras dibujaban el prompt, en algunos entornos suficiente para inflar el archivo gravemente. Las versiones actuales leen los prompts de confirmación como texto plano cuando stdout no es una terminal, y un openspec archive sin argumentos (que de otro modo dibujaría un selector interactivo de cambios) te pide que pases un nombre de cambio de antemano en lugar de renderizar un menú en la captura. De cualquier manera, las ejecuciones redirigidas y de agentes se mantienen limpias; pasar --yes (con un nombre de cambio) omite los prompts por completo.

Configuración

Mi config.yaml no se está aplicando

Tres sospechosos habituales:

1. Nombre de archivo incorrecto. Debe ser openspec/config.yaml, no .yml.
2. YAML inválido. Pásalo por cualquier validador de YAML; el CLI también informa errores de sintaxis con números de línea.
3. Esperabas un reinicio. No lo necesitas. Los cambios de configuración tienen efecto inmediato.

"Unknown artifact ID in rules: X"

Una clave bajo rules: no coincide con ningún artefacto en tu esquema. Para el esquema spec-driven predeterminado, los IDs válidos son proposal, specs, design, tasks. Para ver los IDs de cualquier esquema:

openspec schemas --json

"Context too large"

El campo context: tiene un límite de 50KB, a propósito, porque se inyecta en cada solicitud. Resúmelo, o enlaza a documentación más larga en lugar de pegarla. Un contexto ligero también produce mejores y más rápidos resultados.

"Schema not found"

El nombre de esquema que referenciaste no existe. Lista lo que está disponible y verifica la ortografía:

openspec schemas                    # listar esquemas disponibles
openspec schema which <name>        # ver de dónde se resuelve un esquema
openspec schema init <name>         # crear uno personalizado

Consulta Personalización.

Migración desde el flujo de trabajo anterior

"Legacy files detected in non-interactive mode"

Estás en CI o en un shell no interactivo, y OpenSpec encontró archivos antiguos para limpiar pero no puede preguntarte. Aprueba automáticamente:

openspec init --force

Para Codex, OpenSpec puede detectar antiguos archivos de prompt gestionados en $CODEX_HOME/prompts o ~/.codex/prompts. Esa limpieza se limita a los nombres de archivo de prompt heredados de Codex en la lista blanca de OpenSpec, y el openspec init no interactivo solo elimina los archivos cuyas skills de reemplazo .agents/skills/openspec-* existen. El openspec update no interactivo deja toda la limpieza heredada intacta a menos que pases --force.

Los comandos no aparecieron después de migrar

Reinicia tu IDE. Las skills se detectan al inicio. Si aún no aparecen, ejecuta openspec update y verifica las ubicaciones de los archivos en Herramientas Soportadas.

Mi antiguo project.md no fue migrado

Eso es intencional. OpenSpec nunca elimina project.md automáticamente porque puede contener contexto que escribiste. Mueve las partes útiles a la sección context: de config.yaml, luego elimínalo tú mismo. La Guía de Migración explica esto, incluyendo un prompt que puedes dar a tu IA para hacer la destilación.

¿Aún atascado?

• Discord: discord.gg/YctCnvvshC
• GitHub Issues: github.com/Fission-AI/OpenSpec/issues
• Desde tu terminal: openspec feedback "what went wrong" abre un problema por ti.

Cuando reportes un problema, incluye tu versión de OpenSpec (openspec --version), tu versión de Node (node --version), tu herramienta de IA y el comando y salida exactos. Hace que la ayuda sea mucho más rápida.