merge: quick/pipeline-issue — issue 0044 pipeline de creacion formalizado

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

@@ -0,0 +1,175 @@
+# 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 |

dev/issues/README.md

@@ -54,3 +54,4 @@ afectados y notas de implementacion.
 | 41  | Videollamadas con agentes via LiveKit | [0041-livekit-videocall.md](0041-livekit-videocall.md)                         | pendiente  |
 | 42  | Auto-avatar con proveedores gratuitos | [0042-auto-avatar-providers.md](completed/0042-auto-avatar-providers.md)       | completado  |
 | 43  | Guardrails de seguridad para Father Bot | [0043-father-bot-security-guardrails.md](0043-father-bot-security-guardrails.md) | pendiente  |
+| 44  | Formalizar pipeline de creacion de agentes | [0044-formalize-agent-creation-pipeline.md](0044-formalize-agent-creation-pipeline.md) | pendiente  |