stars-explorer

name	stars-explorer
version	1.0.0
description	Pipeline nocturno que explora las stars de GitHub de David, analiza repos, extrae patrones y crea skills automáticamente. Cada run procesa un batch de repos, genera análisis profundo, y propone skills basados en los patrones detectados.
tags	["github","stars","skills","pipeline","cron","exploration","learning"]
related_skills	["chromadb-skills-vector-search","github-trending-research"]

Stars Explorer — Pipeline de Aprendizaje Automático

Resumen

Pipeline recurrente que explora las ~100+ stars de GitHub de David (Ntizar), analiza los repos más interesantes, extrae patrones arquitectónicos y crea skills automáticamente en el sistema Mastermind/Hermes.

Objetivo: Cada noche, el sistema aprende de los repos que David le gusta, ampliando la base de conocimiento de skills de forma autónoma.

Arquitectura

Cron (nocturno 03:00 UTC)
  ↓
Script explorar-stars.py (batch de 3 repos)
  ↓ Fetch GitHub API → README + tree + key files
  ↓ Análisis: tech stack, patterns, skill angles
  ↓ Actualiza stars-registry.json
  ↓
Agent processa el output del script
  ↓ Para cada repo: decide si merece skill
  ↓ Crea skill con skill_manage si es relevante
  ↓ Actualiza registry (category, skill_created)
  ↓
Re-indexa ChromaDB (si hubo cambios)
  ↓
Guarda resumen en notes/ si hubo hallazgos significativos

Componentes

Script principal

• Ruta: /hermes-home/scripts/explorar-stars.py
• Wrapper: bash /hermes-home/scripts/run-stars-explorer.sh (carga entorno automáticamente)
• Dependencias: Solo stdlib (urllib, json, base64) — NO necesita pip install
• Entorno: Wrapper carga variables de entorno del sistema automáticamente

Registry

• Ruta: /hermes-home/data/stars-registry.json
• Contenido: Repo → fecha explorada, category, skill_created, skill_angles

Skill de referencia

• chromadb-skills-vector-search — Para re-indexar después de crear skills

Uso del Script

Usar SIEMPRE el wrapper que carga el entorno automáticamente:

# Status del registry
bash /hermes-home/scripts/run-stars-explorer.sh --status

# Batch de 3 repos (default) — solo repos >100 stars con topics
bash /hermes-home/scripts/run-stars-explorer.sh

# Batch grande
bash /hermes-home/scripts/run-stars-explorer.sh --batch 5

# Todos los pendientes (SIN FILTRO — explora todos)
bash /hermes-home/scripts/run-stars-explorer.sh --all

# Modo JSON (para agent consumption)
bash /hermes-home/scripts/run-stars-explorer.sh --batch 2 --json

# Incluir propios repos de David
bash /hermes-home/scripts/run-stars-explorer.sh --include-own

# Forzar re-proceso de un repo
bash /hermes-home/scripts/run-stars-explorer.sh --reprocess owner/repo

# Modo LOOP DE APRENDIZAJE — modo completo: explora → aprende → mejora → implementa
bash /hermes-home/scripts/run-stars-explorer.sh --learning-loop

Flujo del Agent (en el cron)

Al recibir el output del script, el agent debe:

1. Leer cada repo analizado del JSON
2. Evaluar si merece skill basándose en:
   • ¿Tiene patrones reutilizables? (architecture, pipeline, performance)
   • ¿Es relevante para los proyectos de David? (3D, CV, geospatial, CRM, transit)
   • ¿Aporta conocimiento que NO tenemos ya?
   • ¿Tiene enough profundidad para justificar un skill?
3. Crear skill con skill_manage(action='create') si:
   • El repo tiene patrones claros y reutilizables
   • El skill serait útil en futuras tareas
   • No duplica un skill existente (check ChromaDB primero)
4. Marcar en registry como skill_created: true + categoría
5. Re-indexar ChromaDB al final si se crearon skills

Criterios de Creación de Skill

Crear skill si:

• Repo tiene patrones arquitectónicos reutilizables (3+ patterns detectados)
• Tech stack relevante para proyectos existentes de David
• El README describe approach único o innovador
• Tiene +1000 stars (indica calidad/comunidad)
• El repo es de David (siempre crear, es su conocimiento)

NO crear skill si:

• Solo tiene README genérico sin patrones concretos
• Es un "awesome list" o curated list sin código
• Ya existe un skill cubriendo lo mismo
• El repo está archivado o sin maintenimiento
• Es demasiado simple (<100 stars, sin code patterns)

Categorías para el registry:

• core — Skills que son parte fundamental del sistema
• domain — Conocimiento de dominio específico (CV, GIS, transit)
• pattern — Patrones arquitectónicos reutilizables
• tool — Herramientas y librerías concretas
• reference — Referencia/inspiración (no skill directo)
• skip — Decidido no procesar (awesome list, etc.)

Datos del Script Output

Cada repo analizado incluye:

