agents_and_robots/.claude/tasks/014-template-agent-standardize.md

014 — Agente plantilla + estandarización de config.yaml

Objetivo

Crear un agente plantilla (no lanzable) que sirva como referencia canónica para la configuración de todos los agentes. Enriquecer !info para mostrar metadata completa. Estandarizar los config.yaml existentes.

Contexto

• El launcher descubre agentes via agents/*/config.yaml (glob en cmd/launcher/main.go:55)
• !info existe como built-in en pkg/command/builtins.go pero solo muestra: nombre, ID, versión, descripción
• No hay herencia de configs ni template base — cada config.yaml es autocontenido
• Agentes actuales: assistant-bot, asistente-2, meteorologo

---

Tareas

Fase 1: Agente plantilla

• 1.1 Decidir mecanismo de exclusión del launcher. Opciones:

  • (A) Campo agent.template: true en config.yaml → launcher lo ignora
  • (B) Directorio especial fuera de agents/ (ej: agents/_template/)
  • (C) Convención de nombre con prefijo _ que el glob excluya
  • Recomendación: opción (A) es la más explícita y extensible. Añadir campo Template bool a AgentMeta en schema.go y filtrar en launcher.

• 1.2 Añadir campo template: true a internal/config/schema.go → AgentMeta

• 1.3 Filtrar agentes template en cmd/launcher/main.go — skip si cfg.Agent.Template == true

• 1.4 Crear agents/_template/config.yaml con TODAS las secciones documentadas y valores por defecto comentados. Este archivo es la referencia canónica. Incluir:

  • agent: — id, name, description, version, tags, template: true
  • personality: — valores estándar (tone, verbosity, language, emoji_style, prefix, templates, behavior)
  • llm: — primary con placeholders, tool_use config, fallback
  • tools: — todas las subsecciones (memory, knowledge, ssh, http, scripts, file_ops, mcp)
  • matrix: — homeserver, user_id, encryption, rooms, filters
  • agents: — peers, delegation
  • security: — roles, audit
  • schedules: — ejemplo de cron
  • observability: — logging, metrics, health
  • resilience: — circuit breaker, retry, shutdown
  • storage: — state, cache, history
  • memory: — window config

• 1.5 Crear agents/_template/agent.go mínimo con Rules() que retorna slice vacío (para que compile, aunque nunca se lance)

• 1.6 Actualizar dev-scripts/agent/new-agent.sh para copiar desde _template/ en lugar de generar inline

Fase 2: Enriquecer !info

• 2.1 Modificar el handler de !info en agents/commands.go para que devuelva:

  • Nombre (agent.name)
  • Descripción (agent.description)
  • Versión (agent.version)
  • Personalidad: tone, verbosity, language, emoji_style
  • LLM: provider + modelo del primary
  • Nº de tools registradas (del toolRegistry)
  • Memoria habilitada (sí/no + window size)
  • Knowledge habilitado (sí/no)
  • Nº de docs en knowledge (si habilitado, contar archivos en knowledge dir)
  • Uptime del agente

• 2.2 Formatear la respuesta como bloque legible (markdown con secciones o tabla)

• 2.3 Asegurar que !info no exponga datos sensibles (tokens, API keys, paths internos)

Fase 3: Estandarizar configs existentes

• 3.1 Definir convenciones estándar obligatorias para todo config.yaml:

  • agent.version siempre presente (semver)
  • agent.tags siempre presente (al menos un tag de categoría)
  • personality.language y personality.languages_supported siempre explícitos
  • personality.behavior siempre con las 6 claves (proactive, ask_confirmation, show_reasoning, thread_replies, typing_indicator, acknowledge_receipt)
  • llm.tool_use siempre explícito (enabled true/false, max_iterations)
  • tools.memory y tools.knowledge siempre presentes (enabled true/false)
  • matrix.homeserver y matrix.encryption siempre presentes
  • observability.logging.level siempre explícito

• 3.2 Actualizar agents/assistant-bot/config.yaml según convenciones

• 3.3 Actualizar agents/asistente-2/config.yaml según convenciones

• 3.4 Actualizar agents/meteorologo/config.yaml según convenciones

• 3.5 Validar que los tres agentes arrancan correctamente tras los cambios

Fase 4: Documentación y tooling

• 4.1 Añadir validación en internal/config/loader.go que emita warnings si faltan secciones recomendadas (no bloquear, solo log)

• 4.2 Actualizar .claude/policies/create_agent.md para referenciar el template

• 4.3 Actualizar docs/creating-agents.md con la nueva referencia del template

---

Orden de ejecución recomendado

1. Fase 1 (template) → base para todo lo demás
2. Fase 2 (info) → independiente, puede hacerse en paralelo
3. Fase 3 (estandarizar) → requiere Fase 1 como referencia
4. Fase 4 (docs) → última, cuando todo esté estable

Decisiones de diseño pendientes

• ¿El template debería ser un config.yaml real parseable o solo documentación con comentarios? → Recomendación: real parseable con template: true, así sirve como test de que el schema está completo
• ¿Añadir un comando agentctl validate <config.yaml> para verificar conformidad? → Nice-to-have, se puede añadir en una fase posterior