theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/optimizacion-costos-llm/SKILL.md

@@ -1,182 +0,0 @@
----
-name: optimizacion-costos-llm
-description: Patrones de optimización de costos para el uso de APIs de LLM — enrutamiento de modelos
-  según complejidad de la tarea, control de presupuesto, lógica de reintentos y caché de prompts.
----
-
-# Pipeline de LLM consciente de costos
-
-Patrones para controlar el costo de las APIs de LLM sin sacrificar calidad. Combina enrutamiento de modelos, seguimiento de presupuesto, lógica de reintentos y caché de prompts en un pipeline componible.
-
-## Cuándo activarla
-
-- Al construir aplicaciones que llaman a APIs de LLM.
-- Al procesar lotes de ítems con complejidad variable.
-- Cuando hay que mantenerse dentro de un presupuesto de gasto en API.
-- Al optimizar costo sin sacrificar calidad en las tareas complejas.
-
-## Conceptos clave
-
-### 1. Enrutamiento de modelos por complejidad de la tarea
-
-Selecciona automáticamente modelos más baratos para tareas simples y reserva los modelos caros para las complejas. Usa constantes o configuración para los identificadores de modelo — nunca los codifiques dispersos por el código.
-
-```python
-# Identificadores según el catálogo de modelos contratado (config, no hardcodeo).
-MODELO_AVANZADO = config.modelo_avanzado   # nivel frontier: tareas complejas
-MODELO_RAPIDO = config.modelo_rapido       # nivel rápido: 3-4x más barato
-
-_UMBRAL_TEXTO_AVANZADO = 10_000  # caracteres
-_UMBRAL_ITEMS_AVANZADO = 30      # ítems
-
-def seleccionar_modelo(
-    longitud_texto: int,
-    cantidad_items: int,
-    modelo_forzado: str | None = None,
-) -> str:
-    """Selecciona el modelo según la complejidad de la tarea."""
-    if modelo_forzado is not None:
-        return modelo_forzado
-    if longitud_texto >= _UMBRAL_TEXTO_AVANZADO or cantidad_items >= _UMBRAL_ITEMS_AVANZADO:
-        return MODELO_AVANZADO  # tarea compleja
-    return MODELO_RAPIDO  # tarea simple (3-4x más barata)
-```
-
-### 2. Seguimiento de costos inmutable
-
-Registra el gasto acumulado con dataclasses congeladas. Cada llamada a la API devuelve un tracker nuevo — nunca muta el estado.
-
-```python
-from dataclasses import dataclass
-
-@dataclass(frozen=True, slots=True)
-class RegistroCosto:
-    model: str
-    input_tokens: int
-    output_tokens: int
-    cost_usd: float
-
-@dataclass(frozen=True, slots=True)
-class CostTracker:
-    budget_limit: float = 1.00
-    records: tuple[RegistroCosto, ...] = ()
-
-    def add(self, record: RegistroCosto) -> "CostTracker":
-        """Devuelve un tracker nuevo con el registro añadido (nunca muta self)."""
-        return CostTracker(
-            budget_limit=self.budget_limit,
-            records=(*self.records, record),
-        )
-
-    @property
-    def total_cost(self) -> float:
-        return sum(r.cost_usd for r in self.records)
-
-    @property
-    def over_budget(self) -> bool:
-        return self.total_cost > self.budget_limit
-```
-
-### 3. Reintentos acotados
-
-Reintenta solo ante errores transitorios. Falla rápido ante errores de autenticación o de petición inválida.
-
-```python
-# Ajusta la tupla a las excepciones del SDK de tu proveedor:
-# errores de conexión, límite de tasa y errores 5xx del servidor.
-_ERRORES_REINTENTABLES = (APIConnectionError, RateLimitError, InternalServerError)
-_MAX_REINTENTOS = 3
-
-def llamar_con_reintento(func, *, max_reintentos: int = _MAX_REINTENTOS):
-    """Reintenta solo ante errores transitorios; falla rápido ante el resto."""
-    for intento in range(max_reintentos):
-        try:
-            return func()
-        except _ERRORES_REINTENTABLES:
-            if intento == max_reintentos - 1:
-                raise
-            time.sleep(2 ** intento)  # backoff exponencial
-    # Errores de autenticación, petición inválida, etc. → propagar de inmediato
-```
-
-### 4. Caché de prompts
-
-Cachea los prompts de sistema largos para no reenviarlos en cada petición. La sintaxis exacta depende del proveedor; muchos aceptan marcar bloques cacheables en el mensaje:
-
-```python
-messages = [
-    {
-        "role": "user",
-        "content": [
-            {
-                "type": "text",
-                "text": system_prompt,
-                "cache_control": {"type": "ephemeral"},  # cachear este bloque
-            },
-            {
-                "type": "text",
-                "text": user_input,  # la parte variable
-            },
-        ],
-    }
-]
-```
-
-## Composición
-
-Combina las cuatro técnicas en una sola función de pipeline:
-
-```python
-def procesar(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
-    # 1. Enrutar modelo
-    model = seleccionar_modelo(len(text), items_estimados, config.modelo_forzado)
-
-    # 2. Verificar presupuesto
-    if tracker.over_budget:
-        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
-
-    # 3. Llamar con reintentos + caché
-    response = llamar_con_reintento(lambda: client.messages.create(
-        model=model,
-        messages=construir_mensajes_cacheados(system_prompt, text),
-    ))
-
-    # 4. Registrar costo (inmutable)
-    record = RegistroCosto(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
-    tracker = tracker.add(record)
-
-    return parsear_resultado(response), tracker
-```
-
-## Referencia de precios por nivel
-
-Los precios absolutos cambian con frecuencia — consulta siempre la tarifa vigente del proveedor o del catálogo de modelos contratado. Lo estable es la relación entre niveles:
-
-| Nivel de modelo | Uso típico | Costo relativo |
-|-----------------|------------|----------------|
-| Rápido | Clasificación, extracción, tareas simples en lote | 1x |
-| Equilibrado | Redacción, análisis, la mayoría de tareas | ~4x |
-| Frontier | Razonamiento complejo, tareas críticas | ~15-20x |
-
-## Buenas prácticas
-
-- **Empieza con el modelo más barato** y enruta al caro solo cuando se cumplan los umbrales de complejidad.
-- **Define límites de presupuesto explícitos** antes de procesar lotes — falla temprano en vez de sobregastar.
-- **Registra las decisiones de selección de modelo** para calibrar los umbrales con datos reales.
-- **Usa caché de prompts** para prompts de sistema de más de ~1024 tokens — ahorra costo y latencia.
-- **Nunca reintentes ante errores de autenticación o validación** — solo fallos transitorios (red, límite de tasa, error de servidor).
-
-## Antipatrones a evitar
-
-- Usar el modelo más caro para todas las peticiones sin importar la complejidad.
-- Reintentar ante todos los errores (desperdicia presupuesto en fallos permanentes).
-- Mutar el estado del seguimiento de costos (dificulta la depuración y la auditoría).
-- Codificar nombres de modelo dispersos por el código (usa constantes o configuración).
-- Ignorar el caché de prompts cuando los prompts de sistema son repetitivos.
-
-## Cuándo usarla
-
-- Cualquier aplicación que llame a APIs de LLM.
-- Pipelines de procesamiento por lotes donde el costo se acumula rápido.
-- Arquitecturas multimodelo que necesitan enrutamiento inteligente.
-- Sistemas en producción que necesitan barandillas de presupuesto.