{
  "full_name": "owner/repo",
  "description": "...",
  "language": "Python",
  "stars": 1234,
  "topics": ["topic1", "topic2"],
  "tech_stack": ["django", "postgres", "..."],
  "potential_patterns": ["pipeline", "real-time", "ai/ml"],
  "skill_angles": ["ai-cv-pipeline"],
  "readme_excerpt": "primeros 2000 chars del README",
  "key_files_present": ["package.json", "Dockerfile"],
  "file_types": {".py": 15, ".js": 8}
}

Pitfalls

• Rate limit GitHub: 5000 req/h autenticados. Batch de 3 repos ≈ 20 req cada uno = 60/batch. Safe.
• README enorme: Truncado a 8000 chars. Suficiente para análisis.
• Skills duplicados: SIEMPRE consultar ChromaDB antes de crear. Si un skill semánticamente similar existe, NO crear otro. Verificado en producción: manim→skip (score 0.85 contra creative/manim-video), twenty→skip (score 0.79 contra crm-erp-fullstack), VibeVoice→skip (score 0.89 contra media/voicebox).
• Quality gate: No crear skills de "awesome lists" o repos sin código sustancial.
• Re-indexación ChromaDB: Obligatoria tras crear skills. Sin ella, los nuevos skills son invisibles en búsquedas semánticas.
• Registry creep: Si un repo no merece skill, marcar con category: "skip" y skill_created: false. NO re-procesarlo cada run.
• Cron security scanner (CRÍTICO 2026-06-16): El scanner de cron bloquea prompts que contienen patrones como cat .env, cat credentials, etc. (regex: cat\s+[^\n]*(\.env|credentials|\.netrc|\.pgpass)). Solución: usar wrapper script (run-stars-explorer.sh) que carga el entorno internamente. NUNCA poner comandos que lean secrets directamente en prompts de cron ni en skills que se carguen en crons. El scanner escanea el prompt ensamblado (user prompt + skill content concatenado).
• ChromaDB dedup funciona en producción (2026-06-16): El pipeline detectó correctamente 3 repos como "ya cubiertos" en el primer batch nocturno. Scores: manim=0.85, twenty=0.79, VibeVoice=0.89. Threshold 0.25 es suficiente para detectar duplicados semánticos.
• Wrapper script obligatorio para cron: El script explorar-stars.py necesita variables de entorno (token de GitHub, API key de NaN). En vez de exponer el patrón de lectura en el prompt del cron, usar bash /hermes-home/scripts/run-stars-explorer.sh que hace source del .env internamente.
• Skill overlap con github-trending-research: github-trending-research explora trending público; stars-explorer explora las stars personales de David. Complementarios, no duplicados. Comparten patrones de GitHub API, creación de skills, y dedup via ChromaDB.

Loop de Aprendizaje Continuo

El sistema no es solo explorador — es un motor de aprendizaje que cada noche:

Diagrama del Loop

🌙 Cron (03:00 UTC)
   ↓
🔍 Explorar 3 stars nuevos
   ↓
📖 Analizar README + tree + key files
   ↓
🧠 ¿Merece skill? (ChromaDB dedup)
   ↓
   ├── ✅ Sí → Crear skill → Indexar en ChromaDB
   └── ❌ No → Marcar como skip (razón)
   ↓
📈 Registrar en stars-registry.json
   ↓
🎯 ¿Patrón relevante para proyecto activo?
   ↓
   ├── Sí → Micro-cron de seguimiento semanal
   └── No → Esperar próxima noche
   ↓
🔄 Loop infinito → Cada noche 3 skills nuevos

Fases del ciclo

Fase	Descripción	Responsable
🔍 Explorar	Fetch 3 repos no procesados	Script explorar-stars.py
📖 Aprender	Analizar tech stack + patrones	Agent (con stars-explorer skill)
✨ Mejorar	¿El patrón es nuevo? → skill	Agent + ChromaDB
🛠️ Implementar	Crear skill + indexar	skill_manage + indexar-skills.py
📊 Registrar	Actualizar registry	Script guarda en JSON
👁️ Watch	Micro-cron semanal si repo >500⭐	cronjob

Criterio Avanzado de Creación de Skill

Matriz de decisión: (stars × topic_count × pattern_diversity) / existing_skill_overlap

def should_create_skill(repo):
    score = repo['stars'] * (1 + 0.1*len(repo['topics'])) * (1 + 0.2*len(repo['potential_patterns']))
    # Penalizar si ya hay skill similar
    chroma_score = chromadb_search(repo['description'])
    if chroma_score > 0.25: return False
    return score > 500  # Threshold mínimo

Micro-crons de Seguimiento

Cuando un repo >500⭐ tiene patrones relevantes para un proyecto activo:

# Automatizado por el cron
cronjob(action='create', 
  name=f'watch-{repo_basename}',
  schedule='0 0 * * 1',  # Cada lunes
  prompt=f"Revisar nuevas releases/issues de {owner}/{repo}")

Estos micro-crons se auto-destruyen tras 4 semanas si no generan ningún skill → skill_created: false en registry tras 4 ciclos sin actividad.

---

Bulk Processing — Modo "Hazlo Rápido" 🚀

Cuando el usuario pide procesar TODAS las stars de una vez (no esperar al cron):

