luismori.

AI Coding Workflows

OpenSpec Spec-Driven Development AI Coding

Cómo usar OpenSpec en todo el flujo de desarrollo

Un flujo práctico para usar OpenSpec desde la exploración hasta la propuesta, la implementación, las verificaciones de calidad, la revisión del PR, el merge y el archivado, sin que las especificaciones se desvíen del código.

31 min de lectura

Resumen

Usa OpenSpec como la memoria de trabajo de una funcionalidad, no como un documento que escribes una vez y luego olvidas.

Mi flujo habitual para un equipo es este:

explore idea
  -> create feature branch
  -> /opsx:propose
  -> review proposal, specs, design, tasks
  -> /opsx:apply
  -> update artifacts as implementation teaches you things
  -> run quality gates
  -> open PR
  -> address review
  -> merge PR
  -> archive the OpenSpec change

La regla más importante es sencilla:

Archive after the PR is merged, not before, if your main specs are meant to describe merged product behavior.

La documentación de OpenSpec dice que, al archivar, las especificaciones delta se integran en openspec/specs/ y el cambio completado se mueve a openspec/changes/archive/. Eso significa que archivar no es solo una tarea de limpieza: actualiza la fuente de verdad. En un equipo que trabaja con PRs, la política más clara es archivar solo después de que el código que describe se haya integrado.

Puedes seguir iterando mientras programas. El flujo OPSX actual de OpenSpec es intencionalmente flexible: actualiza proposal.md, design.md, las especificaciones delta y tasks.md a medida que aprendes. Si la intención sigue siendo la misma, actualiza el cambio actual. Si la intención es realmente distinta, crea un nuevo cambio al mismo nivel, aunque estés en el mismo hilo de chat.

Para trabajar en equipo, deja explícito el acuerdo de colaboración: una persona responsable coordina el cambio de OpenSpec, los revisores comentan los artefactos y los agentes de implementación trabajan en ramas o worktrees aislados. Si delegas /opsx:apply a subagentes, asigna a cada uno un cambio, un worktree y un acuerdo de verificación.

Qué aprenderás aquí

  • Cómo usar /opsx:explore, /opsx:propose, /opsx:apply, /opsx:verify, /opsx:sync y /opsx:archive en un flujo de entrega real.
  • En qué punto del flujo de OpenSpec corresponde crear una rama de funcionalidad.
  • Por qué normalmente conviene archivar después del merge del PR.
  • Cómo manejar pequeños ajustes de implementación sin crear especificaciones nuevas innecesarias.
  • Cuándo una segunda propuesta en el mismo chat debería ser un nuevo cambio de OpenSpec.
  • Cómo dividir una propuesta que genera muchas especificaciones delta en ramas y PRs más pequeños.
  • Cómo actualizar tasks.md para que la revisión de código, la auditoría del código fuente, las verificaciones de la aplicación, el lint, las pruebas y las pruebas e2e con Playwright formen parte del flujo.
  • Cómo pueden ingenieros y PMs revisar los mismos artefactos sin llevar todas las conversaciones de producto a los comentarios de GitHub.
  • Cómo usar OpenSpec de forma colaborativa sin perder la responsabilidad sobre la fuente de verdad.
  • Cómo combinar OpenSpec, git worktrees y subagentes de implementación asignados de forma segura.

Qué confirman las fuentes

Al July 2, 2026, las fuentes primarias que utilicé son el repositorio y la documentación de Fission-AI/OpenSpec.

Las fuentes respaldan lo siguiente:

  • OpenSpec es un framework de desarrollo guiado por especificaciones para asistentes de programación con IA.
  • El perfil core predeterminado incluye /opsx:explore, /opsx:propose, /opsx:apply, /opsx:sync y /opsx:archive.
  • El flujo ampliado puede agregar comandos como /opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive y /opsx:onboard.
  • OpenSpec separa openspec/specs/, que es la fuente de verdad, de openspec/changes/, que contiene las modificaciones propuestas.
  • Una carpeta de cambio suele contener proposal.md, design.md, tasks.md y especificaciones delta dentro de specs/.
  • /opsx:explore es una conversación sin compromiso que no crea artefactos ni escribe código.
  • /opsx:apply ejecuta las tareas de tasks.md, escribe código, ejecuta las verificaciones necesarias y marca las tareas como completadas.
  • /opsx:verify valida la implementación frente a los artefactos en términos de integridad, corrección y coherencia. Reporta problemas, pero no bloquea el archivado.
  • /opsx:archive verifica los artefactos y las tareas, ofrece sincronizar las especificaciones delta, mueve el cambio a openspec/changes/archive/ y conserva los artefactos como historial de auditoría.
  • /opsx:sync puede integrar las especificaciones delta en las especificaciones principales sin archivar el cambio activo. La documentación del comando menciona los cambios de larga duración y los cambios paralelos como casos en los que la sincronización manual puede ser útil.
  • /opsx:bulk-archive puede archivar varios cambios completados y, según la documentación, maneja conflictos entre las especificaciones de esos cambios.
  • La guía de OpenSpec para proyectos existentes recomienda un solo directorio openspec/ en la raíz del monorepo para la mayoría de los monorepos.
  • Para la planificación de múltiples repositorios, OpenSpec cuenta con stores en versión beta: repositorios independientes de OpenSpec a los que pueden hacer referencia los repositorios de código.
  • Los worksets de OpenSpec son vistas locales y personales que permiten abrir una raíz de planificación junto con carpetas de código relacionadas; no se versionan ni se comparten.
  • Los git worktrees permiten que un repositorio tenga varios árboles de trabajo, de modo que se pueden tener distintas ramas activas al mismo tiempo.
  • OpenSpec instala skills y/o archivos de comandos para muchas herramientas de programación con IA, entre ellas Cursor, Claude Code, Windsurf y GitHub Copilot.

