# AGENC-IA — Arquitectura del sistema

> **¿Solo quieres usar el sistema? Abre `MANUAL.md`.** Tres minutos.
>
> Este documento es el **por qué**: decisiones, reglas de negocio y las razones
> detrás de cada una. Se abre cuando dudas de algo o cuando se lo explicas a alguien.
>
> Última actualización: 2026-07-31

---

## 1. Qué es AGENC-IA

Un sistema para que **una sola persona** opere como agencia de marketing atendiendo varios clientes, usando IA para automatizar la producción de contenido sin sacrificar calidad.

No es un SaaS. No es una plataforma para vender. Es **infraestructura propia de entrega de servicio**.

---

## 2. Modelo de negocio: dos negocios, no uno

Esta separación es la decisión estructural más importante del proyecto.

### Negocio A — Producto (implementación)

**Qué:** CRM agéntico para inmobiliarias = GHL como backend + frontend propio + capa conversacional de IA.

**Cómo se cobra:** implementación + reventa de licencia GHL. No por resultados.

**Por qué así:**

| Riesgo de construir SaaS propio | Resuelto con GHL de backend |
|---|---|
| Multi-tenancy con datos ajenos | GHL lo administra |
| Vulnerabilidades de app hecha con IA | La superficie crítica es de GHL |
| Soporte e infraestructura 24/7 | Rentada, no construida |
| Costo de infra creciente | Licencia ilimitada ya pagada |

**La ventaja real:** 7 años usando GHL + saber que su frontend es hostil para el usuario final. El valor no está en la base de datos (es la de GHL), está en **la interfaz y el agente de IA encima**.

**Distribución:** esposa en el ramo inmobiliario + clienta actual (agencia de 10 agentes).

### Negocio B — Servicio (marketing con IA)

**Qué:** producción de contenido, contenido SEO/AEO, sitios web, anuncios, video.

**Cómo se cobra:** retainer mensual o por proyecto.

**Filtro de cliente** (ver sección 3).

---

## 3. Reglas de decisión aprendidas

Estas reglas salieron de experiencia real, no de teoría. No las rompas sin buena razón.

### Regla 1 — Nunca aceptes un cliente donde heredas un input roto que no puedes arreglar

**Origen:** el fracaso del servicio inmobiliario. Los agentes independientes entregaban las propiedades que no habían podido vender — sobrevaloradas por apego del propietario. El marketing no falla; falla el precio. Pero al proveedor lo miden por el resultado.

Esto se llama **selección adversa** y aplica a cualquier industria: un restaurante con mala comida, un curso que nadie quiere, un producto mal precificado.

**Aplicación:** antes de firmar, pregunta qué puedes controlar. Si la variable que decide el éxito está fuera de tu alcance, cambia el modelo (cobra por entregable, no por resultado) o no tomes el cliente.

### Regla 2 — Si no controlas el resultado, no vendas resultado

Vende implementación, entregable o acceso. Te pagan por lo que sí controlas.

Por eso el negocio inmobiliario es **producto** y no servicio.

### Regla 3 — El nicho no es la industria, es el tipo de venta

Patrón observado en los clientes de buen ticket:

- Tecmundo — drones agrícolas de precisión
- Consultora SAP — en cotización
- Péptidos — empresa entrando a México, en cotización

Todos son **B2B técnico de compra considerada**: producto complejo, ciclo largo, comprador que investiga antes de decidir.

Ese perfil se vende con **contenido de educación** — que es justo la fortaleza del arsenal (article-krafter, content-blueprint, framework AEO, SEO, LLMO).

Inmobiliario nunca embonó porque una casa no se vende explicándola; se vende con inventario y precio. La mejor herramienta no aplicaba.

**Filtro para Negocio B:** ¿el producto necesita explicarse para venderse? Si sí, es cliente. Si no, probablemente no.

### Regla 4 — Al vault va lo que se lee; fuera del vault va lo que se ejecuta

Second Brain es un vault de Obsidian. Meterle `node_modules`, `.next` o repos de Git rompe el indexado, el sync y la búsqueda.

- **Dentro** — markdown: skills, briefs, design systems, estrategia, decisiones.
- **Fuera** — código: apps Next.js, Remotion, packs con dependencias.

### Regla 5 — Una sola fuente de verdad por skill

Problema detectado el 2026-07-30: la biblioteca de skills existía en **cinco** ubicaciones, con versiones divergentes (ej. `kopy-krafter` con 532 líneas en una y 546 en otra).

Una carpeta canónica. Un script que sincroniza a las plataformas. Nunca se edita una copia.

