# AGENTS.md — Fuente de Verdad del Sistema de Agentes

**Los agentes deben leer este archivo antes de ejecutar cualquier tarea.**

---

## Regla #1: Pull Requests, NUNCA Commits Directos

**NINGÚN agente puede hacer commit directo a la rama `main`.**

Flujo obligatorio para cualquier cambio:
1. Crear rama con el formato: `tipo/agente-YYYYMMDD-descripcion-corta`
2. Hacer commit en esa rama
3. Abrir Pull Request con título y descripción claros
4. Esperar revisión y aprobación de Carlos antes de mergear

---

## Mapa de Agentes

| Agente | Canal Discord | Rama base | Carpeta destino |
|--------|--------------|-----------|----------------|
| Tyrion (orquestador) | #el-trono-de-hierro | — | — |
| Varys (SEO & Research) | #el-pajarillo | `seo/varys-...` | `src/content/` |
| Samwell (Guiones & Blog) | #la-ciudadela | `guiones/samwell-...` o `blog/samwell-...` | `src/content/guiones/` o `src/content/blog/` |
| Bronn (Sponsors) | #el-banco-de-hierro | `sponsors/bronn-...` | `docs/sponsors/` |
| Bran (Infraestructura) | #el-muro | `infra/bran-...` | `vps/` o `agents/` |
| Davos (Redes Sociales) | #desembarco-del-rey | `social/davos-...` | `docs/social/` |
| Arya (Code Review) | #cara-sin-nombre | — | Revisa PRs, no crea contenido propio |
| Daenerys (Visuales) | #poniente-en-llamas | `visual/daenerys-...` | `remotion/src/components/` |
| Jon (Formación) | #la-guardia-de-la-noche | `edu/jon-...` | `docs/certifications/` |

---

## Estructura del Repositorio

```
src/content/blog/         → Artículos del blog (MDX/MD)
src/content/guiones/      → Guiones de vídeos (MDX/MD)
docs/certifications/      → Guías de certificación (Jon)
docs/sponsors/            → Research de sponsors (Bronn)
docs/social/              → Estrategia de redes sociales (Davos)
remotion/src/components/  → Componentes visuales Remotion (Daenerys)
vps/                      → Configuración de infraestructura (Bran)
agents/                   → Código de los agentes Discord
```

---

## Schema de Frontmatter

### Blog posts (`src/content/blog/`)

```yaml
---
title: "Título del artículo"
description: "150-160 caracteres para SEO. Incluye la keyword principal."
pubDate: YYYY-MM-DD
author: "Carlos Palanca"
tags: [tag1, tag2]          # Máximo 5 tags
draft: true                  # Siempre true hasta aprobación de Carlos
heroImage: "/images/..."     # Opcional
agentCreated: true
agentName: "Samwell"
---
```

### Guiones (`src/content/guiones/`)

```yaml
---
title: "Título del vídeo"
status: borrador             # borrador | revision | aprobado | publicado
tags: [kubernetes, devops]
youtubeId: ""                # Se rellena al publicar
agentCreated: true
agentName: "Samwell"
---
```

---

## Scopes del GitHub Token

El token de GitHub tiene ÚNICAMENTE estos permisos:
- `Contents: Write` — crear ramas y archivos
- `Pull requests: Write` — abrir y comentar PRs
- Scoped SOLO al repositorio `carlospalanca.es`

Los agentes **NO pueden**:
- Eliminar ramas de otros agentes
- Hacer merge de PRs
- Gestionar releases, webhooks o Actions
- Acceder a otros repositorios

---

## Comunicación entre Agentes

Los agentes NO se llaman entre sí directamente por API.
La comunicación ocurre **exclusivamente a través de Discord**:

1. Carlos escribe en `#el-trono-de-hierro`
2. Tyrion analiza y publica la tarea delegada en el canal del agente destino
3. El bot del agente destino detecta el mensaje y lo procesa
4. El resultado (PR creado, análisis, texto) se reporta en ese mismo canal

---

## Conventional Commits

Todos los commits deben seguir este formato:

```
tipo(scope): descripción en español
```

| Tipo | Uso |
|------|-----|
| `content` | Blog posts, guiones |
| `feat` | Nueva funcionalidad o componente |
| `fix` | Corrección de errores |
| `infra` | Cambios de infraestructura |
| `docs` | Documentación |
| `style` | Cambios de estilo sin lógica |

Ejemplos:
- `content(blog): añadir artículo sobre kubernetes ingress`
- `feat(visual): componente lower-third animado`
- `infra(nginx): optimizar config de caché`

---

## Escalación a Carlos

Si un agente encuentra un bloqueo, ambigüedad o problema inesperado:
1. Publica el problema en su canal de Discord con contexto
2. Menciona `@Carlos` para escalación humana
3. **NO intentes adivinar ni ejecutar sin confirmación**
4. Mejor preguntar que deshacer un cambio no deseado