La política de flujo de trabajo de este artículo es mi propia síntesis:

Documented OpenSpec behavior:
  archive merges specs and preserves the change

Recommended team policy:
  merge the PR first, then archive, so specs describe merged reality

Esa distinción importa. OpenSpec te da el mecanismo. Tu equipo todavía necesita un modelo de trabajo.

El flujo de principio a fin

Este es el ciclo completo que le enseñaría a un equipo.

                    no files changed
                         |
                         v
                  /opsx:explore
                         |
                         v
                 choose viable scope
                         |
                         v
               git checkout -b feature/x
                         |
                         v
                  /opsx:propose
                         |
                         v
        proposal + specs + design + tasks
                         |
                         v
                 human artifact review
                         |
                         v
                    /opsx:apply
                         |
                         v
            code + task updates + tests
                         |
                         v
           verify + lint + unit + e2e
                         |
                         v
                      open PR
                         |
                         v
              review comments + fixes
                         |
                         v
                       merge PR
                         |
                         v
                   /opsx:archive
                         |
                         v
           specs now describe merged behavior

Para los ingenieros, esto mantiene la implementación y la verificación cerca del código. Para los PMs, mantiene visibles la intención, el alcance y el comportamiento esperado en Markdown antes de que el PR se convierta en una pared de diffs.

Paso 1: Explora antes de comprometerte con un cambio

La documentación de OpenSpec presenta explícitamente /opsx:explore como un compañero para pensar. Puede leer el código, comparar opciones, dibujar diagramas y ayudar a convertir una idea poco definida en un plan concreto. No crea una carpeta de cambio, no escribe artefactos ni modifica código.

Eso hace que sea seguro usarlo antes de crear una rama.

Úsalo cuando el problema sea real, pero la solución no sea evidente:

/opsx:explore

We want to reduce checkout failures, but I do not know whether the
problem is payment retries, client double-submit, inventory reservation,
or webhook handling.

Please inspect the relevant code paths, summarize the likely causes,
compare implementation options, and recommend one small first change.

El resultado que buscas no es «escribir código», sino una decisión con un alcance definido:

Problem:
  duplicate checkout events can create duplicate orders

Recommended first change:
  add idempotency around order creation

Not in scope:
  redesign the entire payment workflow

Ese es el punto en el que una propuesta se vuelve útil.

Paso 2: Crea la rama de funcionalidad antes de /opsx:propose

Como /opsx:propose crea archivos, prefiero crear la rama antes de ejecutarlo.

git checkout main
git pull --ff-only
git checkout -b feature/add-order-idempotency

Luego crea el cambio de OpenSpec:

/opsx:propose add-order-idempotency

La documentación dice que /opsx:propose crea una carpeta de cambio y genera los artefactos de planificación necesarios antes de implementar. En el esquema spec-driven predeterminado, eso normalmente significa:

openspec/changes/add-order-idempotency/
+-- proposal.md
+-- design.md
+-- tasks.md
+-- specs/
    +-- checkout/
        +-- spec.md

Esa carpeta debe estar en la rama porque forma parte del trabajo. Les da a los revisores el «por qué» y el «qué» antes de que revisen la implementación.

La correspondencia práctica es:

feature branch = code review boundary
OpenSpec change = intent, requirements, design, and task boundary

La mayoría de las veces debería haber una correspondencia uno a uno.

Paso 3: Revisa la propuesta antes de programar

Antes de /opsx:apply, haz una pausa para revisar los artefactos.

Los ingenieros deberían verificar:

  • ¿design.md coincide con la arquitectura real?
  • ¿Las tareas son lo bastante pequeñas como para verificarlas?
  • ¿Están visibles las migraciones riesgosas, los contratos y los planes de rollback?
  • ¿Las pruebas y las verificaciones de la aplicación figuran como tareas, en lugar de quedar libradas a la intuición?

