Workflow

El proceso completo de Argui, desde la idea hasta el producto. Los pasos están en orden deliberado: cada uno le da contexto al siguiente. El proceso se organiza en 7 fases (de la 0 a la 6).

La metodología se sigue desde esta documentación — no desde el CLAUDE.md del proyecto. El CLAUDE.md cumple otro rol: mantener el estado del proyecto (ver CLAUDE.md vivo).

Diagrama del flujo

FASE 0  Fundación        CLAUDE.md vivo + OpenSpec + aislar la herramienta de IA
FASE 1  Entendimiento    Exploración y/o investigación → Documento de Entendimiento ✋
FASE 2  PRD inicial      PRD inicial → agente PRD → validación ✋
FASE 3  Prototipo        Prototipo ↔ PRD, feedback ✋ → PRDs negocio/técnico ✋ → refinamiento opc. ✋
FASE 4  Preparación      MCPs/Skills → arquitecto → backlog → estándares → agentes
FASE 5  Iteración        [ gate → apply → verify → qa ✋ → archive ] × cada ítem
FASE 6  Evolución        Recepción (4 fuentes) → triaje → carril → ciclo de fase 5

✋ = punto de aprobación humana explícita

IDs de paso. Cada paso se identifica como F{fase}.{paso} (p. ej. F3.2 = segundo paso de la fase 3). El contador reinicia en cada fase: insertar o quitar un paso solo renumera su propia fase, nunca las demás —así las referencias entre documentos no se rompen ante cambios estructurales—. La fase 6 es un lazo recurrente, no una secuencia: sus partes se nombran, no se numeran.

Entregable por fase. Cada fase cierra con un artefacto concreto, declarado al inicio de su sección: mientras no exista ese artefacto, la fase no cerró. La fase 6 es la única excepción —es un lazo recurrente, no una secuencia—: cada vuelta entrega lo mismo que la fase 5.

A lo largo de todas las fases corre una disciplina operativa transversal: ramas y commits sugeridos por unidad de trabajo, PR (Pull Request) al archivar, limpieza de contexto por sesión y auditorías periódicas de specs, tokens, salud de la suite de tests y métricas de entrega (Métricas). Ver Operaciones.

Las capas de la definición: qué vive dónde

La definición del producto vive en cuatro capas, cada una con una pregunta que responde, un dueño y un momento en que nace. Separarlas es lo que evita dos fuentes de verdad: el mismo hecho escrito en dos documentos que después se desincronizan.

Capa	Responde	Contiene	Dueño	Nace
PRD de negocio	por qué / para quién	Problema, usuarios, alcance y no-alcance, métricas, restricciones de negocio	agente PRD (`F2.2`)	`F3.4`
PRD técnico	con qué / sobre qué	Stack, arquitectura, estructura, modelo de datos, decisiones transversales	agente PRD al nacer; arquitecto (`F4.2`) de ahí en adelante	`F3.4`
Prototipo + design system — o el contrato + sus convenciones cuando no hay UI	cómo se ve / cómo se consume	Pantallas, flujo visual, tokens y componentes — o schema, ejemplos y convenciones del contrato	agente UX/UI o dueño del contrato (`F3.1`)	`F3.2`
Specs	cómo se comporta	Comportamiento por capacidad (capability en OpenSpec): estados, validaciones, mensajes, permisos, reglas, casos límite	el change que la escribe	con cada ítem — o en `F3.5`

Antes de F3.4 las dos primeras son un solo PRD inicial (F2.1), que se parte recién cuando el prototipo está aprobado. Las cuatro capas son vivas: crecen con el producto y se corrigen cuando dejan de ser verdad. En brownfield cambia cómo nacen —se recuperan incompletas—, no qué contiene cada una (ver Brownfield).

La regla de decisión

Si el dato cambiaría al agregar una capacidad, es spec. Si cambiaría al cambiar el negocio o la arquitectura, es PRD.

El PRD dice “el usuario puede invitar a un compañero de equipo”. Qué pasa cuando ese correo ya fue invitado, qué ve un rol sin permiso, qué dice exactamente el mensaje de error: eso es spec.

Cada hecho se escribe una sola vez. La otra capa lo referencia por ID (RF-2, MET-1) en vez de repetirlo — el mismo mecanismo con el que el prototipo traza a los requisitos (F3.2). Una frase copiada de un documento a otro es una desincronización futura.

La dirección del flujo

