El pipeline de stages

Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro
|------------------ planificación (archivos en flow/) ------------------|  |------- envío (dentro de cards/) -------|

El pipeline no es una lista de documentos que producir. Cada stage existe porque un tipo específico de autoengaño tiende a ocurrir en ese punto de la construcción, y el gate apunta a ese engaño.

Planificación: seis archivos con gates

Los artefactos de planificación viven en flow/ y están numerados para que el orden no sea negociable.

00 — Idea. Un pitch de tres frases: quién tiene el problema, qué hace hoy, qué harías tú en su lugar. El gate busca un problema, no una solución disfrazada de problema. Este es el lugar más barato de todo el proyecto para descartar algo.

01 — Research. Qué ya existe: competidores, sistemas en vivo, precios reales. La regla es inspeccionar primero, evidencia no sensaciones. Este stage es donde la invención es más tentadora y más cara, porque un plan construido sobre competidores inventados está equivocado con confianza durante semanas. Un script no puede detectar una cita inventada; el gate semántico es la única defensa.

02 — Scope. Califica funcionalidades y corta. El fallo característico aquí es el inflado de nivel — una funcionalidad de nivel C redactada como B porque quieres construirla. Scope es donde la mayoría de los proyectos se salvan o se pierden, por eso el modo work se pausa para una aprobación explícita del operador exactamente en este punto y en ningún otro.

03 — PRD. El alcance superviviente se convierte en requisitos funcionales numerados. Cada FRn escrito aquí debe luego ser reclamado por una card y servido por una interfaz del contrato. Esa traza es auditable mecánicamente, así que un requisito no puede evaporarse en silencio entre la planificación y la construcción.

04 — ADR. Decisiones de arquitectura, incluyendo lo que rechazaste y por qué. Las opciones rechazadas son la parte valiosa: seis meses después son la razón por la que nadie reabre una cuestión ya resuelta.

05 — Contract. Las interfaces, escritas antes de que exista código. Método, ruta, autenticación, formas de petición y respuesta para un proyecto web; comandos, flags, formas de salida y códigos de salida para un CLI; la superficie de API exportada para una librería; la superficie de comandos para un skill.

Por qué el contrato nunca se puede saltar

Todos los demás stages de planificación pueden saltarse con deuda honesta registrada. El stage 05 no, nunca.

El contrato es la costura. Los productores construyen hacia él, los consumidores construyen desde él, y ambos lados pueden avanzar de forma independiente precisamente porque la forma entre ellos está fijada. Saltarlo no ahorra tiempo; traslada el coste a la integración, donde dos mitades a medio construir descubren que no están de acuerdo y alguien reescribe una de ellas.

La disciplina que sigue es estricta: nunca improvises una forma. Si una forma resulta estar mal, enmienda primero el contrato y luego cambia el código. Honra una forma ahora con un null o un stub aunque su valor real se envíe en una card posterior.

Si el contrato no encaja con tu tipo de proyecto, adáptalo — lee «endpoint» como «interfaz» o «comando» — en lugar de saltarlo.

Envío: cards

Después de que el stage 05 pasa, /flow card corta cards de construcción. Cada card es una sesión de construcción acotada con una lista de archivos permitidos, los requisitos que implementa, un bloque de verificación, una prueba independiente y una sección de evidencia que empieza vacía.

Construye, revisa de forma adversarial, despliega, luego verifica en vivo como lo haría un usuario. La card está terminada cuando la evidencia del mundo está pegada y el gate de comprobación pasa — no cuando los tests están en verde.

Brownfield: stage 00-inspect

Un código existente no empieza en Idea. /flow assess prepara y pone gates a flow/00-inspect.md, un mapa del estado actual que cubre el stack, lo que el producto hace hoy frente a lo que debería hacer, riesgos y la línea base de tests. Lo revisa el operador, y existe para que la planificación de un sistema existente se base en lo que realmente hay en lugar de en lo que dice el README del repositorio.

Retro

Una línea honesta por ejecución, escrita por el operador y nunca por el agente. Alimenta la capa durable, para que el recall del siguiente proyecto muestre el dolor de este.

Descartar es una salida válida

Cada gate tiene tres resultados, no dos: pasa, bloquea y descarta. Un harness que solo puede decir «procede» es una cinta transportadora con un ritual de cumplimiento adjunto. Descartar una idea débil en Scope es la decisión buena más barata disponible en una construcción.

Avanzar con `/flow next`