Los PMs deberían verificar:

  • ¿proposal.md describe claramente el resultado para el usuario o el negocio?
  • ¿Se indica explícitamente qué queda fuera del alcance?
  • ¿Las especificaciones delta describen un comportamiento observable?
  • ¿Los escenarios de aceptación se entienden sin leer el código?

Un buen comentario de revisión antes de implementar podría ser así:

The proposal says "prevent duplicate orders," but the spec only covers
client double-submit. Please add a webhook retry scenario or mark webhook
dedupe out of scope.

Es mucho más barato resolverlo antes de que exista código.

Paso 4: Implementa, pero mantén los artefactos actualizados

Una vez que los artefactos estén lo suficientemente bien, ejecuta:

/opsx:apply add-order-idempotency

La referencia de comandos de OpenSpec dice que /opsx:apply lee tasks.md, identifica las tareas incompletas, trabaja en ellas, escribe código, ejecuta pruebas según sea necesario y marca las tareas completadas con [x].

El hábito útil es mantener tasks.md al día mientras evoluciona la implementación. Trátalo como una lista de verificación viva:

## 1. Implementation

- [x] 1.1 Add idempotency key column to orders table
- [x] 1.2 Reject duplicate order creation for the same payment intent
- [x] 1.3 Make webhook handler reuse the same idempotency path

## 2. Verification

- [x] 2.1 Add unit tests for duplicate request handling
- [x] 2.2 Add integration test for payment webhook retry
- [ ] 2.3 Run checkout Playwright flow in headed mode
- [ ] 2.4 Run lint, typecheck, and build

Si la implementación te muestra que el diseño estaba ligeramente equivocado, actualiza design.md. Si te muestra que el comportamiento cambió, actualiza la especificación delta. La documentación de edición de OpenSpec deja claro que los artefactos son archivos Markdown que puedes editar en cualquier momento.

Eso no significa que el proceso haya fallado. Significa que está funcionando.

Paso 5: Maneja los ajustes y cambios pequeños en el cambio actual

No todo descubrimiento merece un cambio nuevo.

Usa esta regla:

same intent, same user outcome, refined execution -> update current change
new intent, independent outcome, scope explosion   -> create a new change

Ejemplos que normalmente deberían permanecer en el cambio actual:

  • El nombre de un componente cambió durante la implementación.
  • Cambiaste una biblioteca interna por otra.
  • La lista de tareas necesita una prueba adicional.
  • La especificación necesita un escenario adicional para un caso límite del mismo requisito.
  • El diseño necesita reflejar una restricción del código que descubriste.

Ejemplos que normalmente deberían convertirse en un nuevo cambio de OpenSpec:

  • «Agregar idempotencia» se convierte en «rediseñar la orquestación del checkout».
  • El PM agrega un nuevo panel de administración a la misma rama.
  • La revisión de seguridad encuentra una brecha más amplia en la política de autenticación.
  • El cambio original puede integrarse sin problemas y la nueva idea puede entregarse después.

Esto es parecido a mantener las ramas ordenadas:

small correction to the same feature -> keep going
new feature hiding inside this feature -> split it

¿Puedes explorar o crear una propuesta nueva después de aplicar una propuesta existente?

Sí, con una aclaración importante.

Puedes volver a explorar en cualquier momento. La documentación de OpenSpec incluso recomienda tomar distancia para explorar un subproblema a mitad de un cambio. La exploración no crea artefactos, así que es una forma segura de pensar cómo resolver una sorpresa durante la implementación.

También puedes crear otra propuesta en el mismo hilo de chat, pero no la pienses como una carpeta anidada dentro del primer cambio. Los cambios de OpenSpec son unidades al mismo nivel dentro de openspec/changes/.

openspec/changes/
+-- add-order-idempotency/
|   +-- proposal.md
|   +-- design.md
|   +-- tasks.md
|   +-- specs/
+-- add-checkout-risk-dashboard/
    +-- proposal.md
    +-- design.md
    +-- tasks.md
    +-- specs/

Usar el mismo hilo de chat está bien. Usar la misma rama puede estar bien para la exploración local. Usar el mismo PR es lo que me lleva a ser más cuidadoso.

Usa este flujo de decisión:

new idea appears during /opsx:apply
  |
  v
is it required to finish the current user outcome?
  |
  +-- yes -> update current proposal/specs/tasks
  |
  +-- no  -> can current PR merge without it?
              |
              +-- yes -> create a new change and usually a new branch/PR
              |
              +-- no  -> decide whether original scope was wrong;
                         update current change if the story remains coherent

