fn_registry/.claude/commands/create_functions.md

# /create_functions — Crear funciones para el registry a partir de una peticion

Eres un agente orquestador que evalua una peticion del usuario, consulta el registry, planifica las funciones necesarias y las crea en paralelo usando agentes fn-constructor especializados. Tambien creas unit tests y verificas que todo quedo indexado correctamente.

---

## Argumento

`$ARGUMENTS` — descripcion de lo que el usuario necesita. Ejemplos:

```
/create_functions funciones para parsear y validar JSON schema en Go
/create_functions pipeline Python para ETL de CSVs con filtrado y agregacion
/create_functions funciones de hashing y encoding para ciberseguridad en Go
/create_functions componentes React para formularios con validacion
/create_functions funciones Bash para gestion de contenedores Docker
```

Si `$ARGUMENTS` esta vacio, preguntar al usuario que funciones necesita.

---

## FASE 1: EVALUAR — Entender la peticion

1. **Parsear la peticion** para identificar:
   - Dominio(s) involucrados (core, infra, finance, datascience, cybersecurity, shell, tui, pipelines, browser, notebook, ui)
   - Lenguaje(s) preferido(s) (go, py, bash, typescript). Si no se especifica, inferir del contexto.
   - Tipo de funciones necesarias: puras (algoritmos, transformaciones), impuras (I/O, red, DB), pipelines (composiciones), tipos, componentes
   - Nivel de granularidad: funciones atomicas vs composiciones

2. **Si la peticion es ambigua**, preguntar al usuario SOLO lo esencial (no mas de 2 preguntas).

---

## FASE 2: OBSERVAR — Consultar el registry

Consultar `registry.db` para encontrar funciones existentes relevantes y evitar duplicados.

```bash
# Buscar funciones similares por nombre y descripcion (OBLIGATORIO — usar multiples terminos)
sqlite3 $HOME/fn_registry/registry.db "SELECT id, kind, purity, lang, description FROM functions WHERE id IN (SELECT id FROM functions_fts WHERE functions_fts MATCH 'name:TERMINO1* OR description:TERMINO1* OR name:TERMINO2* OR description:TERMINO2*') ORDER BY name;"

# Buscar tipos relacionados
sqlite3 $HOME/fn_registry/registry.db "SELECT id, algebraic, lang, description FROM types WHERE id IN (SELECT id FROM types_fts WHERE types_fts MATCH 'name:TERMINO* OR description:TERMINO*') ORDER BY name;"

# Funciones del dominio objetivo
sqlite3 $HOME/fn_registry/registry.db "SELECT id, kind, purity, signature, description FROM functions WHERE domain = 'DOMINIO' AND lang = 'LANG' ORDER BY name;"

# Tipos del dominio objetivo
sqlite3 $HOME/fn_registry/registry.db "SELECT id, algebraic, description FROM types WHERE domain = 'DOMINIO' ORDER BY name;"

# Funciones que podrian componerse (misma firma de retorno)
sqlite3 $HOME/fn_registry/registry.db "SELECT id, purity, signature FROM functions WHERE returns LIKE '%TIPO%' OR signature LIKE '%TIPO%' ORDER BY name;"
```

**Clasificar resultados en:**
- **Reutilizables directamente**: funciones que ya hacen lo que se necesita
- **Componibles**: funciones que pueden usarse como building blocks
- **Similares pero diferentes**: funciones parecidas que confirman que no hay duplicado exacto

---

## FASE 3: PLANIFICAR — Disenar las funciones con un agente Plan

Invocar el Agent tool con `subagent_type: "Plan"` para disenar la lista de funciones a crear.

El prompt al agente Plan debe incluir:
- La peticion original del usuario
- Las funciones existentes encontradas en FASE 2 (IDs y descripciones)
- Los tipos existentes relevantes
- Las reglas de pureza del registry

El agente Plan debe producir una lista estructurada de funciones a crear, cada una con:
- **nombre** (snake_case)
- **kind** (function | pipeline | component)
- **lang** (go | py | bash | typescript)
- **domain**
- **purity** (pure | impure) — justificando por que
- **signature** propuesta
- **description** breve
- **uses_functions** — IDs de funciones existentes que reutiliza
- **uses_types** — IDs de tipos existentes que usa
- **dependencias** — si una funcion nueva depende de otra funcion nueva del mismo batch, indicar el orden
- **tests** — que se debe testear (casos de exito, edge cases, errores)

**Reglas del plan:**
- Funciones puras primero, impuras despues, pipelines al final
- Maximizar reutilizacion de funciones existentes
- Cada funcion debe tener tests propuestos
- El plan debe indicar el **orden de creacion** (las que tienen dependencias internas van despues)
- Agrupar funciones independientes para creacion en paralelo

**NO pedir confirmacion al usuario** — proceder directamente a la fase de construccion. Mostrar el plan brevemente en el output como referencia pero sin pausar:

---

## FASE 4: CONSTRUIR — Crear funciones en paralelo con fn-constructor

Para cada batch del plan, lanzar agentes `fn-constructor` **en paralelo** (un agente por funcion o grupo pequeno de funciones relacionadas).

**Como invocar cada fn-constructor:**

Usar el Agent tool con `subagent_type: "fn-constructor"` pasando un prompt completo con:

```
Crea la siguiente funcion para el registry fn_registry en $HOME/fn_registry:

Funcion: {nombre}
Kind: {kind}
Lang: {lang}
Domain: {domain}
Purity: {purity}
Signature: {signature}
Description: {descripcion}
Uses_functions: [{ids}]
Uses_types: [{ids}]

Tests requeridos:
- {test1}: {descripcion del test}
- {test2}: {descripcion del test}
- {test3}: {descripcion del test}

Contexto: Esta funcion es parte de un batch para {descripcion general del objetivo}.
Funciones existentes del registry que puedes reutilizar: {ids relevantes}

IMPORTANTE:
- Crear el archivo de codigo Y el .md con frontmatter completo
- Crear el archivo de tests correspondiente
- Marcar tested: true en el .md si creas tests
- Respetar las reglas de pureza
- Usar tipos nativos en la firma
- file_path relativo a la raiz del registry
- NO ejecutar fn index (lo hare yo al final)
```

**Orden de ejecucion:**
1. Lanzar todos los fn-constructor del Batch 1 en paralelo
2. Esperar a que terminen
3. Lanzar todos los fn-constructor del Batch 2 en paralelo (dependen de Batch 1)
4. Repetir para cada batch subsiguiente

**Sin limite de agentes en paralelo** — lanzar todos los fn-constructor del batch simultaneamente para maxima velocidad.

---

## FASE 5: INDEXAR — Registrar todo en el registry

Despues de que TODOS los fn-constructor terminen:

```bash
# Indexar todo de una vez
cd $HOME/fn_registry && ./fn index
```

Si el indexer reporta errores, corregirlos antes de continuar. Errores comunes:
- ID duplicado → renombrar
- uses_functions referencia ID inexistente → verificar que el batch anterior se creo correctamente
- Violacion de pureza → ajustar purity o quitar dependencia impura
- file_path incorrecto → corregir la ruta

---

## FASE 6: VERIFICAR — Asegurar que todo esta correcto

### 6.1 Verificar indexacion

```bash
# Verificar cada funcion creada
cd $HOME/fn_registry
./fn show {id_de_cada_funcion}

# Verificar que no hay funciones sin params_schema
./fn check params
```

### 6.2 Ejecutar tests

Para cada funcion con tests, ejecutar:

```bash
cd $HOME/fn_registry

# Go
CGO_ENABLED=1 go test -tags fts5 -v -run TestNombreDelTest ./functions/{domain}/

# Python
python/.venv/bin/python3 -m pytest python/functions/{domain}/{nombre}_test.py -v

# TypeScript
cd frontend && pnpm exec vitest run functions/{domain}/{nombre}.test.ts

# Bash (si hay tests)
bash bash/functions/{domain}/{nombre}_test.sh
```

### 6.3 Verificar integridad

```bash
# Verificar que todas las funciones nuevas estan en la BD
sqlite3 $HOME/fn_registry/registry.db "SELECT id, kind, purity, tested FROM functions WHERE id IN ('id1','id2','id3') ORDER BY name;"

# Verificar que los tests estan indexados
sqlite3 $HOME/fn_registry/registry.db "SELECT id, function_id, name FROM unit_tests WHERE function_id IN ('id1','id2','id3') ORDER BY function_id;"

# Verificar dependencias
sqlite3 $HOME/fn_registry/registry.db "SELECT id, uses_functions, uses_types FROM functions WHERE id IN ('id1','id2','id3') AND uses_functions != '[]';"
```

### 6.4 Si algo fallo

- Si un test falla → corregir el codigo y re-ejecutar
- Si una funcion no se indexo → verificar el .md y re-indexar
- Si hay errores de integridad → corregir y re-indexar
- NO continuar al reporte si hay tests fallando o funciones sin indexar

---

## FASE 7: REPORTE — Resumen final

```
=== FUNCIONES CREADAS ===

Peticion: {descripcion original}

Funciones del registry reutilizadas:
  - {id}: {descripcion}

Funciones nuevas:
  - {id} [{kind}, {purity}, {lang}] — {descripcion}
    Tests: N pasando
    Archivo: {file_path}

  - {id} [{kind}, {purity}, {lang}] — {descripcion}
    Tests: N pasando
    Archivo: {file_path}

Tipos nuevos:
  - {id}: {descripcion}

Tests: X/Y pasando
Indexacion: OK

Para usar estas funciones:
  # Go
  import "fn_registry/functions/{domain}"
  result := domain.FunctionName(args)

  # Python
  from {domain} import function_name

  # Bash
  source "$FN_REGISTRY_ROOT/bash/functions/{domain}/{name}.sh"
```

---

## Reglas

- **SIEMPRE** consultar registry.db antes de crear — evitar duplicados
- **NO pedir confirmacion** — mostrar el plan brevemente y proceder directamente
- **SIEMPRE** crear tests para cada funcion
- **SIEMPRE** indexar y verificar despues de crear
- **Funciones puras primero**, impuras despues, pipelines al final
- **Maximizar paralelismo** en la creacion (agentes fn-constructor en paralelo)
- **Maximizar reutilizacion** de funciones existentes
- **NO crear funciones especificas de una app** — solo codigo reutilizable y generico
- Si el usuario pide algo que ya existe, informar y sugerir reutilizar en vez de duplicar
- Si una funcion del batch falla, las demas del mismo batch pueden continuar independientemente
- **Tags con significado especial** — ver `.claude/rules/function_tags.md`:
  - `launcher`: pipelines que deben aparecer en Pipeline Launcher TUI. Añadir cuando se crea un pipeline ejecutable desde el launcher. NO añadir a pipelines interactivos/TUIs.
  - `service`: para apps que son procesos de larga duracion (usado en /app, no en funciones)

$ARGUMENTS