Tu primer proyecto greenfield

Este tutorial lleva un directorio vacío a una build card real. Escribirás seis artefactos de planificación, y cada uno se juzga dos veces — una por un script con el que no se puede discutir, otra por el modelo leyéndolo como crítico.

Necesitas el skill instalado primero: Instalar y primera ejecución.

Tiempo: una hora o dos, dependiendo de lo honesto que seas contigo mismo en el gate de Scope.

El pipeline que vas a recorrer

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 los stages 00 a 05, y viven como archivos en flow/. El envío ocurre dentro de cards/. No puedes cortar una card hasta que los seis gates de planificación han pasado o llevan deuda honesta registrada.

Paso 1 — elige qué significa «terminado»

/flow project-type web

El tipo de proyecto decide qué evidencia exigirá el harness al final: una URL desplegada en vivo para web, una invocación real con la salida esperada y el código de salida para cli, una API pública importable más un ejemplo de uso que funciona para library, un skill instalado que alcanza su propia definición de terminado para skill. El valor por defecto es web. Fijarlo ahora te ahorra escribir un contrato con la forma equivocada.

Paso 2 — decide quién escribe los artefactos

/flow mode teach

En modo teach — el valor por defecto — tú escribes cada artefacto de planificación y el agente solo vigila los gates. En modo work el agente te entrevista una vez, redacta él mismo los stages 00 a 05, y solo se pausa para la aprobación del scope. Los gates atan idénticamente de cualquier forma; la única diferencia es de quién son los dedos en el teclado.

Si estás aprendiendo el harness, quédate en teach para este primer proyecto. Verás lo que cada gate realmente comprueba.

Paso 3 — stage 00, la idea

/flow next

El runner crea flow/00-idea.md y suspende el gate, porque la plantilla está llena de marcadores [FILL] y casillas sin marcar. Abre el archivo y escribe un pitch de tres frases: quién tiene el problema, qué hace hoy, y qué harías tú en su lugar. Marca las casillas que hayas satisfecho genuinamente. Ejecuta /flow next de nuevo.

Cuando el script pasa, el agente aplica el desafío semántico del stage que acabas de terminar. Esta es la mitad que ningún script puede hacer: te replicará si tu «problema» es una solución disfrazada, o si el pitch describe una funcionalidad en lugar de una persona con dolor.

Descartar el proyecto aquí es un resultado válido. Una idea débil descartada en el stage 00 cuesta una hora. La misma idea descartada después del contrato cuesta una semana.

Paso 4 — stage 01, research

Rellena flow/01-research.md con lo que ya existe: competidores, sistemas en vivo que miraste, precios que realmente comprobaste. La regla bajo este stage es inspeccionar primero — evidencia, no sensaciones.

El gate semántico aquí es inusualmente afilado, porque la investigación inventada es lo más fácil de escribir y lo más difícil de atrapar para un script. Una cita sin fuente, un competidor que no abriste, un número de mercado sin enlace — espera que te pregunten de dónde vino.

Si el stage genuinamente no encaja — una herramienta interna sin mercado público, digamos — no lo inventes. Registra la deuda y salta con honestidad:

/flow debt add "skip 01-research" "internal tool, no public market" "before public release"
/flow skip 01-research --reason "internal tool, no public market"

skip solo avanza cuando una línea de deuda abierta nombra ese stage exacto y la razón no es de clase de seguridad.

Paso 5 — stages 02 a 04, scope, PRD, ADR

• Scope (flow/02-scope.md) es donde los proyectos suelen salvarse o perderse. Califica las funcionalidades con honestidad; el gate semántico vigila el inflado de nivel, donde una funcionalidad de nivel C se redacta como B porque quieres construirla.
• PRD (flow/03-prd.md) convierte el alcance superviviente en requisitos funcionales numerados. Cada FRn que escribas aquí debe luego ser reclamado por una card y servido por una interfaz del contrato — esa traza es auditable mecánicamente.
• ADR (flow/04-adr.md) registra las decisiones de arquitectura y, lo importante, lo que rechazaste y por qué.

Ejecuta /flow next después de cada uno. Cualquier cosa sin resolver va bajo un encabezado ## Open decisions como viñeta - [ ]; esas viñetas las cuenta el mismo escáner de gate, así que una decisión sin resolver bloquea el stage hasta que la resuelvas o la muevas conscientemente.

Paso 6 — stage 05, el contrato

flow/05-contract.md es la costura, y es el único stage que nunca puede saltarse. Escribe las interfaces antes de que exista código: método, ruta, autenticación, forma de petición, forma de respuesta para un proyecto web — comandos, flags, formas de salida, códigos de salida para un CLI.

Desde aquí la regla es absoluta: el backend construye hacia el contrato, la UI consume desde él. Si una forma resulta estar mal, enmiendas primero el contrato y luego cambias el código. Honra una forma ahora con un null o un stub aunque su valor real se envíe en una card posterior.

Cuando este gate pasa verás:

PASS: stage 05-contract gate clean. Planning is COMPLETE.
All planning stages passed (or were debt-skipped). Run '/flow card' to create build cards.

Paso 7 — corta la primera card

/flow card

Esto escribe cards/C-001.md. Una card es una sesión de construcción acotada: una lista de archivos permitidos, los requisitos que implementa, un bloque ## Verify que realmente ejecutarás, un ## Independent test que describe la prueba visible para el usuario, y una sección ## Evidence que empieza vacía.

Antes de construir, ejecuta /flow recall — lee de vuelta la deuda abierta, la última retro, el alcance de la card anterior y cualquier playbook promovido, para que empieces con el dolor previo a la vista.

Paso 8 — construye, luego pruébalo

Construye solo lo que nombra la lista de archivos permitidos de la card. Luego:

/flow check C-001

La card suspende mientras ## Evidence esté vacía, aunque el código sea perfecto y todos los tests pasen:

  [x] status is 'done' but ## Evidence is empty (paste world-state proof: URL/curl/DB row)
FAIL: C-001 has gate violations (above).

Pega la prueba real — una URL en vivo con salida real de curl para un proyecto web, la invocación real y el código de salida para un CLI — y compruébala de nuevo:

PASS: C-001 is valid (status: done).

Qué aprendiste

• Seis gates de planificación, cada uno juzgado mecánicamente y luego semánticamente.
• Descartar y el skip honesto respaldado por deuda son ambos resultados de primera clase.
• El contrato se escribe antes del código y es el único stage insaltable.
• «Tests pass» es intermedio; terminado es prueba en el mundo.

Siguiente

• Crear y comprobar cards para el ciclo diario.
• El pipeline de stages para lo que defiende cada stage.
• Terminado significa evidencia del mundo para por qué el paso 8 es estricto.