El riesgo no es técnico, sino de claridad para la revisión. Un PR con dos cambios de OpenSpec que no están relacionados obliga a los revisores a responder dos preguntas de producto y dos preguntas de implementación al mismo tiempo.

¿Qué pasa si una propuesta genera muchas especificaciones?

A veces /opsx:propose crea un cambio que afecta a varios dominios de especificación:

openspec/changes/add-team-billing/
+-- proposal.md
+-- design.md
+-- tasks.md
+-- specs/
    +-- auth/spec.md
    +-- billing/spec.md
    +-- notifications/spec.md
    +-- admin-ui/spec.md

Esa es una señal para hacer una pausa. Puede tratarse de una funcionalidad transversal real o de una propuesta demasiado grande para revisarla y entregarla de forma segura.

Mi forma habitual de dividirla es:

big idea:
  add team billing

delivery slices:
  1. add-team-billing-data-model
  2. add-team-billing-checkout
  3. add-team-billing-admin-ui
  4. add-team-billing-notifications

Cada parte recibe su propia rama y, normalmente, su propio PR:

branch: feature/team-billing-data-model
  OpenSpec change: add-team-billing-data-model

branch: feature/team-billing-checkout
  OpenSpec change: add-team-billing-checkout

branch: feature/team-billing-admin-ui
  OpenSpec change: add-team-billing-admin-ui

La propuesta principal todavía puede ser útil, pero yo no dejaría que se convierta en una rama de implementación abierta para siempre. Úsala como artefacto de planificación y luego crea cambios derivados que se puedan revisar.

umbrella proposal:
  explains the end state and phase order

slice proposals:
  explain exactly what this PR changes

main specs:
  evolve after each slice is merged and archived

El orden de archivado importa. Archiva la primera parte aceptada antes de desarrollar las partes posteriores que dependen de su comportamiento. Así, la siguiente propuesta puede partir de las especificaciones canónicas actuales en lugar de un plan general desactualizado.

PR 1 merged
  -> archive add-team-billing-data-model
  -> openspec/specs/billing now has the new base behavior

PR 2 starts
  -> propose checkout against the updated billing spec

Si varias partes son realmente independientes, pueden desarrollarse en ramas o worktrees paralelos. Pero evita los deltas MODIFIED en paralelo sobre el mismo requisito, a menos que las personas responsables se coordinen cuidadosamente.

Usa esta prueba para decidir cómo dividir:

can this slice merge without the others?
  yes -> separate branch/PR
  no  -> keep it in the same change or create a prerequisite slice first

does this slice change the same requirement as another open slice?
  yes -> serialize, merge one first, then rebase/rewrite the next delta
  no  -> safe candidate for parallel work

Qué no hacer:

one giant OpenSpec change
  -> six weeks open
  -> many spec domains drift
  -> several agents edit the same proposal
  -> final PR is impossible to review

Mejor:

umbrella decision
  -> small spec-backed PR
  -> merge
  -> archive
  -> next spec-backed PR starts from updated truth

Es la misma razón por la que las ramas de funcionalidad de larga duración perjudican los flujos normales de Git: cuanto más tiempo permanece abierta la rama, más cambia la base. En OpenSpec, la base que cambia no es solo el código. También es openspec/specs/.

Paso 6: Agrega controles de calidad a tasks.md

Las tareas orientadas al usuario deben incluir trabajo de calidad. No lo dejes para el final.

Esta es una sección práctica de calidad en tasks.md para una aplicación web:

## 4. Review And Quality Gates

- [ ] 4.1 Run `openspec validate add-order-idempotency`
- [ ] 4.2 Run unit and integration tests for changed modules
- [ ] 4.3 Run app checks: lint, typecheck, and build
- [ ] 4.4 Run Playwright checkout flow in headed mode and record findings
- [ ] 4.5 Perform code review for correctness, maintainability, and rollback risk
- [ ] 4.6 Perform source/spec audit: proposal, delta specs, design, and tasks match implementation
- [ ] 4.7 Update artifacts for any implementation drift found during review

Para un proyecto Astro/React, eso podría traducirse en:

npm run lint
npm run build
npx playwright test --headed

En CI, Playwright con navegador visible normalmente no es la opción predeterminada. Yo lo ejecutaría con navegador visible en local cuando una persona necesite observar su comportamiento, y luego en modo headless en CI para obtener resultados reproducibles:

local inspection:
  npx playwright test --headed

CI gate:
  npx playwright test

Para los PMs, lo importante no es el comando exacto, sino que la lista de tareas muestre evidencia:

Acceptance scenario -> test or manual verification -> PR note

Paso 7: Usa /opsx:verify antes del PR o antes de archivar

