Qué es flow
flow es un harness de construcción con gates. Lleva un producto desde una idea hasta la
evidencia real de terminado — una URL desplegada, un CLI instalado que funciona, una API de
librería importable o un skill que alcanza su propia definición de terminado — a través de
gates que deben satisfacerse con honestidad antes de avanzar.
Es un skill que instalas en un coding agent, no un servicio al que te suscribes ni un framework del que depende tu código. Flow es dueño de los gates y la evidencia, nunca del runtime. Es autónomo: no requiere AgentKit ni claudekit, aunque la revisión multimodelo opcional se desbloquea cuando esos motores están presentes.
El problema para el que existe
Sección titulada «El problema para el que existe»Un coding agent produce con gusto un plan plausible, un documento de investigación plausible y una afirmación plausible de que el trabajo está terminado. Cada artefacto se lee bien por separado. El fallo es sistémico, no local: nada en el ciclo está posicionado para decir no.
Dos modos de fallo específicos explican la mayor parte del daño.
Papeleo que parece progreso. Un documento de investigación con citas inventadas de competidores pasa cualquier comprobación estructural. Un documento de alcance donde una funcionalidad de nivel C se ha redactado como si fuera B también pasa. Ambos se leen bien; ninguno sobrevive al contacto con la realidad.
«Terminado» que no está terminado. Un agente reporta una card completa porque los tests están en verde y la rama se fusionó. Nadie cargó la página. Nadie ejecutó el comando. «Tests pass» es un estado intermedio que se ha ascendido en silencio a estado terminal.
Qué hace flow al respecto
Sección titulada «Qué hace flow al respecto»Tres compromisos, y todo lo demás se deriva de ellos.
Terminado significa prueba en el mundo. Cada card nombra su evidencia por adelantado, y
el gate exige esa evidencia pegada antes de que la card pueda marcarse como terminada. Para
un proyecto web eso es una URL en vivo y salida real de curl; para un CLI, una invocación
real con su código de salida. El código fusionado y el CI en verde están explícitamente
excluidos. Ver Terminado significa evidencia del mundo.
Dos capas deben estar de acuerdo. Un script determinista atrapa la mecánica tramposa —
casillas sin marcar, marcadores [FILL] sin rellenar, evidencia vacía — y sale con 0 o 1.
El modelo que lee el skill atrapa lo que un script no puede: investigación inventada, alcance
con el nivel inflado, un endpoint sin autenticación. Un gate solo se supera cuando ambos
están de acuerdo. Ver El harness de dos capas.
Descartar en un gate es un resultado válido. Un harness que solo puede decir «procede» es una cinta transportadora. Descartar una idea débil en Scope es barato e inteligente, y flow lo trata como un resultado de primera clase, no como un fracaso que hay que esquivar.
Qué no es
Sección titulada «Qué no es»No es una herramienta de gestión de proyectos: no hay tablero, ni burndown, ni estimaciones. No es un generador de código — pone gates a lo que escriba el agente o el humano. No es un sistema de CI, aunque sus reglas de evidencia son más estrictas que la mayoría de los gates de CI. Y no es un envoltorio que hace al agente más inteligente; lo hace responsable, que es algo distinto y más útil.
La forma de una ejecución
Sección titulada «La forma de una ejecución»Idea -> Research -> Scope -> PRD -> ADR -> Contract -> Cards -> Build -> Review -> Deploy -> Verify-live -> Retro|------------------ planificación (archivos en flow/) ------------------| |------- envío (dentro de cards/) -------|La planificación son seis stages con gates que viven como archivos en flow/. El envío es
una serie de cards en cards/, cada una una sesión de construcción acotada contra el
contrato escrito en el stage 05. Entre sesiones, un almacén durable guarda deuda, retros,
trazas y playbooks, para que la siguiente sesión empiece con el dolor previo a la vista.
El chat es la entrada por defecto — describe lo que quieres y el concierge propone una
acción siguiente. Los verbos escritos como /flow next siempre ganan al enrutado del chat.
El harness de dos capas
Sección titulada «El harness de dos capas»Esta es la idea central de flow. Todo lo demás es consecuencia.
Un gate tiene que atrapar dos tipos muy distintos de fallo, y ningún componente es bueno en
ambos. Así que flow ejecuta dos capas, y un gate solo se supera cuando ambas están de
acuerdo. Ambas capas, o no pasó.
Capa uno — el gate mecánico
Sección titulada «Capa uno — el gate mecánico»runner/flow.sh es un motor bash determinista que sale con 0 o 1. Es dueño del ciclo de
vida de stages y cards, y comprueba las cosas trivialmente tramposas y trivialmente
detectables:
- casillas de gate sin marcar, incluyendo viñetas
- [ ]sin resolver bajo## Open decisions— el mismo escáner maneja ambas - marcadores
[FILL]sin rellenar - validez del estado de la card
- una sección
## Evidencevacía en una card que dice estar terminada
Su código de salida es ground truth. La regla para el modelo es directa: ejecuta siempre el script primero, lee su código de salida y transmítelo con fidelidad. Nunca sustituyas tu propio juicio por el suyo.
Lo que esta capa no puede hacer es leer el significado. No distingue una cita real de un competidor de una inventada, ni una funcionalidad honesta de nivel B de una C redactada como B.
Capa dos — el gate semántico
Sección titulada «Capa dos — el gate semántico»Ese es el trabajo del modelo. Después de que el script pasa, el skill aplica un conjunto de desafíos por stage antes de permitir avanzar al operador. Aquí es donde la investigación inventada se cuestiona, donde el alcance con el nivel inflado se nombra, donde un endpoint sin columna de autenticación se marca, y donde «tests pass» pegado en una sección de evidencia se rechaza como estado intermedio.
La instrucción es simétrica e importa en ambas direcciones: no avances en silencio ante un artefacto hueco, y no bloquees en silencio uno sólido. Cuando el script pasa pero el contenido es débil, al operador se le dice exactamente eso — pasó mecánicamente y es cualitativamente débil — y el operador decide.
Por qué la división, en lugar de un comprobador más listo
Sección titulada «Por qué la división, en lugar de un comprobador más listo»Un script no puede juzgar el significado; no se puede confiar en que un modelo sea
determinista con la mecánica. Dividirlos pone cada clase de fallo donde realmente puede
atraparse, y hace que la mitad tramposa sea exigible en lugar de persuadible. No puedes
convencer a exit 1 de que cambie de opinión. Tampoco puedes escribir una expresión regular
que detecte una cita de mercado inventada.
Hay un segundo beneficio, más sutil. Como la capa mecánica es un proceso separado con un código de salida real, las afirmaciones del propio modelo sobre un gate son auditables. Un agente que dice «el gate pasó» puede comprobarse contra una señal que él no produjo.
La tercera capa: memoria durable
Sección titulada «La tercera capa: memoria durable»Debajo de ambas hay una capa durable — un almacén Python y SQLite con intake y carril de
riesgo, story y prueba, traza y nivel, decisiones y backlog. Se degrada con elegancia: si
falta python3, los gates siguen funcionando y solo esta capa se apaga.
+---------------------------------------------------------------+| Capa semántica - SKILL.md + references/ (el modelo) || juicio: contenido hueco, inflado de nivel, revisión || adversarial, orquestación de agentes, modo de trabajo |+---------------------------------------------------------------+ | llama (código de salida = ground truth) v+---------------------------------------------------------------+| Capa mecánica - runner/flow.sh (bash, salida 0/1) || ciclo de vida de stages/cards, comprobaciones de gate, || libro de deuda, comprobación de diseño, pasarela al harness |+---------------------------------------------------------------+ | lee/escribe (mejor esfuerzo, degradación elegante) v+---------------------------------------------------------------+| Capa durable - Python + sqlite3 (propiedad de flow) || intake/carril-riesgo, story+prueba, traza+nivel, decisión |+---------------------------------------------------------------+Es memoria externa. El progreso y la fricción sobreviven entre sesiones y ventanas de contexto, que es el antídoto contra la degradación lenta que ocurre cuando un proyecto largo vive solo en una conversación.
La consecuencia para los agentes
Sección titulada «La consecuencia para los agentes»Los agentes son intercambiables; los gates son fijos. Un stage puede delegar el borrador a un agente especialista cuando hay uno presente, y recurre al comportamiento integrado cuando no lo hay. El gate es idéntico en todos los caminos, así que un agente ausente nunca puede bajar el listón. Un agente redacta; el gate sigue juzgando.
La misma regla gobierna los motores opcionales de otros proveedores. Un segundo o tercer modelo puede revisar una card, pero su veredicto informa el triaje — nunca aprueba ni suspende automáticamente.
Terminado significa evidencia del mundo
Sección titulada «Terminado significa evidencia del mundo»Cada card nombra su evidencia de terminado por adelantado, y el gate exige esa evidencia pegada antes de que la card pueda marcarse como terminada. «Tests pass» y «código fusionado» son estados intermedios. Nunca son terminado.
El fallo que esto previene
Sección titulada «El fallo que esto previene»La forma más común en que una construcción asistida por agentes sale mal no es un bug. Es un estado. Una card se reporta completa porque los tests están en verde, la revisión está aprobada y la rama se fusionó. Cada una de esas afirmaciones es cierta. Nadie ha cargado la página.
Cada una de esas señales mide un proxy de lo que te importa. Los tests miden tu modelo del sistema contra sí mismo. Una fusión mide el acuerdo sobre un diff. Ninguno toca el mundo real en ejecución. Los proxies se alejan de la realidad en silencio, y la deriva es invisible justo cuando más importa, porque todos los paneles están en verde.
La solución no es más proxies. Es exigir una observación de la cosa real.
Qué cuenta, por tipo de proyecto
Sección titulada «Qué cuenta, por tipo de proyecto»El tipo de proyecto decide la forma de la prueba, y el espíritu es idéntico en todos los casos: alguien interactuó con la realidad desplegada y pegó lo que devolvió.
| Tipo de proyecto | Evidencia de terminado |
|---|---|
web |
La URL desplegada en vivo más salida real de curl |
cli |
La herramienta se instala, y una invocación real devuelve la salida esperada y el código de salida |
library |
La API pública se importa, un ejemplo de uso funciona, umbral de cobertura cumplido |
skill |
Instalado en el home del skill, y una ejecución real alcanza su propia definición de terminado |
Fija el tipo con /flow project-type <type>; el valor por defecto es web. La costura del
contrato y el resto de la matriz de tipos están en
Tipos de proyecto.
Qué no cuenta
Sección titulada «Qué no cuenta»Artefactos de proceso, por impresionantes que sean:
- un pull request aprobado
- una insignia de CI en verde o una ejecución de workflow
- notas de release que describen lo enviado
- una revisión de código que no encontró nada
- el propio resumen del agente diciendo que el trabajo está completo
La capa mecánica impone un suelo aquí: una card cuya sección de evidencia contiene solo prosa de proceso se rechaza, así que la disciplina no puede negociarse en el momento. Más allá de ese suelo, el gate semántico hace la pregunta más difícil — ¿esta evidencia es el mundo, o una descripción del mundo?
La autoevaluación de un agente está específicamente excluida. La señal de ground truth para cada gate es algo que el agente no generó: el código de salida de un script, la salida de un comando real de verificación, una comprobación en vivo.
Por qué el gate rechaza tan agresivamente una sección de evidencia vacía
Sección titulada «Por qué el gate rechaza tan agresivamente una sección de evidencia vacía» [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)FAIL: C-001 has gate violations (above).Esto se dispara incluso cuando el código está terminado y es correcto. La razón es que el momento más barato para capturar la evidencia es el momento en que ya estabas mirando la cosa en ejecución. Si se difiere, se reconstruye después de memoria, y la evidencia reconstruida es indistinguible de la evidencia inventada.
El mismo razonamiento impulsa el flip propiedad del CLI, /flow card done C-NNN: aplica
las mismas reglas que check y revierte si el gate falla, así que no hay camino de código
que produzca un terminado hueco.
La salida honesta
Sección titulada «La salida honesta»Si una card genuinamente no puede probarse ahora mismo — el objetivo de despliegue aún no
existe, el servicio externo no está disponible — la respuesta no es debilitar la evidencia.
Es registrar la exposición como deuda, por escrito, con una condición para cerrarla. La
deuda es visible y aparece en recall; un terminado hueco es invisible y aparece en
producción.
Cómo abrir esa línea, y cuándo se rechaza un skip, está en Saltar un gate con deuda. Cómo pegar la prueba en una card está en Crear y comprobar cards.
Desafíos semánticos
Sección titulada «Desafíos semánticos»Un pase mecánico significa que el archivo está estructuralmente completo. No dice nada sobre si el contenido es verdad. El desafío semántico es el conjunto de preguntas por stage que el modelo aplica después de que el script pasa, y es deliberadamente específico de cada stage porque cada stage invita a una mentira distinta.
Research invita a competidores inventados y números sin fuente. Scope invita al inflado de nivel, donde una funcionalidad que quieres construir se redacta un nivel por encima de lo que ganó. El PRD invita a requisitos sin dueño y dolores sin funcionalidad. El contrato invita a un endpoint sin columna de autenticación. Las cards invitan a evidencia que describe el proceso en lugar del mundo. Un genérico «¿esto está bien?» no atrapa nada de esto de forma fiable; un desafío nombrado por stage sí.
La instrucción corre en ambas direcciones: nunca avances en silencio ante un artefacto
hueco, y nunca bloquees en silencio uno sólido. Cuando algo pasa mecánicamente pero se lee
débil, al operador se le dice exactamente eso y decide. También hay una prueba conductual de
que esta capa funciona — /flow eval alimenta fixtures huecos pero mecánicamente limpios a
un juez fresco y puntúa si se marcan, lo que es una cota inferior, no una garantía.
Por stage, no genérico
Sección titulada «Por stage, no genérico»Idea (00). ¿El pitch son realmente tres frases (quién / dolor / qué)? ¿La persona nombrada es una persona o grupo real y específico, no «usuarios»? ¿El dolor es concreto, no una categoría? El ritual forge-idea es opt-in; nunca se convierte en condición que este gate compruebe.
Research (01). Mayor riesgo de invención. ¿Se abrieron realmente tres competidores? Para un producto web / de mercado: ¿las quejas son citas reales con enlaces de fuente que funcionan, y el canal de los primeros diez usuarios es un lugar específico? Para cli / librería / skill / herramienta interna: ¿la fricción de primera parte es concreta y observada, con beneficiarios nombrados — «sin canal de mercado» es lo esperado aquí, no un kill. Los costes deben ser reales, no adivinados.
Scope (02). Vigila el inflado de nivel. Llama C a una C (tiempo real, pagos desde cero,
autenticación propia, pipeline agéntico autónomo, concurrencia pesada). Si quedan abiertas
decisiones materiales de producto (cuota, clave de identidad, tenencia, contrato de
respuesta, dueño de la aplicación), detente y lístalas — los valores por defecto
configurables no son autoridad. Una viñeta bajo ## Assumptions que codifica ley de
producto sin autoridad del operador o del ADR es una decisión abierta o una parada, no un
valor por defecto silencioso.
PRD (03). ¿La métrica de éxito es un número real, no «mejor UX»? ¿Cada dolor cita evidencia y nombra la funcionalidad v1 que lo mata, y cada funcionalidad v1 mata al menos un dolor? Los huérfanos en cualquier lado son deriva de alcance. ¿Podría un extraño construir v1 solo con esto sin preguntar nada al operador?
ADR (04). ¿Cada decisión nombra una alternativa real rechazada, no un hombre de paja? ¿Almacenamiento, autenticación y despliegue están realmente decididos, no «TBD»? ¿La lista de NO-hacer es honesta sobre lo que se difiere?
Contract (05). La interfaz es la costura del tipo de proyecto: web = endpoint, cli = comando + flags + salida/exit, librería = función pública + args + retorno, skill = comando/archivo. Cada funcionalidad del PRD mapea al menos a una interfaz y viceversa. Cada interfaz tiene formas de entrada y salida, con nombres que no derivarán. La columna de acceso/efectos es real para cada interfaz — no dejes que un producto web la deje en blanco. Lee el contrato contra cualquier doc que nombre como su propia fuente de verdad antes de pasarlo; una contradicción aquí se envía como «pasado» y cada card la hereda.
Card (/flow check C-NNN). ¿El alcance es una sola cosa? ¿## Independent test es una
prueba visible para el usuario, no «unit tests pass»? ¿El diff se queda dentro de
## Allowed files? ¿Las formas coinciden exactamente con flow/05-contract.md? ¿## Evidence
es estado del mundo — una URL clicable, salida real de curl, una fila de BD — y cada ítem
nombra el artefacto o el comando que lo produjo?
Consistency (/flow consistency). Asesor; nunca bloquea el camino de construcción.
Después de los pases basados en ID del runner, el modelo aún tiene que atrapar cobertura
hueca (un FRn pegado en una card que no lo entrega), requisitos que se contradicen entre
artefactos, una funcionalidad de la lista de corte reapareciendo como v1, y deriva de
terminología (ticket / issue / request).
El texto completo del desafío para el modelo vive en el archivo de mantenedor enlazado en el pie. Los skips de clase de seguridad y los HALT de auto no están en esta página; están en Cuándo detenerse.
Arquitectura del sistema
Sección titulada «Arquitectura del sistema»flow son tres capas que cooperan más artefactos en disco: un motor determinista rápido
para la mecánica tramposa, un skill para el juicio, y un almacén durable para que los
registros sobrevivan a las sesiones. La imagen pública para el operador son cuatro piezas —
skill, runner, artefactos y dos canales de versión.
La capa semántica es SKILL.md más los playbooks en skills/flow/references/. Es lo que
lee el agente anfitrión: dispatch, gatekeeper, orquestación. Después de que runner/flow.sh
devuelve 0, esta capa ejecuta los desafíos por stage de arriba. Nunca sustituye el código de
salida del script por un pase de sensaciones.
La capa mecánica es runner/flow.sh. Es bash, determinista, salida 0 o 1. Es dueño del
ciclo de vida de stages y cards, las comprobaciones de gate ([FILL], casillas, evidencia
vacía), el libro de deuda, la comprobación de diseño y la pasarela al harness. Su código de
salida es ground truth. Ejecútalo siempre primero; transmítelo siempre con fidelidad.
Debajo, un CLI Python y SQLite propiedad de flow guarda intake y carril de riesgo, story y
prueba, traza y nivel, decisiones y backlog. Si falta python3, los gates siguen
funcionando; solo esta capa durable se apaga.
Artefactos
Sección titulada «Artefactos»Los artefactos viven en el proyecto que se construye, no dentro del home del skill:
flow/00-idea.md .. 05-contract.md planificación, con gatescards/C-NNN.md unidades de envíoMODE, RETRO.md, DEBT.md, AUTO-LOG.md, DESIGN.md.flow/harness.db registros durablesLos archivos de planificación en flow/ son los stages con gates. Cada card en cards/ es
una sesión de construcción acotada contra el contrato del stage 05. Los archivos de libro y
.flow/harness.db son cómo la deuda, las retros y las trazas sobreviven a la siguiente
ventana de contexto.
Dos canales de versión
Sección titulada «Dos canales de versión»La distribución son dos canales paralelos que alimentan el mismo árbol canónico. El
instalador npm (npx @manhquy/flow-skill@latest) es el camino principal: Node puro, sin
shell. El script de instalación del repositorio es la implementación de referencia usada en
desarrollo y CI. Ambos escriben el mismo home del skill, así que un proyecto puede cambiar
de canal sin reemitir un gate.
monorepo skills/flow/ --npm run sync--> npm-wrapper/skills/flow --npm pack--> registry | | | install.sh / agent skill homes | npx @manhquy/flow-skill@latest v v ~/.claude/skills/flow mismo árbol vía instalador CLIEsos canales versionan artefactos distintos. El producto skill versiona los gates,
SKILL.md, el runner, las referencias y las plantillas — lo que juzga tu construcción. El
paquete npm versiona solo el instalador CLI: detección de agentes, rutas de copia,
flags. No se supone que coincidan. --help imprime ambos números. Compruébalos en tu
máquina en lugar de en cualquier documento. La historia del pareado, incluyendo qué número
fijar, está en
Dos números de versión.
A dónde ir
Sección titulada «A dónde ir»- El pipeline de stages — qué defiende cada gate.
- Instalar y primera ejecución — ver un gate rechazar.
- Crear y comprobar cards — pegar la prueba, marcar terminado.
Homes del mantenedor (no la página pública): docs/adr/0001-discipline-layer-identity.md, skills/flow/references/gate-rules.md, docs/system-architecture.md.