Migrando a OPSX

Esta guía te ayuda a realizar la transición del flujo de trabajo heredado de OpenSpec a OPSX. La migración está diseñada para ser fluida: tu trabajo existente se conserva y el nuevo sistema ofrece más flexibilidad.

¿Qué está cambiando?

OPSX reemplaza el antiguo flujo de trabajo basado en fases con un enfoque fluido y orientado a la acción. Aquí está el cambio clave:

Aspecto	Heredado	OPSX
Comandos	/openspec:proposal, /openspec:apply, /openspec:archive	Por defecto: /opsx:propose, /opsx:explore, /opsx:apply, /opsx:update, /opsx:sync, /opsx:archive (comandos de flujo de trabajo ampliados opcionales)
Flujo de trabajo	Crear todos los artefactos a la vez	Crear de forma incremental o todo a la vez: tú eliges
Volver atrás	Puertas de fase incómodas	Natural: actualiza cualquier artefacto en cualquier momento
Personalización	Estructura fija	Basado en esquema, totalmente modificable
Configuración	CLAUDE.md con marcadores + project.md	Configuración limpia en openspec/config.yaml

El cambio de filosofía: El trabajo no es lineal. OPSX deja de fingir que lo es.

Antes de comenzar

Tu trabajo existente está a salvo

El proceso de migración está diseñado con la preservación en mente:

• Cambios activos en openspec/changes/ — Completamente preservados. Puedes continuarlos con los comandos OPSX.
• Cambios archivados — Intactos. Tu historial permanece intacto.
• Especificaciones principales en openspec/specs/ — Intactas. Estas son tu fuente de verdad.
• Tu contenido en CLAUDE.md, AGENTS.md, etc. — Preservado. Solo se eliminan los bloques de marcadores de OpenSpec; todo lo que escribiste permanece.

Lo que se elimina

Solo archivos gestionados por OpenSpec que están siendo reemplazados:

Qué	Por qué
Directorios/archivos de comandos slash heredados	Reemplazados por el nuevo sistema de skills
openspec/AGENTS.md	Disparador de flujo de trabajo obsoleto
Marcadores de OpenSpec en CLAUDE.md, AGENTS.md, etc.	Ya no son necesarios

Ubicaciones de comandos heredados por herramienta (ejemplos—tu herramienta puede variar):

• Claude Code: .claude/commands/openspec/
• Cursor: .cursor/commands/openspec-*.md
• Devin Desktop, anteriormente Windsurf: .windsurf/workflows/openspec-*.md
• Cline: .clinerules/workflows/openspec-*.md
• Roo: .roo/commands/openspec-*.md
• GitHub Copilot: .github/prompts/openspec-*.prompt.md (solo extensiones de IDE; no compatible con Copilot CLI)
• Codex: OpenSpec ahora usa la ruta canónica .agents/skills/openspec-*. Los archivos SKILL.md gestionados por OpenSpec bajo la ruta anterior .codex/skills se reconcilian solo después de que existan los reemplazos; los archivos personalizados y copias divergentes permanecen en su lugar. Si un árbol .agents sin marcar ya contiene skills de OpenSpec, OpenSpec preserva su renderizado existente de Codex ($openspec-*) o genérico (/openspec-*) en lugar de suponer desde el directorio heredado. Selecciona codex explícitamente con openspec init para cambiar la propiedad. La limpieza de prompts heredados aún solo apunta a los nombres de archivos permitidos por OpenSpec en $CODEX_HOME/prompts o ~/.codex/prompts.
• Y otros (Augment, Continue, Amazon Q, etc.)

La migración detecta las herramientas que tengas configuradas y limpia sus archivos heredados.

La lista de eliminación puede parecer larga, pero todos estos son archivos que OpenSpec creó originalmente. Tu propio contenido nunca se elimina.

Lo que requiere tu atención

Un archivo requiere migración manual:

openspec/project.md — Este archivo no se elimina automáticamente porque puede contener contexto del proyecto que hayas escrito. Necesitarás:

1. Revisar su contenido
2. Mover el contexto útil a openspec/config.yaml (consulta la guía a continuación)
3. Eliminar el archivo cuando estés listo

Por qué hicimos este cambio:

El antiguo project.md era pasivo—los agentes podían leerlo o no, podían olvidar lo que leyeron. Encontramos que la confiabilidad era inconsistente.