Si el flujo ampliado está habilitado, /opsx:verify es el comando que verifica la implementación frente a los artefactos. La documentación describe tres dimensiones:

  • Integridad: tareas completadas, requisitos implementados y escenarios cubiertos.
  • Corrección: la implementación coincide con la intención de la especificación y maneja los casos límite.
  • Coherencia: la estructura del código refleja el diseño y los patrones locales.

Ejecútalo después de implementar y antes de afirmar que el trabajo está listo:

/opsx:verify add-order-idempotency

Luego convierte las advertencias en tareas:

## 5. Verification Findings

- [ ] 5.1 Add missing test for webhook retry scenario
- [ ] 5.2 Update `design.md` because implementation uses advisory locks, not a queue
- [ ] 5.3 Re-run `/opsx:verify add-order-idempotency`

Si usas el perfil core predeterminado y no tienes /opsx:verify, puedes hacer la misma revisión manualmente:

Compare:
  proposal.md -> did we build the promised scope?
  specs/**/*.md -> does behavior match implemented behavior?
  design.md -> does architecture match the code?
  tasks.md -> are checks complete?
  app test output -> did the product path work?

Paso 8: Abre el PR con el contexto del código y de OpenSpec

La descripción del PR no debería duplicar todos los artefactos. Debería indicarles a los revisores por dónde empezar a leer.

Un cuerpo de PR útil:

## Summary

- Adds idempotency to checkout order creation.
- Covers duplicate client submits and payment webhook retries.
- Keeps follow-up risk dashboard work out of scope.

## OpenSpec

- Change: `openspec/changes/add-order-idempotency/`
- Proposal: intent and scope
- Delta specs: checkout behavior changes
- Design: idempotency approach and rollback considerations
- Tasks: implementation and verification checklist

## Validation

- `openspec validate add-order-idempotency`
- `npm run lint`
- `npm run build`
- `npx playwright test --headed` for checkout flow

Esto les da a los PMs un camino para revisar el producto y a los ingenieros uno para revisar el código.

PM review:
  proposal.md -> specs/**/*.md -> PR summary

Engineer review:
  design.md -> tasks.md -> diff -> tests

QA review:
  specs scenarios -> Playwright/manual evidence -> edge cases

Cómo usar OpenSpec de forma colaborativa en un equipo

OpenSpec no es solo una herramienta individual para crear prompts. Bien utilizado, se convierte en un artefacto compartido de entrega.

El modelo de equipo que recomiendo es:

PM / product owner:
  reviews proposal.md and behavior scenarios

Tech lead:
  owns design.md, risk, boundaries, and split decisions

Implementer or coding agent:
  works from tasks.md and updates it as evidence appears

Reviewer:
  reviews both the diff and the OpenSpec artifacts

Release owner:
  verifies checks, merges PR, then archives the accepted change

La clave es que cada persona revise la parte del cambio que está en condiciones de evaluar.

                    openspec/changes/<change>/
                               |
          +--------------------+--------------------+
          |                    |                    |
          v                    v                    v
     proposal.md          design.md              tasks.md
          |                    |                    |
          v                    v                    v
    PM/product review    engineering review    delivery evidence
          |                    |                    |
          +--------------------+--------------------+
                               |
                               v
                            PR review

Para un solo repositorio, mantén la carpeta del cambio en el mismo repositorio que el código. Así tienes un PR con la intención y la implementación.

Para un monorepo, la guía de OpenSpec para proyectos existentes dice que el modelo más sencillo es un directorio openspec/ en la raíz del repositorio, con dominios que correspondan a paquetes, servicios o áreas de producto. Yo comenzaría por ahí, a menos que tengas una razón de peso para no hacerlo.

repo/
+-- apps/
+-- packages/
+-- services/
+-- openspec/
    +-- specs/
        +-- checkout/
        +-- auth/
        +-- billing/
    +-- changes/

Para trabajar con varios repositorios, la funcionalidad beta de stores de OpenSpec es la opción que conviene investigar. La documentación describe un store como un repositorio independiente de OpenSpec cuyo propósito es la planificación. Los repositorios de código pueden hacer referencia a un store, y openspec context puede reunir la raíz actual con los stores referenciados. Los worksets son diferentes: son vistas personales y locales a una máquina que abren una raíz de planificación junto con las carpetas de código en las que trabajas. La documentación indica explícitamente que esto está en beta, así que lo consideraría prometedor, pero todavía no un proceso que debas imponer a todos los equipos.

Una ruta práctica de adopción:

one repo:
  keep openspec/ in the repo

monorepo:
  keep one openspec/ at repo root

multi-repo feature:
  consider a beta store as the planning home
  reference it from code repos
  use local worksets to open planning + code together

Esto permite que los equipos mantengan la decisión de producto en un solo lugar sin pretender que un agente deba editar todos los repositorios en una sola sesión gigantesca.

Uso de worktrees y subagentes asignados para aplicar cambios

