## Asset Header

- **Asset ID:** ARQ-XX-SX-SherpaAPIPlan-v01
- **Version:** v01
- **Status:** Draft
- **Owner:** Victor Heredia
- **IntellBank:** IB-XX-Maestro
- **Tipo:** ARQ — Architecture
- **Propósito:** Sherpa IA Integrado — Plan de Implementación
- **Última actualización:** 2026-04-11

---

# Sherpa IA Integrado — Plan de Implementación
## Opción 2: Claude API en App Propia del Equipo

**Asset ID:** SHA-VICTOR-Sherpa-API-Plan-v01
**Versión:** v1.0
**Fecha:** 2026-03-24
**Owner:** Victor Heredia
**Status:** Plan aprobado / pendiente ejecución

---

## 1. QUÉ ES ESTO Y POR QUÉ

El objetivo es que el equipo de EmpowerLabs pueda interactuar directamente con el Sherpa de Victor — un agente Claude contextualizado — desde la misma app que ya usan para gestionar el vault y los activos cognitivos. Sin cambiar de herramienta. Sin copiar contexto manualmente. Sin necesidad de que Victor esté presente para responder preguntas operativas.

**Lo que el Sherpa puede hacer por el equipo:**
- Responder preguntas sobre cómo avanzar en una tarea según los playbooks
- Validar si una decisión está alineada con la estrategia
- Generar borradores de entregables en el estilo y formato EmpowerLabs
- Explicar criterios de aceptación de cualquier tarea del sprint
- Actuar como primer filtro antes de escalar a Victor

**Lo que NO hace:**
- Reemplazar juicio estratégico de Victor en decisiones de negocio
- Tener acceso a datos sensibles de clientes sin diseño explícito de permisos

---

## 2. ARQUITECTURA

```
┌─────────────────────────────────────────────────────┐
│                    APP DE EL EQUIPO                  │
│  ┌────────────┐  ┌──────────────┐  ┌─────────────┐  │
│  │  Chat UI   │  │ Vault Browser│  │  Dashboards │  │
│  └─────┬──────┘  └──────────────┘  └─────────────┘  │
│        │                                             │
│  ┌─────▼──────────────────────────────────────────┐ │
│  │           SHERPA MIDDLEWARE (Backend)           │ │
│  │  ┌──────────────┐  ┌───────────────────────┐   │ │
│  │  │ Context Loader│  │  Conversation Manager │   │ │
│  │  └──────┬───────┘  └──────────┬────────────┘   │ │
│  │         │                     │                 │ │
│  │  ┌──────▼─────────────────────▼────────────┐   │ │
│  │  │         Claude API (Anthropic)           │   │ │
│  │  │   Model: claude-sonnet-4-6               │   │ │
│  │  └──────────────────────────────────────────┘   │ │
│  └─────────────────────────────────────────────────┘ │
│                                                      │
│  ┌──────────────────────────────────────────────┐   │
│  │              VAULT (Git / Archivos .md)       │   │
│  │  System Prompt · Playbooks · Proyectos        │   │
│  └──────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────┘
```

### Capas del sistema

**A. Chat UI** — Interfaz conversacional dentro de la app existente. Cada miembro ve su historial. Victor tiene vista de administrador con todas las conversaciones.

**B. Sherpa Middleware** — El cerebro de la integración. Dos funciones clave:
- *Context Loader*: carga dinámicamente los documentos del Vault relevantes para la pregunta del usuario (RAG básico o lookup por etiquetas)
- *Conversation Manager*: mantiene historial por usuario, gestiona tokens, aplica límites

**C. Claude API** — La llamada a Anthropic. Recibe: system prompt + contexto del vault + historial + pregunta del usuario.

**D. Vault** — La fuente de verdad. Los .md que ya existen son la base de conocimiento del Sherpa.

---

## 3. REQUERIMIENTOS

### 3.1 Requerimientos de negocio

| # | Requerimiento | Prioridad |
|---|---------------|-----------|
| RN-01 | El equipo puede hacer preguntas al Sherpa desde la app sin contexto manual | Alta |
| RN-02 | El Sherpa responde en el estilo y tono EmpowerLabs / Re100X | Alta |
| RN-03 | Victor puede ver todas las interacciones del equipo con el Sherpa | Alta |
| RN-04 | El Sherpa conoce los playbooks, proyectos activos y criterios de aceptación | Alta |
| RN-05 | Cada usuario tiene historial propio de conversaciones | Media |
| RN-06 | El Sherpa puede escalar a Victor cuando la pregunta requiere su decisión | Media |
| RN-07 | El Sherpa responde en español por defecto | Media |
| RN-08 | Victor puede actualizar el contexto del Sherpa sin tocar código | Alta |

### 3.2 Requerimientos técnicos