El nuevo contexto de config.yaml se inyecta activamente en cada solicitud de planificación de OpenSpec. Esto significa que tus convenciones del proyecto, stack tecnológico y reglas siempre están presentes cuando la IA crea artefactos. Mayor confiabilidad.

La compensación:

Debido a que el contexto se inyecta en cada solicitud, querrás ser conciso. Concéntrate en lo que realmente importa:

• Stack tecnológico y convenciones clave
• Restricciones no obvias que la IA necesita conocer
• Reglas que antes se ignoraban con frecuencia

No te preocupes por hacerlo perfecto. Aún estamos aprendiendo qué funciona mejor aquí, y seguiremos mejorando cómo funciona la inyección de contexto a medida que experimentamos.

---

Ejecutando la migración

Tanto openspec init como openspec update detectan archivos heredados y te guían a través del mismo proceso de limpieza. Usa el que se ajuste a tu situación:

• Las instalaciones nuevas usan por defecto el perfil core (propose, explore, apply, update, sync, archive).
• Las instalaciones migradas preservan tus flujos de trabajo previamente instalados escribiendo un perfil custom cuando sea necesario.

Usando openspec init

Ejecuta esto si deseas agregar nuevas herramientas o reconfigurar qué herramientas están configuradas:

openspec init

El comando init detecta archivos heredados y te guía a través de la limpieza:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

Lo que sucede cuando dices que sí:

1. Se eliminan los directorios de comandos slash heredados
2. Se eliminan los marcadores de OpenSpec de CLAUDE.md, AGENTS.md, etc. (tu contenido permanece)
3. Se elimina openspec/AGENTS.md
4. Se instalan nuevas skills en .claude/skills/
5. Se crea openspec/config.yaml con un esquema predeterminado

Usando openspec update

Ejecuta esto si solo deseas migrar y actualizar tus herramientas existentes a la última versión:

openspec update

El comando update también detecta y limpia artefactos heredados, y luego actualiza las skills/comandos generados para que coincidan con tu perfil y configuración de entrega actuales.

Entornos no interactivos / CI

Para migraciones automatizadas:

openspec init --force --tools claude

La bandera --force omite los prompts y acepta automáticamente la limpieza.

Esto incluye la limpieza de archivos de prompts de Codex gestionados por OpenSpec en el directorio global de prompts de Codex. La limpieza solo apunta a los nombres de archivos heredados de prompts de Codex permitidos por OpenSpec, los elimina solo después de que existan las skills de reemplazo .agents/skills/openspec-*, y preserva todos los demás archivos.

---

Migrando project.md a config.yaml

El antiguo openspec/project.md era un archivo markdown libre para el contexto del proyecto. El nuevo openspec/config.yaml es estructurado y—críticamente—se inyecta en cada solicitud de planificación para que tus convenciones siempre estén presentes cuando la IA trabaja.

Antes (project.md)

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Después (config.yaml)

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Diferencias clave

project.md	config.yaml
Markdown libre	YAML estructurado
Un solo bloque de texto	Contexto separado y reglas por artefacto
No está claro cuándo se usa	El contexto aparece en TODOS los artefactos; las reglas aparecen solo en los artefactos correspondientes
Sin selección de esquema	El campo schema: explícito establece el flujo de trabajo predeterminado

Qué conservar, qué descartar

Al migrar, sé selectivo. Pregúntate: "¿Necesita la IA esto para cada solicitud de planificación?"

Buenos candidatos para context:

• Stack tecnológico (lenguajes, frameworks, bases de datos)
• Patrones arquitectónicos clave (monorepo, microservicios, etc.)
• Restricciones no obvias ("no podemos usar la librería X porque...")
• Convenciones críticas que a menudo se ignoran

Mover a rules: en su lugar

• Formato específico de artefacto ("usar Given/When/Then en specs")
• Criterios de revisión ("las propuestas deben incluir planes de reversión")
• Estos solo aparecen para el artefacto correspondiente, manteniendo las demás solicitudes más ligeras

Excluir por completo

• Mejores prácticas generales que la IA ya conoce
• Explicaciones verbosas que podrían resumirse
• Contexto histórico que no afecta el trabajo actual

Pasos de migración

1. Crear config.yaml (si no fue creado ya por init):

   schema: spec-driven

