agents_and_robots/dev/issues/completed/0044-formalize-agent-creation-pipeline.md

0044 — Formalizar pipeline de creacion de agentes

Estado: pendiente

Objetivo

Definir, documentar y garantizar que el pipeline de creacion de agentes/robots sea completo, robusto y consistente — tanto cuando se ejecuta manualmente via dev-scripts/ como cuando father-bot lo ejecuta via Matrix. El pipeline debe culminar siempre con el propio bot recien creado enviando un mensaje de bienvenida a los desarrolladores.

Contexto

• dev-scripts/agent/create-full.sh ya ejecuta un pipeline de 6-7 pasos: scaffold → build → register → verify E2EE → [convert robot] → auto-avatar → notify-developer.
• notify-developer.sh ya usa el token del bot recien creado para enviar DMs a los devs listados en DEVELOPER_MATRIX_USERS.
• Father-bot (issue 0037) puede crear agentes via Matrix, ejecutando create-full.sh internamente.
• Problema actual: no hay garantia de que todos los pasos se ejecuten siempre ni de que el bot quede operativo antes de hablar a los devs. Falta un "health check" final.

Pipeline formalizado

Estos son los pasos obligatorios, en orden estricto. Todo agente o robot creado debe pasar por TODOS:

┌─────────────────────────────────────────────────────────────┐
│  PIPELINE DE CREACION DE AGENTES/ROBOTS                     │
│                                                             │
│  1. SCAFFOLD         → crear archivos base desde template   │
│  2. BUILD            → go build -tags goolm ./...           │
│  3. REGISTER         → crear usuario Matrix + token         │
│  4. VERIFY E2EE      → cross-signing + recovery key         │
│  5. CONVERT (robot)  → eliminar LLM/prompts si type=robot   │
│  6. AUTO-AVATAR      → generar y aplicar foto de perfil     │
│  7. DISPLAY NAME     → configurar nombre visible en Matrix  │
│  8. PERSONALIZE      → config.yaml, agent.go, system prompt │
│  9. REBUILD          → recompilar tras personalizacion      │
│  10. START/RESTART   → arrancar el launcher con el bot      │
│  11. HEALTH CHECK    → verificar que el bot esta activo     │
│  12. SELF-INTRODUCE  → el bot envia bienvenida a los devs   │
│                                                             │
│  Env var requerida: DEVELOPER_MATRIX_USERS                  │
│  Si no esta definida, paso 12 se salta con warning.         │
└─────────────────────────────────────────────────────────────┘

Detalle de cada paso

1. SCAFFOLD

• Ejecutar new-agent.sh <id> "Display Name" o copiar desde template
• Crea: agents/<id>/agent.go, config.yaml, prompts/system.md, data/
• Registra blank import en cmd/launcher/main.go

2. BUILD

• go build -tags goolm ./...
• Si falla: STOP, reportar error

3. REGISTER

• register.sh <id> "Display Name"
• Crea usuario Matrix, genera token, password, pickle key
• Anade env vars a .env

4. VERIFY E2EE

• verify.sh <id>
• Genera cross-signing keys, firma device
• Anade recovery key a .env

5. CONVERT (solo robots)

• convert-to-robot.sh <id>
• Elimina config LLM, prompts, ajusta type a robot

6. AUTO-AVATAR

• agentctl auto-avatar <id>
• Genera avatar automatico (DiceBear/RoboHash/Multiavatar)
• Lo sube como foto de perfil del usuario Matrix

7. DISPLAY NAME (NUEVO)

• Configurar el display name en Matrix via API:

  PUT /_matrix/client/v3/profile/@<id>:<server>/displayname
  {"displayname": "<Display Name>"}
  

• Actualmente no se hace de forma consistente — el display name queda como el MXID

8. PERSONALIZE

• Editar config.yaml: descripcion, LLM, tools, personalidad
• Editar agent.go: reglas especificas (si aplica)
• Escribir prompts/system.md: identidad, capacidades, seguridad
• Incluir siempre seccion de seguridad anti-injection

9. REBUILD

• go build -tags goolm ./... tras personalizacion
• Si falla: corregir y reintentar antes de continuar

10. START/RESTART

• ./dev-scripts/server/restart.sh o arrancar el launcher
• Esperar ~5 segundos para que el bot sincronice

