OpenSpec avanzado: workflows ampliados, ciclos de verificación y schemas personalizados

TL;DR

• El perfil core predeterminado de OpenSpec es suficiente para la mayoría de los equipos al principio: explore, propose, apply, sync y archive.
• Los comandos del workflow ampliado son útiles cuando quieres tener más control sobre la creación de artefactos, una verificación más explícita, manejo de cambios en paralelo u onboarding guiado.
• Usa /opsx:continue cuando quieras revisar los artefactos uno a la vez. Usa /opsx:ff cuando el alcance esté claro y quieras obtener rápidamente el conjunto completo de planificación.
• Usa /opsx:verify antes de archivar cuando exista riesgo de que la implementación se desvíe: las tareas pueden estar marcadas como completadas, pero el código aún podría no coincidir con la especificación o el diseño.
• Usa /opsx:bulk-archive solo cuando haya varios cambios completados y listos para archivar, y necesites que OpenSpec analice el orden de integración de las especificaciones y los conflictos.
• Extiende OpenSpec por capas:
  • openspec/config.yaml para el contexto y las reglas del equipo
  • templates personalizados cuando la redacción predeterminada de los artefactos se acerque a lo que necesitas, pero no sea del todo adecuada
  • schemas personalizados cuando tu equipo necesite otros artefactos o dependencias
• Mi regla general: no crees un schema personalizado hasta que tengas evidencia repetida de que la configuración del proyecto no es suficiente.

Qué aprenderás aquí

Al terminar este artículo, deberías poder:

• explicar cuándo es suficiente el perfil core de OpenSpec y cuándo ayudan los workflows ampliados
• elegir entre /opsx:new, /opsx:continue y /opsx:ff
• usar /opsx:verify como un ciclo de revisión antes de archivar
• entender dónde encaja /opsx:bulk-archive en el trabajo paralelo
• diseñar un pequeño schema personalizado con un nuevo grafo de dependencias de artefactos
• validar y aplicar un workflow personalizado sin hacer un fork de OpenSpec
• explicar las ventajas y desventajas a ingenieros y PMs sin convertir OpenSpec en un proceso ceremonioso

El July 1, 2026, revisé la documentación vigente de OpenSpec sobre OPSX, comandos, conceptos, personalización y herramientas compatibles, además del primer artículo de esta serie. Los nombres de los comandos, el comportamiento de los perfiles, los campos de los schemas, el comportamiento de las dependencias y los mecanismos de personalización están respaldados por las fuentes. Las recomendaciones sobre workflows y adopción son mi propia síntesis.

Una aclaración sobre la terminología: la documentación de OpenSpec suele referirse a los workflows como /opsx:propose, /opsx:continue y así sucesivamente. La referencia de comandos también señala que algunas herramientas usan una sintaxis diferente, como las variantes con guiones en Cursor. En este artículo uso los nombres /opsx:* para referirme a los workflows. Usa la sintaxis exacta de los comandos generados para tu herramienta de IA.

¿Por qué ir más allá del perfil core?

El primer artículo de esta serie se centró en los primeros pasos:

/opsx:explore
  -> /opsx:propose
  -> /opsx:apply
  -> /opsx:archive

Ese camino es intencionalmente sencillo. Es la opción predeterminada adecuada para los equipos que están aprendiendo OpenSpec.

Las funciones avanzadas se vuelven útiles cuando el workflow en sí empieza a importar:

You need staged review
  -> create artifacts one at a time

You need faster planning for a clear change
  -> fast-forward all artifacts

You need confidence before archive
  -> verify implementation against artifacts

You have multiple active changes
  -> name changes explicitly, sync carefully, bulk-archive when ready

Your team process has a missing artifact
  -> add config, then templates, then a custom schema if needed

El workflow ampliado no es «más maduro» por defecto. Es más explícito. Úsalo cuando esa claridad reduzca el riesgo.

Perfil core vs. perfil ampliado

La documentación de OpenSpec describe el perfil global predeterminado como core.

core profile
  /opsx:explore
  /opsx:propose
  /opsx:apply
  /opsx:sync
  /opsx:archive

Los comandos ampliados se habilitan mediante la configuración del perfil:

