# Flows

Casos de uso end-to-end **reutilizables** que prueban el sistema multi-app del registry.

Un flow describe una secuencia de pasos que atraviesa varias apps (`navegator_dashboard`, `dag_engine`, `data_factory`, `agents_and_robots`, ...) para producir valor real (extraer datos, sincronizar, notificar).

## Convencion

- Archivo por flow: `NNNN-<slug>.md` (numeracion zero-padded propia, NO comparte con `dev/issues/`).
- Estado vivo en frontmatter (`status`).
- Acceptance checkboxes `[ ]` en el body — `/flow status` calcula % completado.
- Cerrados se mueven a `completed/`.

## Para agentes / LLMs

Antes de crear o editar un flow, lee `AGENT_GUIDE.md`. Define:
- donde buscar funciones (capability groups, MCP search por tag, etc.),
- mapa actual de apps / projects / vaults disponibles,
- reglas duras para recomendar piezas reales del registry,
- plantilla de prompt para el agente cuando recibe `/flow create`.

Cada flow debe citar IDs reales del registry. Si una pieza no existe, marcarla `FALTA: crear <id>` — NUNCA inventar nombres.

## Slash command `/flow`

| Subcomando | Que hace |
|---|---|
| `/flow create <slug>` | Scaffold `NNNN-<slug>.md` desde `template.md` con siguiente ID libre. |
| `/flow list` | Tabla resumen desde `INDEX.md` + checkbox %. |
| `/flow show <NNNN>` | Imprime el `.md`. |
| `/flow status <NNNN>` | Status + acceptance % + ultima run. |
| `/flow done <NNNN> [--notes "..."]` | Marca status=done, anade notas, mueve a `completed/`, actualiza INDEX. |
| `/flow run <NNNN>` | **Fase 2** (no implementado). Ejecuta steps automatizables. |

## Estructura archivo

```yaml
---
name: hn-top-stories
id: 0001
status: pending           # pending | running | done | failed | deferred
created: 2026-05-16
updated: 2026-05-16
priority: high            # low | medium | high
risk: low                 # low | medium | high (sensibilidad de datos)
related_issues: [0097, 0098]
apps: [navegator_dashboard, dag_engine, data_factory, agents_and_robots]
trigger: manual           # manual | cron | webhook
schedule: ""
expected_runtime_s: 60
tags: [scraping, news]
---

## Goal
Una frase: que estamos probando.

## Pre-requisitos
- Lista de requisitos manuales (ej. Chrome con remote-debugging).

## Flow
Pasos numerados. Cada paso puede ser:
- texto libre (manual)
- `function: <id>` (registry function)
- `cmd: <bash>`
- `js: <expression>` (en tab Chrome)

## Acceptance
- [ ] Checklist
- [ ] ...

## Telemetria esperada
Que cambia en call_monitor / data_factory.runs / dag_engine.

## Notas
Hallazgos tras correr.
```

## Numeracion + status workflow

```
pending  --create-->  in-progress  --run OK-->  done  --move--> completed/
                          |                       ^
                          v                       |
                       failed -----------fix-----+
```

`deferred` para flows fuera de scope actual pero que conservas.

## Trazabilidad

Cada `function: X` invocado dentro de un flow pasa por hook PostToolUse -> queda en `call_monitor.calls`. Si la funcion graba en `data_factory.runs` (ej. `cdp_extract_recipe_py_pipelines`), tienes cadena:

```
flow 0001 -> /flow run -> ./fn run cdp_extract_recipe -> call_monitor.calls
                                                       \-> data_factory.runs
```

Asi la observabilidad cross-app es gratis.

## Cuando crear flow vs issue

| Caso | Donde |
|---|---|
| Bug del registry / funcion | `dev/issues/NNNN-...` |
| Feature de una app | `dev/issues/NNNN-...` |
| Caso de uso real que cruza N apps | **`dev/flows/NNNN-...`** |
| Trabajo recurrente reutilizable | **`dev/flows/NNNN-...`** |
| Refactor de codigo | `dev/issues/NNNN-...` |

Un flow puede generar issues secundarios si descubres bugs corriendo el flow.