Flujos de trabajo

Esta guía cubre patrones comunes de flujo de trabajo para OpenSpec y cuándo usar cada uno. Para la configuración básica, consulta Primeros pasos. Para referencia de comandos, consulta Comandos.

Filosofía: Acciones, no fases

Los flujos de trabajo tradicionales te obligan a pasar por fases: planificación, luego implementación, luego finalizado. Pero el trabajo real no encaja perfectamente en cajas.

OPSX adopta un enfoque diferente:

Tradicional (bloqueado en fases):

  PLANIFICACIÓN ────────► IMPLEMENTACIÓN ────────► FINALIZADO
      │                           │
      │   "No se puede volver"    │
      └───────────────────────────┘

OPSX (acciones fluidas):

  propuesta ──► especificaciones ──► diseño ──► tareas ──► implementar

Principios clave:

• Acciones, no fases - Los comandos son cosas que puedes hacer, no etapas en las que estás atascado.
• Las dependencias son habilitadores - Muestran lo que es posible, no lo que se requiere a continuación.

Personalización: Los flujos de trabajo de OPSX son impulsados por esquemas que definen secuencias de artefactos. Consulta Personalización para obtener detalles sobre la creación de esquemas personalizados.

Flujo de trabajo de un vistazo

El flujo de trabajo predeterminado se mantiene fluido: la exploración y la verificación son opcionales, y puedes actualizar los artefactos de planificación siempre que la implementación revele algo nuevo.

flowchart TD
    Idea["Idea or problem"] --> Explore["/opsx:explore<br/>(optional)"]
    Idea --> Propose["/opsx:propose"]
    Explore --> Propose
    Propose --> Review{"Planning artifacts<br/>ready?"}
    Review -->|"Refine"| Update["/opsx:update"]
    Update --> Review
    Review -->|"Implement"| Apply["/opsx:apply"]
    Apply -->|"Plan changed"| Update
    Apply --> Archive["/opsx:archive"]
    Apply --> Verify["/opsx:verify<br/>(optional, custom selection)"]
    Apply --> Sync["/opsx:sync<br/>(optional before archive)"]
    Verify --> Verified{"Ready to archive?"}
    Verified -->|"Fix implementation"| Apply
    Verified -->|"Revise plan"| Update
    Verified -->|"Ready"| Sync
    Verified -->|"Ready"| Archive
    Sync --> Archive

El asistente de IA impulsa el flujo de trabajo, mientras que la CLI proporciona el andamiaje, el estado y las instrucciones de artefactos de manera determinista:

sequenceDiagram
    actor Human
    participant Assistant as AI assistant
    participant CLI as OpenSpec CLI
    participant Files as Planning and implementation files

    Human->>Assistant: /opsx:propose "change"
    Assistant->>CLI: openspec new change
    CLI->>Files: Scaffold change metadata
    Assistant->>CLI: Request status and artifact instructions
    CLI-->>Assistant: Build order, paths, and templates
    Assistant->>Files: Write schema-defined planning artifacts
    Assistant-->>Human: Present artifacts for review

    Human->>Assistant: /opsx:apply
    Assistant->>CLI: Request apply instructions
    CLI-->>Assistant: Context files and task state
    Assistant->>Files: Implement tasks and update checkboxes
    Assistant-->>Human: Report implementation status

    Human->>Assistant: /opsx:archive
    Assistant->>CLI: Request archive inputs and artifact status
    CLI-->>Assistant: Planning paths and artifact completion
    Assistant->>Files: Read task state and compare delta specs
    opt Delta specs exist
        Assistant-->>Human: Offer to sync before archiving
        alt Sync accepted
            Human->>Assistant: Confirm sync
            Assistant->>Files: Merge delta specs into main specs
        else Sync skipped
            Human->>Assistant: Archive without syncing
        end
    end
    Assistant->>Files: Move the change into the archive
    Assistant-->>Human: Report archive location and sync result

    Note over Human,CLI: CLI alternative: openspec archive change-name --yes skips confirmation prompts. It still validates, then applies any delta specs and archives

Dos modos

Ruta rápida predeterminada (perfil core)

Las instalaciones nuevas usan por defecto core, que proporciona:

• /opsx:explore
• /opsx:propose
• /opsx:apply
• /opsx:update
• /opsx:sync
• /opsx:archive

Flujo típico:

/opsx:explore ──► /opsx:propose ──► /opsx:apply ──► /opsx:sync ──► /opsx:archive
  (opcional)

Comienza explorando (el hábito que vale la pena formar)

/opsx:explore es parte del perfil predeterminado, no un complemento avanzado. Es la jugada que debes hacer cuando tienes un problema pero aún no un plan, lo que, con un asistente de IA, ocurre la mayoría de las veces.

Tú: /opsx:explore

IA: ¿Qué te gustaría explorar?

