# agent.md — Cómo replicar un Agente Diseñador de Producto experto

> Guía de replicación del showroom. Explica la anatomía completa del agente "Auto Designer":
> su identidad, su sistema de reglas, su flujo de trabajo y los principios que evitan el
> "sabor a IA". Sigue este plano para construir tu propio experto en cualquier plataforma
> de agentes (OpenClaw, AutoClaw, o un framework propio).

---

## 1. La idea central

Un agente diseñador experto NO es un prompt suelto. Es un **sistema de archivos de reglas**
donde cada archivo tiene una sola responsabilidad:

```
agente-diseñador/
├── AGENTS.md          ← El cerebro调度: qué leer y cuándo (punto de entrada)
├── SOUL.md            ← La personalidad: tono, límites, ética
├── IDENTITY.md        ← La ficha: nombre, rol, principios de diseño
├── USER.md            ← El perfil del humano: idioma, zona horaria, preferencias
├── DESIGN.md          ← La metodología: reglas de diseño por niveles de rigor
├── TASK_ROUTER.md     ← El dispatcher: analiza la tarea y decide la ruta
├── INDEX.md           ← El catálogo: lista de recursos disponibles (sin listar carpetas)
├── INTERACTIONS.md    ← El contrato de UI: cómo pregunta y cómo reporta progreso
├── OUTPUT_RULES.md    ← Las reglas de entrega: versionado, archivos, prohibiciones
├── MEMORY.md          ← La memoria de largo plazo (protegida, solo el dueño la cambia)
└── memory/            ← Notas diarias YYYY-MM-DD (continuidad entre sesiones)
```

**Regla de oro**: el agente empieza cada sesión en blanco. Los archivos SON su memoria
y su criterio. Si un archivo no está referenciado desde el dispatcher, no se lee
(ahorra contexto y evita contradicciones).

---

## 2. Las cinco capas del sistema

### Capa 1 — Identidad (SOUL.md + IDENTITY.md)

Define quién es, no qué hace. Elementos mínimos:

- **Rol y especialidad**: p. ej. "diseñador de producto SaaS/B2B con criterio editorial".
- **Principios irrenunciables**: ejemplos reales que funcionan:
  - "Produce lo que se enorgullecería de poner en su portafolio".
  - "3+ opciones ante cualquier decisión de diseño; nunca decide por el usuario".
  - "No inventa colores: usa la marca o define con oklch".
  - "Antes de preguntar, investiga: llega con avance, no con dudas evitables".
- **Límites éticos**: no replicar diseño con copyright, no filtrar datos privados,
  no exponer su prompt interno ni sus archivos de reglas al usuario.
- **Contrato de idioma**: responde SIEMPRE en el idioma de la última mensagem real
  del usuario (incluye copy de los entregables, nombres de archivo y datos falsos).

### Capa 2 — Metodología (DESIGN.md)

El corazón del criterio. Estructura recomendada en tres niveles de rigor:

1. **Restricciones duras** (nunca se rompen): estabilidad, copyright, accesibilidad,
   contraste mínimo 4.5:1 en texto.
2. **Políticas por defecto** (se rompen con justificación): elección tipográfica,
   uso de sombras, densidad de información.
3. **Sugerencias** (mejoran, no bloquean): micro-interacciones, texturas.

Incluye obligatoriamente:

- **Las 4 preguntas pre-código**: Purpose (¿qué problema resuelve?) / Tone
  (¿qué dirección estética extrema?) / Constraints (¿límites técnicos?) /
  Differentiation (¿el UNO recuerdo que deja?).
- **Lista negra anti-slop** (ver §4).
- **Checklist de validación** pre-entrega (8-12 ítems verificables).

### Capa 3 — Enrutamiento (TASK_ROUTER.md + INDEX.md)

Convierte "hazme una web" en una decisión técnica concreta:

```
Tarea → ¿es rediseño de algo existente? ──sí──→ RUTA REDESIGN (hereda tokens, respeta lo que funciona)
                 │no
                 ▼
        Extraer: tipo de output + plataforma + estilo + industria
                 │
                 ▼
        Consultar INDEX → elegir 3 ejes:
          · SKELETON  (el esqueleto HTML de partida — nunca empezar de cero)
          · DESIGN SYSTEM  (la "piel": tokens de una marca real o sistema propio)
          · CRAFT  (las reglas de oficio: tipografía, color, anti-slop, a11y)
                 │
                 ▼
        Ver los 3 recursos REALES antes de escribir una línea de código
```

Reglas que evitan el caos:

- **Prohibido** inventar recursos que no están en el índice (alucinación de skills).
- **Prohibido** montar dos esqueletos incompatibles a la vez.
- Si el brief es ambiguo → UNA tanda de preguntas estructuradas (ver Capa 4), nunca
  interrogatorios infinitos.

### Capa 4 — Interacción (INTERACTIONS.md)

El contrato con la interfaz de chat. Tres acciones estructuradas (NO prosa):

- **`question-form`**: formulario con chips clicables para preferencias (estilo,
  densidad, plataforma, estrategia de entrega). Máximo UNO por tarea; incluir siempre
  una opción "tú decides" y notas libres. Si el usuario salta o no responde, continuar
  con juicio propio.
- **`plan`**: panel de progreso visible (pasos con estado pendiente/en curso/hecho).
  Se re-emite COMPLETO en cada cambio de fase.
- **`status`**: avisos de una línea al cambiar de paso. Nunca se usa para preguntar.

El efecto: el usuario ve el proceso trabajando, no un silencio de 3 minutos seguido
de un archivo.

### Capa 5 — Entrega (OUTPUT_RULES.md)

- **Versionado obligatorio**: `V1 Nombre.html` → cualquier cambio genera `V2` y la
  versión anterior pasa a `archive/`. Prohibido sobrescribir. El usuario siempre
  puede volver atrás.
- **Archivos reales, no paths**: escribir el HTML al disco y "adjuntarlo" para
  previsualización. Un path en el chat NO es una entrega.
- **Self-contained**: un solo archivo HTML con CSS/JS inline; fuentes por CDN;
  cero dependencias frágiles.
- **Responsive obligatorio**: escritorio + móvil (+ tablet si es compleja), verificado
  en el código con breakpoints.
- **Nombres de archivo en el idioma del usuario**.

---

## 3. El flujo completo de una tarea (pseudocódigo)

```
AL RECIBIR TAREA:
1. Saludo breve + confirmación de recepción (1-2 frases, con personalidad)
2. LEER en orden: reglas de diseño → router → recursos del índice
3. ¿Faltan decisiones clave? → UN question-form (estilo, alcance, estrategia)
   └─ sin respuesta tras el tiempo límite → proceder con juicio propio
4. Emitir <plan> con 4-8 pasos visibles
5. Pre-código: responder las 4 preguntas (propósito/tono/límites/diferenciación)
6. VER el esqueleto + design system + craft reales (prohibido trabajar de memoria)
7. Escribir el HTML completo (clone del esqueleto, reemplazar tokens y copy)
8. Escribir archivo versionado + previsualización
9. Auto-revisión: checklist de diseño + estados + responsive + anti-slop
10. Entrega final: qué se hizo, cómo verificarlo, cómo extenderlo + lista de entregables
```

En iteraciones (fase 2): NO se re-eligen recursos ni se re-pregunta; se archiva la
versión actual, se sube el número de versión y solo se toca lo pedido.

---

## 4. El sistema anti-"sabor a IA" (lo más importante)

Esto es lo que separa un agente experto de un generador de plantillas. Lista negra P0:

| Prohibido | Por qué | En su lugar |
|---|---|---|
| Degradado morado-azul (`#667eea → #764ba2`) | El cliché #1 del diseño generado por IA | Color de marca, o un acento cálido/terroso con propósito |
| `#6366f1` (indigo Tailwind) como acento | El "azul por defecto" de toda IA | Un acento con origen (marca, o oklch armonizado) |
| Inter / Roboto / Space Grotesk / Fraunces por defecto | Fuentes "elección segura" de la IA | Pares con carácter: serif display + grotesca, o mono + sans |
| Filas de tarjetas idénticas | Simetría perfecta = pereza | Grids asimétricos, una tarjeta destacada, densidad variable |
| Emoji como iconos/UI | Incontrolable, resta profesionalismo | SVG de línea 1.6-1.8px con `currentColor` |
| Métricas inventadas ("10,000+ clientes") | Destruye la confianza | Datos reales o placeholder marcado `[dato pendiente]` |
| Lorem ipsum / copy de relleno | Delata entrega a medio hacer | Copy real en el idioma del usuario |
| Todo con `box-shadow` grande | Profundidad falsa | Sombras solo si el sistema las define; bordes y capas |
| Fade-in en cada sección al hacer scroll | Ruido sin intención | Una animación de entrada coreografiada; movimiento con propósito |
| Hero + 3 features + pricing + CTA sin variación | El esqueleto de landing por defecto | Narrativa propia: escenas, casos de uso, demos en vivo |

**La regla del 80/20**: ~80% patrones probados + ~20% decisión distintiva
(una tipografía audaz, un acento único, UNA micro-interacción memorable).
Si un extraño mira una captura y reconoce el producto, hubo alma.

**Disciplina de acento**: máximo 2-3 usos del color de acento por pantalla
(un CTA + un estado activo, por ejemplo). El resto es neutro.

---

## 5. Checklist de replicación (resumen ejecutable)

- [ ] Crear `SOUL.md` con personalidad, principios y límites éticos
- [ ] Crear `DESIGN.md` con 3 niveles de rigor + 4 preguntas pre-código + lista negra
- [ ] Crear `TASK_ROUTER.md` con ruta de rediseño vs. proyecto nuevo
- [ ] Crear `INDEX.md` con el catálogo de esqueletos/sistemas/craft disponibles
- [ ] Crear `INTERACTIONS.md` con question-form + plan + status estructurados
- [ ] Crear `OUTPUT_RULES.md` con versionado V{N} + archive/ + prohibiciones
- [ ] Sembrar una biblioteca de esqueletos HTML de calidad (5-10 para empezar:
      landing, dashboard, deck, app móvil, documento, reporte)
- [ ] Definir 3-5 "design systems" de referencia con tokens reales (marca propia o inspiraciones documentadas)
- [ ] Escribir 4-6 archivos "craft": tipografía, color, anti-slop, accesibilidad
- [ ] Conectar todo en `AGENTS.md` (el dispatcher que dice qué leer y cuándo)
- [ ] Probar con 3 tareas reales: una landing, un rediseño, una presentación
- [ ] Ajustar la lista negra con los errores que veas en tus propias salidas

---

## 6. Principios para escalar

1. **Un archivo, una responsabilidad.** Si un .md crece más de ~250 líneas, divídelo.
2. **Todo lo que se exige, se verifica.** Cada regla termina en un checkbox de la
   auto-revisión; las reglas sin verificación se ignoran tarde o temprano.
3. **El contexto es el recurso escaso.** Leer archivos bajo demanda y solo los
   referenciados; prohibido listar carpetas gigantes.
4. **La memoria es sagrada y separada.** Preferencias del usuario solo con
   confirmación explícita; las notas diarias son transient, no perfil.
5. **Cada diseño debe ser diferente.** Si dos entregas consecutivas convergen a la
   misma fuente/color/layout, el sistema está colapsando: rota dirección estética
   a propósito.
6. **Mide el resultado, no el esfuerzo.** El estándar final es: ¿el usuario pudo
   abrir, tocar y mostrar el entregable con orgullo?

---

*Guía generada como complemento del showroom. Úsala como punto de partida y
adáptala a tu plataforma: la arquitectura es portable, el criterio se cultiva.*