docs: documentar pipeline formalizado de 12 pasos en rules y system prompt
Actualiza create_agent.md con el pipeline completo (12 pasos) al inicio de la guia, referenciando los scripts de cada paso. Actualiza system prompt de father-bot con: - Pipeline de 12 pasos explicito con "nunca saltar pasos" - Health check (paso 11) via health-check.sh antes de confirmar - Self-introduce (paso 12) via notify-developer.sh - Paso de reporte incluye confirmacion de health check y notify - Manejo de errores para health check y notify Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -2,6 +2,32 @@
|
||||
|
||||
Guia ejecutable para Claude. Seguir paso a paso sin desviarse.
|
||||
|
||||
## Pipeline formalizado (12 pasos)
|
||||
|
||||
Todo agente o robot creado debe pasar por TODOS estos pasos, en orden estricto:
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
**Pasos 1-7**: ejecutados por `./dev-scripts/agent/create-full.sh`
|
||||
**Paso 8**: personalizar manualmente agent.go, config.yaml, prompts/system.md
|
||||
**Paso 9**: `go build -tags goolm ./...`
|
||||
**Paso 10**: `./dev-scripts/server/start.sh` (o `restart.sh`)
|
||||
**Paso 11**: `./dev-scripts/agent/health-check.sh <id>`
|
||||
**Paso 12**: `./dev-scripts/agent/notify-developer.sh <id> <type> "<display-name>"` (requiere `DEVELOPER_MATRIX_USERS` en `.env`)
|
||||
|
||||
## Robot vs Agent — decidir primero
|
||||
|
||||
| | Agent | Robot |
|
||||
@@ -36,18 +62,18 @@ Guia ejecutable para Claude. Seguir paso a paso sin desviarse.
|
||||
|
||||
Si el usuario da todos los inputs, ir directo a la Ruta Rapida. Si faltan, preguntar antes de empezar.
|
||||
|
||||
## Ruta rápida — script automatizado
|
||||
## Ruta rapida — script automatizado (pasos 1-7)
|
||||
|
||||
```bash
|
||||
./dev-scripts/agent/create-full.sh <agent-id> "Display Name"
|
||||
```
|
||||
|
||||
Este script ejecuta en orden: scaffold → build → register Matrix → verify E2EE.
|
||||
Este script ejecuta en orden: scaffold, build, register Matrix, verify E2EE, auto-avatar, display name, notify.
|
||||
Crea todos los archivos, registra en el launcher, genera todas las env vars en `.env`.
|
||||
|
||||
Después del script, personalizar los 3 archivos del agente (ver sección siguiente).
|
||||
Despues del script, personalizar los 3 archivos del agente (paso 8) y continuar con pasos 9-12.
|
||||
|
||||
## Archivos a personalizar después del scaffold
|
||||
## Archivos a personalizar despues del scaffold (paso 8)
|
||||
|
||||
### 1. `agents/<agent-id>/agent.go` — Reglas puras
|
||||
|
||||
@@ -62,7 +88,7 @@ import (
|
||||
)
|
||||
|
||||
func init() {
|
||||
devdevagents.Register("<agent-id>", Rules)
|
||||
devagents.Register("<agent-id>", Rules)
|
||||
}
|
||||
|
||||
func Rules() []decision.Rule {
|
||||
@@ -89,18 +115,18 @@ func Rules() []decision.Rule {
|
||||
- **No usar reglas para comandos** (`!help`, `!ping`, etc.) — los comandos se gestionan via `RegisterCommand` (ver policy `create_command.md`)
|
||||
- Las reglas solo aplican a mensajes normales (sin prefijo `!`)
|
||||
|
||||
Tipos de acción disponibles:
|
||||
- `ActionKindReply` — respuesta estática (con `ReplyAction{Content: "..."}`)
|
||||
Tipos de accion disponibles:
|
||||
- `ActionKindReply` — respuesta estatica (con `ReplyAction{Content: "..."}`)
|
||||
- `ActionKindLLM` — pasa al LLM (con `LLMAction{}`)
|
||||
|
||||
### 2. `agents/<agent-id>/config.yaml` — Configuración
|
||||
### 2. `agents/<agent-id>/config.yaml` — Configuracion
|
||||
|
||||
El scaffold genera un config completo con defaults sensatos. Solo personalizar estas secciones:
|
||||
|
||||
**Identidad** (siempre editar):
|
||||
```yaml
|
||||
agent:
|
||||
description: "<la descripción del agente>"
|
||||
description: "<la descripcion del agente>"
|
||||
```
|
||||
|
||||
**LLM** (si quieres cambiar provider/model):
|
||||
@@ -118,11 +144,11 @@ llm:
|
||||
primary:
|
||||
provider: claude-code
|
||||
claude_code:
|
||||
working_dir: "/tmp/claude-agents/<agent-id>" # SIEMPRE configurar, nunca dejar vacío
|
||||
working_dir: "/tmp/claude-agents/<agent-id>" # SIEMPRE configurar, nunca dejar vacio
|
||||
permission_mode: "bypassPermissions"
|
||||
```
|
||||
|
||||
**Importante**: `working_dir` debe apuntar fuera del repositorio para evitar que el subproceso `claude -p` acceda al código fuente. Si se deja vacío, se usará un directorio temporal (con WARN en logs).
|
||||
**Importante**: `working_dir` debe apuntar fuera del repositorio para evitar que el subproceso `claude -p` acceda al codigo fuente. Si se deja vacio, se usara un directorio temporal (con WARN en logs).
|
||||
|
||||
**Tool use** (si el agente necesita herramientas):
|
||||
```yaml
|
||||
@@ -145,7 +171,7 @@ personality:
|
||||
matrix:
|
||||
threads:
|
||||
enabled: true # responder en threads cuando el mensaje viene de un thread
|
||||
auto_thread: false # true para crear thread automático por cada conversación nueva
|
||||
auto_thread: false # true para crear thread automatico por cada conversacion nueva
|
||||
```
|
||||
|
||||
Referencia completa del schema: `internal/config/schema.go`
|
||||
@@ -153,32 +179,32 @@ Referencia completa del schema: `internal/config/schema.go`
|
||||
### 3. `agents/<agent-id>/prompts/system.md` — System prompt
|
||||
|
||||
Escribir el system prompt completo. Debe incluir:
|
||||
- **Identidad**: quién es, cómo se llama
|
||||
- **Rol**: qué hace, para qué sirve
|
||||
- **Capacidades**: qué puede hacer (incluir tools si `tool_use.enabled: true`)
|
||||
- **Identidad**: quien es, como se llama
|
||||
- **Rol**: que hace, para que sirve
|
||||
- **Capacidades**: que puede hacer (incluir tools si `tool_use.enabled: true`)
|
||||
- **Estilo**: idioma, tono, formato de respuestas
|
||||
- **Restricciones**: qué NO debe hacer
|
||||
- **Restricciones**: que NO debe hacer
|
||||
- **Seguridad** (obligatorio): copiar la seccion de `.claude/templates/security-prompt.md` al final del prompt. Esta seccion protege contra prompt injection.
|
||||
|
||||
Ejemplo de referencia: `agents/asistente-2/prompts/system.md`
|
||||
|
||||
## Registro en el launcher — `cmd/launcher/main.go`
|
||||
|
||||
El script `new-agent.sh` (ejecutado por `create-full.sh`) hace esto automáticamente.
|
||||
El script `new-agent.sh` (ejecutado por `create-full.sh`) hace esto automaticamente.
|
||||
Si falla, hacer manualmente:
|
||||
|
||||
**Blank import** (en la sección de blank imports de agentes):
|
||||
**Blank import** (en la seccion de blank imports de agentes):
|
||||
```go
|
||||
_ "github.com/enmanuel/agents/agents/<agent-id>"
|
||||
```
|
||||
|
||||
Las reglas se registran automáticamente via `init()` en el paquete del agente.
|
||||
No se necesita editar ningún map ni registry manualmente.
|
||||
Las reglas se registran automaticamente via `init()` en el paquete del agente.
|
||||
No se necesita editar ningun map ni registry manualmente.
|
||||
**El ID en `devagents.Register()` DEBE coincidir exactamente con `agent.id` en config.yaml.**
|
||||
|
||||
## Convención de env vars — REGLA CRÍTICA
|
||||
## Convencion de env vars — REGLA CRITICA
|
||||
|
||||
Normalización: `normalize_id()` → mayúsculas, guiones → underscores. **Sin eliminar sufijos.**
|
||||
Normalizacion: `normalize_id()` → mayusculas, guiones → underscores. **Sin eliminar sufijos.**
|
||||
|
||||
| Agent ID | Normalizado | Env vars |
|
||||
|---|---|---|
|
||||
@@ -187,7 +213,49 @@ Normalización: `normalize_id()` → mayúsculas, guiones → underscores. **Sin
|
||||
|
||||
**NUNCA** aplicar transformaciones que eliminen partes del ID (no `sed 's/_BOT$//'`).
|
||||
|
||||
## Verificación post-creación
|
||||
## Pasos 9-12: post-personalizacion
|
||||
|
||||
### Paso 9 — REBUILD
|
||||
|
||||
```bash
|
||||
go build -tags goolm ./...
|
||||
```
|
||||
|
||||
Si falla, corregir y reintentar. **Nunca arrancar el launcher si la compilacion falla.**
|
||||
|
||||
### Paso 10 — START/RESTART
|
||||
|
||||
```bash
|
||||
./dev-scripts/server/start.sh # primera vez
|
||||
./dev-scripts/server/restart.sh # si ya estaba corriendo
|
||||
```
|
||||
|
||||
### Paso 11 — HEALTH CHECK
|
||||
|
||||
```bash
|
||||
./dev-scripts/agent/health-check.sh <agent-id>
|
||||
```
|
||||
|
||||
Verifica en los logs del launcher que el agente arranco correctamente (busca `"e2ee ready"`, `"runner started"`, etc.). Timeout: 30 segundos (configurable como segundo argumento).
|
||||
|
||||
**No continuar al paso 12 si el health check falla.** Diagnosticar primero.
|
||||
|
||||
### Paso 12 — SELF-INTRODUCE
|
||||
|
||||
```bash
|
||||
./dev-scripts/agent/notify-developer.sh <agent-id> <type> "<display-name>"
|
||||
```
|
||||
|
||||
El propio bot envia DM de bienvenida a cada developer en `DEVELOPER_MATRIX_USERS`. Incluye:
|
||||
- Nombre y tipo (agent/robot)
|
||||
- Descripcion (leida de config.yaml)
|
||||
- Tools habilitadas (si aplica)
|
||||
- Instrucciones de uso
|
||||
|
||||
Reintenta hasta 3 veces con backoff si el envio falla.
|
||||
Si `DEVELOPER_MATRIX_USERS` no esta definida en `.env`, se salta con warning.
|
||||
|
||||
## Verificacion post-creacion
|
||||
|
||||
Checklist a verificar antes de considerar el agente listo:
|
||||
|
||||
@@ -199,30 +267,17 @@ Checklist a verificar antes de considerar el agente listo:
|
||||
- [ ] `prompts/system.md` tiene contenido real (no el stub)
|
||||
- [ ] `prompts/system.md` incluye la seccion de seguridad anti-injection (de `.claude/templates/security-prompt.md`)
|
||||
- [ ] Si `tool_use.enabled: true`, el prompt menciona las tools disponibles
|
||||
|
||||
## Arranque y verificación
|
||||
|
||||
```bash
|
||||
# Arrancar (reconstruye y lanza todos los agentes habilitados)
|
||||
./dev-scripts/server/start.sh
|
||||
|
||||
# Verificar logs
|
||||
tail -f run/launcher.log
|
||||
|
||||
# Logs esperados al arrancar correctamente:
|
||||
# {"level":"INFO","msg":"e2ee ready"}
|
||||
# {"level":"INFO","msg":"agent running"}
|
||||
# {"level":"INFO","msg":"starting matrix sync"}
|
||||
```
|
||||
- [ ] Health check pasa (`./dev-scripts/agent/health-check.sh <id>`)
|
||||
- [ ] Bot envio bienvenida a los devs (o `DEVELOPER_MATRIX_USERS` no esta configurado)
|
||||
|
||||
## Troubleshooting E2EE
|
||||
|
||||
| Problema | Solución |
|
||||
| Problema | Solucion |
|
||||
|----------|----------|
|
||||
| "device not verified by its owner" | `./dev-scripts/agent/verify.sh <id>` y reiniciar |
|
||||
| "self-signing private key not in cache" | Recovery key incorrecta → re-ejecutar verify.sh |
|
||||
| "received update for device with different signing key" | Recompilar launcher: `go build -tags goolm -o bin/launcher ./cmd/launcher` |
|
||||
| Recovery key sin comillas en .env | Añadir comillas: `SSSS_RECOVERY_KEY_*="EsXX YYYY ..."` |
|
||||
| Recovery key sin comillas en .env | Anadir comillas: `SSSS_RECOVERY_KEY_*="EsXX YYYY ..."` |
|
||||
|
||||
## Reglas generales
|
||||
|
||||
|
||||
Reference in New Issue
Block a user