package/vendor/theus-arsenal/skills/optimizador-conexiones/SKILL.md

@@ -1,191 +0,0 @@
----
-name: optimizador-conexiones
-description: Reorganiza la red del usuario en X y LinkedIn con poda revisada primero, recomendaciones
-  de seguimiento y borradores de contacto cálido por canal escritos con la voz real del usuario.
-  Úsala para limpiar listas de seguidos, crecer hacia las prioridades actuales o reequilibrar
-  un grafo social alrededor de relaciones de mayor señal.
----
-
-# Optimizador de conexiones
-
-Reorganiza la red del usuario en lugar de tratar el contacto saliente como una lista de prospección de un solo sentido.
-
-Esta skill cubre:
-
-- Limpieza y expansión de la lista de seguidos en X
-- Análisis de seguimientos y conexiones en LinkedIn
-- Colas de poda con revisión previa obligatoria
-- Recomendaciones de a quién añadir o seguir
-- Identificación de rutas cálidas (warm paths)
-- Generación de borradores para correo (Apple Mail), DM de X y mensajes de LinkedIn con la voz real del usuario
-
-## Cuándo activarla
-
-- El usuario quiere podar a quién sigue en X
-- El usuario quiere reequilibrar a quién sigue o con quién mantiene conexión
-- El usuario dice "limpia mi red", "¿a quién debería dejar de seguir?", "¿a quién debería seguir?", "¿con quién debería reconectar?"
-- La calidad del contacto saliente depende de la estructura de la red, no solo de generar listas frías
-
-## Entradas requeridas
-
-Recopila o infiere:
-
-- Prioridades actuales y trabajo activo
-- Roles, industrias, geografías o ecosistemas objetivo
-- Selección de plataforma: X, LinkedIn o ambas
-- Lista de intocables (do-not-touch)
-- Modo: `pasada-ligera`, `estandar` o `agresivo`
-
-Si el usuario no especifica modo, usa `estandar`.
-
-## Requisitos de herramientas
-
-### Preferidas
-
-- `api-x` para inspeccionar el grafo de X y la actividad reciente
-- `inteligencia-leads` para el descubrimiento de objetivos y el ranking de rutas cálidas
-- `ranking-grafo-social` cuando el usuario quiere puntuar el valor de puente de forma independiente del flujo de leads
-- `busqueda-exa` o `investigacion-profunda` para enriquecer datos de personas y empresas
-- `voz-de-marca` antes de redactar cualquier contacto saliente
-
-### Alternativas
-
-- Control del navegador para el análisis y la redacción en LinkedIn
-- Control del navegador para X si la cobertura de la API es limitada
-- Borradores en Apple Mail / Mail.app vía automatización de escritorio (solo macOS) cuando el correo es el canal correcto
-
-## Salvaguardas por defecto
-
-- El comportamiento por defecto es revisión primero; nunca poda automática a ciegas
-- X: poda solo cuentas que el usuario sigue, nunca seguidores
-- LinkedIn: la eliminación de conexiones de 1.er grado siempre pasa por revisión manual primero
-- No envíes automáticamente DMs, invitaciones ni correos
-- Emite un plan de acción priorizado y los borradores antes de cualquier paso de aplicación
-
-## Reglas por plataforma
-
-### X
-
-- Los mutuos son más valiosos que los seguimientos de un solo sentido
-- Las cuentas que no devuelven el seguimiento pueden podarse con más agresividad
-- Las cuentas muy inactivas o desaparecidas deben aflorar rápido
-- El engagement, la calidad de la señal y el valor de puente pesan más que el número bruto de seguidores
-
-### LinkedIn
-
-- API primero solo si el usuario realmente tiene acceso a la API de LinkedIn
-- El flujo por navegador debe funcionar cuando no hay acceso a la API
-- Distingue seguimientos salientes de conexiones de 1.er grado aceptadas
-- Los seguimientos salientes pueden podarse con más libertad
-- Las conexiones de 1.er grado aceptadas van por defecto a revisión, nunca a eliminación automática
-
-## Modos
-
-### `pasada-ligera`
-
-- Poda solo seguimientos de un solo sentido de bajo valor y alta confianza
-- El resto aflora para revisión
-- Genera una lista pequeña de cuentas a añadir/seguir
-
-### `estandar`
-
-- Cola de poda equilibrada
-- Lista de conservación equilibrada
-- Cola priorizada de cuentas a añadir/seguir
-- Redacta introducciones cálidas o contacto directo donde aporte
-
-### `agresivo`
-
-- Cola de poda más grande
-- Menor tolerancia a seguimientos estancados sin reciprocidad
-- Sigue exigiendo revisión antes de aplicar
-
-## Modelo de puntuación
-
-Señales positivas:
-
-- Reciprocidad
-- Actividad reciente
-- Alineación con las prioridades actuales
-- Valor de puente en la red
-- Relevancia del rol
-- Historial real de engagement
-- Presencia y capacidad de respuesta recientes
-
-Señales negativas:
-
-- Cuenta desaparecida o abandonada
-- Seguimiento de un solo sentido estancado
-- Clúster temático fuera de las prioridades
-- Ruido de bajo valor
-- Falta de respuesta repetida
-- Sin seguimiento de vuelta cuando existen muchos reemplazos mejores
-
-Los mutuos y los puentes cálidos reales deben penalizarse con menos agresividad que los seguimientos de un solo sentido.
-
-## Flujo de trabajo
-
-1. Captura prioridades, restricciones de intocables y plataformas seleccionadas.
-2. Extrae el inventario actual de seguidos / conexiones.
-3. Puntúa las candidatas a poda con razones explícitas.
-4. Puntúa las candidatas a conservar con razones explícitas.
-5. Usa `inteligencia-leads` más las superficies de investigación para priorizar candidatas de expansión.
-6. Asigna el canal adecuado:
-   - DM de X para toques sociales cálidos y rápidos
-   - Mensaje de LinkedIn para adyacencia en el grafo profesional
-   - Borrador de Apple Mail para introducciones o contactos de mayor contexto
-7. Ejecuta `voz-de-marca` antes de redactar mensajes.
-8. Devuelve un paquete de revisión antes de cualquier paso de aplicación.
-
-## Formato del paquete de revisión
-
-```text
-INFORME DEL OPTIMIZADOR DE CONEXIONES
-=====================================
-
-Modo:
-Plataformas:
-Conjunto de prioridades:
-
-Cola de poda
-- usuario / perfil
-  razón:
-  confianza:
-  acción:
-
-Cola de revisión
-- usuario / perfil
-  razón:
-  riesgo:
-
-Conservar / proteger
-- usuario / perfil
-  valor de puente:
-
-Objetivos a añadir / seguir
-- persona
-  por qué ahora:
-  ruta cálida:
-  canal preferido:
-
-Borradores
-- DM de X:
-- LinkedIn:
-- Apple Mail:
-```
-
-## Reglas de contacto saliente
-
-- La ruta de correo por defecto es la creación de borradores en Apple Mail / Mail.app.
-- No envíes nada automáticamente.
-- Elige el canal según la calidez, la relevancia y la profundidad de contexto.
-- No fuerces un DM cuando un correo — o no contactar — es la jugada correcta.
-- Los borradores deben sonar al usuario, no a copy de ventas automatizado.
-
-## Skills relacionadas
-
-- `voz-de-marca` para el perfil de voz reutilizable
-- `ranking-grafo-social` para la puntuación de puentes y la matemática de rutas cálidas de forma independiente
-- `inteligencia-leads` para el descubrimiento ponderado de objetivos y rutas cálidas
-- `api-x` para el acceso al grafo de X, la redacción y los flujos de aplicación opcionales
-- `motor-de-contenido` cuando el usuario también quiere contenido público de lanzamiento alrededor de los movimientos de red