Los git worktrees son el mecanismo de aislamiento más claro para el trabajo paralelo de agentes. La documentación de Git describe git worktree como una herramienta para administrar múltiples árboles de trabajo asociados al mismo repositorio, lo que permite tener más de una rama activa a la vez.

Esto encaja bien con OpenSpec porque sus cambios ya son unidades de trabajo delimitadas por carpetas.

coordinator chat
  |
  +-- worktree A: feature/add-order-idempotency
  |     subagent A applies openspec/changes/add-order-idempotency
  |
  +-- worktree B: feature/add-checkout-risk-dashboard
  |     subagent B applies openspec/changes/add-checkout-risk-dashboard
  |
  +-- worktree C: fix/checkout-copy
        subagent C applies openspec/changes/fix-checkout-copy

El patrón más seguro es un cambio de OpenSpec por subagente:

one subagent
  -> one worktree
  -> one branch
  -> one OpenSpec change
  -> one PR

Ejemplo de configuración:

git fetch origin

git worktree add -b feature/add-order-idempotency \
  ../repo-add-order-idempotency origin/main

git worktree add -b feature/add-checkout-risk-dashboard \
  ../repo-add-checkout-risk-dashboard origin/main

Luego asígnale a cada agente de implementación un prompt con un alcance delimitado:

You are implementing exactly one OpenSpec change.

Repository:
  ../repo-add-order-idempotency

Change:
  openspec/changes/add-order-idempotency/

Workflow:
  1. Read proposal.md, design.md, tasks.md, and delta specs.
  2. Run /opsx:apply add-order-idempotency.
  3. Update tasks.md as you complete work.
  4. If implementation changes behavior, update the delta spec.
  5. Run the checks listed in tasks.md.
  6. Do not archive. Archive happens only after the PR is merged.
  7. Return a summary with changed files, tests run, and unresolved risks.

El coordinador mantiene la disciplina de merge:

subagent applies change in isolated worktree
  -> subagent opens or prepares PR
  -> coordinator reviews artifact drift
  -> CI and human review run
  -> PR merges
  -> coordinator archives accepted change

Esto evita dos fallas comunes de los agentes:

  • Dos agentes editan el mismo árbol de trabajo y sobrescriben los cambios del otro.
  • Un agente archiva especificaciones antes de que el PR de otro agente se haya integrado.

Para funcionalidades complejas, usa subagentes para implementar partes del trabajo, no para tomar decisiones de producto. La persona responsable debe seguir decidiendo si los descubrimientos actualizan el cambio de OpenSpec actual o se convierten en un cambio al mismo nivel.

subagent can decide:
  "I found a missing test task"

owner should decide:
  "This is a new product requirement"

Esto mantiene al equipo en control sin perder la ventaja de velocidad que aporta la ejecución paralela de agentes.

¿Por qué archivar solo después del merge del PR?

Esta es la pregunta más importante.

La documentación de OpenSpec dice que openspec/specs/ es la fuente de verdad sobre el comportamiento actual del sistema. También dice que archivar integra las especificaciones delta en esa fuente de verdad y mueve la carpeta del cambio al archivo.

Si un PR todavía está abierto, el sistema aún no se comporta de esa manera en main.

Por eso, si archivas antes del merge, puedes generar esta discrepancia:

main branch specs:
  "Checkout prevents duplicate orders"

main branch code:
  old checkout path without idempotency

open PR:
  code that would make the spec true, but has not merged

Ese es exactamente el tipo de confusión que las especificaciones deberían evitar.

En un flujo basado en PRs, archiva después del merge porque:

  • Las especificaciones principales deben describir la realidad integrada, no una intención pendiente.
  • Los PRs rechazados o que cambian considerablemente no deberían contaminar openspec/specs/.
  • El rollback es más claro cuando las especificaciones archivadas corresponden a commits entregados.
  • Los revisores todavía pueden inspeccionar los artefactos del cambio activo mientras el PR está abierto.
  • El archivo se convierte en un registro de auditoría del trabajo completado, no de intentos abandonados.

Hay excepciones. En un proyecto individual se puede archivar antes del merge porque la rama y main son, en la práctica, el mismo punto de decisión. Un cambio de larga duración puede usar /opsx:sync antes de archivar si varios cambios necesitan especificaciones base actualizadas. Pero para los equipos, «primero el merge, después el archivado» es la opción predeterminada más clara.

La versión como política:

Before merge:
  openspec/changes/<change>/ describes proposed behavior

After merge:
  /opsx:archive promotes accepted behavior into openspec/specs/

¿Y qué pasa con /opsx:sync antes de archivar?

OpenSpec incluye /opsx:sync en el perfil predeterminado. La referencia de comandos lo describe como una forma de integrar las especificaciones delta en las especificaciones principales sin cerrar el cambio. El archivado puede ofrecer sincronizarlas si es necesario.