| # | Requerimiento | Notas |
|---|---------------|-------|
| RT-01 | API Key de Anthropic (cuenta de pago) | Plan Scale o API directa |
| RT-02 | Backend capaz de hacer llamadas HTTP (Node.js / Python / cualquier stack) | Ya existe en su app |
| RT-03 | Almacenamiento de conversaciones (DB o archivos) | SQL, MongoDB o incluso JSON por usuario |
| RT-04 | Autenticación de usuarios (ya tienen) | Mapear usuario → rol → permisos de contexto |
| RT-05 | Acceso de lectura al Vault (.md files) desde el backend | Ya tienen si el vault está en el mismo repo |
| RT-06 | Variable de entorno segura para API Key | `.env`, secrets manager o equivalente |
| RT-07 | Endpoint backend: `POST /sherpa/message` | Recibe: user_id, message, session_id |
| RT-08 | Contexto máximo gestionado (no exceder 200K tokens por llamada) | El middleware corta y prioriza |

### 3.3 Requerimientos del System Prompt (el más importante)

El system prompt es el "alma" del Sherpa. Debe contener:

1. **Identidad** — Quién es el Sherpa, su rol, su tono
2. **Contexto de EmpowerLabs** — La empresa, productos, equipo, metodología
3. **Reglas de respuesta** — Qué puede responder, qué escala a Victor, qué no hace
4. **Formato preferido** — Sin bullet points exagerados, respuestas accionables, español
5. **Referencia al vault** — Instrucción de usar los documentos inyectados como fuente de verdad

---

## 4. DISEÑO DEL SYSTEM PROMPT BASE

```
Eres el Sherpa de Victor Heredia — su Sherpa IA operativo para EmpowerLabs / Re100X.

QUIÉN ERES
Actúas como el agente de inteligencia operativa de Victor. Tu función es ayudar
al equipo a avanzar con claridad, sin necesitar a Victor presente para cada pregunta.
No eres un asistente genérico. Conoces el contexto específico de este equipo,
sus proyectos, su metodología y sus estándares de calidad.

CONTEXTO DE LA ORGANIZACIÓN
[Aquí se inyecta dinámicamente: nombre del proyecto activo, equipo asignado,
sprint actual, documentos relevantes del vault]

CÓMO RESPONDES
- Español siempre, salvo que el usuario escriba en otro idioma
- Respuestas directas y accionables. Sin relleno.
- Cuando la pregunta requiere decisión estratégica de Victor,
  respondes: "Esta decisión requiere validación de Victor.
  Mi recomendación técnica es X, pero el go/no-go es de él."
- Cuando la pregunta está cubierta por un playbook, lo citas explícitamente
- Criterio de calidad: si tu respuesta no ayuda a avanzar en las próximas 2 horas,
  no es una buena respuesta

LO QUE NO HACES
- No inventas información que no está en el vault
- No tomas decisiones de negocio o presupuesto
- No compartes información de un proyecto con usuarios que no tienen acceso a él
- No confirmas que algo "está bien" sin revisar el criterio de aceptación correspondiente

DOCUMENTOS DE REFERENCIA ACTIVOS
[Aquí se inyecta el contenido de los .md relevantes según la pregunta]
```

---

## 5. GUÍA DE IMPLEMENTACIÓN — 3 FASES

### FASE 1 — MVP Funcional (1-2 semanas)
*Objetivo: el equipo puede hablar con el Sherpa desde la app*

**Pasos:**

1. **Obtener API Key de Anthropic**
   - Crear cuenta en console.anthropic.com
   - Generar API Key
   - Guardar en variable de entorno segura del backend

2. **Crear endpoint backend `/sherpa/message`**
   ```
   POST /sherpa/message
   Body: { user_id, message, session_id (opcional) }
   Response: { reply, session_id, tokens_used }
   ```
   El endpoint:
   - Recibe el mensaje del usuario
   - Carga el system prompt base (desde archivo .md del vault)
   - Hace la llamada a Claude API (modelo: claude-sonnet-4-6)
   - Devuelve la respuesta

3. **Llamada básica a Claude API**
   ```javascript
   // Ejemplo Node.js con SDK oficial de Anthropic
   import Anthropic from "@anthropic-ai/sdk";

   const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

   const response = await client.messages.create({
     model: "claude-sonnet-4-6",
     max_tokens: 2048,
     system: systemPromptContent,  // string del .md de system prompt
     messages: [
       ...conversationHistory,     // historial previo
       { role: "user", content: userMessage }
     ]
   });
   ```

4. **Almacenar conversaciones**
   - Tabla/colección: `sherpa_sessions` — campos: `session_id, user_id, messages[], created_at, updated_at`
   - Al inicio de cada mensaje: cargar historial, añadir mensaje nuevo, llamar a API, guardar respuesta

5. **UI mínima: panel de chat**
   - Botón/sección "Sherpa" en la app
   - Input de texto + historial de mensajes
   - Identificador visual de quién responde (Sherpa vs usuario)

**Entregable de Fase 1:** cualquier miembro del equipo puede abrir el Sherpa, hacer una pregunta y recibir respuesta con contexto de EmpowerLabs.

---

### FASE 2 — Context Injection (2-3 semanas adicionales)
*Objetivo: el Sherpa responde con el vault, no solo con el system prompt*

**Pasos:**