/flow next comprueba el gate del stage en el que estás y, solo si pasa, desbloquea el siguiente. El runner trata el archivo de stage contiguo de número más alto en flow/ como actual — un archivo de stage solo cuenta si existen todos los stages anteriores (un 05 solitario sin 00–04 no se trata como actual). La planificación solo está completa cuando los seis gates de stage están limpios; solo entonces se desbloquea /flow card.

Cuando la capa mecánica falla imprime exactamente qué está mal con números de línea — casillas de gate sin marcar, marcadores [FILL] sin rellenar — y se detiene. Un FAIL nunca avanza. El listado es todo el diagnóstico: abre el archivo nombrado, arregla esas líneas, ejecuta /flow next de nuevo. No adivines qué casilla estaba vacía.

Cuando el script pasa, el desafío semántico del stage recién completado se aplica antes de permitirte avanzar, así que un artefacto mecánicamente limpio pero hueco aún se nombra como débil. En modo teach el agente nunca marcará una casilla ni escribirá un artefacto por ti; solo te dice qué está fallando.

Descartar es un estado terminal válido. Parar en cualquier gate, especialmente en Scope, es un resultado honrado, no un fracaso del flow. Pasar, bloquear y descartar son las tres respuestas; un harness que solo puede decir «procede» es una cinta transportadora.

Tipos de proyecto

flow nació con forma web. La forma honesta de soportar otros tipos de software no fue generalizar los gates hasta la vaguedad, sino nombrar exactamente qué tres cosas cambian. Fija el tipo con /flow project-type web|cli|library|skill antes del stage 05. El valor se guarda en un archivo PROJECT_TYPE y vale web por defecto. Ejecutar el comando sin argumento imprime el valor actual y la regla de evidencia de terminado que implica.

El tipo adapta la costura del contrato del stage 05, la secuencia estándar de cards y lo que significa la evidencia de terminado. Todo lo demás — el espíritu de cada gate, «contrato antes que código», «terminado es prueba en el mundo» — queda intacto. Cambiar el tipo después significa revisar el contrato, así que es barato ahora y caro después.

web. Contrato: endpoints HTTP (método, ruta, autenticación, petición, respuesta); OpenAPI servido. Terminado: una URL desplegada en vivo más salida real de curl.
cli. Contrato: comandos, flags, formas de salida, códigos de salida. Terminado: la herramienta se instala y una invocación real devuelve la salida esperada y el código de salida. Primer movimiento en una construcción CLI: /flow project-type cli.
library. Contrato: la superficie de API pública — funciones y tipos exportados con sus formas. Terminado: la API pública se importa, un ejemplo de uso funciona, umbral de cobertura cumplido.
skill. Contrato: los comandos y archivos que lee el agente. Terminado: instalado en el home del skill y una ejecución real alcanza su propia definición de terminado. Primer movimiento en una construcción de skill: /flow project-type skill.

Una construcción CLI no es una construcción web diluida: la prueba que debe producir es igual de concreta, simplemente toma la forma de una herramienta instalada y un código de salida real en lugar de una URL desplegada. Los gates en sí no cambian — solo se mueve la forma de la prueba.

Alguna redacción del gate del stage 05 aún dice «endpoint» y pide una columna de autenticación, que es sabor web. Para otros tipos lees «endpoint» como «interfaz» o «comando» y sustituyes escrituras y efectos secundarios por autenticación — el preámbulo del stage licencia explícitamente esa adaptación, y la comprobación equivalente sin deriva es que la evidencia de terminado por tipo realmente pase.

Matriz de tipos de proyecto

Se fija con /flow project-type <web|cli|library|skill>, se guarda en PROJECT_TYPE, por defecto web.

Tipo	Costura del contrato (stage 05)	Evidencia de terminado	Secuencia de cards
`web`	Endpoints HTTP — método, ruta, autenticación, petición, respuesta; OpenAPI servido	Una URL desplegada en vivo más salida real de `curl`	scaffold y `/healthz`, corte vertical, backend, test de contrato, mock de UI, frontend, e2e
`cli`	Comandos, flags, formas de salida, códigos de salida	La herramienta se instala y una invocación real devuelve la salida esperada y el código de salida	scaffold más un comando real, grupos de subcomandos, tests, humo de instalación en un directorio limpio
`library`	La superficie de API pública — funciones y tipos exportados con sus formas	La API pública se importa, un ejemplo de uso funciona, umbral de cobertura cumplido	scaffold más API central, rondas de API, tests, un ejemplo de uso ejecutable, dry-run de publicación
`skill`	Los comandos y archivos que lee el agente	Instalado en el home del skill y una ejecución real alcanza su propia definición de terminado	scaffold más un comando ejecutable, referencias y ley, instalación, una ejecución dogfood