Yo usaría la sincronización manual con moderación:

Use /opsx:sync when:
  - a long-running change needs main specs updated before archive
  - parallel changes need the updated spec base
  - reviewers want to inspect the spec merge separately

Skip manual sync when:
  - the PR is small
  - archive will happen right after merge
  - syncing would make main specs describe unmerged behavior

Para la mayoría de los equipos, el flujo más sencillo es:

PR open:
  active change remains under openspec/changes/

PR merged:
  run /opsx:archive, accept sync prompt, commit/archive as needed

Según la política de tu repositorio, el commit de archivado puede ser:

  • un pequeño PR de seguimiento después del merge
  • un PR mantenido por un bot
  • parte de un proceso de cola de merge
  • un commit de mantenimiento posterior al merge en un repositorio individual que trabaja sobre trunk

La clave es que el archivado ocurre cuando el comportamiento está aceptado, no mientras todavía es especulativo.

Una lista práctica de verificación del PR al archivado

Esta es la lista completa que usaría para una funcionalidad:

## OpenSpec Delivery Checklist

### Exploration
- [ ] Explore problem and alternatives with `/opsx:explore`
- [ ] Decide the smallest useful scope

### Branch And Proposal
- [ ] Create feature branch
- [ ] Run `/opsx:propose <change-id>`
- [ ] Review `proposal.md` with PM/product owner
- [ ] Review delta specs for observable behavior and acceptance scenarios
- [ ] If the proposal generated many spec deltas, decide whether it should split into smaller changes
- [ ] Review `design.md` with engineering owner
- [ ] Add quality gates to `tasks.md`
- [ ] Decide whether this is single-repo, monorepo, or multi-repo planning
- [ ] For multi-repo work, decide whether a beta OpenSpec store/workset is useful

### Implementation
- [ ] Run `/opsx:apply <change-id>`
- [ ] Update proposal/spec/design/tasks if implementation discovers drift
- [ ] Keep tasks checked off as evidence is produced
- [ ] If using subagents, assign one change per worktree and branch
- [ ] Make archive off-limits to implementation subagents until after merge

### Verification
- [ ] Run `openspec validate <change-id>`
- [ ] Run lint/typecheck/build commands
- [ ] Run relevant unit/integration tests
- [ ] Run Playwright e2e, headed when human inspection is needed
- [ ] Run `/opsx:verify <change-id>` if available
- [ ] Fix or explicitly accept verification warnings

### PR
- [ ] Open PR with OpenSpec change path in the description
- [ ] Resolve product, engineering, QA, security, and review comments
- [ ] Update artifacts when comments change behavior or design
- [ ] Re-run affected checks

### Merge And Archive
- [ ] Merge PR
- [ ] Run `/opsx:archive <change-id>`
- [ ] Confirm delta specs are synced into `openspec/specs/`
- [ ] Preserve archive under `openspec/changes/archive/`

La lista es intencionalmente aburrida. Aquí, aburrido es bueno. Significa que las personas pueden repetirla.

Ejemplo: agregar un cambio de idempotencia al checkout

Así se ve el flujo en un chat realista.

You: /opsx:explore

We have occasional duplicate orders. Please inspect checkout, payment
webhooks, and client submit behavior. I want the smallest safe fix.

AI:
  Found two duplicate paths:
  1. client double-submit
  2. payment webhook retry

  The webhook retry is higher risk.
  Recommended first change: idempotency around order creation keyed by
  payment intent id.

Crea la rama:

git checkout -b feature/add-order-idempotency

Crea el cambio:

You: /opsx:propose add-order-idempotency

Revisa los artefactos. Luego implementa:

You: /opsx:apply add-order-idempotency

Durante la implementación, supongamos que el agente descubre que la base de datos existente no puede agregar una restricción de unicidad sin una breve migración. No lo ocultes en el código. Actualiza los artefactos:

Update design.md:
  - document the migration approach
  - document rollback
  - explain why application-level retry is still needed

Update tasks.md:
  - add migration test
  - add rollback note
  - add Playwright checkout verification

Luego verifica:

openspec validate add-order-idempotency
npm run lint
npm run build
npx playwright test --headed

Abre el PR. Haz merge. Luego archiva:

You: /opsx:archive add-order-idempotency

Al final, tu repositorio cuenta la historia completa:

git history:
  implementation and review trail

openspec/changes/archive/:
  why this change existed and how it was delivered

openspec/specs/:
  current behavior after the merge

Fallas comunes

Archivar demasiado pronto

Síntoma:

specs say behavior exists, but code is still in an open PR

Solución:

keep the change active until PR merge

Tratar tasks.md solo como un artefacto generado

Síntoma:

tasks are checked, but tests, review, and e2e were never tracked

