OpenSpec en Argui

OpenSpec es el motor del ciclo iterativo (fase 5): un framework de desarrollo guiado por specs, multi-herramienta por diseño. Es la dependencia núcleo de la metodología —la única requerida y la única estructural (el ciclo se construye sobre su schema y sus comandos)—, así que tiene reglas claras de personalización y de mantenimiento para no quedar atada a una versión que evoluciona. El inventario completo de dependencias, por nivel, está en Dependencias.

Independiente de la herramienta: con otro framework SDD (Spec-Driven Development) de stages equivalentes, los mismos principios aplican (ver Portabilidad).

Qué va en un spec

El spec es la capa de comportamiento: por capacidad (capability), qué hace el sistema en cada estado —validaciones, mensajes, permisos, reglas, casos límite—. Lo que responde por qué o para quién es del PRD de negocio; lo estructural y transversal, del PRD técnico. Cada hecho se escribe en una sola capa y las demás lo referencian por su ID (RF-2). La frontera completa, con la regla de decisión y qué manda cuando dos capas se contradicen, está en workflow.md → Las capas de la definición.

Cada spec cita el RF-* que satisface: es la trazabilidad que continúa la de las insignias del prototipo.

El modelo de personalización

Se personaliza con el mecanismo oficial de OpenSpec, nunca editando sus internals:

• Schema propio forkeado. openspec schema fork spec-driven argui copia el schema base a openspec/schemas/argui/ en el proyecto. Ese fork es donde vive la personalización.
• El schema.yaml define artifacts y stages con los campos id / generates / template / instruction / requires. El campo instruction es la prosa que dirige a la IA en ese artifact o stage.
• Perfil de Argui = core + verify + qa. El perfil core de OpenSpec no incluye verify por defecto; en Argui verify no es opcional —es donde opera la separación implementador/revisor— así que el fork lo conserva. qa es un stage propio de Argui (no existe en OpenSpec), entre verify y archive.
• Los slash commands (/opsx:apply, /opsx:verify, /opsx:sync, /opsx:archive…) son los bindings por asistente. Los regenera openspec update desde el CLI (Command Line Interface) instalado — nunca se editan a mano.

Dónde vive la orquestación de agentes

Las decisiones de invocación de agentes (ver Agentes y Eficiencia) viven en los campos instruction de cada stage del schema argui. Ese es el lugar concreto al que se refiere “la lógica de invocación vive en la skill”:

• apply.instruction: qué agente(es) implementador(es) corren; batch de archivos en una invocación; si el gate marcó impacto arquitectónico, el arquitecto participa.
• verify.instruction: hasta tres pases — cumplimiento (económico), juicio (capaz, es la revisión de código del ciclo) y seguridad (capaz), este último solo si el gate de superficie sensible marca el change. Describe el trabajo, no el comando: si el asistente ofrece una revisión empaquetada se nombra como atajo disponible, nunca como única vía.
• qa.instruction: generar el artefacto de QA (Quality Assurance) y correr su protocolo en orden —verificar los datos en la base, correr lo automatizable y registrarlo, entregar los bloques manuales—, gate de costo de automatización, cierre con aprobación humana.
• archive.instruction: sync de delta specs, revisión final, actualización de progreso (incluido el diagrama de dependencias del backlog), la fila del change en el índice de changes archivados —crearlo si no existe— y la pregunta por la regla aprendida, que se escribe donde se aplica (ver Las 7 fases F5.1).

Es prosa = comportamiento, no código frágil: un LLM (Large Language Model) ejecuta el instruction sin un parser acoplado al formato. El model de cada agente vive en el agente (qué tier); el cuándo invocarlo vive aquí. Es el principio “código vs. responsabilidad” de Portabilidad.

Qué se distribuye y qué no (anti-obsolescencia)

Forkear copia el spec-driven del momento. Si OpenSpec mejora su schema base, el fork no lo recibe (los bindings sí, vía openspec update; el schema forkeado no). Esa es la superficie de obsolescencia. La regla:

Argui distribuye el delta + la receta, no un schema congelado. Ver Delta sobre OpenSpec.

Cómo se arma en un proyecto

En dos mitades, cada una donde tiene sus dependencias.

En la fundación (F0.2) — no depende de nada, y evita que el proyecto cambie de schema a mitad de camino:

1. Fijar la versión de OpenSpec: npm install -D @fission-ai/openspec@<versión> (nunca @latest).
2. Forkear el schema contra esa versión: openspec schema fork spec-driven argui. Al principio es idéntico al base; desde ese momento todo change del proyecto nace en el schema propio.

En la preparación técnica (F4.8) — necesita los estándares base y los agentes, que se crean en esa misma fase:

3. Aplicar el delta de Argui sobre el fork: conservar verify, agregar el stage qa (snippet en templates/openspec/), y pegar los instruction de orquestación de cada stage (instructions.snippet.yaml), reemplazando los [corchetes] por los agentes del proyecto.
4. Regenerar bindings: openspec update.
5. Validar el ciclo end-to-end con un ítem de prueba antes de soltarlo al backlog real.

Entre las dos mitades el ciclo funciona con el comportamiento base: alcanza para las etapas de definición —las que corre el refinamiento opcional de F3.5—, no para las de construcción.

Mantenimiento al subir de versión

OpenSpec queda fuera de las actualizaciones automatizadas (Estándares §11): el bump es un trabajo con receta, que se hace en la auditoría periódica (ver Operaciones) o al arrancar un proyecto:

1. Leer las release notes de OpenSpec.
2. Diff del nuevo spec-driven contra el fork argui; re-aplicar el delta sobre una base fresca si cambió algo relevante.
3. openspec update para refrescar los bindings.
4. Re-validar el ciclo.
5. Actualizar la versión declarada en el CLAUDE.md del proyecto — al re-validar, no al instalar: mientras la receta no corra, la línea sigue diciendo la verdad (contra qué versión está validado el fork) y su divergencia con el lockfile es la señal de que falta trabajo. Ver CLAUDE.md vivo → Directivas operativas.
6. Actualizar en el CHANGELOG contra qué versión de OpenSpec se validó.

Mantener el delta mínimo y aditivo hace barato re-aplicarlo — y es la mejor defensa contra la obsolescencia.