fn_registry/.claude/commands/flow.md

description

description
Gestiona flows (casos de uso multi-app reutilizables) en dev/flows/. Subcomandos: create, list, show, status, done. Runner automatizado en fase 2.

/flow — Gestionar flows del registry

Flows = casos de uso end-to-end que prueban / ejercitan el sistema multi-app. Viven en dev/flows/NNNN-<slug>.md. Cada flow describe Goal + Flow steps + Acceptance checkboxes + Telemetria.

OBLIGATORIO antes de create: lee dev/flows/AGENT_GUIDE.md. Define donde buscar piezas (capability groups, FTS por tag, apps existentes, vaults), reglas duras para no inventar IDs, y plantilla de razonamiento para recomendar extractor / transformer / sink / scheduler / notify por flow.

Cada flow nuevo cita IDs reales del registry. Si una pieza falta, escribir FALTA: crear <id> en la tabla correspondiente. Nada de inventar nombres.

Diferencia con dev/issues/:

• Issues = bugs / features de implementacion.
• Flows = trabajos reutilizables que cruzan varias apps.

Sintaxis

/flow create <slug>              # nuevo flow desde template, ID auto
/flow list                        # tabla resumen
/flow show <NNNN>                 # imprime contenido + acceptance %
/flow status <NNNN>               # status + acceptance % + ultima run
/flow done <NNNN> [--notes "..."] # cierra flow (status=done, mueve a completed/)
/flow run <NNNN>                  # fase 2 — runner automatizado (NO IMPLEMENTADO)

Implementacion por subcomando

create <slug>

Pasos:

1. Valida <slug> es kebab-case: ^[a-z][a-z0-9-]*$. Si no, error.
2. Comprueba que no existe ya: ls dev/flows/*-<slug>.md. Si existe, error.
3. Calcula siguiente ID libre:
   • ls dev/flows/*.md dev/flows/completed/*.md | grep -oE '^dev/flows/(completed/)?[0-9]{4}' | sort -u | tail -1
   • Suma 1, zero-pad a 4 digitos.
4. Lee dev/flows/template.md.
5. Sustituye <slug>, NNNN, YYYY-MM-DD (hoy).
6. Escribe dev/flows/NNNN-<slug>.md.
7. Append fila a dev/flows/INDEX.md (mantener orden por ID asc).
8. Reporta path nuevo + recordatorio "edita Goal / Flow / Acceptance".

list

Lee dev/flows/INDEX.md y lo imprime tal cual. Si flag --pending solo pending, --done solo done, --app <name> filtra por app.

Tambien anade columna Accept% calculada desde body:

• Para cada flow .md, cuenta [ ] y [x] en seccion ## Acceptance.
• % = checked / total * 100 redondeo entero.

show <NNNN>

cat dev/flows/NNNN-*.md (busca con glob NNNN-*). Si no existe, prueba dev/flows/completed/NNNN-*.md. Si no, error.

status <NNNN>

Imprime resumen del frontmatter + acceptance %:

=== flow 0001 ===
name:        hn-top-stories
status:      pending
risk:        low
priority:    high
apps:        navegator_dashboard, dag_engine, data_factory, agents_and_robots
acceptance:  2/6 (33%)
updated:     2026-05-16

Pending checks:
- [ ] Recipe creada y validada
- [ ] DAG corre OK 2 veces consecutivas via scheduler
- [ ] data_factory.runs tiene >=2 entries
- [ ] Schema extraido cubre 6/6 fields

done <NNNN> [--notes "..."]

Pasos:

1. Verifica todos los [ ] estan checked. Si no, prompt "X checks pendientes, --force para cerrar igualmente".
2. Edita frontmatter: status: done, updated: <hoy>.
3. Si --notes, append a seccion ## Notas.
4. git mv dev/flows/NNNN-<slug>.md dev/flows/completed/.
5. Actualiza dev/flows/INDEX.md: cambia status del flow + mueve fila a seccion Completed (mantener tabla principal solo con pending/running/failed/deferred).

run <NNNN> — FASE 2 (NO IMPLEMENTADO AUN)

Hoy: imprime /flow run no implementado todavia. Sigue los pasos manualmente y marca acceptance con sed/edit.

Diseño futuro:

• Parsea ## Flow en pasos.
• Cada paso tipo function: <id> -> ejecuta ./fn run <id>.
• Cada paso tipo cmd: <bash> -> ejecuta subprocess.
• Texto libre -> "MANUAL: " + pause user input.
• Persistencia ejecuciones en dev/flows/runs/<id>-<timestamp>.jsonl.
• Update acceptance checkboxes automaticamente segun heuristics (count runs en data_factory, etc.).

Conventions

• Numeracion 0001+, propia (no comparte con dev/issues/).
• Status: pending | running | done | failed | deferred.
• Risk: low (publico) | medium (auth no sensible) | high (datos personales).
• Apps listadas en frontmatter — /flow list --app navegator_dashboard filtra.
• Acceptance es la fuente de verdad del progreso.

Output style

Caveman. Tablas markdown. Sin emojis. Sin verbosidad.

Errores: 1 linea con el problema + sugerencia.

Ejemplos

/flow create reddit-sentiment-tracker
# crea dev/flows/0008-reddit-sentiment-tracker.md
# anade fila a INDEX

/flow list --pending
# muestra solo flows no cerrados

/flow status 0001
# acceptance 0/6, todos los checks pendientes

# Tras correr el flow manualmente:
# editas el .md, marcas [x] los checks completados
/flow status 0001
# acceptance 6/6
/flow done 0001 --notes "smoke pass; LLM tardo 14s; recipe robusta"
# mueve a completed/, marca status=done