1. **Indexar el vault**
   - Leer todos los `.md` del vault y crear un índice: `{ filename, title, tags, path, content }`
   - Dos estrategias (elegir según complejidad tolerada):
     - **Simple (recomendado para empezar):** búsqueda por keywords en metadata/tags de los .md
     - **Avanzado:** embeddings vectoriales (pgvector, Chroma, Pinecone) para búsqueda semántica

2. **Context Loader**
   - Al recibir una pregunta del usuario, el middleware identifica qué documentos del vault son relevantes
   - Estrategia simple: el usuario selecciona el proyecto activo → el sistema carga los .md de ese proyecto
   - Estrategia media: extraer palabras clave de la pregunta y buscar en el índice
   - Los documentos relevantes se inyectan en el system prompt antes de la llamada

3. **Gestión de tokens**
   - El contexto total (system prompt + vault docs + historial + pregunta) no puede superar ~180K tokens
   - Prioridad de inyección: 1) system prompt base, 2) doc del proyecto activo, 3) docs relacionados, 4) historial reciente

4. **Vista de administrador para Victor**
   - Panel donde Victor ve todas las sesiones del equipo
   - Filtro por usuario, por proyecto, por fecha
   - Indicador de preguntas que el Sherpa escaló a Victor

**Entregable de Fase 2:** el Sherpa responde citando los playbooks y documentos reales del vault. Las respuestas son contextualizadas a EmpowerLabs, no genéricas.

---

### FASE 3 — Sherpa Avanzado (mes 2-3)
*Objetivo: el Sherpa aprende, escala y se conecta al flujo del sprint*

**Posibles extensiones:**

- **Integración con Sprint Diario:** el Sherpa recibe el reporte de la mañana y genera automáticamente el análisis con semáforo (✅ / ⚠️ / 🔴)
- **Actualización dinámica del vault:** cuando Victor o el equipo actualiza un .md, el índice se regenera automáticamente (webhook o watcher de archivos)
- **Modo "Decisión para Victor":** cuando el Sherpa detecta una pregunta que requiere decisión estratégica, crea automáticamente una notificación/tarea para Victor con el contexto listo
- **Multi-idioma:** el Sherpa detecta el idioma del usuario y responde en el mismo
- **Historial de decisiones:** el Sherpa registra en el vault las decisiones validadas (una forma de memoria organizacional)
- **MCP Server propio:** exponer el vault como servidor MCP para que Claude Cowork también lo consuma nativamente

---

## 6. ESTIMADO DE COSTOS

| Componente | Costo | Notas |
|------------|-------|-------|
| Anthropic API | ~$15-50 USD/mes | Depende del volumen. claude-sonnet-4-6 = $3 input / $15 output por M tokens. 9 usuarios con uso moderado ≈ $20-30/mes |
| Infraestructura backend | $0 extra | Ya tienen servidor |
| Base de datos para historial | $0 extra | Ya tienen DB |
| Desarrollo Fase 1 | 8-16 horas | Si el backend ya existe y tiene auth, es integración directa |
| Desarrollo Fase 2 | 16-24 horas | Depende de estrategia de indexación |

**Comparación vs Opción 1 (Team Plan):** El Team Plan costaría $270/mes para 9 personas. La Opción 2 costaría ~$25-50/mes en API + tiempo de desarrollo inicial. El break-even es al mes 1 si el equipo ya tiene capacidad de desarrollo.

---

## 7. DECISIONES DE DISEÑO QUE VICTOR DEBE TOMAR

| # | Decisión | Opciones |
|---|----------|----------|
| D1 | ¿Quién puede acceder al Sherpa? | Todos / Solo leads / Por proyecto |
| D2 | ¿El Sherpa puede ver todos los proyectos del vault? | Sí todo / Solo proyectos donde el usuario tiene acceso |
| D3 | ¿Victor recibe notificación cuando el Sherpa escala algo? | Sí / No / Solo urgentes |
| D4 | ¿La estrategia de contexto es manual (usuario elige proyecto) o automática (RAG)? | Manual primero, luego RAG |
| D5 | ¿Qué modelo usar? | claude-sonnet-4-6 (recomendado: balance costo/calidad) |
| D6 | ¿El historial de conversaciones se guarda para siempre? | Definir retención (30/90/365 días) |

---

## 8. STACK RECOMENDADO (si aplica)

Si el equipo está evaluando qué usar:

- **Backend:** Node.js + Anthropic SDK oficial (`@anthropic-ai/sdk`) — es el más documentado y con más ejemplos
- **Alternativa Python:** `anthropic` SDK en Python — igual de completo
- **Base de datos historial:** PostgreSQL con tabla simple o SQLite para empezar
- **Indexación vault (Fase 2):** LlamaIndex (Python) o LangChain.js (Node) — simplifican mucho el RAG
- **UI chat:** componente de chat simple en React/Vue — no hace falta librería especializada

---

## RUNLOG

| Fecha | Evento |
|-------|--------|
| 2026-03-24 | Plan generado por Sherpa en sesión Cowork con Victor |