Hacia abajo: cada spec cita el RF-* que satisface. Es la trazabilidad que continúa la de las insignias del prototipo.
Hacia arriba no sube comportamiento. Del ciclo a los PRDs vuelven solo correcciones estructurales —una relación descubierta, una decisión transversal que cambió— y las preguntas abiertas que se cierran, que se anotan como decisión en decisiones.md.

Cuando se contradicen

Comportamiento: manda la spec del change archivado — describe lo que está construido.
Alcance y porqué: manda el PRD.

La discrepancia es un hallazgo de la auditoría specs↔código (Operaciones): se corrige la capa desactualizada. Nunca se resuelve escribiendo el dato en las dos.

Fase 0 — Fundación

Entregable: proyecto fundado — CLAUDE.md vivo y decisiones.md abierto, OpenSpec inicializado con su versión fijada y su schema forkeado, .gitignore de partida puesto y entorno de IA aislado.

Setup — aislar la herramienta de IA

Antes de tocar el proyecto, confina el asistente al repositorio: lectura/escritura acotadas a la carpeta y red default-deny. Es baseline de seguridad y privacidad, no opcional —por defecto la lectura del asistente es amplia e incluye ~/.ssh/ y ~/.aws/credentials—. El detalle y los dos niveles (nativo / contenedor) están en Operaciones → Aislamiento del entorno de IA; la implementación de referencia para Claude Code, en Aislamiento del entorno. (Es setup previo a los pasos de la fase; no recibe ID de paso.)

F0.1 · CLAUDE.md vivo

Establecer un CLAUDE.md que se mantenga actualizado a medida que el proyecto evoluciona, que se automejore y que siempre contenga de forma concisa la información más relevante para el proyecto y su fase actual.

El CLAUDE.md no contiene el paso a paso de la metodología. Contiene tres cosas: el estado del proyecto, el mecanismo de automejora y las directivas operativas del proyecto (por ejemplo: los agentes no hacen commits — el control de lo que se confirma es humano).

Se abre también el decisiones.md en la raíz —vacío, con su encabezado—: es el log append-only donde caen las decisiones de arquitectura, proceso y producto desde el primer día, y el destino al que el CLAUDE.md manda todo lo que empieza con una fecha. Ver Operaciones → Registro de decisiones y Registro de decisiones.

Ver CLAUDE.md vivo y la plantilla CLAUDE.md.

F0.2 · OpenSpec

Inicializar OpenSpec en el proyecto desde el inicio. Sus herramientas se usan a lo largo de todo el proceso (la exploración de la fase 1 puede hacerse con /opsx:explore), no solo en el ciclo iterativo de la fase 5.

Dos cosas se hacen ya, porque no dependen de nada y evitan una mudanza después:

Fijar la versión, nunca @latest: npm install -D @fission-ai/openspec@<versión>. Esa versión se declara en el CLAUDE.md (F0.1): es contra la que queda forkeado el schema y la que un agente necesita saber en sesión — ver CLAUDE.md vivo.
Forkear el schema contra esa versión: openspec schema fork spec-driven argui. Al principio es idéntico al base; lo que importa es que todo change del proyecto nazca en el schema propio desde el día uno.

Lo que sí espera a la fase 4 (F4.8) es llenar ese fork —el stage qa, los criterios de verify y la orquestación por agente—, porque necesita los estándares y los agentes que ahí se crean. Todo el detalle está en OpenSpec.

Acelerador (Claude Code, no requisito). Instalar también temprano la skill find-skills: es el mecanismo con el que en la fase 4 se descubren e instalan las demás skills del proyecto. Recomendada, no estructural — ver Dependencias. El inventario completo de dependencias externas vive ahí.

F0.3 · `.gitignore` de partida

Poner el .gitignore antes de que llegue el primer archivo confidencial. Lo que entra al historial no se saca sin reescribirlo, y el material sensible llega en la fase 1 —cuando ya es tarde para acordarse—.

Se copia .gitignore de partida a .gitignore en la raíz y se le agrega lo propio del stack. Trae initial-references/ (material de stakeholders, F1.1), .claude/settings.local.json, los .env y los volcados de base de datos.

Es la otra mitad del aislamiento: el sandbox acota lo que el asistente lee; el .gitignore acota lo que el repositorio publica.

Fase 1 — Entendimiento

Entregable: el Documento de Entendimiento, aprobado ✋.

F1.1 · Exploración y/o investigación

Referencias iniciales. Es común que los stakeholders entreguen un conjunto de documentos en la primera aproximación al proyecto: imágenes, notas, audios, PRDs (Product Requirements Document) previos, requerimientos. Ese material se guarda en una carpeta initial-references/ en la raíz del proyecto y es insumo de cualquiera de las dos rutas. Como casi siempre contiene información confidencial, la carpeta ya viene ignorada desde el .gitignore de F0.3 — solo se versiona si se confirma que no hay nada sensible, quitando esa línea y anotándolo como decisión.

