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.

• Edición programática del registry (maratón 2026-09-01): El registry está en CRLF con indent=2; al reescribirlo con Python leer/escribir con newline="" y normalizar saltos con json.dumps(...).replace("\n","\r\n") — un json.dump a secas reescribe todo el fichero a LF y genera un diff de 500+ líneas que ensucia el commit. NO inyectar claves nuevas (tipo full_name con setdefault). Y NO hacer git checkout -- data/stars-registry.json después de ejecutar el script: revierte las entradas explored que el script ya escribió y obliga a re-pasar el batch (el re-paso es inocuo porque las marcas skip se re-aplican, pero gasta ~1 min de API).

• Indexador YA ve cambios de contenido (arreglado 2026-09-02, verificado 2026-09-03): scripts/indexar-skills.py compara por hash sha256 del contenido, no solo por ID — un skill parcheado se re-indexa solo (batch del 03:03: "1 modificado → indexados 1/1" automático). El upsert manual vía importlib ya NO es necesario. Ejecutar directo con el Python del sistema: C:/Users/d_ant/AppData/Local/Programs/Python/Python312/python.exe scripts/indexar-skills.py (el wrapper run-indexar-skills.sh invoca python3, que en Windows es el stub del Store → salida vacía engañosa).

• skill_angles del script NO es fiable (batch 2026-09-06): los heurísticos por topics fallan en repos multi-dominio — dio obra/superpowers → "crm-erp-patterns" y Graphify-Labs/graphify → "voice-ai-integration", ambos absurdos. NUNCA decidir el ángulo del skill desde ese campo: leer siempre el README real (gh api repos/{o}/{r}/readme | base64 -d) antes de crear/patchear.

• Repos RENOMBRADOS evaden el dedup por nombre (2026-09-07): carnot-tech/consulting-pptx-skill apareció como repo nuevo aunque el skill existía de gozen3ji/consulting-pptx-skill — gh api confirmó que es el mismo repo transferido (el API redirige y devuelve el nuevo nombre). Antes de crear un skill, dedup SEMÁNTICO con ChromaDB (consultar-skills.py), no solo por nombre: el dedup por contenido lo cazó (0.84). Si es el mismo repo renombrado → skill_manage(patch) upgrade + nota en el registry, no skill duplicado.

• Registry: entradas bajo reg["processed"], no en raíz: desde 2026-09 las claves repo→entry viven en el subdict processed (algunas entradas antiguas quedaron en raíz — comprobar antes de indexar por clave).

• Sincronización skills→repo es MANUAL (verificado 2026-09-04): skill_manage(create/patch) escribe SOLO en %LOCALAPPDATA%\hermes\skills\...; para que aparezcan en GitHub hay que copiar el SKILL.md a agent/skills/<categoria>/<skill>/ del repo antes del commit. OJO: los skills antiguos del maratón viven en la raíz agent/skills/<skill>/ (sin categoría) — conservar su ubicación original al actualizarlos, no moverlos.

• Formato frontmatter de skills nuevos (2026-09): el validador exige description ≤60 chars (trigger primero, en castellano, punto final) y advierte si faltan author, license y metadata.hermes.{tags,related_skills} — incluirlos ya en el create.

• Auditoría quantstats-pro completada (2026-09-04): de la lista pendiente (gtfs-tidy, gtfs2shp, colmap-view, quantstats-pro), queda auditado y reescrito quantstats-pro → v2.0.0. Pendientes de auditoría v1: CERRADOS el 2026-09-04 — gtfs-tidy reauditado → v2.0.0 (CLI inventado --input/--validate/--info reemplazado por flags reales verificados en gtfstidy.go: -v, -o, shorthands --fix/--compress/--Compress/--merge, tabla de procesadores, orden interno fijo, --keep-*). Registry patrickbr/gtfstidy skip→upgrade. gtfs2shp y colmap-view ya estaban v2 (09-03 y 09-01).

• Auditoría gtfs-box completada (2026-09-04, batch vespertino): v1 tenía CLI/npm inventados → reescrito mobility/gtfs-box v2.0.0 verificado contra gtfs-box.js (web estática sobre mt3d/Mini Tokyo 3D, sin build). geospatial/gtfs-box-3d-viewer marcado SUPERADO con banner. Lección: git clone NO — basta curl de 2-3 ficheros clave del tree para verificar la API real de un repo pequeño antes de auditar.

• Auditoría agresiva de v1 (2026-09-05, 12 skills × 3 subagentes en paralelo): el problema de v1 fabricados es PEOR de lo que se creía — no eran solo "bullets genéricos": había APIs REST inventadas (baidu-unlimited-ocr decía ser un "servicio de OCR gratis sin límites" con endpoint api.unlimitedocr.com cuando es un modelo de parsing con HuggingFace/GPU), comandos falsos (pip install chatterbox→chatterbox-tts; pip install PDFMathTranslate→pdf2zh; python infer.py→webui.py; build cmake→autotools), imports inexistentes (from index_tts import TTS→indextts.IndexTTS2; f5_tts.infer.api.synthesize→f5_tts.api.F5TTS), claim falsos (RVC "zero-shot sin fine-tuning" cuando es training-based; OpenVoice "+no GPU"; Valhalla imagen docker mapbox→valhalla y payload mode/range→costing/contours; autoscraper run()→get_result_similar). Resultado: 10/12 NEEDS_PATCH → todos reescritos a v2.0.0 (los 2 OK: mapcn, semantica). Lección: NO auditear solo los flaggeados — barrer el registry completo con subagentes (cada uno verifica 4-6 skills contra su README real via gh api/raw.githubusercontent.com, devuelve JSON NEEDS_PATCH con discrepancias; el orquestador parchea). Al auditar, marcar category upgrade + skill_version + skill_audited en el registry.