Tú: Nuestros resultados de búsqueda se sienten desactualizados. No estoy seguro de si es el caché,
     la indexación o la consulta en sí.

IA: Déjame mirar... [lee el servicio de búsqueda y la capa de caché]
     Es el índice: solo se reconstruye por la noche, por lo que las ediciones no aparecen
     hasta el día siguiente. Dos opciones: reconstruir en escritura (simple,
     más carga) o una invalidación de caché de TTL corto (más partes móviles,
     menos carga). Dado que tu volumen de escritura es bajo, reconstruir en escritura es
     la solución más limpia. ¿Quieres acotarlo?

Tú: Sí.

Tú: /opsx:propose rebuild-search-index-on-write

Explore no crea artefactos ni escribe código. Es una conversación libre y sin riesgos que convierte una preocupación vaga en un cambio preciso, para que la propuesta que sigue sea nítida. ¿Ya sabes exactamente lo que quieres? Omítela y ve directo a /opsx:propose. Guía completa: Explore First.

Flujo de trabajo ampliado/completo (selección personalizada)

Si deseas comandos explícitos de andamiaje y construcción (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard), actívalos con:

openspec config profile
openspec update

Patrones de flujo de trabajo (modo ampliado)

Característica rápida

Cuando sabes lo que quieres construir y solo necesitas ejecutar:

/opsx:new ──► /opsx:ff ──► /opsx:apply ──► /opsx:verify ──► /opsx:archive

Ejemplo de conversación:

Tú: /opsx:new add-logout-button

IA: Creado openspec/changes/add-logout-button/
     Listo para crear: propuesta

Tú: /opsx:ff

IA: Creando todos los artefactos de planificación...
     ✓ proposal.md
     ✓ specs/
     ✓ design.md
     ✓ tasks.md
     ¡Listo para la implementación!

Tú: /opsx:apply

IA: Trabajando en las tareas...
     ✓ Agregado botón de cerrar sesión en el encabezado
     ✓ Implementado el borrado de sesión
     ✓ Agregado diálogo de confirmación
     ¡Todas las tareas completadas!

Tú: /opsx:archive

IA: ✓ Fusionadas las especificaciones
     ✓ Archivado el cambio

Ideal para: Características pequeñas o medianas, correcciones de errores, cambios sencillos.

Exploratorio

Cuando los requisitos no están claros o necesitas investigar primero:

/opsx:explore ──► /opsx:new ──► /opsx:continue ──► ... ──► /opsx:apply

Ejemplo de conversación:

Tú: /opsx:explore

IA: ¿Qué te gustaría explorar?

Tú: Quiero mejorar el rendimiento de carga de la página pero no estoy seguro
     de dónde están los cuellos de botella.

IA: Déjame ayudar a investigar...
     [Analiza tamaños de los bundles, identifica consultas lentas, revisa
     patrones de renderizado de componentes]

     Encontré tres cuellos de botella principales:
     1. Imágenes grandes no optimizadas
     2. Obtención de datos síncrona en ProductList
     3. Re-renderizados por cambios de contexto

     ¿Cuál quieres abordar primero?

Tú: Abordemos el tema de la obtención de datos.

Tú: /opsx:new optimize-product-list-fetching

IA: Cambio creado. Listo para crear: propuesta

Tú: /opsx:continue

IA: Creando propuesta basada en nuestra exploración...
     [Escribe la propuesta incorporando los hallazgos de la investigación]

     Listo para crear: specs, design
     ¿Cuál quieres a continuación?

Tú: /opsx:continue

IA: Creando especificaciones...

Ideal para: Optimización de rendimiento, depuración, decisiones arquitectónicas, requisitos poco claros.

Cambios paralelos

Trabaja en múltiples cambios a la vez:

Cambio A: /opsx:new ──► /opsx:ff ──► /opsx:apply (en progreso)
                                         │
                                    cambio de contexto
                                         │
Cambio B: /opsx:new ──► /opsx:ff ──────► /opsx:apply

Ejemplo de conversación:

Tú: Estoy trabajando en add-dark-mode pero me desvié para corregir un bug

Tú: /opsx:new fix-login-redirect

IA: Creado openspec/changes/fix-login-redirect/

Tú: /opsx:ff

IA: ✓ Creados los artefactos de planificación

Tú: /opsx:apply

IA: Trabajando en fix-login-redirect...
     [Implementa la corrección]
     ¡Todas las tareas completadas!

Tú: /opsx:archive

IA: ✓ Archivado fix-login-redirect

Tú: Volvamos al modo oscuro

Tú: /opsx:apply add-dark-mode

IA: Reanudando add-dark-mode...
     Continuando en la tarea 2.3: Actualizar Header...

Ideal para: Flujos de trabajo en paralelo, interrupciones urgentes, colaboración en equipo.