El punto de partida es flexible. Hay dos rutas, que pueden combinarse:

Ruta A — Exploración conversacional: una sesión de exploración (/opsx:explore) donde se cuenta lo que se tiene en la cabeza, se conversa para descubrir alcance, restricciones y dudas, y se converge en el Documento de Entendimiento (F1.2), que es lo que queda por escrito de la conversación. Es la ruta natural cuando la idea ya existe y necesita estructura.
Ruta B — Investigación formal: una investigación documentada (análisis de initial-references/ + consultas en internet) sobre el dominio del problema. El documento de investigación es insumo del Documento de Entendimiento (F1.2) y se conserva aparte como material de respaldo. Es la ruta natural cuando el dominio es desconocido o el riesgo de asumir es alto.

En ambas rutas el objetivo es el mismo: entender el problema lo suficiente para escribir un primer PRD honesto — no código, no arquitectura. Y en ambas el resultado se consolida en un solo artefacto (F1.2): una exploración sin documento no deja rastro y se pierde al cerrar el contexto.

F1.2 · Documento de Entendimiento ✋

El entregable de la fase: la síntesis de lo entendido — del problema, no de la solución. Es lo que hace que el primer PRD no nazca de la nada.

Contiene siete cosas:

Problema y contexto — qué se resuelve, para quién, por qué ahora.
Usuarios y sus trabajos — quién lo usa y qué intenta lograr (no qué funcionalidad pide).
Alcance y no-alcance — qué es el producto y qué deliberadamente no es. Si se entrega en más de un hito —bloques que se venden y se cobran por separado—, acá nace el mapa de hitos (ver Hitos).
Restricciones y supuestos — lo que no se puede cambiar y lo que se está dando por cierto.
Riesgos y preguntas abiertas — los huecos honestos, localizados.
Glosario / lenguaje ubicuo — los términos del dominio con el significado que tienen acá.
Decisiones tomadas durante la exploración, con su porqué.

Frontera: no lleva requisitos funcionales, specs ni decisiones de stack — eso es la fase 2. Si aparecen durante la exploración, entran como decisión (punto 7), no como requisito.

Las preguntas abiertas se heredan al PRD en vez de desaparecer: son las que vuelven honesta la v1 y las que el prototipo de la fase 3 ayuda a cerrar.

Se escribe sin datos sensibles para poder versionarlo: se nutre de initial-references/ (confidencial, en .gitignore) pero no copia su contenido.

Aprobación ligera ✋. No hay checklist de agente: el humano confirma tres cosas —que el alcance y el no-alcance son los correctos, que los riesgos listados son los reales y que el problema está bien encuadrado—. Cuesta minutos y evita que el PRD y el prototipo se construyan sobre un problema mal planteado.

Plantilla: Documento de Entendimiento.

Fase 2 — PRD inicial

Entregable: PRD inicial validado ✋ — la definición única que el prototipo va a materializar e iterar.

F2.1 · PRD inicial

Escribir un solo PRD a partir del Documento de Entendimiento (F1.2). Todavía no se parte en negocio y técnico: antes del prototipo lo que hace falta es una definición única y manejable que se pueda materializar y corregir rápido.

Breve y manejable: si el archivo crece demasiado, se divide en varios.
Es una v1 deliberadamente: se itera con el prototipo durante toda la fase 3.
Requisitos con ID estable (RF-1, MET-1, …). El prototipo traza a esos IDs, no a números de sección: es lo que mantiene viva la trazabilidad cuando el documento se parte en dos (F3.4).
Hereda las preguntas abiertas del Documento de Entendimiento — el prototipo es el instrumento con el que se cierran.

Plantilla: PRD inicial.

F2.2 · Agente PRD

Crear el agente experto en el PRD después del primer borrador — no antes. Al inicio del proyecto no se sabe con precisión de qué va el producto; con la v1 ya existe el material para definir una experticia real. Este agente ajusta, mejora y mantiene el PRD durante el resto del proyecto: es quien lo itera con el prototipo en F3.3 y quien ejecuta la explosión en dos documentos en F3.4.

Pautas de creación de agentes: Agentes.

F2.3 · Validación del PRD inicial ✋

Validar la definición antes de construir el prototipo. Dos partes:

Checklist del agente PRD: problema claramente definido, usuarios objetivo identificados, alcance del PMV (Producto Mínimo Viable) explícito con sus casos fuera de alcance, métricas de éxito establecidas y preguntas abiertas heredadas de la fase 1.
Confirmación humana: se presenta un resumen ejecutivo con preguntas concretas: ¿el problema está bien definido? ¿el alcance del PMV es correcto? ¿hay algo crítico ausente? El proceso no avanza hasta la aprobación explícita.

Se valida la definición, no el detalle: lo que quede abierto se cierra con el prototipo. El detalle de comportamiento —estados, validaciones, mensajes, permisos— nunca vive acá: es de las specs (ver Las capas de la definición).

Fase 3 — Prototipo trazable

Entregable: prototipo aprobado ✋ —referencia visual canónica del producto—, la semilla del design system y los PRDs de negocio y técnico validados ✋ (F3.4). Si se corre el paso opcional F3.5, se suma el acuerdo de detalle de los flujos refinados.

La validación temprana se hace con un prototipo navegable enlazado al PRD inicial — no con código de producción. Guía completa: Prototipo.

Sin UI —una API, una CLI, un pipeline— la fase es la misma y cambia el artefacto: se valida la superficie observable del producto contra su consumidor (ver prototype.md → Cuando no hay UI).

F3.1 · Agente UX/UI

(Sin UI: el dueño del contrato — quien diseña y mantiene la superficie que se va a validar.)

Crear el agente UX/UI (experiencia / interfaz de usuario) que construirá y mantendrá el prototipo. Su Expertise incluye criterio de diseño real (no solo maquetar) y declara la skill de diseño que usa siempre antes de generar UI. Antes de maquetar fija una dirección de diseño ligera —derivada del manual de marca del cliente si existe, o decisiones provisionales explícitas si no— que es la semilla de un design system que crece dentro del prototipo y la fase 4 consolida. Ver Prototipo.

F3.2 · Prototipo no funcional con trazabilidad

(Sin UI: el contrato trazado, con su RF-* declarado en cada operación.)

Construir un prototipo navegable cuyo propósito es validar con los stakeholders lo definido en el PRD:

Es un solo archivo HTML autónomo —pantallas, estilos y andamiaje adentro— con un switch de modo: encendido muestra insignias, notas y feedback; apagado se ve como producción. Un artefacto para las dos audiencias, no dos versiones que mantener.
Cada bloque de la UI lleva una insignia de trazabilidad con el ID estable del requisito que lo define (RF-2, MET-1), que enlaza al PRD (visible con el modo encendido). Se traza por ID y no por número de sección para que la referencia sobreviva a la explosión en dos PRDs de F3.4.
Las dudas y aclaraciones para el cliente se anotan en el lugar correspondiente del prototipo, registradas también en el PRD y enlazadas desde el prototipo.
Hay un mecanismo de feedback por bloque de bajo costo y baja fricción (comentarios exportables y/o formulario que llega por correo), para recolección autónoma en un sitio estático.

La maquinaria de trazabilidad y feedback se toma del andamiaje reutilizable (Andamiaje del prototipo), no se reimplementa por proyecto.

F3.3 · Iteración prototipo ↔ PRD ✋

Los stakeholders ven lo que describe el PRD, comentan, y ese feedback alimenta el ajuste del prototipo y del PRD —y el design system, cuando el ajuste toca apariencia— siempre juntos. Todo cambio al prototipo cumple una Definition of Done que mantiene la trazabilidad, de a un ajuste y con confirmación antes de propagar (ver Prototipo). Se opera con el comando de ciclo de ajustes (prototype-adjust).

El paso cierra cuando los stakeholders aprueban el prototipo. Desde ese momento el prototipo es la referencia visual canónica del producto: en la fase 4 se consolida el design system extrayéndolo del prototipo aprobado (venía creciendo desde fase 3), para evitar divergencias de apariencia entre lo aprobado y lo entregado.

F3.4 · PRDs de negocio y técnico ✋

Con el prototipo aprobado, el PRD inicial se parte en dos documentos, que de aquí en adelante tienen audiencias y ritmos distintos: el de negocio (problema, usuarios, alcance, métricas — el contrato con el cliente) y el técnico (stack, arquitectura, restricciones), que es el insumo directo de la fase 4.

Se hace después del prototipo y no antes por una razón: el prototipo cambia la definición. Partir en dos un documento que todavía se va a mover obliga a mantener sincronizados dos archivos justo en la fase donde más cambian.

