Argui

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 dependencies.md.

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

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 agents.md y efficiency.md) 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: dos pases — cumplimiento (económico) y juicio (capaz).
  • qa.instruction: generar el artifact de QA (Quality Assurance), recorrer pruebas, 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).

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 portability.md.

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:

Parte De quién es Cómo se distribuye
Stages base (proposal, specs, design, tasks, apply, verify, archive) OpenSpec No se congelan copias. Salen del fork generado contra la versión instalada.
Stage qa + plantilla del artifact de QA Argui Se distribuye como snippet/template (no tiene upstream del cual diverja).
instruction de orquestación de agentes Argui Se distribuye como delta documentado que se aplica sobre el fork.

Argui distribuye el delta + la receta, no un schema congelado. Ver templates/openspec/.

Cómo se arma en un proyecto (fase 4)

  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.
  3. Aplicar el delta de Argui sobre el fork: conservar verify, agregar el stage qa (snippet en templates/openspec/), y escribir los instruction de orquestación de cada stage.
  4. Regenerar bindings: openspec update.
  5. Validar el ciclo end-to-end con un item de prueba antes de soltarlo al backlog real.

Mantenimiento al subir de versión

Parte de la auditoría de dependencias (ver operations.md) y del arranque de cada 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 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.