11. HEALTH CHECK (NUEVO)

• Verificar en logs que el bot arranco correctamente:
  • "e2ee ready" o "starting matrix sync"
  • "runner started" o "agent running"
• Si no aparecen en 30s: reportar error, no continuar al paso 12

12. SELF-INTRODUCE (MEJORAR)

• El propio bot recien creado envia DM a cada developer en DEVELOPER_MATRIX_USERS
• Mensaje de bienvenida con:
  • Nombre y tipo (agent/robot)
  • Descripcion breve de capacidades
  • Comandos disponibles (si es robot)
  • Instrucciones de uso ("Invitame a un room" o "Escribeme por DM")
• Usa notify-developer.sh (que ya usa el token del bot)
• Si DEVELOPER_MATRIX_USERS no esta definido: warning, no error

Tareas

Fase 1 — Display name automatico

• 1.1 Agregar paso de display name en create-full.sh (POST al API de Matrix con el token del bot)
• 1.2 Verificar que father-bot tambien ejecute este paso al crear agentes
• 1.3 Retroactivamente configurar display name para agentes existentes que no lo tengan

Fase 2 — Health check post-arranque

• 2.1 Crear dev-scripts/agent/health-check.sh <id> que revise logs del agente buscando mensajes de arranque exitoso
• 2.2 Integrarlo en create-full.sh tras el restart (o tras notify, si el restart lo hace el usuario)
• 2.3 Father-bot debe ejecutar health check antes de confirmar al usuario

Fase 3 — Mejorar mensaje de bienvenida

• 3.1 Enriquecer el mensaje de notify-developer.sh:
  • Incluir descripcion del agente (leer de config.yaml)
  • Incluir lista de tools habilitadas (si es agent con tools)
  • Formato Markdown con estructura clara
• 3.2 Garantizar que el mensaje se envia DESPUES de que el bot este activo (health check ok)
• 3.3 Si el DM falla (el bot no esta synceando), reintentar 3 veces con backoff

Fase 4 — Consistencia entre manual y father-bot

• 4.1 Documentar el pipeline completo (12 pasos) en .claude/rules/create_agent.md
• 4.2 Actualizar system prompt de father-bot para que ejecute TODOS los pasos, incluyendo:
  • Display name (paso 7)
  • Rebuild tras personalizacion (paso 9)
  • Health check (paso 11)
  • Self-introduce (paso 12)
• 4.3 Actualizar skill /create-agent y /create-bot para que sigan el mismo pipeline
• 4.4 Test E2E que verifique que el bot creado envia bienvenida a los devs

Fase 5 — Cleanup y docs

• 5.1 Actualizar CLAUDE.md con el pipeline formalizado
• 5.2 Actualizar dev-scripts/agent/README.md con diagrama del pipeline
• 5.3 Agregar DEVELOPER_MATRIX_USERS a .env.example con documentacion

Decisiones de diseno

1. El bot mismo habla a los devs: no un script externo ni otro bot. El notify-developer.sh ya usa el token del bot recien creado, asi que el DM viene del propio bot. Esto es intencional — los devs ven el mensaje directamente del bot nuevo.

2. Health check antes de self-introduce: si el bot no arranco, no puede enviar DMs. El health check evita intentos fallidos y da un diagnostico util.

3. Display name obligatorio: sin display name, el bot aparece como @id:server en Element, confundiendo a los usuarios. Debe configurarse siempre.

4. Pipeline identico para manual y father-bot: no debe haber diferencia en el resultado final. Un agente creado por create-full.sh y uno creado por father-bot deben pasar por los mismos 12 pasos.

5. DEVELOPER_MATRIX_USERS como gate: si no esta configurada, el paso 12 se salta con warning. Nunca bloquea la creacion.

Prerequisitos

• Father-bot funcional (issue 0037) — completado
• Auto-avatar (issue 0042) — completado
• Scripts de creacion existentes — ya implementados

Riesgos

Riesgo	Mitigacion
Bot no arranca y no puede enviar bienvenida	Health check detecta el fallo antes de intentar
Display name no se actualiza (API falla)	Warning, no bloqueante; se puede corregir despues
Father-bot no ejecuta todos los pasos	System prompt actualizado con los 12 pasos; E2E test lo verifica
DEVELOPER_MATRIX_USERS no configurado	Warning explicito; documentado en .env.example