# Referencia de Agentes

Todos los agentes comparten la misma arquitectura base pero tienen roles, canales y system prompts distintos.

---

## Arquitectura Común

**Tecnología:** Python 3.12, discord.py 2.3, httpx, PyGithub
**Patrón:** Discord bot que llama a OpenWebUI y opcionalmente crea PRs en GitHub

**Variables de entorno requeridas por todos:**
```bash
DISCORD_TOKEN           # Token del bot de Discord
DISCORD_CHANNEL_ID      # ID del canal que monitoriza este agente
OPENWEBUI_URL           # https://ai.carlospalanca.es
OPENWEBUI_API_KEY       # API key de OpenWebUI
OPENWEBUI_MODEL         # Modelo a usar (gpt-4o, claude-3-5-sonnet, etc.)
GITHUB_TOKEN            # Fine-grained PAT de GitHub
GITHUB_REPO             # usuario/carlospalanca.es
```

---

## Tyrion Lannister — La Mano del Rey

**Rol:** Orquestador principal
**Canal Discord:** `#el-trono-de-hierro`
**Archivo:** `agents/tyrion/`

**Función:** Analiza cada mensaje de Carlos y decide qué agente debe manejarlo. Publica la tarea delegada en el canal del agente destino.

**Variables adicionales (solo Tyrion):**
```bash
DISCORD_CHANNEL_VARYS
DISCORD_CHANNEL_SAMWELL
DISCORD_CHANNEL_BRONN
DISCORD_CHANNEL_BRAN
DISCORD_CHANNEL_DAVOS
DISCORD_CHANNEL_ARYA
DISCORD_CHANNEL_DAENERYS
DISCORD_CHANNEL_JON
```

**Lógica de enrutamiento:**
| Solicitud | Agente destino |
|-----------|---------------|
| SEO, keywords, títulos YouTube, tags | Varys |
| Guión de vídeo, artículo de blog | Samwell |
| Sponsor, colaboración, afiliado | Bronn |
| Servidor, Docker, nginx, infra | Bran |
| Twitter, LinkedIn, Instagram, redes | Davos |
| Code review, revisar PR | Arya |
| Thumbnail, gráfico, animación, Remotion | Daenerys |
| Certificación, curso, formación, AWS | Jon |

**No hace:** Nunca ejecuta tareas directamente. Solo coordina.

---

## Varys — El Pajarito

**Rol:** SEO & Research
**Canal Discord:** `#el-pajarillo`
**Archivo:** `agents/varys/`

**Outputs típicos:**
- 3 variantes de título (CTR-optimized)
- Descripción YouTube (primeras 150 chars son críticas)
- Lista de hasta 15 tags (max 500 chars total)
- Copy para thumbnail (4 palabras principales + 3 secundarias)
- Análisis de keywords con intención de búsqueda

**PRs que crea:** `seo/varys-YYYYMMDD-tema` en `src/content/` (solo para análisis documentados largos)

**No hace:** No crea guiones ni artículos de blog. Solo SEO y research.

---

## Samwell Tarly — El Maestre

**Rol:** Guiones & Blog
**Canal Discord:** `#la-ciudadela`
**Archivo:** `agents/samwell/`

**Outputs típicos:**
- Guiones completos con estructura hook → secciones → demo → CTA
- Artículos de blog en MDX con frontmatter correcto
- Documentación técnica

**PRs que crea:**
- Guiones: `guiones/samwell-YYYYMMDD-slug` → `src/content/guiones/nombre.md`
- Blog: `blog/samwell-YYYYMMDD-slug` → `src/content/blog/YYYY-MM-DD-nombre.md`

**Detección automática de tipo:**
Si el LLM responde con frontmatter que contiene `status:` → es guión.
Si contiene `pubDate:` → es blog post.

**Frontmatter generado (guiones):**
```yaml
---
title: "Título"
status: borrador
tags: [tag1, tag2]
agentCreated: true
agentName: "Samwell"
---
```

**Frontmatter generado (blog):**
```yaml
---
title: "Título"
description: "150-160 chars"
pubDate: YYYY-MM-DD
author: "Carlos Palanca"
tags: [tag1, tag2]
draft: true
agentCreated: true
agentName: "Samwell"
---
```

---

## Bronn — El Mercenario

**Rol:** Sponsors & Monetización
**Canal Discord:** `#el-banco-de-hierro`
**Archivo:** `agents/bronn/`

**Outputs típicos:**
- Informe de sponsor potencial (relevancia, precio estimado, red flags)
- Lista de programas de afiliados relevantes con URLs
- Plantilla de outreach para contactar empresas

**PRs que crea:** `sponsors/bronn-YYYYMMDD-empresa` → `docs/sponsors/nombre-empresa.md`

**Rechaza automáticamente:** crypto dudoso, gambling, MLM, esquemas piramidales.

**Afiliados de alto valor para el nicho:**
- Cloud: Hetzner, DigitalOcean, Linode, Vultr
- AWS: programa de afiliados de A Cloud Guru, Udemy
- Tools: JetBrains, DataDog, Grafana Cloud
- Cursos: Udemy, Coursera, Linux Foundation

---

## Bran Stark — El Cuervo de Tres Ojos

**Rol:** Infraestructura & DevOps
**Canal Discord:** `#el-muro`
**Archivo:** `agents/bran/`

**Outputs típicos:**
- Dockerfiles y Docker Compose configs
- Playbooks de Ansible
- Configuraciones de nginx
- Scripts de mantenimiento del servidor

**PRs que crea:** `infra/bran-YYYYMMDD-cambio` → `vps/` o `agents/`