Pipeline completo (1 hora para ~117 repos)

Fase 1: Registrar todas → Fase 2: Clasificar → Fase 3: Analizar en lote
→ Fase 4: Crear skills → Fase 5: Indexar ChromaDB → Fase 6: GitHub push

Fase 1 — Registrar masivamente

No usar --all (timeout 300s). Hacer fetch de todas las stars paginadas + repo info básica (sin README) en batch:

# Fetch de todas las stars
curl -s "https://api.github.com/users/Ntizar/starred?per_page=100&page=1" -H "Authorization: token $GITHUB_TOKEN"

# Registrar cada repo en el registry como "pending" con stars_count + language
# 1 llamada API por repo (GET /repos/{owner}/{repo})
# ~30 segundos para 50 repos

Fase 2 — Clasificar en 4 tiers

tiers = {
    "high":   stars >= 3000,          # → subagent prioritario
    "medium": 500 <= stars < 3000,    # → subagent si hay slots
    "low":    stars < 500,            # → cron (no urgente)
    "skip":   "awesome" in name.lower() or "clone-wars" in name.lower(),
           or "collection" in name.lower(),  # → marcar y olvidar
}

También detectar ALREADY_COVERED por nombre: si el repo coincide con un skill existente (voicebox→media/voicebox, mlx-vlm→mlx-vlm-inference, nango→nango, city2graph→geoai-city2graph-pattern, postgres-mcp→postgres-mcp, gaze-tracking→gaze-tracking, supervision→vision/roboflow-supervision, etc.)

Fase 3 — Análisis en lote con subagentes paralelos

# 3 subagentes × 6-8 repos cada uno
delegate_task(tasks=[
  {"goal": "Analizar 6 repos y decidir skills (CREATE/SKIP/COVERED)", 
   "context": "REPOS: [lista de 6...]", "toolsets": ["terminal", "file"]},
  ...  # hasta 3 tasks en paralelo
])

# Cada subagente: fetch README → check existing skills → decidir CREATE/SKIP/COVERED
# Output: JSON con decisión por repo

IMPORTANTE: Cada subagente recibe una lista explícita de "ya cubiertos" para que no investigue skills existentes desde cero. Pasar en context:

context = f"""
Ya existen skills para: voicebox (media/voicebox), mlx-vlm (mlx-vlm-inference),
nango (nango), city2graph (geoai-city2graph-pattern), postgres-mcp (postgres-mcp),
gaze-tracking (gaze-tracking), supervision (vision/roboflow-supervision),
crm-erp-fullstack (mastermind/), etc.
Repo high-value para analizar: {repo_list}
"""

Fase 4 — Crear skills

Para cada repo con CREATE_SKILL:

# 1. Fetch README completo (o leer del JSON ya guardado)
# 2. skill_manage(action='create', name=..., category=..., content=SKILL.md)
# 3. skill_manage(action='patch', name='stars-explorer', ...) # NO — marcar en registry

La creación debe ser rápida: SKILL.md conciso pero útil, con:

• YAML frontmatter (name, version, description, tags)
• Resumen del repo
• Instalación y uso básico
• Integración con Mastermind
• Referencia al repo original

Fase 5 — Indexar en ChromaDB

bash /hermes-home/scripts/start-chromadb.sh   # Si no está running
python3 /hermes-home/scripts/indexar-skills.py  # Re-indexa todo

Fase 6 — Subir a GitHub (OBLIGATORIO)

Todos los skills deben estar en el repo Mastermind de GitHub. David es explícito: "recuerda que estén en el github de mastermind también".

# Copiar skills al repo
cp -r /hermes-home/skills/<category>/<skill-name> /root/workspace/Mastermind/skills/<category>/
cp /hermes-home/data/stars-registry.json /root/workspace/Mastermind/data/
cp /hermes-home/scripts/explorar-stars.py /root/workspace/Mastermind/scripts/
cp /hermes-home/scripts/run-stars-explorer.sh /root/workspace/Mastermind/scripts/

# Commit + push
cd /root/workspace/Mastermind
git add -A
git commit -m "✨ Stars Explorer: <N> skills nuevos de stars de David"
git push

Resumen de tiempos (117 repos)

Fase	Tiempo
Registrar 117 repos	~40s
Clasificar	~2s
3 subagentes × 6 repos (paralelo)	~3-5 min
Crear 8 skills	~3 min
Indexar ChromaDB	~1 min
GitHub push	~30s
Total	~10 min

Lecciones aprendidas (próxima vez)

• El --all del script timeout a 300s → mejor registrar manualmente con paginación
• Los subagentes de delegate_task necesitan context explícito sobre qué skills ya existen (evita que investiguen desde cero)
• Los repos "awesome-*", "Clone-Wars" etc. se SKIP automáticamente
• Los skills deben estar en /hermes-home/skills/ (el sistema Hermes) Y en /root/workspace/Mastermind/skills/ (GitHub)

Cron Asociado

• Nombre: stars-explorer-nocturno
• Schedule: 0 3 * * * (03:00 UTC diario)
• Job ID: f22516e4ab77
• Batch: 3 repos/run → 3 por noche