fn_registry/.claude/commands/subagentes.md

description

description
Recordatorio operativo para usar subagentes fn (constructor/executor/recopilador/analizador/mejorador) y paralelizar trabajo independiente

/subagentes — usa subagentes fn y paraleliza

Recuerda: antes de escribir codigo nuevo o ejecutar pipelines en serie, delega a subagentes y paraleliza llamadas independientes (un mensaje, varios Agent calls).

---

Mapa de subagentes fn (ciclo reactivo)

Fase	Agente	Cuando dispararlo
1 CONSTRUIR	fn-constructor	Falta funcion/tipo/test reutilizable. NUNCA escribir inline en apps/ si es reutilizable
2 EJECUTAR	fn-executor	Correr pipeline/funcion del registry + registrar ejecucion en operations.db
3 RECOPILAR	fn-recopilador	Auditar integridad de operations.db. Modo design-e2e <app> propone bloque e2e_checks
4 ANALIZAR	fn-analizador	Ejecutar e2e_checks de app.md, veredicto pass/fail, persistir en e2e_runs
5 MEJORAR	fn-mejorador	Convertir fallos de e2e_runs en proposals con evidencia trazable
6 META	fn-orquestador	Recorrer fases 1-5 solo hasta convergencia. Sandbox auto/<issue>. Issue 0069

Pre-condiciones de fn-orquestador (abortara si no se cumplen):

• Migration fn_operations/migrations/006_task_runs.sql aplicada
• Issue con criterios de aceptacion verificables programaticamente (no "funciona bien")
• master local up-to-date con origin/master
• Branch auto/<issue> NO existe ya (limpiar previo si hace falta)
• gh autenticado (PR draft al converger)
• Tipo soportado: feature_app_simple, bugfix_with_repro, refactor_safe, add_e2e_check

Aislamiento por worktree: cada run crea /tmp/fn_orq_<issue>_<ts>/ via git worktree add. Working tree principal del usuario queda intacto. N orquestadores paralelos = N worktrees independientes. task_runs persiste en BD del repo principal (auditoria sobrevive aunque borres worktree).

Otros subagentes utiles

• Explore — busquedas amplias en codebase (>3 queries) sin contaminar contexto principal
• general-purpose — research multi-step open-ended

Reglas duras

1. Paralelo real: tareas independientes → un mensaje con varios Agent calls. NO en serie.
2. Briefing autocontenido: subagente no ve historial. Pasar paths absolutos, IDs, criterio exito.
3. No delegar comprension: nada de "haz lo que veas". Especificar que cambiar, donde, por que.
4. Verificar output: leer diff/resultado, no confiar en resumen del subagente.
5. No duplicar: si delegas research, no lo repitas tu.

Patrones canonicos de paralelismo

• 3 funciones de registry independientes → 3 fn-constructor en paralelo
• Auditar N apps → N fn-recopilador en paralelo
• Validar varias apps → N fn-analizador en paralelo
• Build cpp + tests py + audit operations.db → 3 calls paralelos
• Tras fn-analizador con fallos → fn-mejorador por cada run_id
• Tarea multi-fase autonoma (issue con criterios verificables) → fn-orquestador (1 sola run, NO recursivo)

Anti-patrones

• Escribir funcion reutilizable inline en apps/ (debe ir a functions/ via fn-constructor)
• Lanzar subagentes en serie cuando son independientes
• Prompt de 1 linea sin contexto ("arregla esto")
• Invocar subagente y luego hacer tu mismo el trabajo
• Spawn fn-orquestador sin migration 006 o sin issue verificable (abortara)
• fn-orquestador recursivo (un orquestador no spawn-ea otro)

Checklist pre-respuesta

• ¿>1 tarea independiente? → paralelizar
• ¿Hace falta funcion/tipo nuevo? → fn-constructor, NO inline
• ¿Hay que ejecutar/auditar/validar? → fase 2/3/4 segun toque
• ¿e2e_runs con fallos? → fn-mejorador
• ¿Issue con criterios verificables + tipo soportado? → fn-orquestador (chequear pre-condiciones)
• ¿Research amplio (>3 queries)? → Explore

Plantilla minima de prompt para subagente

Contexto: <que repo, que app, que objetivo>
Input: <paths absolutos, IDs registry, run_id si aplica>
Tarea: <accion concreta y acotada>
Criterio exito: <como sabe que termino>
Limites: <que NO debe tocar>
Telemetria: tus tool calls quedan registradas en projects/fn_monitoring/apps/call_monitor/operations.db
            via hook PostToolUse heredado de settings.local.json. Sigue patrones canonicos
            (mcp__registry__fn_*, ./fn run, heredoc importando) — los antipatrones se loguean
            como violations.

Telemetria heredada (issue 0085 hardening 5)

Los hooks de .claude/settings.local.json se heredan automaticamente por cada sub-agente que Claude Code lance via la tool Agent. Eso significa:

• Cada Bash, Edit, Write, MultiEdit, mcp__registry__* del sub-agente dispara hook_call_monitor.sh exactamente igual que en la sesion principal.
• El session_id del JSON de input del hook viene del sub-agente, distinto al de la sesion padre. Util para auditar comportamiento por agente.
• Las violations detectadas (sqlite3 directo, heredoc reinventando, etc) cuentan tambien para sub-agentes — un fn-constructor que reescribe inline en lugar de delegar a otro fn-constructor queda registrado.
• FN_TELEMETRY=1 esta en el env block de settings.local.json — los heredocs Python/Bash de sub-agentes ya tienen wrappers activos automaticamente.

Implicacion: NO necesitas pasar flags --telemetry a sub-agentes. Solo asegurate de que el prompt sigue patrones canonicos. La regla .claude/rules/registry_calls.md se aplica igual.

Si un sub-agente abre un proceso hijo que escapa al hook (ej. nohup ... &, daemons), ese subproceso queda fuera de la telemetria — documentalo en el prompt si es un caso valido.