2. Agregar tu contexto (sé conciso—esto va en cada solicitud):

   context: |
     Your project background goes here.
     Focus on what the AI genuinely needs to know.

3. Agregar reglas por artefacto (opcional):

   rules:
     proposal:
       - Your proposal-specific guidance
     specs:
       - Your spec-writing rules

4. Eliminar project.md una vez que hayas movido todo lo útil.

No lo sobrepienses. Comienza con lo esencial y itera. Si notas que la IA se pierde algo importante, agrégalo. Si el contexto se siente hinchado, recórtalo. Este es un documento vivo.

¿Necesitas ayuda? Usa este prompt

Si no estás seguro de cómo destilar tu project.md, pregúntale a tu asistente de IA:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

La IA te ayudará a identificar qué es esencial y qué puede recortarse.

---

Los nuevos comandos

La disponibilidad de comandos depende del perfil:

Predeterminado (perfil core):

Comando	Propósito
/opsx:propose	Crear un cambio y generar artefactos de planificación en un solo paso
/opsx:explore	Reflexionar sobre ideas sin estructura
/opsx:apply	Implementar tareas desde tasks.md
/opsx:update	Revisar los artefactos de planificación de un cambio y mantenerlos coherentes
/opsx:sync	Fusionar especificaciones delta en las especificaciones principales
/opsx:archive	Finalizar y archivar el cambio

Flujo de trabajo ampliado (selección personalizada):

Comando	Propósito
/opsx:new	Iniciar un andamiaje de nuevo cambio
/opsx:continue	Crear el siguiente artefacto (uno a la vez)
/opsx:ff	Avance rápido—crear artefactos de planificación de una vez
/opsx:verify	Validar que la implementación coincide con las especificaciones
/opsx:bulk-archive	Archivar múltiples cambios a la vez
/opsx:onboard	Flujo de trabajo guiado de incorporación de extremo a extremo

Habilita los comandos ampliados con openspec config profile, y luego ejecuta openspec update.

Mapeo de comandos desde los heredados

Heredado	Equivalente OPSX
/openspec:proposal	/opsx:propose (predeterminado) o /opsx:new seguido de /opsx:ff (ampliado)
/openspec:apply	/opsx:apply
/openspec:archive	/opsx:archive

Nuevas capacidades

Estas capacidades forman parte del conjunto de comandos del flujo de trabajo ampliado.

Creación granular de artefactos:

/opsx:continue

Crea un artefacto a la vez basado en dependencias. Usa esto cuando quieras revisar cada paso.

Modo de exploración:

/opsx:explore

Reflexiona sobre ideas con un compañero antes de comprometerte con un cambio.

---

Comprensión de la nueva arquitectura

De fase-locked a fluido

El flujo de trabajo heredado forzaba una progresión lineal:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Si estás en la fase de implementación y te das cuenta de que el diseño es incorrecto?
Demasiado tarde. Las puertas de fase no permiten volver atrás fácilmente.

OPSX utiliza acciones, no fases:

         ┌───────────────────────────────────────────────┐
         │           ACCIONES (no fases)                 │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    cualquier orden            │
         └───────────────────────────────────────────────┘

Grafo de dependencias

Los artefactos forman un grafo dirigido. Las dependencias son habilitadores, no puertas de control:

                        proposal
                       (nodo raíz)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requiere:                  (requiere:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requiere:
                     specs, design)

Cuando ejecutas /opsx:continue, verifica qué está listo y ofrece el siguiente artefacto. También puedes crear múltiples artefactos listos en cualquier orden.

Habilidades vs Comandos

El sistema heredado utilizaba archivos de comandos específicos de herramientas:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

OPSX utiliza el estándar emergente de habilidades (skills):

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Las habilidades son reconocidas por múltiples herramientas de codificación con IA y proporcionan metadatos más ricos.

Codex es solo de habilidades en OPSX. OpenSpec ya no genera archivos de prompt personalizados para Codex; utiliza en su lugar los directorios generados .agents/skills/openspec-*.

---

Continuación de cambios existentes

Tus cambios en curso funcionan sin problemas con los comandos de OPSX.

¿Tienes un cambio activo del flujo de trabajo heredado?

/opsx:apply add-my-feature

OPSX lee los artefactos existentes y continúa desde donde lo dejaste.

¿Quieres agregar más artefactos a un cambio existente?

/opsx:continue add-my-feature