Lo ejecuta el agente PRD (F2.2), que ya conoce el documento y lo iteró durante la fase.
Los IDs de requisito no cambian: RF-2 sigue siendo RF-2 aunque se mude de documento. Es lo que mantiene vivas las insignias del prototipo — y lo que después referencian las specs.
El reparto sigue la frontera de las capas: el porqué y el alcance al de negocio, la estructura al técnico, el comportamiento a ninguno de los dos (ver Las capas de la definición).
El PRD de negocio registra las dos decisiones que activan estándares condicionales en la fase 4: la descubribilidad pública (sí/no) —gate del estándar SEO (Search Engine Optimization)/GEO (Generative Engine Optimization), Estándares §8— y si el producto lleva IA dentro (sí/no) —gate de evals y guardrails, §10; la pregunta no es si se construye con IA, sino si el usuario ve la salida de un modelo—.
Validación ✋: checklist de completitud del agente PRD —problema, usuarios, métricas, restricciones técnicas documentadas, casos fuera de alcance— y confirmación humana. Acá se valida que la definición está completa para construir el producto, no solo para el prototipo. Nada de la fase 4 arranca sin esa aprobación.

Plantillas: PRD de negocio y PRD técnico.

F3.5 · Refinamiento del prototipo (opcional) ✋

El prototipo aprobado sirvió para validar y para vender. Este paso lo convierte en especificación visual ejecutable: se completan pasos intermedios, estados de vacío/carga/error, validaciones y textos reales, permisos por rol y máquinas de estado como pantallas, hasta que cada paso cumple el umbral —camino feliz, estado vacío, un error realista, permisos por rol, textos reales—.

Es opcional y parcial. Se hace cuando el costo de la ambigüedad es alto (alcance cerrado por contrato, equipo externo, muchos roles y estados) y solo sobre los flujos que lo justifican. Saltarlo no es deuda: el detalle se define igual, más tarde, dentro de cada change de la fase 5.
Es un punto de re-entrada. Cuando el prototipo se usó para vender y la venta se cierra meses después, se vuelve a la fase 3 por este paso.
Arranca con el inventario de flujos: matriz rol × flujo × paso (completo / parcial / ausente), de la que salen el backlog de refinamiento, el estimado y el guion de la sesión con el cliente. Plantilla: Inventario de flujos.
El entregable es el acuerdo escrito, no el prototipo más grande: un change de OpenSpec por flujo completo, con su delta de spec, que queda pendiente —el spec entra a openspec/specs/ cuando la fase 5 lo construye y archiva—. Corre solo las etapas de definición (proposal → specs → design), así que no requiere el ciclo personalizado de la fase 4.
Validación ✋: el stakeholder aprueba el detalle acordado por flujo, sobre el prototipo.

Va después de F3.4 y no antes porque la partición del PRD no debe esperar a un paso opcional que puede ocurrir meses más tarde: F3.4 valida el qué; F3.5 acuerda el detalle. Y va en la fase 3 y no en la 4 porque es trabajo con el stakeholder —sesiones y acuerdos—, y la fase 4 es interna por diseño.

No hay mudanza de schema que arreglar después: el fork del proyecto existe desde F0.2, y lo que F4.8 agrega gobierna las etapas de construcción, que aquí no se corren. Solo si esa personalización llegara a exigir algo nuevo a las etapas de definición, se revisan los changes ya definidos.

Guía completa: Prototipo.

Fase 4 — Preparación técnica

Entregable: backlog priorizado con dependencias —encabezado por el ítem que consolida el design system, que se construye ya en la fase 5—, estándares base, agentes del proyecto y el ciclo de OpenSpec personalizado —sin él la fase 5 no puede arrancar—.

F4.1 · MCPs y Skills — primera pasada

Análisis preliminar de MCPs (Model Context Protocol) y skills candidatos según el stack y dominio definidos en el PRD técnico, para que el backlog nazca con contexto real de lo que es posible y eficiente.

Recursos: context7.com para docs de librerías y skills.sh para skills. En Claude Code, el descubrimiento e instalación de skills se hace con find-skills (instalada en la fase 0 — ver Dependencias).

F4.2 · Agente arquitecto

Crear el agente de arquitectura antes del backlog, porque es quien valida que el backlog sea técnicamente coherente. Sus responsabilidades:

Definir el stack tecnológico y justificarlo basado en los PRDs
Resolver ambigüedades técnicas del PRD antes de que lleguen al backlog
Revisar el backlog para detectar dependencias ocultas o decisiones que comprometan la arquitectura
Ser el árbitro cuando los implementadores encuentran decisiones de diseño no especificadas
Intervenir en el ciclo iterativo cuando un cambio tiene impacto arquitectónico