package/vendor/theus-arsenal/skills/optimizador-paralelismo/SKILL.md

@@ -1,75 +0,0 @@
----
-name: optimizador-paralelismo
-description: Úsala cuando el usuario quiera terminar una tarea mucho más rápido mediante trabajo en paralelo, agentes concurrentes, llamadas a herramientas en lote, worktrees aislados o muchos carriles de verificación independientes sin perder corrección.
-tools: Read, Write, Edit, Bash, Grep, Glob
----
-
-# Optimizador de ejecución paralela
-
-Usa esta skill cuando la velocidad venga de hacer trabajo independiente al mismo
-tiempo: inspección del repositorio, lecturas de archivos, verificaciones de API,
-comprobaciones en el navegador, carriles de build/test, lecturas de verificación
-tras un deploy o pasadas de implementación en múltiples worktrees.
-
-## Patrón central
-
-Convierte la urgencia en un grafo de dependencias antes de actuar.
-
-1. Define el objetivo y la señal de "terminado".
-2. Divide el trabajo en carriles.
-3. Marca cada carril como paralelo, secuencial o condicionado (gated).
-4. Ejecuta juntas las lecturas/verificaciones independientes.
-5. Mantén las escrituras aisladas por archivo, worktree, branch, servicio o dataset.
-6. Fusiona solo cuando la evidencia demuestre que los carriles son compatibles.
-7. Termina con una tabla de verificación, no con una afirmación vaga de velocidad.
-
-## Matriz de carriles
-
-Antes de un empujón grande, escribe una matriz compacta:
-
-```text
-Carril | ¿Puede ir en paralelo? | Superficie de escritura | Riesgo | Verificación
-Escaneo del repo | sí | ninguna | bajo | salidas de rg/git status
-Parche de backend | quizá | src/api | medio | tests unitarios
-Parche de frontend | quizá | app/components | medio | captura del navegador
-Lectura post-deploy | tras el build | servicio remoto | alto | URL en vivo + logs
-```
-
-Ejecuta carriles en paralelo solo cuando sus superficies de escritura no
-colisionen.
-
-## Reglas de ejecución
-
-- Agrupa en lote lecturas de archivos, búsquedas, verificaciones de estado y
-  consultas de metadatos.
-- Usa worktrees aislados para carriles de implementación grandes y no
-  relacionados.
-- Lanza tests, builds, backfills y deploys de larga duración en sesiones
-  separadas, y luego sondéalos deliberadamente.
-- Si un carril descubre un bloqueador que cambia el plan, pausa los carriles
-  dependientes y actualiza la matriz.
-- Nunca dejes que un proceso en segundo plano sobreviva al turno salvo que el
-  usuario haya pedido explícitamente un servicio continuo.
-- No paralelices comandos destructivos, migraciones, escrituras a la misma tabla
-  ni deploys en vivo con impacto en clientes sin una compuerta explícita.
-
-## Forma de la salida
-
-Usa esto al reportar:
-
-```text
-Resultado de ejecución paralela:
-- Carriles ejecutados: 5
-- Carriles completados: 4
-- Carril bloqueado: lectura post-deploy, esperando propagación de DNS
-- Ruta rápida encontrada: escaneo del repo en lote + tests enfocados
-- Verificación: lint OK, unitarios OK, smoke en vivo OK
-```
-
-## Modos de fallo
-
-- Más concurrencia que genera ediciones en conflicto.
-- Medir la herramienta en vez de la tarea.
-- Tratar "rápido" como terminado antes de probar la corrección.
-- Olvidar sondear las sesiones en ejecución.
-- Ocultar verificaciones omitidas detrás de un resumen de éxito.