Muestra qué está listo para crear basándose en lo que ya existe.

¿Necesitas ver el estado?

openspec status --change add-my-feature

---

El nuevo sistema de configuración

Estructura de config.yaml

# Obligatorio: Esquema predeterminado para nuevos cambios
schema: spec-driven

# Opcional: Contexto del proyecto (máx. 50KB)
# Inyectado en TODAS las instrucciones de artefactos
context: |
  Antecedentes de tu proyecto, pila tecnológica,
  convenciones y restricciones.

# Opcional: Reglas por artefacto
# Solo se inyectan en los artefactos coincidentes
rules:
  proposal:
    - Incluir plan de reversión
  specs:
    - Usar formato Dado/Cuando/Entonces
  design:
    - Documentar estrategias de respaldo
  tasks:
    - Dividir en fragmentos de máximo 2 horas

Resolución de esquemas

Al determinar qué esquema utilizar, OPSX verifica en el siguiente orden:

1. Bandera CLI: --schema <name> (mayor prioridad)
2. Metadatos del cambio: .openspec.yaml en el directorio del cambio
3. Configuración del proyecto: openspec/config.yaml
4. Predeterminado: spec-driven

Esquemas disponibles

Esquema	Artefactos	Ideal para
spec-driven	proposal → specs → design → tasks	La mayoría de proyectos

Lista todos los esquemas disponibles:

openspec schemas

Esquemas personalizados

Crea tu propio flujo de trabajo:

openspec schema init my-workflow

O bifurca uno existente:

openspec schema fork spec-driven my-workflow

Consulta Personalización para obtener detalles.

---

Solución de problemas

"Archivos heredados detectados en modo no interactivo"

Estás ejecutando en un entorno CI o no interactivo. Utiliza:

openspec init --force

Los comandos no aparecen después de la migración

Reinicia tu IDE. Las habilidades se detectan al inicio.

"ID de artefacto desconocido en reglas"

Verifica que las claves de tus rules: coincidan con los IDs de artefactos de tu esquema:

• spec-driven: proposal, specs, design, tasks

Ejecuta esto para ver los IDs de artefactos válidos:

openspec schemas --json

La configuración no se está aplicando

1. Asegúrate de que el archivo esté en openspec/config.yaml (no .yml)
2. Valida la sintaxis YAML
3. Los cambios de configuración surten efecto inmediatamente; no se requiere reinicio

project.md no migrado

El sistema preserva intencionalmente project.md porque puede contener tu contenido personalizado. Revísalo manualmente, mueve las partes útiles a config.yaml y luego elimínalo.

¿Quieres ver qué se limpiaría?

Ejecuta init y rechaza la solicitud de limpieza; verás el resumen completo de detección sin que se realicen cambios.

---

Referencia rápida

Archivos después de la migración

project/
├── openspec/
│   ├── specs/                    # Sin cambios
│   ├── changes/                  # Sin cambios
│   │   └── archive/              # Sin cambios
│   └── config.yaml               # NUEVO: Configuración del proyecto
├── .claude/
│   └── skills/                   # NUEVO: Habilidades OPSX
│       ├── openspec-propose/     # perfil principal predeterminado
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # el perfil expandido agrega new/continue/ff/etc.
├── CLAUDE.md                     # Marcadores de OpenSpec eliminados, tu contenido preservado
└── AGENTS.md                     # Marcadores de OpenSpec eliminados, tu contenido preservado

Lo que ha desaparecido

• .claude/commands/openspec/ — reemplazado por .claude/skills/
• openspec/AGENTS.md — obsoleto
• openspec/project.md — migrar a config.yaml, luego eliminar
• Bloques de marcadores de OpenSpec en CLAUDE.md, AGENTS.md, etc.

Lista de referencia de comandos

/opsx:propose      Iniciar rápidamente (perfil principal predeterminado)
/opsx:apply        Implementar tareas
/opsx:archive      Finalizar y archivar

# Flujo de trabajo expandido (si está habilitado):
/opsx:new          Crear estructura para un cambio
/opsx:continue     Crear siguiente artefacto
/opsx:ff           Crear artefactos de planificación

---

Obtener ayuda

• Discord: discord.gg/YctCnvvshC
• Issues de GitHub: github.com/Fission-AI/OpenSpec/issues
• Documentación: docs/opsx.md para la referencia completa de OPSX