Flujo de trabajo OPSX
Agradecemos tus comentarios en Discord.
¿Qué es?
OPSX es ahora el flujo de trabajo estándar para OpenSpec.
Se trata de un flujo de trabajo fluido e iterativo para los cambios en OpenSpec. Ya no hay fases rígidas, solo acciones que puedes realizar en cualquier momento.
Por qué existe esto
El flujo de trabajo legacy de OpenSpec funciona, pero está bloqueado:
- Las instrucciones están codificadas en el código — enterradas en TypeScript, no puedes cambiarlas
- Todo o nada — un solo comando grande crea todo, no puedes probar piezas individuales
- Estructura fija — el mismo flujo de trabajo para todos, sin personalización
- Caja negra — cuando la salida de la IA es mala, no puedes ajustar los prompts
OPSX lo abre. Ahora cualquiera puede:
- Experimentar con instrucciones — editar una plantilla y ver si la IA lo hace mejor
- Probar de forma granular — validar las instrucciones de cada artefacto de forma independiente
- Personalizar flujos de trabajo — definir tus propios artefactos y dependencias
- Iterar rápidamente — cambiar una plantilla, probar de inmediato, sin recompilar
Legacy workflow: OPSX:
┌────────────────────────┐ ┌────────────────────────┐
│ Hardcoded in package │ │ schema.yaml │◄── You edit this
│ (can't change) │ │ templates/*.md │◄── Or this
│ ↓ │ │ ↓ │
│ Wait for new release │ │ Instant effect │
│ ↓ │ │ ↓ │
│ Hope it's better │ │ Test it yourself │
└────────────────────────┘ └────────────────────────┘Esto es para todos:
- Equipos — crear flujos de trabajo que se ajusten a cómo realmente trabajan
- Usuarios avanzados — ajustar prompts para obtener mejores salidas de la IA para su base de código
- Contribuidores de OpenSpec — experimentar con nuevos enfoques sin lanzamientos
Todavía estamos aprendiendo qué funciona mejor. OPSX nos permite aprender juntos.
La experiencia de usuario
El problema con los flujos de trabajo lineales: Estás "en la fase de planificación", luego "en la fase de implementación" y luego "terminado". Pero el trabajo real no funciona así. Implementas algo, te das cuenta de que tu diseño estaba equivocado, necesitas actualizar las especificaciones, y continúas implementando. Las fases lineales luchan contra cómo realmente se desarrolla el trabajo.
Enfoque de OPSX:
- Acciones, no fases — crear, implementar, actualizar, archivar — haz cualquiera de ellas en cualquier momento
- Las dependencias son habilitadoras — muestran qué es posible, no qué es obligatorio a continuación
proposal ──→ specs ──→ design ──→ tasks ──→ implementConfiguración
# Make sure you have openspec installed — skills are automatically generated
openspec initEsto crea skills en .claude/skills/ (o equivalente) que los asistentes de codificación con IA detectan automáticamente.
Por defecto, OpenSpec usa el perfil de flujo de trabajo core (propose, explore, apply, update, sync, archive). Si deseas los comandos de flujo de trabajo expandido (new, continue, ff, verify, bulk-archive, onboard), configúralos con openspec config profile y aplícalos con openspec update.
Durante la configuración, se te pedirá que crees una configuración de proyecto (openspec/config.yaml). Esto es opcional pero recomendado.
Configuración del proyecto
La configuración del proyecto te permite establecer valores predeterminados e inyectar contexto específico del proyecto en todos los artefactos.
Creando la configuración
La configuración se crea durante openspec init, o manualmente:
# openspec/config.yaml
schema: spec-driven
context: |
Tech stack: TypeScript, React, Node.js
API conventions: RESTful, JSON responses
Testing: Vitest for unit tests, Playwright for e2e
Style: ESLint with Prettier, strict TypeScript
rules:
proposal:
- Include rollback plan
- Identify affected teams
specs:
- Use Given/When/Then format for scenarios
design:
- Include sequence diagrams for complex flowsCampos de configuración
| Campo | Tipo | Descripción |
|---|---|---|
schema | string | Esquema predeterminado para nuevos cambios (p. ej., spec-driven) |
context | string | Contexto del proyecto inyectado en las instrucciones de todos los artefactos |
rules | object | Reglas por artefacto, indexadas por ID de artefacto |
Cómo funciona
Precedencia del esquema (de mayor a menor):
- Bandera de CLI (
--schema <name>) - Metadatos del cambio (
.openspec.yamlen el directorio del cambio) - Configuración del proyecto (
openspec/config.yaml) - Predeterminado (
spec-driven)
Inyección de contexto:
- El contexto se antepone a las instrucciones de cada artefacto
- Envuelto en etiquetas
<context>...</context> - Ayuda a la IA a entender las convenciones de tu proyecto
Inyección de reglas:
- Las reglas solo se inyectan para los artefactos coincidentes
- Envueltas en etiquetas
<rules>...</rules> - Aparecen después del contexto y antes de la plantilla
IDs de artefactos por esquema
spec-driven (predeterminado):
proposal— Propuesta de cambiospecs— Especificacionesdesign— Diseño técnicotasks— Tareas de implementación
Validación de configuración
- Los IDs de artefacto desconocidos en
rulesgeneran advertencias - Los nombres de esquema se validan contra los esquemas disponibles
- El contexto tiene un límite de tamaño de 50KB
- El YAML inválido se reporta con números de línea
Solución de problemas
"Unknown artifact ID in rules: X"
- Verifica que los IDs de artefacto coincidan con tu esquema (ver lista anterior)
- Ejecuta
openspec schemas --jsonpara ver los IDs de artefacto de cada esquema
La configuración no se está aplicando:
- Asegúrate de que el archivo esté en
openspec/config.yaml(no.yml) - Verifica la sintaxis YAML con un validador
- Los cambios de configuración surten efecto de inmediato (no se necesita reiniciar)
Contexto demasiado grande:
- El contexto está limitado a 50KB
- Resume o enlaza a documentación externa en su lugar
Comandos
| Comando | Qué hace |
|---|---|
/opsx:propose | Crea un cambio y genera artefactos de planificación en un solo paso (ruta rápida predeterminada) |
/opsx:explore | Reflexiona sobre ideas, investiga problemas, aclara requisitos |
/opsx:new | Inicia un andamiaje de nuevo cambio (flujo de trabajo expandido) |
/opsx:continue | Crea el siguiente artefacto (flujo de trabajo expandido) |
/opsx:ff | Avanza rápidamente los artefactos de planificación (flujo de trabajo expandido) |
/opsx:apply | Implementa tareas, actualizando artefactos según sea necesario |
/opsx:update | Revisa los artefactos de planificación de un cambio y los mantiene coherentes |
/opsx:verify | Valida la implementación contra los artefactos (flujo de trabajo expandido) |
/opsx:sync | Fusiona especificaciones delta en las especificaciones principales (opcional) |
/opsx:archive | Archiva cuando termines |
/opsx:bulk-archive | Archiva múltiples cambios completados (flujo de trabajo expandido) |
/opsx:onboard | Recorrido guiado de un cambio de extremo a extremo (flujo de trabajo expandido) |
Uso
Explorar una idea
/opsx:exploreReflexiona sobre ideas, investiga problemas, compara opciones. No se requiere estructura, solo un compañero de pensamiento. Cuando los insights se cristalicen, transiciona a /opsx:propose (predeterminado) o /opsx:new//opsx:ff (expandido).
Iniciar un nuevo cambio
/opsx:proposeCrea el cambio y genera los artefactos de planificación necesarios antes de la implementación.
Si has habilitado los flujos de trabajo expandidos, puedes usar en su lugar:
/opsx:new # solo andamiaje
/opsx:continue # crear un artefacto a la vez
/opsx:ff # crear todos los artefactos de planificación a la vezCrear artefactos
/opsx:continueMuestra qué está listo para crearse basado en dependencias, y luego crea un artefacto. Úsalo repetidamente para construir tu cambio de forma incremental.
/opsx:ff add-dark-modeCrea todos los artefactos de planificación a la vez. Úsalo cuando tengas una imagen clara de lo que estás construyendo.
Implementar (la parte fluida)
/opsx:applyAvanza por las tareas, marcándolas como completadas a medida que vas. Si estás manejando múltiples cambios, puedes ejecutar /opsx:apply <name>; de lo contrario, debería inferirlo de la conversación y pedirte que elijas si no puede determinarlo.
Actualizar un cambio
/opsx:update add-dark-mode - we're storing the theme in a cookie nowRevisa los artefactos de planificación existentes del cambio y los mantiene coherentes, en cualquier dirección (una edición de diseño puede repercutir en la propuesta). Solo artefactos de planificación: nunca edita código, y nunca crea artefactos faltantes (eso es /opsx:continue). Cada edición se confirma contigo primero. Si el cambio ya fue implementado, recomienda /opsx:apply para que el código se ponga al día con el plan revisado. Si tu revisión cambia la intención del cambio, empieza de nuevo en su lugar — ver Cuándo actualizar vs. empezar de nuevo.
Sincronizar especificaciones delta
/opsx:syncFusiona las especificaciones delta del cambio actual en tus openspec/specs/ principales sin archivar — el cambio permanece activo. Aplica todo el delta: un requisito bajo ## REMOVED se elimina de la especificación principal y uno renombrado se retitula en su lugar, mientras que el contenido que el delta no menciona se deja intacto. Sincronizar es opcional — al archivar se te pedirá que sincronices primero si no lo has hecho. Úsalo cuando quieras las especificaciones principales actualizadas antes de archivar, cuando un cambio paralelo necesite construir sobre especificaciones que este acaba de agregar, o cuando quieras revisar la especificación principal fusionada antes de archivar.
Terminar
/opsx:archive # Mover al archivo cuando termines (pide sincronizar especificaciones si es necesario)Cuándo actualizar vs. empezar de nuevo
Siempre puedes editar tu propuesta o especificaciones antes de la implementación. Pero ¿cuándo se convierte el refinamiento en "esto es trabajo diferente"?
Qué captura una propuesta
Una propuesta define tres cosas:
- Intención — ¿Qué problema estás resolviendo?
- Alcance — ¿Qué está dentro/fuera de límites?
- Enfoque — ¿Cómo lo vas a resolver?
La pregunta es: ¿cuál cambió y en qué medida?
Actualiza el cambio existente cuando:
Misma intención, ejecución refinada
- Descubres casos límite que no consideraste
- El enfoque necesita ajustes pero el objetivo no cambia
- La implementación revela que el diseño estaba ligeramente desviado
El alcance se reduce
- Te das cuenta de que el alcance completo es demasiado grande, quieres lanzar el MVP primero
- "Agregar modo oscuro" → "Agregar interruptor de modo oscuro (preferencia del sistema en v2)"
Correcciones basadas en aprendizaje
- La base de código no está estructurada como pensaste
- Una dependencia no funciona como se esperaba
- "Usar variables CSS" → "Usar el prefijo dark: de Tailwind en su lugar"
Empieza un nuevo cambio cuando:
La intención cambió fundamentalmente
- El problema en sí mismo es diferente ahora
- "Agregar modo oscuro" → "Agregar sistema de temas completo con colores, fuentes y espaciados personalizados"
El alcance explotó
- El cambio creció tanto que esencialmente es trabajo diferente
- La propuesta original sería irreconocible después de las actualizaciones
- "Corregir bug de login" → "Reescribir el sistema de autenticación"
El original es completable
- El cambio original puede marcarse como "hecho"
- El nuevo trabajo se sostiene solo, no es un refinamiento
- Completar "Agregar modo oscuro MVP" → Archivar → Nuevo cambio "Mejorar modo oscuro"
Las heurísticas
┌─────────────────────────────────────┐
│ Is this the same work? │
└──────────────┬──────────────────────┘
│
┌──────────────────┼──────────────────┐
│ │ │
▼ ▼ ▼
Same intent? >50% overlap? Can original
Same problem? Same scope? be "done" without
│ │ these changes?
│ │ │
┌────────┴────────┐ ┌──────┴──────┐ ┌───────┴───────┐
│ │ │ │ │ │
YES NO YES NO NO YES
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
UPDATE NEW UPDATE NEW UPDATE NEW| Prueba | Actualizar | Nuevo cambio |
|---|---|---|
| Identidad | "Lo mismo, refinado" | "Trabajo diferente" |
| Solapamiento de alcance | >50% de solapamiento | <50% de solapamiento |
| Completación | No puede marcarse como "hecho" sin los cambios | Se puede terminar el original, el nuevo trabajo se sostiene solo |
| Narrativa | La cadena de actualizaciones cuenta una historia coherente | Los parches confundirían más que aclararían |
El principio
Actualizar preserva el contexto. Un nuevo cambio proporciona claridad.
Elige actualizar cuando el historial de tu pensamiento sea valioso. Elige nuevo cuando empezar de nuevo sería más claro que parchear.
Piensa en ello como en ramas de git:
- Sigue haciendo commits mientras trabajas en la misma funcionalidad
- Empieza una nueva rama cuando sea genuinamente trabajo nuevo
- A veces fusiona una funcionalidad parcial y empieza de nuevo para la fase 2
¿Qué es diferente?
Legacy (/openspec:proposal) | OPSX (/opsx:*) | |
|---|---|---|
| Estructura | Un único documento de propuesta | Artefactos discretos con dependencias |
| Flujo de trabajo | Fases lineales: planificar → implementar → archivar | Acciones fluidas: haz lo que quieras en cualquier momento |
| Iteración | Difícil retroceder | Actualiza los artefactos a medida que aprendes |
| Personalización | Estructura fija | Basado en esquemas (define tus propios artefactos) |
La idea clave: el trabajo no es lineal. OPSX deja de fingir que lo es.
Inmersión Profunda en la Arquitectura
Esta sección explica cómo funciona OPSX internamente y cómo se compara con el flujo de trabajo heredado. Los ejemplos de esta sección utilizan el conjunto de comandos ampliados (new, continue, etc.); los usuarios predeterminados de core pueden mapear el mismo flujo a propose → apply → sync → archive.
Filosofía: Fases vs Acciones
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW │
│ (Phase-Locked, All-or-Nothing) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PLANNING │ ───► │ IMPLEMENTING │ ───► │ ARCHIVING │ │
│ │ PHASE │ │ PHASE │ │ PHASE │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ /openspec:proposal /openspec:apply /openspec:archive │
│ │
│ • Creates ALL artifacts at once │
│ • Can't go back to update specs during implementation │
│ • Phase gates enforce linear progression │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX WORKFLOW │
│ (Fluid Actions, Iterative) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────┐ │
│ │ ACTIONS (not phases) │ │
│ │ │ │
│ │ new ◄──► continue ◄──► apply ◄──► archive │ │
│ │ │ │ │ │ │ │
│ │ └──────────┴───────────┴───────────┘ │ │
│ │ any order │ │
│ └────────────────────────────────────────────┘ │
│ │
│ • Create artifacts one at a time OR fast-forward │
│ • Update specs/design/tasks during implementation │
│ • Dependencies enable progress, phases don't exist │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Arquitectura de Componentes
Flujo de trabajo heredado utiliza plantillas codificadas en TypeScript:
┌─────────────────────────────────────────────────────────────────────────────┐
│ LEGACY WORKFLOW COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Hardcoded Templates (TypeScript strings) │
│ │ │
│ ▼ │
│ Tool-specific configurators/adapters │
│ │ │
│ ▼ │
│ Generated Command Files (.claude/commands/openspec/*.md) │
│ │
│ • Fixed structure, no artifact awareness │
│ • Change requires code modification + rebuild │
│ │
└─────────────────────────────────────────────────────────────────────────────┘OPSX usa esquemas externos y un motor de grafo de dependencias:
┌─────────────────────────────────────────────────────────────────────────────┐
│ OPSX COMPONENTS │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ Schema Definitions (YAML) │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ name: spec-driven │ │
│ │ artifacts: │ │
│ │ - id: proposal │ │
│ │ generates: proposal.md │ │
│ │ requires: [] ◄── Dependencies │ │
│ │ - id: specs │ │
│ │ generates: specs/**/*.md ◄── Glob patterns │ │
│ │ requires: [proposal] ◄── Enables after proposal │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Artifact Graph Engine │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ • Topological sort (dependency ordering) │ │
│ │ • State detection (filesystem existence) │ │
│ │ • Rich instruction generation (templates + context) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ Skill Files (.claude/skills/openspec-*/SKILL.md) │
│ │
│ • Cross-editor compatible (Claude Code, Cursor, Devin) │
│ • Skills query CLI for structured data │
│ • Fully customizable via schema files │
│ │
└─────────────────────────────────────────────────────────────────────────────┘Modelo de Grafo de Dependencias
Los artefactos forman un grafo acíclico dirigido (DAG). Las dependencias son habilitadores, no compuertas:
proposal
(root node)
│
┌─────────────┴─────────────┐
│ │
▼ ▼
specs design
(requires: (requires:
proposal) proposal)
│ │
└─────────────┬─────────────┘
│
▼
tasks
(requires:
specs, design)
│
▼
┌──────────────┐
│ APPLY PHASE │
│ (requires: │
│ tasks) │
└──────────────┘Transiciones de estado:
BLOCKED ────────────────► READY ────────────────► DONE
│ │ │
Missing All deps File exists
dependencies are DONE on filesystemFlujo de Información
Flujo de trabajo heredado — el agente recibe instrucciones estáticas:
User: "/openspec:proposal"
│
▼
┌─────────────────────────────────────────┐
│ Static instructions: │
│ • Create proposal.md │
│ • Create tasks.md │
│ • Create design.md │
│ • Create delta spec files │
│ │
│ No awareness of what exists or │
│ dependencies between artifacts │
└─────────────────────────────────────────┘
│
▼
Agent creates ALL artifacts in one goOPSX — el agente consulta para obtener contexto enriquecido:
User: "/opsx:continue"
│
▼
┌──────────────────────────────────────────────────────────────────────────┐
│ Step 1: Query current state │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec status --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "artifacts": [ │ │
│ │ {"id": "proposal", "status": "done"}, │ │
│ │ {"id": "specs", "status": "ready"}, ◄── First ready │ │
│ │ {"id": "design", "status": "ready"}, │ │
│ │ {"id": "tasks", "status": "blocked", │ │
│ │ "missingDeps": ["specs", "design"]} │ │
│ │ ] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Get rich instructions for ready artifact │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ $ openspec instructions specs --change "add-auth" --json │ │
│ │ │ │
│ │ { │ │
│ │ "template": "# Specification\n\n## ADDED Requirements...", │ │
│ │ "dependencies": [{"id": "proposal", "path": "...", "done": true}│ │
│ │ "unlocks": ["tasks"] │ │
│ │ } │ │
│ └────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Read dependencies → Create ONE artifact → Show what's unlocked │
└──────────────────────────────────────────────────────────────────────────┘Modelo de Iteración
Flujo de trabajo heredado — incómodo para iterar:
┌─────────┐ ┌─────────┐ ┌─────────┐
│/proposal│ ──► │ /apply │ ──► │/archive │
└─────────┘ └─────────┘ └─────────┘
│ │
│ ├── "Wait, the design is wrong"
│ │
│ ├── Options:
│ │ • Edit files manually (breaks context)
│ │ • Abandon and start over
│ │ • Push through and fix later
│ │
│ └── No official "go back" mechanism
│
└── Creates ALL artifacts at onceOPSX — iteración natural:
/opsx:new ───► /opsx:continue ───► /opsx:apply ───► /opsx:archive
│ │ │
│ │ ├── "The design is wrong"
│ │ │
│ │ ▼
│ │ Just edit design.md
│ │ and continue!
│ │ │
│ │ ▼
│ │ /opsx:apply picks up
│ │ where you left off
│ │
│ └── Creates ONE artifact, shows what's unlocked
│
└── Scaffolds change, waits for directionEsquemas Personalizados
Cree flujos de trabajo personalizados utilizando los comandos de gestión de esquemas:
# Create a new schema from scratch (interactive)
openspec schema init my-workflow
# Or fork an existing schema as a starting point
openspec schema fork spec-driven my-workflow
# Validate your schema structure
openspec schema validate my-workflow
# See where a schema resolves from (useful for debugging)
openspec schema which my-workflowLos esquemas se almacenan en openspec/schemas/ (local del proyecto, controlado por versiones) o en ~/.local/share/openspec/schemas/ (global del usuario).
Estructura del esquema:
openspec/schemas/research-first/
├── schema.yaml
└── templates/
├── research.md
├── proposal.md
└── tasks.mdEjemplo de schema.yaml:
name: research-first
artifacts:
- id: research # Added before proposal
generates: research.md
requires: []
- id: proposal
generates: proposal.md
requires: [research] # Now depends on research
- id: tasks
generates: tasks.md
requires: [proposal]Grafo de dependencias:
research ──► proposal ──► tasksResumen
| Aspecto | Legado | OPSX |
|---|---|---|
| Plantillas | TypeScript codificado | YAML + Markdown externos |
| Dependencias | Ninguna (todo a la vez) | DAG con orden topológico |
| Estado | Modelo mental basado en fases | Existencia en el sistema de archivos |
| Personalización | Editar código fuente, reconstruir | Crear schema.yaml |
| Iteración | Bloqueado por fases | Fluido, editar cualquier cosa |
| Soporte de editores | Configuradores/adaptadores específicos de herramienta | Directorio de habilidades único |
Esquemas
Los esquemas definen qué artefactos existen y sus dependencias. Actualmente disponibles:
- spec-driven (predeterminado): propuesta → especificaciones → diseño → tareas
# Listar esquemas disponibles
openspec schemas
# Ver todos los esquemas con sus fuentes de resolución
openspec schema which --all
# Crear un nuevo esquema de forma interactiva
openspec schema init my-workflow
# Bifurcar un esquema existente para personalizarlo
openspec schema fork spec-driven my-workflow
# Validar la estructura del esquema antes de usarlo
openspec schema validate my-workflowConsejos
- Usa
/opsx:explorepara reflexionar sobre una idea antes de comprometerte con un cambio /opsx:ffcuando sepas lo que quieres,/opsx:continuecuando estés explorando- Durante
/opsx:apply, si algo está mal, corrige el artefacto y luego continúa - Las tareas siguen el progreso mediante casillas de verificación en
tasks.md - Consulta el estado en cualquier momento:
openspec status --change "name"
Comentarios
Esto es preliminar. Eso es intencional — estamos aprendiendo qué funciona.
¿Encontraste un error? ¿Tienes ideas? Únete a nosotros en Discord o abre un problema en GitHub.