F4.3 · Agente para backlog

Basado en los PRDs (ya validados con prototipo), crear un agente con la experticia adecuada para construir el backlog. Antes de construirlo, el arquitecto resuelve las ambigüedades técnicas pendientes de los PRDs.

F4.4 · Crear backlog

Construir el backlog con el agente experto. Especificaciones obligatorias:

Los primeros ítems son siempre: (1) el design system consolidado (extraído del prototipo aprobado, donde venía creciendo desde fase 3) y (2) la configuración de CI/CD (Continuous Integration / Continuous Delivery) —con versión trazable y rollback automático (Estándares §7), instrumentación del monitoreo mínimo (§9) y el audit de dependencias (§11)—. Ambos van primero porque todo lo demás los consume.
Los flujos ya refinados en F3.5 entran como ítems que apuntan a su change pendiente, no se vuelven a describir: heredan su tamaño (un flujo completo) y su definición. El backlog sigue siendo la lista única y completa; el refinamiento solo adelantó parte de ella.
Dependencias explícitas — ningún ítem arranca si sus dependencias no están archivadas.
Si el proyecto se entrega por hitos, cada ítem declara el suyo. El backlog sigue siendo una sola cola: el corte entre hitos es prioridad y dependencia, no un archivo aparte (ver Hitos).
Diagrama de dependencias — el backlog incluye un grafo (Mermaid) que es a la vez el mapa de progreso: cada nodo refleja el estado de su ítem (pendiente / en curso / archivado). Cómo se mantiene vivo, en F5.1.
Si es necesario, dividido en múltiples archivos.

El arquitecto revisa el backlog resultante antes de darlo por finalizado.

Plantilla: Backlog

F4.5 · MCPs y Skills — refinamiento

El backlog puede revelar necesidades que el PRD no anticipó. Segunda pasada para confirmar y agregar al proyecto los MCPs y skills definitivos (skills vía find-skills).

F4.6 · Estándares base

Crear los estándares base del proyecto antes de los agentes especializados, para evitar patrones implícitos inconsistentes. Mínimo: base del proyecto, backend, frontend, tests, documentación, workflow, despliegue continuo (§7), monitoreo en producción (§9) e higiene de dependencias (§11) —los tres se cablean en el ítem PRJ-002—. Condicionales, según lo que el PRD de negocio haya decidido en F3.4: descubribilidad (SEO/GEO) (§8) y evals y guardrails (§10), este último solo si el producto lleva IA dentro.

Ver Estándares.

F4.7 · Agentes especializados

Analizar el backlog y crear los agentes más adecuados para las necesidades específicas del proyecto: implementadores, revisores, testers, documentadores. No hay agentes fijos ni plantillas universales — los agentes dependen del proyecto y se crean siguiendo las pautas de Agentes, incluida la asignación del modelo más eficiente por agente (ver Eficiencia).

Cada agente extiende los estándares base con criterios de su dominio y usa siempre los skills y MCPs del proyecto que le correspondan.

F4.8 · Personalizar el ciclo de OpenSpec

El fork del schema existe desde F0.2; acá se llena, que es lo que convierte el ciclo base en el ciclo de Argui:

Conservar verify y agregar el stage qa (snippet en Delta sobre OpenSpec).
Escribir los instruction de orquestación de cada stage: qué agente lo corre y con qué criterio. Aquí se cablea la separación implementador/revisor.
Regenerar los bindings: openspec update.
Validar el ciclo end-to-end con un ítem de prueba antes de soltarlo al backlog real.

Va al final de la fase porque depende de lo que la fase produce: los estándares base (F4.6) dan los criterios de verify, y los agentes (F4.7) son los que se nombran en la orquestación. Detalle completo en OpenSpec.

Fase 5 — Ciclo iterativo

Entregable: por cada ítem del backlog, un change archivado — código integrado, specs actualizadas y QA (Quality Assurance) registrado.

F5.1 · Ciclo OpenSpec por cada ítem del backlog

Ejecutar el ciclo personalizado en F4.8 por cada ítem, en orden de dependencias —un schema propio que conserva verify y agrega el stage qa, con la orquestación de agentes en los campos instruction (ver OpenSpec)—. El ciclo:

Gate de impacto arquitectónico (antes de apply): un paso barato clasifica el cambio como architectural: true | false con criterios explícitos; solo si marca true se invoca al arquitecto. Criterios y mecanismo en OpenSpec y Eficiencia. Si el change venía definido desde F3.5, el gate también lo revalida contra el PRD y el prototipo vigentes: entre que se acordó y se construye pueden haber cambiado sus vecinos.
Apply: los agentes implementadores ejecutan el cambio. Con impacto arquitectónico, el arquitecto toma o valida las decisiones de diseño.
Verify: hasta tres pases — cumplimiento (lo objetivo: tests, estándares, criterios literales del spec); juicio (calidad, bugs sutiles, idoneidad del enfoque), que es la revisión de código del ciclo —la hace un agente que no implementó—; y un pase de seguridad condicional, que corre solo si un gate de superficie sensible marca el change —autenticación o autorización, datos personales o de pago, entradas no confiables, secretos, dependencias nuevas, superficie pública—. Un hallazgo de seguridad bloquea el archive salvo disposición explícita del humano con motivo, y al aplazarse genera candidato de backlog. Los pases son responsabilidades, no comandos: si el asistente trae una revisión empaquetada se usa como atajo; si no, corre como instrucción al agente revisor. Ver Eficiencia y Portabilidad.
QA (Quality Assurance) ✋: un artefacto de QA hace el seguimiento de la fase y corre un protocolo de tres pasos, secuencial y bloqueante: (1) verificar los datos en la base —no “corrí el seed”, sino confirmar que existen los usuarios, los estados y los casos borde que estas pruebas necesitan, sobre un seed reproducible y versionado—; (2) correr lo automatizable y registrar comando y resultado, declarando qué queda cubierto para que no se vuelva a probar a mano; (3) entregar los bloques manuales. Si (1) falla no hay (2); si (2) queda en rojo, al humano no se le entrega nada. Un bloque = un rol × un flujo —lo que una persona prueba de una sentada sin cambiar de sesión—, autocontenido y con su propio cierre, porque QA real ocurre en varias sentadas. Cada bloque declara qué usuario y de dónde sale la contraseña (el script de seed, válida solo en local): nunca se escribe una credencial en el artefacto, ni credenciales de un entorno real. El triaje de QA decide qué se automatiza y qué va al juicio humano: las verificaciones objetivas (API (Application Programming Interface), BD (base de datos), lógica) son tests automáticos en verify/CI, no ítems manuales; los flujos E2E (end-to-end) se automatizan con Playwright solo cuando el gate de costo lo justifica (ver Eficiencia). Los bugs se corrigen y confirman, o se marcan won't resolve / skipped con motivo —y al aplazarse así generan un candidato de backlog para la fase 6—. La automatización nunca reemplaza la validación humana: la fase solo cierra cuando el usuario aprueba explícitamente.
Sync + Archive: primero se sincronizan las delta specs con las principales (/opsx:sync, acción separada de archive). Luego los revisores hacen la revisión final y corrigen issues; con impacto arquitectónico, el arquitecto verifica consistencia. Se actualiza el progreso en todos los archivos (backlog —incluido su diagrama de dependencias—, CLAUDE.md, documentos de estado), se agrega la fila del change al índice de changes archivados y se pregunta si dejó una regla aprendida (ver abajo). Al archivar se cuentan los ítems archivados desde la última auditoría: al llegar al umbral (5 ítems, o fin de sprint) se sugiere correr la auditoría (/auditoria — ver Operaciones y Métricas).

El diagrama de dependencias es un artefacto vivo: el agente de progreso/documentador (haiku) regenera el bloque Mermaid desde los campos Estado y Dependencias de los ítems —recolorea nodos y agrega los nuevos epics/changes— como parte de la actualización de progreso. Es responsabilidad del agente, no un script (Portabilidad); quien quiera un gate duro agrega el chequeo de sincronía al CI (ítem PRJ-002).

El índice de changes archivados y las reglas aprendidas

Un change archivado guarda toda la historia de cómo se construyó algo — y nadie la vuelve a abrir. Dos mecanismos, escritos en el mismo paso de archive, evitan que se pierda:

El índice. Un archivo delgado en la carpeta de archivo, una fila por change: ID, fecha, título, capabilities/specs tocadas, RF-* que satisface y la regla aprendida. Es append-only y lo mantiene el agente de progreso, igual que el diagrama de dependencias. Responde ¿dónde está la historia de esta capability? — la pregunta que pagan caro la auditoría de specs↔código, una arqueología puntual y cualquier dev nuevo. No es el backlog (qué falta) ni el CHANGELOG del producto (qué ve el usuario).
La regla aprendida. Lo que el proyecto aprendió construyendo —una convención que hubo que decidir sobre la marcha, un supuesto que resultó falso, algo que verify o qa corrigieron y se repetiría— no vive en un log: vive donde se aplica. El archive la escribe en su destino —los estándares base, decisiones.md, CLAUDE.md o la spec de su capability— y en el índice queda solo el puntero. El default es ninguna: la mayoría de los changes no dejan regla.