• Auditoría COMPLETA de todo el registry (2026-09-05, 120 skills en 6 oleadas): se auditó el 100% de los skills derivados de stars. Resultado: ~56 skills con errores corregidos a v2.0.0 (el resto OK o DESIGNED = patrón manuscrito sin repo que verificar). El problema de "v1 inventados" era GENERAL, no puntual: APIs REST/CLIs/imports/estrellas inventadas en casi todas las categorías (TTS, OCR, scraping, GIS, visión, 3D, transporte). PITFALL CRÍTICO de concurrencia — delegación con subagentes: NO lanzar ≤10 subagentes a la vez. NaN limita a max 5 requests LLM simultáneos (HTTP 429: <modelo> concurrency limit: max 5) → con 10 auditoros, ~5 se truncaron por max_iterations. Regla: lanzar ≤4 subagentes por oleada (o ≤5 justo). Manifiesto compartido (data/...: array JSON con repo, url, skill, skill_path) + cada subagente lee su rango de filas [start,end) y devuelve JSON {auditoria:[{skill,veredicto,repo_real,discrepancias[],fix_sugerido,stars_reales,lenguaje}]}; el ORQUESTADOR aplica los patches (los subagentes solo investigan — no pueden skill_manage). Auditar por skill (dedupe por skill_path), no por repo (varios repos apuntan al mismo skill y mapeos del registry pueden ser erróneos: el skill manda).

• execute_code bloqueado en cron: en modo cron programático solo hay terminal; para lógica Python de edición de registry escribir un script temporal en %LOCALAPPDATA%\Temp y ejecutarlo con python. El parser de terminal TAMBIÉN bloquea heredocs python - <<EOF y python -c multilínea — siempre script temporal + python <ruta>.

• Skills-v1 inventados del maratón 2026-06-18/19 (detectado 2026-09-02): varios skills creados en batch masivo describían el repo SIN leer el README (bullets genéricos, CDN inventado, función equivocada: minimaps→"librería de minimapas" cuando es generador de relieves 3D puck; gtfs-to-chart→"frecuencias" cuando son stringlines/Marey). Cuando el scout re-encuentra un repo ya procesado, NO hacer dedup-skip a ciegas: comparar el skill existente contra el README real y parchearlo (category: "upgrade") si está mal. Pendientes de auditar: gtfs-tidy, gtfs2shp, colmap-view, quantstats-pro y demás v1 del maratón.

• Indexar en Windows: run-indexar-skills.sh invoca python3 (no existe → stub del Store, salida vacía engañosa). Ejecutar directo con el Python del sistema: C:/Users/d_ant/AppData/Local/Programs/Python/Python312/python.exe scripts/indexar-skills.py — la DB es embebida (~/.mastermind/chromadb), no necesita server. El indexador solo ve IDs nuevos: para skills PARCHeados, upsert manual vía importlib (patrón documentado arriba).

Comparativa en dedup — mejorar, no solo descartar (regla 2026-09-01)

Cuando el dedup encuentra un skill existente que cubre el tema, NO basta con SKIP: hay que decidir cuál de los dos es mejor referencia hoy. El objetivo del pipeline es aprendizaje continuo, y un repo nuevo puede ser la evolución del que ya tenemos.

Procedimiento:

1. Traer metadatos de ambos (GET /repos/{owner}/{repo}): stars, pushed_at, archived.
2. Comparar en la misma liga temática (no comparar un motor de routing con un generador de shapes).
3. Decisión:
   • Nuevo ≥ existente (más stars/actividad, o aporta un enfoque que falta) → skill_manage(patch) sobre el skill existente: añadir sección ## Comparativa de alternativas (cuándo usar cada cuál, con fechas de consulta) y actualizar la referencia principal si procede. Registry: category: "upgrade".
   • Nuevo < existente → SKIP dedup como siempre, pero la nota del batch debe decir por qué gana el actual ("R3 310⭐ frente a VGGT 14K⭐ + Depth Anything 3 6.2K⭐ ya cubiertos → el skill se queda, R3 queda como alternativa menor"). Registry: category: "skip", skip_reason con el ganador.
4. Nunca borrar del skill la mención al repo peor: la comparativa ES el valor — saber que existe algo mejor y por qué.

Ejemplo verificado (2026-09-01): KevinXu02/R3 (310⭐, push 2026-06-19) vs el terreno 3D-reconstruction ya cubierto: facebookresearch/vggt (14.314⭐, CVPR 2025 Best Paper), colmap/colmap (12.609⭐, activo), ByteDance-Seed/Depth-Anything-3 (6.244⭐). Veredicto: R3 es la opción minoritaria; el dedup acierta descartando, pero la nota debe dejar constancia del ranking.

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
   ↓