Cuando tengas múltiples cambios completados, usa /opsx:bulk-archive:

Tú: /opsx:bulk-archive

IA: Encontrados 3 cambios completados:
     - add-dark-mode (todas las tareas listas)
     - fix-login-redirect (todas las tareas listas)
     - update-footer (todas las tareas listas)

     Comprobando conflictos de especificaciones...
     ⚠ add-dark-mode y update-footer tocan ambos specs/ui/

     Inspeccionando el código para resolver...
     Ambos cambios están implementados. Se aplicarán en orden cronológico.

     ¿Archivar los 3 cambios?

Tú: Sí

IA: ✓ Archivado add-dark-mode
     ✓ Archivado fix-login-redirect
     ✓ Archivado update-footer
     Especificaciones fusionadas en orden: add-dark-mode → update-footer

El archivado masivo detecta cuando múltiples cambios tocan las mismas especificaciones y resuelve los conflictos comprobando lo que realmente está implementado.

Completar un cambio

El flujo de finalización recomendado:

/opsx:apply ──► /opsx:verify ──► /opsx:archive
                    │                 │
              valida          solicita sincronizar
              implementación   si es necesario

Verificar: Revisa tu trabajo

/opsx:verify valida la implementación contra tus artefactos en tres dimensiones:

Tú: /opsx:verify

IA: Verificando add-auth...

     COMPLETITUD
     ✓ Las 12 tareas en tasks.md están marcadas
     ✓ Todos los requisitos en specs tienen código correspondiente
     ⚠ Escenario "Timeout de sesión después de inactividad" no probado

     CORRECCIÓN
     ✓ La implementación coincide con la intención de las specs
     ✓ Los casos límite de los escenarios se manejan
     ✓ Los estados de error coinciden con las definiciones de las specs

     COHERENCIA
     ✓ Las decisiones de diseño se reflejan en la estructura del código
     ✓ Las convenciones de nombres son consistentes con design.md
     ⚠ El diseño menciona "orientado a eventos" pero la implementación usa polling

     RESUMEN
     ─────────────────────────────
     Problemas críticos: 0
     Advertencias: 2
     Listo para archivar: Sí (con advertencias)

     Recomendaciones:
     1. Agregar prueba para el escenario de timeout de sesión
     2. Considerar refactorizar a orientado a eventos como se diseñó, o actualizar design.md

Qué comprueba verify:

Dimensión	Qué valida
Completitud	Todas las tareas hechas, todos los requisitos implementados, escenarios cubiertos
Corrección	La implementación coincide con la intención de las specs, casos límite manejados
Coherencia	Decisiones de diseño reflejadas en el código, patrones consistentes

Verify no bloqueará el archivado, pero saca a la luz problemas que quizás quieras abordar primero.

Archivar: Finalizar el cambio

/opsx:archive completa el cambio y lo mueve al archivo:

Tú: /opsx:archive

IA: Archivando add-auth...

     Estado de los artefactos:
     ✓ proposal.md existe
     ✓ specs/ existe
     ✓ design.md existe
     ✓ tasks.md existe (12/12 tareas completas)

     Especificaciones delta: Aún no sincronizadas al principal
     → ¿Te gustaría sincronizar ahora?

Tú: Sí

IA: ✓ Especificaciones sincronizadas en openspec/specs/auth/spec.md
     ✓ Movido a openspec/changes/archive/2025-01-24-add-auth/

     Cambio archivado correctamente.

Archive preguntará si las especificaciones no están sincronizadas. No bloqueará por tareas incompletas, pero advertirá.

Cuándo usar qué

/opsx:ff vs /opsx:continue

Situación	Uso
Requisitos claros, listo para construir	/opsx:ff
Explorando, quieres revisar cada paso	/opsx:continue
Quieres iterar en la propuesta antes de las specs	/opsx:continue
Presión de tiempo, necesitas avanzar rápido	/opsx:ff
Cambio complejo, quieres control	/opsx:continue

Regla general: Si puedes describir el alcance completo desde el principio, usa /opsx:ff. Si lo vas descubriendo sobre la marcha, usa /opsx:continue.

Cuándo actualizar vs. empezar de nuevo

Una pregunta común: ¿cuándo está bien actualizar un cambio existente y cuándo deberías empezar uno nuevo?

Actualiza el cambio existente cuando:

• Misma intención, ejecución refinada
• El alcance se reduce (MVP primero, el resto después)
• Correcciones basadas en el aprendizaje (el código no es lo que esperabas)
• Ajustes de diseño basados en descubrimientos de implementación

Empieza un cambio nuevo cuando:

• La intención ha cambiado fundamentalmente
• El alcance explotó a un trabajo completamente diferente
• El cambio original puede marcarse como "hecho" de manera independiente
• Los parches confundirían más de lo que aclararían

                     ┌─────────────────────────────────────┐
                     │     ¿Es el mismo trabajo?           │
                     └──────────────┬──────────────────────┘
                                    │
                 ┌──────────────────┼──────────────────┐
                 │                  │                  │
                 ▼                  ▼                  ▼
          ¿Misma intención?  ¿Más del 50% de     ¿Puede el original
          ¿Mismo problema?   superposición?      ser "hecho" sin
                 │           ¿Mismo alcance?     estos cambios?
                 │                  │                  │
       ┌────────┴────────┐  ┌──────┴──────┐   ┌───────┴───────┐
       │                 │  │             │   │               │
      YES               NO YES           NO  NO              YES
       │                 │  │             │   │               │
       ▼                 ▼  ▼             ▼   ▼               ▼
    ACTUALIZAR        NUEVO  ACTUALIZAR  NUEVO  ACTUALIZAR  NUEVO

Ejemplo: "Añadir modo oscuro"

• "También necesitamos soportar temas personalizados" → Nuevo cambio (el alcance explotó)
• "La detección de preferencia del sistema es más difícil de lo esperado" → Actualizar (misma intención)
• "Vamos a lanzar primero el toggle, añadir preferencias después" → Actualizar, luego archivar, luego nuevo cambio

Mejores prácticas

Mantener los cambios enfocados

Una unidad lógica de trabajo por cambio. Si estás realizando "añadir la función X y también refactorizar Y", considera hacer dos cambios separados.

Por qué es importante:

• Más fácil de revisar y entender
• Historial de archivo más limpio
• Se pueden publicar de forma independiente
• Reversión más sencilla si es necesario

Usar /opsx:explore para requisitos poco claros

Antes de comprometerse con un cambio, explora el espacio del problema:

Tú: /opsx:explore

IA:  ¿Qué te gustaría explorar?

Tú: ¿Cómo deberíamos manejar la limitación de velocidad (rate limiting) para nuestra API?

IA:  Déjame investigar tu configuración actual y las opciones...
     [Investiga la base de código, analiza patrones]

     Veo tres enfoques que podríamos tomar:
     1. Basado en middleware (simple, por punto final)
     2. Respaldado por Redis (escalable, estado compartido)
     3. Cubeta de tokens por usuario (justo, complejo)

     Tu pila tecnológica actual sugiere #1 o #2. ¿Cuál es tu escala?

La exploración aclara el pensamiento antes de crear artefactos.

Verificar antes de archivar

Usa /opsx:verify para comprobar que la implementación coincide con los artefactos:

Tú: /opsx:verify

IA:  Verificando add-dark-mode...

     ✓ Todas las tareas en tasks.md están marcadas
     ✓ Los requisitos en specs tienen código correspondiente
     ✓ Las decisiones de diseño se reflejan en la implementación

     ¡Listo para archivar!

Detecta discrepancias antes de cerrar el cambio.

Nombrar los cambios claramente

Los buenos nombres hacen que openspec list sea útil:

Bueno:                         Evitar:
add-dark-mode                   feature-1
fix-login-redirect              update
optimize-product-query          changes
implement-2fa                   wip

Referencia rápida de comandos

Para obtener detalles completos sobre los comandos y opciones, consulta Comandos.

Comando	Propósito	Cuándo usarlo
/opsx:propose	Crear cambio + artefactos de planificación	Ruta predeterminada rápida (perfil core)
/opsx:explore	Analizar ideas con la IA	Comienza aquí cuando hay dudas: requisitos poco claros, investigación, comparación de opciones
/opsx:new	Iniciar una estructura de cambio	Modo expandido, control explícito de artefactos
/opsx:continue	Crear el siguiente artefacto	Modo expandido, creación de artefactos paso a paso
/opsx:ff	Crear todos los artefactos de planificación	Modo expandido, alcance claro
/opsx:apply	Implementar tareas	Listo para escribir código
/opsx:verify	Validar la implementación	Modo expandido, antes de archivar
/opsx:sync	Fusionar especificaciones delta	Modo expandido, opcional
/opsx:archive	Completar el cambio	Todo el trabajo finalizado
/opsx:bulk-archive	Archivar múltiples cambios	Modo expandido, trabajo paralelo

Próximos pasos

• Escribir buenas especificaciones - Cómo deben verse un requisito sólido y un escenario, y cómo dimensionar adecuadamente un cambio
• Revisión de un cambio - El repaso rápido de dos minutos sobre un plan redactado antes de escribir cualquier código
• OpenSpec en un equipo - Cómo se integran los cambios con las ramas y las solicitudes de extracción (pull requests)
• Comandos - Referencia completa de comandos con opciones
• Conceptos - Análisis profundo de especificaciones, artefactos y esquemas
• Personalización - Crear flujos de trabajo personalizados