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.

# Buscar funciones similares por nombre y descripcion (OBLIGATORIO — usar multiples terminos)
sqlite3 /home/lucas/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/lucas/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/lucas/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/lucas/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/lucas/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/lucas/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:

# Indexar todo de una vez
cd /home/lucas/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

# Verificar cada funcion creada
cd /home/lucas/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:

cd /home/lucas/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

# Verificar que todas las funciones nuevas estan en la BD
sqlite3 /home/lucas/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/lucas/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/lucas/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