---

## 4. Estructura de carpetas

```
Second Brain/                                  ← Obsidian. Markdown. Liviano.
├── agencia/                                   ← privado: método, skills y plantillas
│   ├── ARQUITECTURA.md                        ← este documento
│   ├── motor/                                 ← las skills del motor de contenido
│   └── plantillas/_ESTRUCTURA/                ← plantilla privada para clientes
├── 02-proyectos/
│   └── {cliente}/                             ← datos y contexto de cada cliente
└── 06-conocimiento/skills/                    ← biblioteca canónica de skills

Documents/Dev/AGENC-IA/                        ← FUERA del vault. Código pesado.
├── crm-agentico/                              ← frontend GHL
├── agencia-app/
├── video-system/                              ← Remotion
└── WebKreator*/
```

### Estructura por cliente

> Patrón probado en producción en el sistema PHIX (`MPG/Phix/IA PHIX/`).
> No se inventó aquí: se extrajo de lo que ya funciona.

```
02-proyectos/{cliente}/
├── catalogo-creativos.md      ← ÍNDICE. Punto de entrada único.
├── design-system/
│   ├── design-system.md
│   └── (logo, paleta, referencias visuales)
├── productos/
│   ├── catalogo.md
│   ├── {id}-descriptor.md     ← física verbatim → alimenta prompts
│   ├── {id}-ficha.md          ← reglas de uso → gobierna
│   └── fotos/                 ← incluye REFERENCIAS DE ESCALA
├── personajes/
│   ├── catalogo.md
│   ├── {id}-ficha.md
│   └── fotos/                 ← varios ángulos, no solo frente
├── escenarios/
│   ├── catalogo.md
│   └── refs/
├── estrategia/                ← market intelligence, oferta, copy
└── outputs/
    ├── entregas.md
    ├── imagenes/{campana}/
    ├── videos/{campana}/
    └── watermarked/
```

**Los assets binarios** (fotos de producto, renders) viven junto a su ficha — no separados en otra carpeta. La ficha sin la foto no sirve.

### Por qué escenarios va aparte

Porque el sistema es **combinatorio**:

```
N productos  ×  M escenarios  ×  P personajes  =  variantes disponibles
```

Se pide un creativo por IDs — *"producto 1, escenario 3, personaje 2"* — y el director creativo abre solo esas tres fichas más el design system. Antes de inventar concepto nuevo, se revisa si una combinación sin usar ya resuelve el pedido.

### Carga progresiva también en los datos

`catalogo-creativos.md` no es decoración: es el índice que evita cargar toda la carpeta. Su regla es:

> Abrir **solo** la ficha del activo elegido y el design system.

Mismo principio que `SKILL.md` delgado + `references/`, aplicado a los datos del cliente.

---

## 5. El motor de contenido

Un solo motor que sirve a todos los frentes:

```
                    MOTOR DE CONTENIDO
                            │
   ┌─────────┬──────────────┼──────────────┬─────────────┐
   │         │              │              │             │
Tecmundo  Inmobiliaria  Multinivel   Self Marketing   SAP / Péptidos
(paga)      (paga)      (en obra)     (branding)      (cotizados)
```

Construyes una vez, cobras varias. Y Self Marketing no es vanidad: **es el pipeline comercial** que corrige el problema de ticket bajo por falta de branding propio.

### Capas

| # | Capa | Entrada | Salida |
|---|---|---|---|
| 0 | **Setup de cliente** | brief, marca, producto | design-system, product-sheet, character-sheet |
| 1 | **Estrategia** | config del cliente | temario de contenido, pilares |
| 2 | **Guion** | tema + config | guion + copy, listo para producir |
| 3 | **Imagen** | guion + design-system | PNG en carpeta del cliente |
| 4 | **Video** | guion + character-sheet | MP4 en carpeta del cliente |
| 5 | **Publicación** | assets aprobados | programado o publicado |

**Regla de las capas:** cada una lee de archivos y escribe archivos. Ninguna capa asume que otra corrió en la misma sesión. Así se puede correr el motor por pedazos, retomar días después, o programarlo como tarea automática.

### Contratos entre capas

Los catálogos y fichas son **el contrato**. Todas las skills los leen; ninguna los inventa.

Si un dato no está en la ficha, la skill **pregunta** — no asume.

### Reglas de producción aprendidas en PHIX

Estas salieron de generar creativos reales, no de teoría:

**1. Referencia de escala obligatoria.** Si el producto tiene tamaño no obvio, la IA lo dibuja del tamaño equivocado. El snap de PHIX mide 4×4 cm y los modelos lo convertían en botella de bloqueador. La solución: fotos del producto en mano, y describir el tamaño en palabras comparativas ("del tamaño de un pulgar"), no solo en centímetros.

**2. Reglas negativas explícitas.** Escribir qué NO debe volverse el producto, porque los modelos derivan hacia el objeto más común de esa categoría.

**3. Descriptor ≠ ficha.** El descriptor es física verbatim que se pega en prompts. La ficha son reglas de uso y comunicación. Mezclarlos hace que el prompt cargue gobernanza que no necesita, y que las reglas se pierdan entre detalles visuales.

**4. Varios ángulos por personaje.** Una sola foto frontal produce personajes que se deforman al cambiar de encuadre. Mínimo: frente, ambos perfiles, tres cuartos, cuerpo completo.

**5. Permisos antes de generar.** No crear una identidad comercial a partir de una foto sin autorización del titular. Va escrito en el catálogo de personajes, no en la memoria.

**6. Formatos como composiciones adaptadas, no recortes.** 9:16, 1:1 y 16:9 se generan cada uno con su composición.

**7. Honestidad de escena.** No presentar una imagen generada como fotografía documental de una persona, instalación o cultivo real.

---

## 6. Generación: qué herramienta para qué

| Necesidad | Herramienta |
|---|---|
| Imágenes | Higgsfield MCP (`images_generate`) |
| Video ≤15s por clip | Higgsfield MCP (`video_generate`) |
| Consistencia de personaje | Higgsfield Soul → reusar como `image_references` |
| Video con texto animado / diagramas | Remotion (video-system, fuera del vault) |
| Voz | Higgsfield (`audio_tts`) |

**Restricción dura:** un clip generado = **15 segundos máximo**. Videos más largos = varios clips unidos. Todo guion se diseña alrededor de eso.

---

## 7. Portabilidad entre plataformas

Un skill es una carpeta con `SKILL.md` + `references/`. Markdown puro. **La misma carpeta funciona en Claude, Codex y Antigravity.**

Estructura correcta (carga progresiva):

```
mi-skill/
├── SKILL.md              ← delgado. Índice + reglas duras. ~40-80 líneas.
└── references/
    ├── paso-1.md         ← se carga solo cuando ese paso corre
    └── paso-2.md
```

Un `SKILL.md` de 600 líneas quema contexto aunque solo uses el 10%. Los skills actuales de AGENC-IA son monolíticos (hasta 608 líneas) — migrarlos a este formato es deuda técnica pendiente.

**Sync:** un script empuja la carpeta canónica a cada plataforma. Se edita en un solo lugar.

---

## 8. Estado actual

### Hecho

- **Sistema PHIX funcionando en producción** (`MPG/Phix/IA PHIX/`) — la referencia de la que se extrajo toda esta arquitectura. Incluye 8 skills en `.agents/skills/` ya conectadas a Higgsfield: `higgsfield-generate` (11 references), `higgsfield-soul-id`, `higgsfield-product-photoshoot`, `higgsfield-marketplace-cards`, `phix-visual-reference-director`, `phix-product-photo-remix`, `phix-seo-aeo-publisher`, `phix-social-planner-publisher`
- Brief completo de Tecmundo (posicionamiento, avatar, dolores, ecosistema)
- `video-system` con estructura por cliente y motor Remotion
- CRM agéntico con frontend propio sobre GHL, avanzado
- ~30 skills escritas (dispersas en 5 ubicaciones, con duplicados)
- Higgsfield MCP conectado, plan Premium

### Pendiente

- [ ] Generalizar las skills `phix-*` a versiones agnósticas de cliente
- [ ] Tecmundo llenado con la estructura nueva como segundo caso
- [ ] Inventario y consolidación de las 5 ubicaciones de skills
- [ ] Script de sincronización entre plataformas
- [ ] Prueba end-to-end generando con Higgsfield desde la estructura nueva
- [ ] Tareas programadas para generación diaria

> **Nota de método:** el motor no se está construyendo desde cero. Se está
> **extrayendo y generalizando** de PHIX, que ya funciona. El segundo cliente
> (Tecmundo) es el que revela qué era realmente genérico y qué era específico de PHIX.

### Deuda técnica conocida

- Skills monolíticos sin `references/`
- Duplicados divergentes: `kopy-krafter`, `oferta-irresistible`
- Código pesado (`node_modules`) dentro del árbol de trabajo
- `CRM Agentico` y `CRM%20Agentico` — carpeta duplicada por error de codificación de URL
