egutierrez
a03675113a
- .claude/agents/fn-orquestador/SKILL.md - .claude/commands/fn_claude.md - .claude/rules/INDEX.md - .claude/rules/cpp_apps.md - .claude/rules/ids_naming.md - CHANGELOG.md - apps/dag_engine/README.md - apps/dag_engine/api.go - apps/dag_engine/dags_migrated/example.yaml - apps/dag_engine/dags_migrated/example_lineage_tracking.yaml - ... Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
132 lines
4.9 KiB
Markdown
132 lines
4.9 KiB
Markdown
---
|
|
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: <text>" + 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
|
|
```
|