| name | foundation-orchestrator |
| description | Orquesta la Foundation v3.0: 7 secciones, 8 layers, gate checks con requires/enriches_with. Flujo: Kickoff (1 skill, company-brief.current.md) → Trust Score (opcional, auto-arranca tras Company Brief) → Full Foundation (9 skills individuales) → Metrics Setup → Strategic Plan. Al aprobar un pilar, ejecuta automáticamente el siguiente. Leer pillar-registry.md para detalle de cada pilar. |
| user-invocable | false |
| context_required | ["_system/foundation-protocol.md"] |
Foundation Orchestrator v3.0
Orquesta el flujo de Foundation pilar a pilar. Presenta → Valida → Aprueba → Siguiente.
Protocolo: _system/foundation-protocol.md
Registry: references/pillar-registry.md
Estado: el status de cada pilar vive en su task 1:1 (proyectos P00). Se lee vía GET {MC_BASE}/api/brand-brain/state?slug={slug} (mismo shape de siempre: sections→pillars→status, vocabulario canónico de task: todo | in-progress | pending-review | completed | blocked | cancelled) y se escribe vía POST {MC_BASE}/api/brand-brain/pillar-status con body {"slug", "section", "pillar", "status"}. Auth: header x-admin-token con el adminToken de la raíz de clients.json (mismo patrón que los crons).
Secciones de Output
| Sección | Dir | Qué contiene |
|---|
| Company Brief | company-brief/ | Company Brief inicial: company-brief.current.md (un archivo, secciones H2) |
| Site Audit | site-audit/ | Trust Score (opcional, auto-arranca tras Company Brief): trust-score/trust-score.current.md (6 pilares + gap vs competidores + verdict) |
| Market & Us | market-and-us/ | Research profundo + Market Synthesis (SWOT, Summary, OPE Canvas, Presentación) |
| Go-To-Market | go-to-market/ | Niche Discovery, Positioning, Pricing |
| Brand Identity | brand-identity/ + brand-voice/ | Full Voice Guide + Visual Identity |
| Métricas | go-to-market/metrics-plan/ | Plan de métricas + integraciones + dashboard |
| Strategic Plan | strategic-plan/ | Roadmap GTM |
DAG — 8 Layers
L0 KICKOFF: kickoff (1 skill → company-brief/company-brief.current.md)
└─ trust-score? (OPCIONAL, auto-arranca tras company-brief — requires URL; no bloquea)
L1 RESEARCH: market-intelligence + competitor-intelligence + self-intelligence
L2 SYNTHESIS: market-synthesis (SWOT + Summary + OPE Canvas + Presentación)
L3 DISCOVERY: niche-discovery-100x + existing-customer-data?
L4 ACTIVATION: positioning-messaging + pricing-strategy + ecp-validation?
L5 BRAND: brand-voice + visual-identity
L6 METRICS: metrics-setup (plan + connect APIs + dashboard)
L7 STRATEGY: strategic-plan
Gate Check — requires vs enriches_with
ANTES de cada pilar, leer GET {MC_BASE}/api/brand-brain/state?slug={slug} y verificar:
- requires → TODOS deben ser
completed. Si no → BLOQUEAR.
- enriches_with → Si
completed, cargar como input. Si no → funcionar sin él.
Ver references/pillar-registry.md para mapa completo de dependencias.
Flujo de Entrada
Paso 1: Leer Estado
- Leer
GET {MC_BASE}/api/brand-brain/state?slug={slug} (sections→pillars→status, vocabulario de task)
- Pilares sin task →
todo
- Determinar dónde quedamos
Paso 2: Mostrar Progreso
🏗️ FOUNDATION — [Cliente]
📋 Kickoff ✅ (company-brief/company-brief.current.md)
🔍 Site Audit ⬜ Trust Score (opcional)
📊 Market & Us ✅ Market · ⬜ Competitors · ✅ Self · ⬜ Synthesis
🎯 Go-To-Market ⬜ Niches · ⬜ Positioning · ⬜ Pricing
🎨 Brand Identity ⬜ Voice · ⬜ Visual
📏 Métricas ⬜ Plan + Conexiones
🗺️ Strategic Plan ⬜
Progreso: 6/13 pilares
Iconos: ✅ completed | ⚠️ pending-review | 🔧 in-progress | ⬜ todo | 🚫 blocked | ➖ cancelled
Paso 3: Continuar
- Si hay pilar en
pending-review → re-presentar
- Si hay pilar en
in-progress con correcciones pedidas → aplicar correcciones
- Else → ejecutar siguiente pilar disponible (gate check)
Kickoff — Layer 0
Skill: kickoff
Thread: {slug}:kickoff
Sesión de intake única (~30 min):
- Usuario introduce URL (o modo manual sin URL)
- Scrape web + sociales → pre-fill grounding
- Validar con usuario → completar gaps
- Genera
brand/{slug}/company-brief/company-brief.current.md (un archivo, secciones H2: Company, Market, Brand Voice, ECPs)
Al aprobar → marcar el pilar company-brief como completed (POST pillar-status) → desbloquea Layer 1.
Auto-arranque del Trust Score (Layer 0, OPCIONAL): ya NO es trabajo del orquestador — vive en código (SAN-309), que es donde es fiable. Cuando el pilar company-brief se marca completed (ya hay URL), el endpoint POST /api/brand-brain/pillar-status dispara runTrustScore(slug) (src/lib/trust-score/run.ts) fire-and-forget, una sola vez (guard: solo si aún no hay cache metrics/trust-score.json). Corre el analyzer en modo compare (auto-descubre + fija competidores), persiste la serie diaria en metric_snapshots (source=trust_score), escribe site-audit/trust-score/trust-score.current.md y enciende la superficie Reputation. NO bloquea: si el analyzer falla (sin competidores → 409, discovery caído → 502, o _stale), el pilar trust-score queda pendiente sin trabar el avance ni el gate de Foundation. trust-score nunca es requires de ningún pilar downstream; el refresco recurrente lo hace el cron trust_score_refresh.
Ciclo por Pilar (Layer 1+)
1. Gate Check
Verificar requires + cargar enriches_with disponibles.
2. Ejecutar Skill
Invocar el skill del registry. Si hay enriches_with disponibles, pasarlos como contexto.
Convención de paths (v3.2):
- Kickoff escribe SOLO
brand/{slug}/company-brief/company-brief.current.md (Company Brief inicial, un archivo). NO toca carpetas de pilares.
- Las skills full escriben a
{carpeta}/{carpeta}.current.md (brand/{slug}/{carpeta}/{carpeta}.current.md).
- Las skills full leen su sección de
company-brief/company-brief.current.md como grounding opcional (si no existe, arrancan standalone). El {carpeta}.current.md final se regenera desde el paquete completo, nunca se limita a refinar el grounding.
- Si una skill full necesita un input upstream, ese input debe existir como
{carpeta}.current.md (full, source of truth). No degradar a leer grounding como fuente final.
Con model fallback:
- 1er intento: sessions_spawn con model=default (Opus)
- Si falla: re-spawn con model=minimax/MiniMax-M2.5
- Si sigue fallar: marcar error + notificar usuario
3. Presentar Resumen Ejecutivo
5-10 bullets. NO el doc entero. Formato:
───────────────────────────────
📊 MARKET ANALYSIS — Resumen
───────────────────────────────
• TAM: €X.XM en [país]
• Segmentos principales: [lista]
• Tendencia: [crecimiento/estable]
• Regulación clave: [impactos]
• Oportunidad principal: [descripción]
📄 Doc: brand/{slug}/market-and-us/market/market.current.md
───────────────────────────────
¿Correcto? ¿Cambios?
───────────────────────────────
4. Respuesta del Usuario
Aprobación → actualizar state → regenerar MC → mensaje de celebración + progreso → ejecutar siguiente automáticamente
Corrección → aplicar cambios → re-presentar
Skip → pedir razón → marcar cancelled → siguiente
5. Persistir
- Actualizar el status del pilar vía
POST {MC_BASE}/api/brand-brain/pillar-status con body {"slug", "section", "pillar", "status"} — status SIEMPRE en vocabulario canónico (completed | in-progress | pending-review).
- El Brand Snapshot del dashboard se deriva automáticamente del company-brief — no hay que mantener
brand_summary a mano.
- Ejecutar
python3 scripts/regenerate.py (legacy mc-data; no toca status)
Market Synthesis — Layer 2 (skill dedicado)
Skill: market-synthesis
Thread: {slug}:market-synthesis
Genera 4 outputs en secuencia:
- SWOT + TOWS con ICE prioritization
- Market Summary (1-2 páginas)
- OPE Canvas (14 secciones)
- Presentación HTML (vía frontend-slides)
Nota: En v2.0 las síntesis (summary, ope-canvas) eran inline del orchestrator. En v3.0 son parte del skill market-synthesis. El orchestrator solo invoca el skill y valida el output.
Competitors — Lista Dinámica
Los competidores se descubren en múltiples momentos:
- Kickoff (L0): "¿Quiénes son tus competidores?"
- Market Analysis (L1): descubiertos durante research
- Niche Discovery (L3): competidores por nicho
Cada competidor → market-and-us/competitors/{nombre}/{nombre}.current.md (deep-dive). El roll-up consolidado vive en market-and-us/competitors/competitors.current.md y se regenera desde los subdirs.
El orchestrator puede preguntar proactivamente: "¿Hay otros competidores que deberíamos analizar?"
Viability Checkpoint
Después de aprobar self-analysis:
- Si señales negativas (reviews <2.5, PMF dudoso) → alertar
- Advisory, NO bloqueante. El usuario decide.
Resumen Final
Al completar toda la Foundation (Layer 0-5):
═══════════════════════════════════════
🏁 FOUNDATION COMPLETA — [Cliente]
═══════════════════════════════════════
📋 Company Brief: [empresa] — [1 línea]
📊 Mercado: TAM [€X] | Tendencia: [X]
⚔️ Competidores: [top 3]
🎯 ICP: [perfil principal]
💬 Posicionamiento: "[statement]"
💰 Pricing: [estrategia]
🎨 Voz: [3 atributos]
Siguiente: Métricas y Conexiones → Strategic Plan
Docs en: brand/{slug}/
═══════════════════════════════════════
Error Handling & Retry
Si una skill FALLA:
Paso 1: Clasificar el error
- API/Timeout (rate limit, network, 5xx) → Retry
- Tool Error (scraper failed, missing API key) → Retry con fallback
- Quality (output incompleto, mal formato) → Retry con más contexto
- Unknown → Notificar usuario + marcar pilar como
blocked (POST pillar-status)
Paso 2: Retry con Model Fallback
| Intento | Model | Contexto | Notes |
|---|
| 1 | Opus (thinking:high) | Normal | Primary |
| 2 | Opus (thinking:high) | + enriches_with disponibles | Si primer intento tuvo context gaps |
| 3 | MiniMax-M2.5 | Normal | Fallback económico |
Paso 3: Si sigue fallando
- Marcar el pilar como
blocked vía POST {MC_BASE}/api/brand-brain/pillar-status (status "blocked")
- Notificar al usuario: qué falló, por qué, qué hacer
- Ofrecer: reintentar manualmente, skippear, o resolver el error
Reglas
- Gate check SIEMPRE antes de cada pilar
- Resumen ejecutivo — nunca el doc entero
- Flujo automático — al aprobar, siguiente arranca solo
- Kickoff = 1 skill — produce Company Brief directamente; no hay merge-view ni scripts de regeneración separados
- Market Synthesis = 1 skill (SWOT + Summary + OPE Canvas + Presentación)
- Status siempre actualizado —
POST /api/brand-brain/pillar-status tras cada transición (vocabulario canónico)
- Retomable — si la sesión se corta, retoma donde quedó
- enriches_with es silencioso — si no está disponible, funcionar sin avisar
- Retry automático — 3 intentos con model fallback antes de rendirse
- Error = notificar — nunca silently fail
- Grounding — las skills full leen su sección de
company-brief/company-brief.current.md como seed opcional; nunca lo tratan como fuente final.
- Path discipline — kickoff escribe SOLO
company-brief/company-brief.current.md. Nunca toca carpetas de pilares. {carpeta}.current.md = full (source of truth); company-brief.current.md = Company Brief inicial (grounding opcional).
