Serie: Openspec (5/6)
/opsx:propose → apply → archive: Ejecutar un Flujo de Trabajo Completo de OpenSpec
El flujo de trabajo principal de OpenSpec son solo tres comandos: /opsx:propose, /opsx:apply y /opsx:archive. No son muchos — pero estos tres pasos conectan toda la cadena desde "quiero construir esto" hasta "está construido y documentado." Este artículo usa "agregar modo oscuro" como ejemplo para recorrer un ciclo completo.
Paso 1: /opsx:propose — Declara Qué Estás Construyendo
/opsx:propose add-dark-mode
Lo que hace este comando: la IA crea la carpeta openspec/changes/add-dark-mode/ y genera cuatro artifacts:
openspec/changes/add-dark-mode/
├── proposal.md ← por qué lo estamos haciendo, qué está en el alcance
├── specs/ui/spec.md ← delta spec: qué comportamientos están cambiando
├── design.md ← enfoque técnico
└── tasks.md ← lista de verificación de implementación
La IA frecuentemente hará preguntas aclaratorias para ayudar a generar estos, como:
- ¿Cuál es la motivación para esta funcionalidad?
- ¿Debería soportar preferencia del sistema (seguir la configuración del SO)?
- ¿Debería localStorage guardar la preferencia?
Este es el paso más importante en todo el flujo de trabajo — dedica tiempo a revisar los cuatro documentos que genera la IA y confirma que coinciden con lo que tenías en mente. Presta especial atención a proposal.md y tasks.md. Si algo parece incorrecto, díselo de inmediato y deja que la IA lo corrija. Cambiar las cosas aquí es mucho más barato que cambiarlas después de la implementación.
Una vez que estés satisfecho, avanza.
Punto Intermedio: Revisar tasks.md
Antes de ejecutar /opsx:apply, abre tasks.md y léelo — esta es la lista de verificación que la IA está a punto de ejecutar, y quieres verificar que las tareas estén bien desglosadas y que no falte nada:
# Tasks
## 1. Theme Infrastructure
- [ ] 1.1 Create ThemeContext to manage light/dark state
- [ ] 1.2 Add CSS custom properties
- [ ] 1.3 Implement localStorage preference persistence
## 2. UI Components
- [ ] 2.1 Build ThemeToggle component
- [ ] 2.2 Add settings page
- [ ] 2.3 Add quick-toggle button in Header
## 3. Styling
- [ ] 3.1 Define dark theme color palette
- [ ] 3.2 Update components to use CSS variablesSi la lista se ve bien, continúa.
Paso 2: /opsx:apply — Implementar
/opsx:apply
La IA trabaja a través de la lista de verificación de tasks.md elemento por elemento. Verás cómo va marcando cada tarea:
✓ 1.1 Create ThemeContext with light/dark state
✓ 1.2 Add CSS custom properties to globals.css
✓ 1.3 Implement localStorage persistence
✓ 2.1 Build ThemeToggle component
✓ 2.2 Add settings page
...
All tasks complete!
Si durante la implementación la IA descubre un problema con el diseño original — digamos que encuentra que tu biblioteca de componentes ya tiene un mecanismo de temas que entra en conflicto con el enfoque planificado en tasks — díselo directamente, actualiza design.md o tasks.md, y continúa. OpenSpec no te impide volver a actualizar los artifacts. Eso es lo que significa "fluido, no rígido."
Después de la Implementación, Verificar
Una vez completada la implementación, recorre manualmente la funcionalidad para confirmar que funciona — este no es un paso que OpenSpec requiera formalmente, pero es un buen hábito, especialmente para cualquier cosa moderadamente compleja.
Si has habilitado un perfil de flujo de trabajo avanzado, puedes usar:
/opsx:verify
Esto permite a la IA comparar la implementación con las especificaciones de los artifacts y detectar cualquier brecha evidente.
Paso 3: /opsx:archive — Cerrar
/opsx:archive
La IA hace tres cosas para cerrar el cambio:
- Fusionar el delta spec en la spec principal — Los specs ADDED/MODIFIED/REMOVED en
changes/add-dark-mode/specs/se fusionan de vuelta en los archivosopenspec/specs/correspondientes - Mover la carpeta del change —
changes/add-dark-mode/se mueve achanges/archive/2026-04-01-add-dark-mode/ - Listo — La spec principal ahora refleja el estado más reciente y puedes comenzar el siguiente cambio
En este punto, openspec/specs/ui/spec.md incluirá el requisito "los usuarios pueden alternar entre temas claro y oscuro," por lo que cualquiera que construya sobre esto en el futuro tendrá una spec existente a la que referirse y desde la cual hacer un delta.
El Flujo Completo de un Vistazo
/opsx:propose → Revisar artifacts → /opsx:apply → Verificar → /opsx:archive
↓ ↓ ↓ ↓
Crear carpeta proposal/specs/ Ejecutar tasks.md Delta spec fusionado
de changes, design/tasks elemento por elemento en specs principal
generar cuatro revisar y confirmar
artifacts
¿Qué Pasa si Quieres Explorar Antes de Proponer?
Si aún no tienes clara la dirección, empieza con /opsx:explore:
/opsx:explore How should we handle login for a mobile app?
La IA revisará tu base de código existente, explicará lo que hay y comparará algunos enfoques con sus trade-offs — sin crear ningún artifact. Una vez que tengas clara la dirección, ejecuta /opsx:propose, y la calidad de los artifacts generados será mucho mayor.
El flujo de trabajo es claro. El siguiente artículo cubre escenarios del mundo real — nuevas funcionalidades, corrección de bugs, y agregar OpenSpec a un proyecto existente cada uno tiene su propio playbook correspondiente.