**Regla de oro:** Cualquier cambio en producción requiere:
1. PR con descripción de impacto
2. Plan de rollback explícito
3. Comandos de verificación post-deploy
4. Aprobación de Carlos

**No hace sin confirmación:** Comandos destructivos (`rm`, `drop`, `reset`, reinicio de servicios críticos).

---

## Davos Seaworth — El Caballero de la Cebolla

**Rol:** Redes Sociales & Comunicación
**Canal Discord:** `#desembarco-del-rey`
**Archivo:** `agents/davos/`

**Outputs típicos (por vídeo publicado):**
- Tweet de anuncio (día -1)
- Thread técnico en Twitter/X con puntos clave (día +2)
- Post para LinkedIn (día +7)
- Copy para Instagram/Reel con descripción de edición (día +14)

**PRs que crea:** `social/davos-YYYYMMDD-plataforma` → `docs/social/nombre-video.md`

**Formato del entregable (siempre listo para copiar/pegar):**
```markdown
## Twitter/X — Tweet de anuncio
🧵 [Texto del tweet - 280 chars]

## Twitter/X — Thread completo
1/ [...]
2/ [...]

## LinkedIn
[Texto del post]

## Instagram
[Descripción visual + texto sobreimpuesto sugerido]
```

**No hace:** Nunca publica directamente en ninguna red social.

---

## Arya Stark — Sin Nombre

**Rol:** Code Review & Seguridad
**Canal Discord:** `#cara-sin-nombre`
**Archivo:** `agents/arya/`

**Cómo usarla:**
Tyrion la activa cuando hay un PR que revisar, o Carlos escribe directamente en `#cara-sin-nombre` con la URL del PR.

**Checklist de revisión:**
- Secretos o credenciales expuestos → **SIEMPRE BLOQUEANTE**
- Build roto → **BLOQUEANTE**
- Tipos TypeScript incorrectos → **MEJORA o BLOQUEANTE**
- Frontmatter MDX inválido según content.config.ts → **BLOQUEANTE**
- Nombres de archivos en kebab-case → **NITPICK**
- Commit message en formato Conventional Commits → **NITPICK**
- `console.log` en código de producción → **MEJORA**

**Etiquetas de respuesta:**
- `[BLOQUEANTE]` — No se mergea hasta corregir
- `[MEJORA]` — Recomendado pero opcional
- `[NITPICK]` — Estilo, no crítico
- `[APROBADO]` — Todo correcto

**No hace:** No crea contenido nuevo, no hace commits.

---

## Daenerys Targaryen — La Madre de Dragones

**Rol:** Recursos Visuales & Remotion
**Canal Discord:** `#poniente-en-llamas`
**Archivo:** `agents/daenerys/`

**Outputs típicos:**
- Componentes Remotion en TypeScript/React
- Descripción detallada de thumbnails (copy, colores, composición)
- Lower thirds animados reutilizables
- Intros/outros de 3-5 segundos

**PRs que crea:** `visual/daenerys-YYYYMMDD-componente` → `remotion/src/components/`

**Especificaciones técnicas:**
- Resolución: 1920×1080 (16:9) para vídeos, 1080×1920 para Shorts
- FPS: 30 para general, 60 para animaciones fluidas
- Todos los colores en variables CSS
- Props tipadas con interfaces TypeScript

**Ejemplo de componente:**
```tsx
interface LowerThirdProps {
  name: string;
  role: string;
  duration?: number; // frames
}

export const LowerThird: React.FC<LowerThirdProps> = ({ name, role, duration = 90 }) => {
  // ...
};
```

---

## Jon Snow — El Guardián

**Rol:** Formación & Certificaciones
**Canal Discord:** `#la-guardia-de-la-noche`
**Archivo:** `agents/jon/`

**Outputs típicos:**
- Roadmaps de certificación por semanas
- Comparativa de recursos (gratuitos vs pago)
- Plan de estudio personalizado
- Sugerencias de series de vídeos educativos para el canal

**PRs que crea:** `edu/jon-YYYYMMDD-certificacion` → `docs/certifications/`

**Certificaciones cubiertas:**
| Cert | Código | Dificultad | Horas estudio |
|------|--------|-----------|--------------|
| AWS Solutions Architect Associate | SAA-C03 | Media | 80-120h |
| AWS DevOps Engineer Professional | DOP-C02 | Alta | 100-150h |
| Certified Kubernetes Administrator | CKA | Alta | 80-120h |
| HashiCorp Terraform Associate | 003 | Media | 40-60h |
| AWS Security Specialty | SCS-C02 | Alta | 100-150h |

**Regla crítica:** NUNCA reproduce preguntas reales de exámenes (copyright). Solo crea preguntas de práctica propias basadas en los dominios públicos.

---

## `agents/shared/github_client.py`

Módulo compartido por todos los agentes que crean contenido.

**Función principal:**
```python
create_content_pr(
    file_path: str,      # Ruta del archivo en el repo (ej: "src/content/blog/post.md")
    content: str,        # Contenido del archivo
    title: str,          # Título del PR
    description: str,    # Cuerpo del PR
    agent_name: str,     # Nombre del agente (ej: "Samwell")
    branch_prefix: str,  # Prefijo de rama (ej: "blog", "guiones", "seo")
) -> str                 # Devuelve la URL del PR
```

**Lo que hace internamente:**
1. Obtiene el SHA del último commit de `main`
2. Crea una rama: `{branch_prefix}/{agent_name}-{timestamp}-{slug}`
3. Hace commit del archivo en esa rama
4. Abre un PR con etiquetas `agent-created` y `needs-review`
5. Devuelve la URL del PR

**Nunca hace commit a `main`.**