# 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 |