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

Diagrama del flujo

FASE 0  Fundación        CLAUDE.md vivo + OpenSpec + aislar la herramienta de IA
FASE 1  Entendimiento    Exploración conversacional y/o investigación formal
FASE 2  PRDs             PRD v1 → agente PRD → validación ✋
FASE 3  Prototipo        Prototipo trazable ↔ PRDs, feedback de stakeholders ✋
FASE 4  Preparación      MCPs/Skills → arquitecto → backlog → estándares → agentes
FASE 5  Iteración        [ gate → apply → verify → qa ✋ → archive ] × cada item
FASE 6  Evolución        Intake (4 fuentes) → triage → 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.

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 (metrics.md). Ver operations.md.

Fase 0 — Fundación

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 operations.md → Aislamiento del entorno de IA; la implementación de referencia para Claude Code, en templates/aislamiento/. (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).

Ver claude-md.md y la plantilla CLAUDE.md.template.

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.

La personalización del ciclo —el schema propio, dónde vive la orquestación de agentes y cómo no quedar obsoleto frente a la evolución de OpenSpec— se arma en la fase 4 y está documentada en openspec.md. Regla mínima desde ya: fijar la versión, nunca @latest.

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 dependencies.md. El inventario completo de dependencias externas vive ahí.

Fase 1 — Entendimiento

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 se agrega al .gitignore por defecto — solo se versiona si se confirma que no hay nada sensible.

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 los insumos del primer PRD. 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 el insumo del primer PRD. Es la ruta natural cuando el dominio es desconocido o el riesgo de asumir es alto.

En ambas rutas el objetivo es el mismo: información suficiente para escribir un primer PRD honesto — no código, no arquitectura.

Fase 2 — PRDs

F2.1 · PRD v1

Crear la primera versión de los PRDs de negocio y técnico directamente desde la fase de entendimiento. Son documentos distintos porque tienen audiencias distintas.

Deben ser breves y manejables: si un archivo crece demasiado, se divide en varios.
Es una v1 deliberadamente: se va a iterar con el prototipo en la fase 3.
El PRD de negocio registra la decisión de descubribilidad pública (sí/no) — es el gate que activa o elimina el estándar SEO (Search Engine Optimization)/GEO (Generative Engine Optimization) de la fase 4 (ver standards.md §8).

Plantillas: prd-business.md.template y prd-technical.md.template.

F2.2 · Agente PRD

Crear el agente experto en los PRDs 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 se encarga de ajustar, mejorar y mantener los PRDs durante el resto del proyecto (en especial durante la iteración con el prototipo).

Pautas de creación de agentes: agents.md.

F2.3 · Validación de PRDs ✋

Validar los PRDs antes de continuar. Dos partes:

Checklist de completitud: el agente PRD autoevalúa si cubrió los criterios mínimos — problema claramente definido, usuarios objetivo identificados, métricas de éxito establecidas, restricciones técnicas documentadas, casos fuera de alcance explicitados.
Confirmación humana: se presenta un resumen ejecutivo al usuario con preguntas concretas: ¿el problema está bien definido? ¿el alcance del PMV (Producto Mínimo Viable) es correcto? ¿hay algo crítico ausente? El proceso no avanza hasta la aprobación explícita.

Fase 3 — Prototipo trazable

La validación temprana se hace con un prototipo navegable enlazado a los PRDs — no con código de producción. Guía completa: prototype.md.

F3.1 · Agente UX/UI

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

F3.2 · Prototipo no funcional con trazabilidad

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

Cada bloque de la UI lleva una insignia de trazabilidad que enlaza a la sección exacta del PRD que lo define (visible en modo demo).
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 demo.
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 (templates/prototype/), no se reimplementa por proyecto.

F3.3 · Iteración prototipo ↔ PRDs ✋

Los stakeholders ven lo que describe el PRD, comentan, y ese feedback alimenta el ajuste del prototipo y de los PRDs —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 prototype.md). Se opera con el comando de ciclo de ajustes (templates/commands/prototype-adjust.md).

La fase 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.

Fase 4 — Preparación técnica

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

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 items 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 (standards.md §7) e instrumentación del monitoreo mínimo (§9)—. Ambos van primero porque todo lo demás los consume.
Dependencias explícitas — ningún item arranca si sus dependencias no están archivadas.
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 item (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.md.template

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 y despliegue continuo. Condicional, si el PRD de negocio lo activó: descubribilidad (SEO/GEO) (§8).

Ver standards.md.

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 agents.md, incluida la asignación del modelo más eficiente por agente (ver efficiency.md).

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

Fase 5 — Ciclo iterativo

F5.1 · Ciclo OpenSpec por cada item del backlog

Ejecutar el ciclo personalizado por cada item, en orden de dependencias. La personalización —un schema propio que conserva verify y agrega el stage qa, con la orquestación de agentes en los campos instruction— está en openspec.md. 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.md y efficiency.md.
Apply: los agentes implementadores ejecutan el cambio. Con impacto arquitectónico, el arquitecto toma o valida las decisiones de diseño.
Verify: dos pases — cumplimiento (lo objetivo: tests, estándares, criterios literales del spec) y luego juicio (calidad, bugs sutiles, idoneidad del enfoque). Ver efficiency.md.
QA (Quality Assurance) ✋: un artifact de QA describe las pruebas manuales del cambio y hace tracking de la fase. Precondición: base de datos local con seed reproducible (estado conocido → pruebas repetibles). El triage 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 items manuales; los flujos E2E (end-to-end) se automatizan con Playwright solo cuando el gate de costo lo justifica (ver efficiency.md). 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). Al archivar se cuentan los items archivados desde la última auditoría: al llegar al umbral (5 items, o fin de sprint) se sugiere correr la auditoría (/auditoria — ver operations.md y metrics.md).

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 items —recolorea nodos y agrega los nuevos epics/changes— como parte de la actualización de progreso. Es responsabilidad del agente, no un script (portability.md); quien quiera un gate duro agrega el chequeo de sincronía al CI (item CHQ-002).

Plantilla del artifact de QA: qa-artifact.md.template

Medición y ajuste

Después de los primeros 3 a 5 items 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 operations.md). Detalle en efficiency.md.

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 metrics.md, agregadas en la misma auditoría periódica.

Fase 6 — Evolución continua

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 un intake 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 (standards.md §9 y §10)— no mueren en un dashboard; vuelven al intake 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 item 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 standards.md §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 operations.md).

Triage: tres carriles por tamaño e impacto

En el grooming periódico (cadencia y mecánica en operations.md) 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 item(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.

Gate: definición validada antes del item

Ningún item 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.md.

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