Plantilla: Índice de archivados (umbral y destinos completos ahí).

Plantilla del artefacto de QA: Artefacto de QA

Medición y ajuste

Después de los primeros 3 a 5 ítems del backlog, revisar el consumo real de tokens por fase y por agente, y ajustar la asignación de modelos en los agentes outliers — sin tocar la metodología general. Esta revisión se repite luego como auditoría periódica (ver Operaciones). Detalle en Eficiencia.

Esto mide el costo del proceso (tokens). El resultado de la entrega —¿la velocidad sigue siendo confiable?— se mide aparte, con las métricas de Métricas, agregadas en la misma auditoría periódica.

Fase 6 — Evolución continua

Entregable: no tiene uno propio. Es la excepción al entregable por fase: cada vuelta del lazo entrega lo mismo que la fase 5 —un change archivado— sobre trabajo que llegó después.

Cuando el backlog inicial se agota, el producto no se “termina”: entra en evolución continua. El trabajo nuevo no llega por un workflow distinto — re-entra al ciclo de fase 5, pero antes pasa por una recepción que lo captura, lo tría y lo enruta. El objetivo: que ningún trabajo se pierda y que nada significativo se construya sin definición validada.

Esto es el lazo runtime → planificación cerrado: las señales que el producto emite ya en producción —errores, disponibilidad, patrones de uso, regresiones de eval y feedback de usuarios (Estándares §9 y §10)— no mueren en un dashboard; vuelven a la recepción y se convierten en el próximo trabajo. Ir rápido sirve de poco si lo que aprende producción no regresa al plan.

De dónde viene el trabajo nuevo (4 fuentes)

Todo desemboca en el backlog como cola única; cada ítem declara su Origen. La regla clave es capturar en el origen, no redescubrir después:

Pedidos de stakeholders → candidato de backlog directo.
Monitoreo / feedback de producción → un error recurrente del error tracker o un feedback se tría a candidato (engancha con el monitoreo de Estándares §9).
Deuda aplazada que el propio proceso generó —bugs won't resolve/skipped, lo “fuera de alcance” del PRD, la automatización de QA pospuesta por el gate de costo— escrita como candidato en el momento en que se aplaza.
Hallazgos de las auditorías periódicas (specs↔código, tokens, salud de la suite — ver Operaciones).

Triaje: tres carriles por tamaño e impacto

En el refinamiento periódico (cadencia y mecánica en Operaciones) los candidatos se priorizan y se enrutan según tamaño e impacto:

Cambio chico / bug / mejora puntual → directamente un nuevo change de OpenSpec en el ciclo de fase 5, sin ceremonia de PRD.
Feature / epic nuevo, visible en UI → loop de validación liviano antes de construir: actualizar PRD → maquetar el slice nuevo con el design system ya canónico → validar ✋ → derivar ítem(s) → ciclo. /opsx:explore solo cuando el pedido es difuso.
Área de producto nueva → prácticamente re-correr las fases 1–4 para esa rebanada.

Proyecto entregado por hitos (el cliente contrató el trabajo en bloques y llama “fase 2” al siguiente). El hito nuevo entra por acá: los dos primeros carriles si es continuación del mismo producto, el tercero si es un área nueva. Lo que cambia no es el proceso sino qué se corrió una vez para todo el proyecto y qué se cierra al entregar cada hito — detalle en Hitos.

Gate: definición validada antes del ítem

Ningún ítem significativo entra al ciclo sin su definición validada (PRD, y prototipo/design system si es visible) — el mismo principio de las fases 2–3 aplicado a cada incremento. Los cambios chicos del primer carril no lo necesitan: su “definición” es el propio change spec, que el gate de impacto arquitectónico ya filtra.

Proyecto brownfield (código que no nació con Argui). La Fase 6 es la misma, con tres diferencias: (1) antes de tocar un módulo aún no recuperado se hace una arqueología puntual y se completa su spec (comando recuperar-zona); (2) los PRDs nacen recuperados en el onboarding y los primeros incrementos los completan tanto como agregan; (3) tocar un camino crítico exige caracterizarlo antes. Detalle y onboarding en Brownfield.

El prototipo, después del lanzamiento, es instrumento de validación acotado —no fuente de verdad—: se usa para maquetar trabajo nuevo significativo y visible con el design system canónico, no para espejar producción. Detalle en Prototipo.