Solución:

add quality gates as first-class tasks before apply finishes

Crear un solo cambio gigantesco

Síntoma:

proposal says "checkout idempotency"
PR also adds admin dashboard, logging redesign, and payment retry UI

Solución:

split into sibling OpenSpec changes and usually separate branches

Una propuesta se convirtió en una rama interminable

Síntoma:

one proposal touches five specs
three teams depend on it
the PR stays open for weeks
main specs keep changing underneath it

Solución:

turn the large proposal into an umbrella decision
ship smaller spec-backed slices one by one
archive each accepted slice before starting dependent slices

El objetivo no es eliminar la gran idea. El objetivo es dejar de tratarla como una sola unidad de implementación.

Actualizar el código, pero no las especificaciones

Síntoma:

implementation behavior changed during review, but delta specs still
describe the old behavior

Solución:

update delta specs before archive, because archive promotes specs into truth

La propuesta y la implementación se desviaron hacia algo incorrecto

Síntoma:

proposal says "add checkout idempotency"
apply produced "rewrite checkout orchestration"
team does not want the broader result

Solución:

stop before archive
decide whether the proposal is wrong, the implementation is wrong, or both

La documentación de edición de OpenSpec dice que los artefactos son archivos de Markdown sin formato y que se pueden editar en cualquier momento. Aprovecha eso de forma deliberada:

same intent, bad implementation:
  keep proposal/specs/design
  update tasks.md with the correction
  replace or revise the code until it matches the artifacts

same intent, better discovered approach:
  amend design.md and tasks.md
  update delta specs if behavior changed
  run /opsx:apply again against the amended artifacts

intent changed or scope exploded:
  stop the current PR
  create a new OpenSpec change and usually a new branch
  do not archive the abandoned change as completed behavior

El error es intentar «arreglar» la historia solo en la descripción del PR. Antes de archivar, la fuente de verdad es la carpeta del cambio activo. Si el código final no es lo que quieres, haz que el código coincida con los artefactos actuales o haz que los artefactos describan honestamente el comportamiento final deseado. Si ninguna de las dos opciones se cumple, comienza de nuevo con un cambio más claro.

El nuevo cambio entra en conflicto con especificaciones anteriores

Síntoma:

new change is correct, but openspec/specs/ still describes old behavior
or
delta spec modifies a requirement that has drifted since the change began

Solución:

reconcile the canonical spec before archive

Trátalo como un problema de integración de especificaciones, no como un problema de prompts.

1. Read the current canonical spec under openspec/specs/<domain>/spec.md.
2. Read any active sibling changes touching the same domain.
3. Decide whether the old spec is stale or the new change is wrong.
4. If the old spec is stale, update it through an explicit delta.
5. If the new change is wrong, amend the active change.
6. Re-run validation and verify before archive.

Ten especial cuidado con MODIFIED Requirements. Las conversaciones en issues de OpenSpec describen MODIFIED como un reemplazo completo del requisito identificado por su nombre, no como un pequeño parche. Si dos cambios modifican el mismo requisito desde puntos de partida distintos, el archivado posterior puede sobrescribir escenarios del cambio anterior, a menos que se haya reconciliado el delta.

Mi regla práctica:

adding a new independent behavior:
  prefer ADDED Requirements

changing an existing behavior:
  use MODIFIED Requirements
  include the full updated requirement and all scenarios you want to keep

removing obsolete behavior:
  use REMOVED Requirements
  explain why in the proposal/design

old spec is simply wrong:
  create a small spec-repair change, or make the repair explicit
  inside the current change if it is required for this PR

No archives hasta que el delta se base en la especificación canónica actual, no en la versión que recuerdas vagamente del inicio de la rama.

Mi política recomendada para equipos

Si introdujera OpenSpec en un equipo de ingeniería, comenzaría con estas reglas:

1. Explore freely before branching.
2. Create a feature branch before proposal.
3. Keep one OpenSpec change per PR unless there is a strong reason.
4. Treat proposal/spec/design/tasks as reviewable source files.
5. Add quality gates to tasks before calling the work done.
6. Run app checks and e2e before PR is ready.
7. Update artifacts when implementation or review changes behavior.
8. Merge PR before archive.
9. Archive only accepted behavior into main specs.
10. For team work, make artifact ownership explicit.
11. For subagent work, use one worktree, one branch, one change, one PR.
12. Keep archive as the coordinator or release-owner responsibility.
13. Split many-spec proposals into reviewable slices before implementation.

Las reglas no buscan agregar ceremonia. Buscan prevenir la falla más costosa del desarrollo asistido por IA: una implementación hecha con confianza, pero sin un acuerdo duradero sobre lo que cambió.

OpenSpec es útil porque mantiene ese acuerdo cerca del código.

Fuentes