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>
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# 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.
|