openspec config profile
openspec update

Los comandos ampliados incluyen:

expanded workflow commands
  /opsx:new
  /opsx:continue
  /opsx:ff
  /opsx:verify
  /opsx:bulk-archive
  /opsx:onboard

La documentación de herramientas compatibles de OpenSpec deja claro que las skills y los comandos generados dependen del perfil y del mecanismo de entrega. Después de cambiar de perfil, ejecuta openspec update dentro del proyecto para que tu asistente de IA reciba las instrucciones regeneradas.

Mapa del workflow ampliado

Este es el modelo mental:

idea
  |
  |-- unclear? ----------------------.
  |                                  |
  v                                  |
/opsx:explore                       |
  |                                  |
  v                                  |
/opsx:new <change>                  |
  |                                  |
  |-- careful path --> /opsx:continue repeated
  |                                  |
  |-- fast path -----> /opsx:ff
  |
  v
/opsx:apply
  |
  v
/opsx:verify
  |
  |-- drift found? --> update code or artifacts, then verify again
  |
  v
/opsx:archive

El cambio importante es que los workflows ampliados separan la creación del cambio de la generación de artefactos.

El camino core dice:

propose = create the change + generate planning artifacts

El camino ampliado dice:

new      = create the change folder
continue = create the next artifact
ff       = create all planning artifacts in dependency order

Esa separación es lo que te da más control.

/opsx:new: Inicia el cambio sin completar todo

Usa /opsx:new cuando sabes que hay un cambio por hacer, pero todavía no quieres que la IA genere el conjunto completo de artefactos.

/opsx:new add-tenant-audit-log

La documentación de OpenSpec describe este paso como la creación de la estructura inicial de un cambio y de un archivo de metadatos .openspec.yaml. Después, el agente debería mostrar qué artefacto está listo para generarse.

Úsalo cuando:

• el nombre del cambio está claro, pero el alcance no
• quieres revisar la propuesta antes de que existan las especificaciones, el diseño y las tareas
• el equipo necesita acordar primero los límites de un dominio
• estás probando un schema personalizado y quieres ver qué artefacto va primero

Ejemplo:

You: /opsx:new add-tenant-audit-log

AI:
  Created openspec/changes/add-tenant-audit-log/
  Schema: spec-driven
  Ready to create: proposal
  Use /opsx:continue to create it, or /opsx:ff to create all artifacts.

Esto es útil para los PMs porque crea un elemento de trabajo con nombre sin fingir que todo el plan está listo.

Para los ingenieros, es útil porque permite mantener el grafo de artefactos fiel a las dependencias reales.

/opsx:continue: Revisa un artefacto a la vez

Usa /opsx:continue para cambios complejos o riesgosos.

/opsx:continue add-tenant-audit-log

La documentación de comandos indica que /opsx:continue consulta el grafo de dependencias de artefactos, muestra cuáles están listos y cuáles bloqueados, crea el primer artefacto disponible, lee sus dependencias para obtener contexto y muestra qué queda disponible después.

Para el schema predeterminado spec-driven, la estructura es aproximadamente esta:

proposal
  |-- specs
  |-- design
  `-- tasks after specs + design

En ASCII:

              proposal
                 |
        +--------+--------+
        |                 |
      specs             design
        |                 |
        +--------+--------+
                 |
               tasks
                 |
               apply

Esto permite que el equipo haga pausas en los momentos adecuados:

After proposal
  PM checks problem, scope, non-goals

After specs
  PM + QA check behavior and scenarios

After design
  engineers check architecture, dependencies, rollout risk

After tasks
  team checks review size and validation path

Usa /opsx:continue cuando:

• los requisitos son ambiguos
• la funcionalidad afecta la seguridad, los pagos, la identidad, las migraciones de datos o las APIs externas
• esperas recibir feedback real de producto antes de implementar
• quieres revisar los artefactos con otra persona antes de que la IA escriba código

No lo uses solo porque parezca más serio. Para correcciones pequeñas, puede ser demasiado lento.

/opsx:ff: Avanza rápido cuando el alcance ya está claro

Usa /opsx:ff cuando el cambio sea lo suficientemente pequeño como para que revisar cada artefacto por separado no aporte mucho valor.

/opsx:ff fix-empty-state-copy

La documentación de comandos describe /opsx:ff como un comando que crea todos los artefactos de planificación en orden de dependencia, lee cada dependencia antes de crear el siguiente artefacto y se detiene cuando todos los artefactos necesarios para aplicar el cambio están completos.

Casos adecuados:

• cambios pequeños en el comportamiento de la interfaz
• correcciones de bugs sencillas
• cambios de configuración de bajo riesgo
• funcionalidades que siguen patrones bien conocidos

Casos poco adecuados:

• rediseños de autenticación
• cambios en el modelo de permisos
• flujos de pago
• migraciones de datos
• alcance de producto poco claro

La decisión no es «rápido o lento». Es «¿necesitamos revisar cada artefacto por separado?».

Can the team review the whole plan in one pass?
  yes -> /opsx:ff
  no  -> /opsx:continue

/opsx:verify: El comando avanzado que más usaría

/opsx:verify comprueba si la implementación coincide con los artefactos. La documentación de comandos enumera tres dimensiones:

• integridad
• corrección
• coherencia

Estas se traducen bien en preguntas de revisión concretas:

Completeness
  Did we implement all requirements and tasks?
  Are the scenarios covered?

Correctness
  Does the behavior match the spec intent?
  Are edge cases handled?

Coherence
  Does the code reflect the design?
  Did implementation drift from the planned architecture?

Úsalo antes de archivar:

/opsx:apply add-tenant-audit-log
/opsx:verify add-tenant-audit-log

Si la verificación encuentra advertencias, no las trates automáticamente como bloqueos. Úsalas como insumos para la revisión.

verify warning
  |
  |-- code is wrong
  |     -> fix code, keep artifact
  |
  |-- artifact is stale
  |     -> update proposal/spec/design/tasks
  |
  |-- warning is acceptable
        -> document why and archive

Aquí es donde OpenSpec se convierte en algo más que un prompt de planificación. Los artefactos se convierten en un contrato para la revisión.

/opsx:sync y /opsx:archive: Conoce la diferencia

En el ciclo predeterminado, la mayoría de los equipos pueden dejar que el archivado se encargue de sincronizar las especificaciones.

Pero conviene conocer la diferencia:

/opsx:sync
  merges delta specs into openspec/specs/
  keeps the change active

/opsx:archive
  checks artifacts and tasks
  offers to sync if needed
  moves the change to openspec/changes/archive/

La sincronización manual es útil cuando:

• un cambio de larga duración actualiza especificaciones que otros cambios necesitan
• quieres revisar la integración de las especificaciones por separado
• varios cambios activos dependen del comportamiento base actualizado

Para cambios rápidos, omite la sincronización manual y archiva cuando termines.

/opsx:bulk-archive: Útil, pero no es un botón de limpieza

/opsx:bulk-archive archiva varios cambios completados a la vez. La documentación de comandos indica que enumera los cambios completados, valida cada uno, detecta conflictos entre especificaciones, los resuelve comprobando qué está implementado y archiva en orden cronológico.

Es una herramienta potente, pero no debería convertirse en una rutina semanal de limpieza.

Úsala cuando:

• hay varios cambios completados pendientes de archivar
• el trabajo en paralelo afectó dominios de especificaciones que se superponen
• necesitas que el agente inspeccione la implementación antes de integrar los cambios en las especificaciones

Evítala cuando:

• las tareas están incompletas
• los cambios no están relacionados entre sí y son riesgosos
• quienes revisan no han examinado los artefactos individuales
• los conflictos entre especificaciones requieren decisiones de producto, no son detalles de implementación

Mi regla:

bulk-archive is for completed, reviewed work.
It is not for making messy active work disappear.

/opsx:onboard: Ideal para aprender, no para imponer procesos

/opsx:onboard es un recorrido guiado. La documentación de comandos indica que examina tu código real, encuentra pequeñas oportunidades de mejora, crea un cambio real, lo implementa, lo verifica, lo archiva y explica los pasos.

Esto lo hace valioso para:

• introducir a un desarrollador a OpenSpec
• enseñar a un equipo el ciclo de vida de los artefactos
• probar OpenSpec en una parte del código de bajo riesgo
• mostrar el workflow a los PMs sin recurrir a un ejemplo ficticio

No usaría /opsx:onboard como la forma habitual de iniciar cada funcionalidad real. Su fortaleza está en la explicación y el aprendizaje.

Úsalo una o dos veces. Después, pasa a workflows explícitos.

Patrón avanzado 1: Cambio que comienza con investigación

Algunos cambios no deberían comenzar con una propuesta. Deberían comenzar con un artefacto de investigación.

Ejemplos:

• elegir un proveedor de pagos
• evaluar una estrategia de SSO
• comparar opciones de bases de datos vectoriales
• decidir si agregar Redis o usar bloqueos consultivos de Postgres

El OpenSpec predeterminado aún puede manejar esto con /opsx:explore, pero un proceso de equipo que se repita podría justificar un schema personalizado.

Flujo de artefactos deseado:

research
  -> decision
  -> proposal
  -> specs
  -> design
  -> tasks
  -> apply

Por qué ayuda:

• los PMs ven alternativas antes de que una opción cobre impulso
• los ingenieros documentan los enfoques descartados
• quienes revisen en el futuro pueden entender por qué se eligió un camino

Patrón avanzado 2: Revisión de cumplimiento antes de las tareas

Para funcionalidades reguladas o de alto riesgo, generar tareas puede ser prematuro hasta que alguien revise los riesgos.

Flujo de artefactos deseado:

proposal
  -> specs
  -> design
  -> compliance-review
  -> tasks
  -> apply
  -> verify
  -> archive

Ejemplo de artefacto:

compliance-review.md
  - data categories touched
  - retention impact
  - audit logging requirement
  - security review owner
  - launch constraints

Este es un buen caso para un schema personalizado porque la dependencia es real: las tareas deberían depender de compliance-review, no solo del diseño.

Patrón avanzado 3: Workflow que comienza con la migración

Las migraciones de datos merecen un enfoque de revisión diferente.

Flujo de artefactos deseado:

proposal
  -> migration-plan
  -> rollback-plan
  -> specs
  -> design
  -> tasks
  -> verify

Esto ayuda a prevenir un problema común:

spec looks fine
design looks fine
tasks look fine
but rollback was never made explicit

No crees este schema para cada funcionalidad CRUD. Créalo para equipos que implementan cambios de datos riesgosos con frecuencia.

Capas de extensión: Empieza poco a poco

La personalización de OpenSpec tiene tres capas prácticas.

Layer 1: Project config
  openspec/config.yaml
  use for team context and per-artifact rules

Layer 2: Template changes
  openspec/schemas/<schema>/templates/*.md
  use when the artifact shape is close but needs better prompts

Layer 3: Custom schema
  openspec/schemas/<schema>/schema.yaml
  use when artifact types or dependencies must change

Empieza con la configuración del proyecto.

schema: spec-driven

context: |
  Tech stack: TypeScript, Astro, React islands, Tailwind CSS.
  Product context: public devlog for engineers and PMs.
  Delivery: static build on Cloudflare Pages.

rules:
  proposal:
    - Include explicit non-goals.
    - Identify affected readers or user roles.
  specs:
    - Use Given/When/Then when behavior needs examples.
  design:
    - Mention migration, rollback, or launch risk when state changes.
  tasks:
    - Include build or validation commands.

La configuración del proyecto es suficiente cuando solo necesitas mejores instrucciones.

Un schema personalizado sirve para un proceso diferente.

Cómo funcionan los schemas personalizados

La documentación de OpenSpec describe los schemas como definiciones de tipos de artefactos y sus dependencias. Los schemas personalizados se encuentran en openspec/schemas/ y se mantienen bajo control de versiones junto con tu proyecto.

El camino más rápido es hacer un fork del schema integrado:

openspec schema fork spec-driven research-first

Esto crea algo como lo siguiente:

openspec/schemas/research-first/
|-- schema.yaml
`-- templates/
    |-- proposal.md
    |-- spec.md
    |-- design.md
    `-- tasks.md

Luego edita schema.yaml y los templates.

También puedes inicializar un schema nuevo:

openspec schema init research-first

Ejemplo: Construye un schema que comienza con investigación

Este es un schema personalizado práctico para equipos que comparan opciones antes de implementar.

name: research-first
version: 1
description: Research and decision workflow before implementation planning

artifacts:
  - id: research
    generates: research.md
    description: Compare options, constraints, and unknowns
    template: research.md
    instruction: |
      Create a research brief before proposing implementation.
      Include alternatives, constraints, risks, and open questions.
    requires: []

  - id: decision
    generates: decision.md
    description: Record the chosen direction and rejected options
    template: decision.md
    instruction: |
      Summarize the selected approach and why alternatives were rejected.
      Mark assumptions that still need validation.
    requires:
      - research

  - id: proposal
    generates: proposal.md
    description: Scoped proposal informed by research and decision
    template: proposal.md
    instruction: |
      Create a concise proposal based on research.md and decision.md.
      Focus on intent, scope, non-goals, and affected users.
    requires:
      - decision

  - id: specs
    generates: specs/**/*.md
    description: Behavior delta specs
    template: spec.md
    requires:
      - proposal

  - id: design
    generates: design.md
    description: Technical design
    template: design.md
    requires:
      - proposal

  - id: tasks
    generates: tasks.md
    description: Implementation checklist
    template: tasks.md
    requires:
      - specs
      - design

apply:
  requires: [tasks]
  tracks: tasks.md

El grafo de artefactos ahora se ve así:

research
   |
decision
   |
proposal
   |
   +--> specs ----+
   |              |
   +--> design ---+
                  |
                tasks
                  |
                apply

Esto es diferente del workflow predeterminado porque proposal ya no es la raíz. La investigación lo es.

Templates: Donde realmente está la calidad

El schema define el grafo. Los templates definen la estructura de los artefactos.

Para templates/research.md:

## Research Question

<!-- What decision are we trying to make? -->

## Options Compared

<!-- List realistic options. Include "do nothing" when relevant. -->

## Constraints

<!-- Product, engineering, security, cost, timeline, migration constraints. -->

## Findings

<!-- Source-backed findings. Use absolute dates for recent claims. -->

## Risks and Unknowns

<!-- What would make this recommendation wrong? -->

## Recommendation

<!-- Preferred option and why. Mark this as a recommendation, not a fact. -->

Para templates/decision.md:

## Decision

<!-- What direction are we choosing? -->

## Why This Wins

<!-- Explain the trade-off, not just the choice. -->

## Rejected Options

<!-- Preserve useful context for future reviewers. -->

## Assumptions

<!-- What still needs validation during implementation? -->

## Reviewers

<!-- Product, engineering, security, data, or support stakeholders. -->

Los buenos templates evitan artefactos vagos. Los templates deficientes solo trasladan los prompts vagos a archivos markdown.

Valida y usa el schema

Antes de usar un schema personalizado:

openspec schema validate research-first

La documentación de personalización indica que la validación comprueba la sintaxis del schema, los templates referenciados, las dependencias circulares y los IDs de los artefactos.

Para usarlo en un solo cambio:

/opsx:new choose-payment-provider --schema research-first
/opsx:continue choose-payment-provider

O conviértelo en el predeterminado del proyecto en openspec/config.yaml:

schema: research-first

No establecería un schema personalizado como predeterminado hasta que el equipo lo haya probado en algunos cambios.

Cómo diagnosticar la resolución de schemas

Si OpenSpec no está usando el schema que esperas, la documentación de personalización describe el orden de resolución de schemas:

1. CLI flag
2. change metadata in .openspec.yaml
3. openspec/config.yaml
4. default spec-driven schema

Usa los comandos de inspección de schemas cuando tengas dudas:

openspec schema which research-first
openspec schema which --all

Esto importa porque un cambio creado con un schema puede conservarlo en sus metadatos incluso después de que cambies el predeterminado del proyecto.

Cuándo no extender OpenSpec

No crees un schema personalizado porque:

• un artefacto tuvo una mala redacción en una ocasión
• una persona que revisó quería un encabezado diferente
• el equipo todavía está aprendiendo el workflow predeterminado
• quieres que OpenSpec imponga decisiones que las personas aún no han acordado

Usa primero la configuración del proyecto o edita los templates.

Crea un schema personalizado cuando:

• el mismo artefacto faltante aparece en varios cambios
• las tareas no deberían generarse hasta que exista una revisión adicional
• tu equipo tiene una dependencia real que el schema predeterminado no puede representar
• un workflow personalizado hace que las revisiones sean más pequeñas y claras

El mejor schema personalizado es aburrido. Formaliza un proceso que tu equipo ya necesita.

Un plan práctico para adoptar OpenSpec avanzado

Lo implementaría en cuatro pasos:

Step 1: Use core profile for 2-3 changes
  learn the default artifact lifecycle

Step 2: Enable expanded workflows
  try /opsx:continue on one risky change
  try /opsx:ff on one clear change
  try /opsx:verify before archive

Step 3: Add project config
  add context and rules based on repeated review comments

Step 4: Fork or create a custom schema
  only after you know which artifact is missing

Para los PMs, la pregunta sobre la adopción es:

Do we get earlier, clearer product review?

Para los ingenieros, la pregunta sobre la adopción es:

Do artifacts reduce rework and implementation drift?

Si la respuesta es no, simplifica el workflow.

Lista de verificación para OpenSpec avanzado

Antes de adoptar workflows ampliados:

[ ] The team understands core OpenSpec first
[ ] The reason for expanded commands is explicit
[ ] Reviewers know which artifact they own
[ ] /opsx:verify is used before archive on risky work
[ ] Custom schemas are version-controlled
[ ] Schema validation is part of the workflow
[ ] The team can explain why config was not enough

Antes de crear un schema personalizado:

[ ] The missing artifact is repeated, not one-off
[ ] Dependencies are real, not decorative
[ ] Templates are clear and reviewable
[ ] The schema is tested on a low-risk change
[ ] The default schema remains available

Notas de revisión de fuentes

Afirmaciones de este artículo respaldadas por las fuentes:

• El perfil core incluye explore, propose, apply, sync y archive.
• Los workflows ampliados incluyen new, continue, ff, verify, bulk-archive y onboard.
• /opsx:continue crea el siguiente artefacto según el estado de las dependencias.
• /opsx:ff crea los artefactos de planificación en orden de dependencia.
• /opsx:verify comprueba la integridad, la corrección y la coherencia, y no bloquea el archivado.
• /opsx:bulk-archive detecta conflictos entre cambios completados y archiva en orden cronológico.
• Los schemas personalizados se encuentran en openspec/schemas/, se pueden crear mediante un fork o inicializar desde cero y se pueden validar.
• La resolución de schemas comprueba la flag de CLI, los metadatos del cambio, la configuración del proyecto y, finalmente, el schema predeterminado.

Criterio editorial en este artículo:

• Qué comandos conviene usar en situaciones específicas de equipo.
• Cuándo evitar los schemas personalizados.
• La secuencia de implementación para la adopción avanzada.
• Los ejemplos de workflows que comienzan con investigación, revisión de cumplimiento y migración.

Fuentes

Fuentes primarias revisadas el July 1, 2026:

• Fission AI, Workflow OPSX de OpenSpec - filosofía de OPSX, acciones en lugar de fases, workflow basado en schemas, modelo de dependencias de artefactos
• Fission AI, Comandos de OpenSpec - comportamiento de los comandos predeterminados y ampliados, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard
• Fission AI, Conceptos de OpenSpec - especificaciones, cambios, schemas, grafos de dependencias, schema integrado spec-driven
• Fission AI, Personalización de OpenSpec - openspec/config.yaml, schemas personalizados, templates, validación y resolución de schemas
• Fission AI, Herramientas compatibles con OpenSpec - generación de skills y comandos según el perfil

Lecturas relacionadas en este sitio:

• Cómo empezar con OpenSpec: proyectos existentes, aplicaciones nuevas y primeros cambios comunes
• OpenSpec vs. GitHub Spec Kit: una comparación del desarrollo guiado por especificaciones