Constante en los cuatro tipos: cada requisito mapea a una interfaz, cada interfaz tiene sus formas escritas antes del código, el contrato es la costura, y «tests pass» o «fusionado» nunca es terminado.

Modos y estrategias de ejecución

flow tiene cuatro ejes de modo y son genuinamente independientes, así que fijas cada uno por proyecto y los combinas como exija el trabajo.

Modo de autoría decide quién escribe los artefactos de gate: teach, el valor por defecto, significa que tú escribes y el agente solo vigila los gates; work significa que el agente te entrevista una vez, redacta los stages 00 a 05, y solo se pausa para la aprobación del scope.

Tipo de proyecto decide qué significa terminado — una URL en vivo para web, una invocación real y código de salida para un CLI, una API importable para una librería, una ejecución instalada para un skill.

Modo de ejecución decide cómo se construyen las cards: manual, donde tú diriges card, construcción, comprobación; o auto, una ejecución autónoma con manejo por niveles que se detiene ante trabajo de clase de seguridad.

Greenfield versus brownfield decide dónde empiezas: stage 00-idea para algo nuevo, o una evaluación del estado actual con gates para un código existente.

Lo que ningún eje cambia es el listón. Los gates y las reglas de terminado son idénticos en todas las combinaciones; los modos mueven autoría, forma de la prueba e impulso, nunca la altura del gate.

Aclarar decisiones abiertas

Las decisiones de producto sin resolver viven como viñetas - [ ] bajo un encabezado ## Open decisions en los artefactos Scope, PRD y Contract. Las cuenta el mismo escáner de casillas que ya usan los gates, lo que significa que una decisión sin cerrar bloquea genuinamente el stage en lugar de quedarse en un comentario que nadie lee.

/flow clarify imprime esas viñetas restantes, acotadas a esa sección, y siempre sale con 0 — es un impresor asesor, no un segundo gate. Resolverlas es un ritual de escritura acotado y opt-in: recorre las viñetas una a una, registra la decisión en el artefacto y marca la casilla. Nada de clarify es prerrequisito para /flow next; el escáner del gate que ya impone las casillas lo es.

Artefactos de stage

El runner copia plantillas a tu proyecto a medida que cada stage se desbloquea. Los artefactos de planificación viven en flow/, las unidades de envío en cards/, y los libros en la raíz del proyecto. Las rutas de abajo son archivos, no encabezados.

Ruta	Stage	Contenido
`flow/00-idea.md`	00	El pitch de tres frases: quién tiene el problema, qué hace hoy, qué harías tú en su lugar
`flow/00-inspect.md`	brownfield	Evaluación del estado actual: stack, funcionalidad frente a objetivos de producto, riesgos, línea base de tests
`flow/01-research.md`	01	Qué ya existe — competidores, sistemas en vivo, evidencia real
`flow/02-scope.md`	02	Funcionalidades calificadas, cortes y la aprobación del scope
`flow/03-prd.md`	03	Requisitos funcionales numerados (`FRn`)
`flow/04-adr.md`	04	Decisiones de arquitectura, incluyendo opciones rechazadas
`flow/05-contract.md`	05	Las interfaces, escritas antes del código. La costura. Nunca saltable
`flow/constitution.md`	opcional	Invariantes por proyecto del operador, asesor
`cards/C-NNN.md`	construcción	Una sesión de construcción acotada: archivos permitidos, implementa, verificación, prueba independiente, evidencia, riesgo
`MODE`, `PROJECT_TYPE`	—	Modo de autoría y tipo de proyecto
`DEBT.md`, `RETRO.md`, `AUTO-LOG.md`	—	Skips deliberados, líneas de retro, log de ejecución autónoma
`.flow/harness.db`	—	Registros durables

Cada artefacto de planificación trae marcadores [FILL] y casillas de gate; ambos se escanean mecánicamente, y dejar cualquiera sin resolver suspende el stage. Las decisiones sin resolver pertenecen bajo un encabezado ## Open decisions, donde el mismo escáner las cuenta.

Ver también

Homes del mantenedor (no la página pública): skills/flow/references/stage-state-machine.md, skills/flow/references/project-types.md, skills/flow/references/mode-work.md, skills/flow/references/clarify.md.