mastermind-orchestration

# Mastermind Orchestration — Sistema Unificado ## Resumen Sistema de orquestación multi-agente para Mastermind ejecutándose en Hermes con repos en GitHub. Reemplaza el antiguo sistema mastermind (Obsidian+OpenCode), orca y canvas-workflow. Simple, rápido, Hermes-native. ## Principios 1. **Un orquestador, muchos especialistas** — Mastermind clasifica y delega. Los 143 skills especializados ejecutan con conocimiento profundo de su dominio. 2. **Hermes-native** — Todo usa `delegate_task`, sin herramientas externas 3. **GitHub-centric** — El repo es la fuente de verdad, no Obsidian 4. **Skills sobre agentes** — Cada skill es un especialista en un dominio, no un rol genérico 5. **Delegar, no comprimir** — Paralelizar cuando sea posible 6. **Human loop obligatorio** — En cambios críticos (>5 archivos, decisiones de arquitectura), Mastermind presenta el plan y espera ✅ antes de ejecutar ## Carga de skills — Búsqueda semántica con ChromaDB (PRIMARIO) Desde 2026-06-10, la carga de skills usa ChromaDB local como mecanismo principal: 1. **Mastermind recibe una petición** → extrae palabras clave / intención 2. **Consulta ChromaDB** (`localhost:8000`, colección `mastermind-skills`) con `consultar-skills.py` 3. **ChromaDB devuelve top-5 skills** con scores de similitud (0.0 - 1.0) usando vectores 4096-dim de `qwen3-embedding` 4. **Filtro por score > 0.5** → carga solo esos skills con `skill_view()` 5. **Fallback:** si ChromaDB no responde o no encuentra nada, usar el sistema de prioridad por dominio (abajo) **Scripts:** - `/hermes-home/scripts/consultar-skills.py` — consulta semántica (modo `--json` para Mastermind) - `/hermes-home/scripts/indexar-skills.py` — re-indexación manual - `scripts/delegation-flows.py` — clasificación de complejidad con `classify_task()` y heurísticas **Cron:** `chromadb-reindex-semanal` (domingo 04:00 UTC) **Skill de referencia:** `chromadb-skills-vector-search` ### Sistema de Prioridad por Dominio (FALLBACK) Si ChromaDB no está disponible, se usa este sistema tradicional: ### Antes (v3.1) — Agentes genéricos ``` Implementer genérico → hace frontend, backend, infra, todo mal ``` ### Después (v4.0) — Skills especializados ``` Mastermind clasifica dominio → Carga skills del dominio → delegate_task con contexto especializado ``` | Dominio | Skills | Especialización | |---------|--------|----------------| | **Software** (HIGH) | 17 skills | TDD, debug, code review, refactor, iteración | | **GitHub** (MEDIUM) | 7 skills | PR workflow, code review, issues, repo mgmt | | **Frontend** (MEDIUM) | 3 skills | Aurora Design System, patrones dashboard | | **Backend** (MEDIUM) | 6 skills | APIs REST, ESM interop, fetch paralelo | | **Infra** (MEDIUM) | 6 skills | HTTP robusto, Docker, seguridad, cache | | **DevOps** (MEDIUM) | 10 skills | Deploy NaN, Aurora Nightly, cron jobs | | **Data Science** (MEDIUM) | 8 skills | Simuladores, Monte Carlo, análisis | | **Creative** (MEDIUM) | 22 skills | Diagramas, ASCII, diseño, video | **Carga de skills:** - **HIGH (Core)** → Se cargan automáticamente: `subagent-driven-development`, `delegar-no-comprimir`, `mastermind-orchestration`, `github-workflow`, `systematic-debugging` - **MEDIUM (Dominio)** → Se cargan con `skill_view()` cuando toca ese tema - **LOW (Archivo)** → Solo si el usuario los pide Ver `skills_list` de Hermes para el índice completo (143 skills cargados dinámicamente). ## Roles de Agentes ### Mastermind (Orquestador Principal) - Clasifica tareas por complejidad - Decide: hacer directamente o delegar - Integra resultados y verifica - Define en SOUL.md ### Subagentes (vía `delegate_task`) | Rol | Cuándo usarlo | Toolsets típicos | |---|---|---| | **Explorer** | Analizar código/contexto sin modificar | `file`, `terminal` | | **Planner** | Diseñar estrategia y pasos | `file` | | **Implementer** | Ejecutar código o cambios | `terminal`, `file` | | **Reviewer** | Validar calidad contra spec | `file` | | **Critic** | Revisión adversarial (cosas críticas) | `file` | **Regla:** Tareas simples → Mastermind directo. Complejas (5+ pasos) → delegar. ## Niveles de Complejidad ### Nivel 1 — Directo (Mastermind solo) - 1-3 tool calls - Cambios en 1-2 archivos - Respuestas simples - **Ejemplo:** Buscar algo, leer archivo, hacer commit ### Nivel 2 — Delegación simple - 4-8 tool calls - Cambios en 3-5 archivos independientes - **Ejemplo:** Refactor de módulo, implementar feature con tests - **Patrón:** Mastermind planifica → 1 Implementer → Mastermind verifica ### Nivel 3 — Delegación paralela - 8+ tool calls - Múltiples features o módulos independientes - **Ejemplo:** Optimizar frontend + backend + tests simultáneamente - **Patrón:** Mastermind planifica → 2-3 Implementers en paralelo → Mastermind integra ### Nivel 4 — Orquestación completa - Proyectos grandes, múltiples PRs - **Ejemplo:** Feature completa con backend, frontend, docs, tests - **Patrón:** Planner → Implementers paralelos → Reviewer → Critic → Mastermind integra y merge ## Flujo de Trabajo ### Tarea recibida ``` 1. ¿Cuántos archivos toca? - 1-2 → Nivel 1 (directo) - 3-5 → Nivel 2 (delegación simple) - 5+ independientes → Nivel 3 (paralelo) - Proyecto completo → Nivel 4 (orquestación) 2. ¿Es código, análisis, o infra? - Código → subagentes de dev - Análisis → Mastermind directo o Explorer - Infra → Mastermind directo (conocimiento específico) 3. Ejecutar según nivel ``` ### Delegación estándar (Nivel 2-3) ```python delegate_task( tasks=[ { "goal": "Tarea específica con contexto completo", "context": "Archivos, paths, errores, constraints", "toolsets": ["terminal", "file"] } ] ) ``` ### Reglas de delegación - ** SIEMPRE** dar contexto completo al subagente (no puede leer el chat) - **NUNCA** delegar tareas que necesitan interacción con el usuario - **NUNCA** delegar más de 3 tareas en paralelo (límite de Hermes) - **SIEMPRE** verificar resultados del subagente antes de entregar ## Patrones de Uso ### Patrón: Fix paralelo Cuando hay 3+ bugs independientes: ``` Mastermind identifica bugs → delega fixes en paralelo → integra y verifica ``` ### Patrón: Feature completa ``` Mastermind planifica → Implementer(s) ejecutan → Reviewer valida → Mastermind merge ``` ### Patrón: Investigación + implementación ``` Explorer analiza → Mastermind decide → Implementer ejecuta → Reviewer valida ``` ### Patrón: Ecosystem Module Factory — Creación paralela de módulos TS Cuando hay que crear un ecosistema de 3+ módulos TypeScript independientes (ej: Adela con 10 módulos), este patrón maximiza throughput mediante delegación paralela. #### Estructura estándar de cada módulo ``` modulo/ ├── README.md # Quick start + API + "Integración con otros ..." ├── package.json # name, version 1.0.0, type: module, scripts: build + test ├── tsconfig.json # Strict, ES2022, Node16 moduleResolution ├── src/ │ ├── index.ts # Barrel export │ ├── ...ts # Módulos funcionales │ └── types.ts # Interfaces ├── tests/ │ └── *.test.ts # Tests con tsx --test (mínimo 15 tests) └── dist/ # outDir, rootDir: src ``` #### Flujo de ejecución **FASE 1 — Preparación:** 1. Ver qué módulos extraer de código existente vs crear desde cero 2. Para cada módulo: leer código fuente con read_file si hay extracción 3. Para cada módulo desde cero: diseñar API completa (interfaces, funciones) **FASE 2 — Delegación paralela:** 1. Lanzar 3-4 subagentes en paralelo, cada uno con: - Estructura exacta de archivos - API a exponer (copia-pega de interfaces) - Código fuente de referencia (si hay extracción) - Número mínimo de tests - Dependencias runtime necesarias 2. Asignar timeout=600s para módulos complejos (auth, db, export) 3. Cada subagente es autónomo: crea, testea, compila **FASE 3 — Verificación post-ejecución:** POR CADA módulo completado: 1. `cd /path/modulo && npm run build` → ¿Compila? 2. `npm test` → ¿Pasan tests? 3. Si falla: diagnóstico rápido y fix directo (tsconfig, imports, test config) 4. Si timeout (subagente no terminó): completar manualmente lo que falta **FASE 4 — Push a GitHub (paralelo):** 1. Lanzar push en paralelo para N/2 grupos 2. Cada grupo: .gitignore → git init → add → commit → push #### Pitfalls del patrón - **Timeout en módulos complejos**: Adela_db (sql.js + migraciones) requirió 600s y aun así timeout. El subagente creó src/ pero no database.ts ni tests de migrations. Solución: para módulos con 3+ archivos src o dependencias nativas, hacer en 2 tandas o supervisar más cerca. - **Build failure no siempre significa error real**: Adela_http compiló con tsc exit 0 pero tsconfig tenía rootDir="." en vez de "src", generando dist/src/. Fácil de arreglar, pero hay que revisar tsconfig de cada módulo. - **TypeScript strict + tests de Jest**: los tests con jest+ts-jest hacen typecheck, y TS strict encuentra errores en tests (variables no usadas, imports raros). Arreglo: desactivar diagnostics en transform de jest.config, o configurar noUnusedLocals: false en tests. - **Subagentes pueden modificar archivos que ya leíste**: Adela_auth/src/auth.ts fue modificado por un subagente después de leerlo → warning de "re-read antes de editar". Siempre re-read antes de parchear. #### Ejemplo real: Ecosistema Adela (2026-06-14) ``` Sesión 1: 3 subagentes → Adela_time, Adela_env, Adela_http (P0) → 74 tests, push a 3 repos GitHub ✅ Sesión 2: 3 subagentes → Adela_cache, Adela_health (P1) + push P0 + 1 subagente → Adela_auth (P1, timeout parcial, completado manual) → 106 tests, push a 5 repos ✅ Sesión 3: 3 subagentes → Adela_export, Adela_ai (P2) + Adela_i18n (P3) + 1 manual → Adela_db (P2, timeout, completado por Mastermind) + 2 pushes → push paralelo de 4 módulos → 114 tests, push a 10 repos ✅ ``` ### Patrón: Plan de mejora por fases (pipeline de crons) Cuando hay múltiples mejoras pendientes que dependen unas de otras: ``` 1. AUDIT → evaluar estado actual con métricas reales 2. PLAN → dividir en fases (cimientos → inteligencia → verificación) 3. EJECUTAR → cada fase como cron one-shot independiente 4. VERIFICAR → comprobar que todo funciona al final ``` **Reglas:** - Cada fase debe ser **idempotente** (puede repetirse sin daño) - Las fases se ejecutan en **serie** (cimientos antes que inteligencia) - Cada cron entrega un resumen al final - Si una fase falla, la siguiente no se ejecuta **Ejemplo real (2026-06-10):** Pipeline de 14 crons para mejorar Mastermind: Fase 1 (8 crons, cimientos: ChromaDB, SOUL.md, limpieza skills) → Fase 2 (5 crons, inteligencia: Ebbinghaus, grafo, lifecycle, orquestación, dashboard) → Fase 3 (1 cron, verificación + mantenimiento semanal). **Skill dedicado:** `micro-crons-pipeline` — para pipelines de proyectos grandes con backlog de tareas atómicas y cron maestro automático. Usar cuando el usuario quiera un proyector que avance solo con iteraciones programadas. ### Patrón: Parallel Batch Data Processing — Análisis masivo de items independientes Cuando hay un **conjunto grande de items** (50-200) que necesitan **análisis/classificación independiente** (no construcción de código), y cada item produce un veredicto: **Ejemplo real:** Analizar 117 repos de GitHub Stars → decidir CREATE_SKILL / SKIP / ALREADY_COVERED para cada uno. ``` FASE 1 — Registro masivo sin análisis profundo → Solo fetch básico (nombres, stars, lenguaje) — ~2 min para 117 items → NO fetch de README/tree/content (se timeout: 117 × 4 reqs ≈ 1h) FASE 2 — Clasificación por valor → High (>3000⭐) → procesar AHORA con subagentes → Medium (500-3000⭐) → dejar para cron/siguiente → Low (<500⭐) o awesome lists → skip automático FASE 3 — Batch en paralelo (3 subagentes × 6-8 items cada uno) ├── Subagente A: items 1-6 ├── Subagente B: items 7-12 └── Subagente C: items 13-18 Toolsets: ["terminal", "file"] (necesitan acceso a archivos + shell) FASE 4 — Cada subagente produce un veredicto por item: ├── CREATE_SKILL → nombre, categoría, razón ├── ALREADY_COVERED → qué skill existente lo cubre └── SKIP → razón (awesome list, irrelevante, <500⭐, C++ legacy, etc.) FASE 5 — Mastermind agrega resultados: ├── Crea skills pendientes con skill_manage (acción real) ├── Actualiza registry con las decisiones └── Re-indexa ChromaDB si hubo cambios FASE 6 — Pendientes para el cron: → Items que no se procesaron van al cron nocturno (3/noche) ``` **Características clave de este patrón:** - Los items son **INDEPENDIENTES** (no comparten estado) — pueden ir en paralelo sin riesgo - Cada subagente recibe **contexto completo** de sus 6 items (nombres, stars, descripciones) - El output es **estructurado** (veredictos), no código - **No hay riesgo de conflictos** entre subagentes (cada uno decide sobre items distintos) - **Tiempo total:** 3 subagentes × ~3 min = ~5 min para 18 items (vs ~1h en serie) **Pitfalls:** - **Contexto grande:** 6 repos × READMEs de 8K chars = 48K chars de input. Asegurar que el modelo tiene suficiente ventana de contexto (min 32K, recomendar 128K) - **Timeout en --all:** No ejecutar `explorar-stars.py --all` con 100+ repos si el script hace fetch de README/tree. Se timeout. Mejor hacer registro masivo primero (solo 1 req/repo) - **Deduplicación ChromaDB:** Antes de crear skill, cada subagente debe consultar ChromaDB local para evitar duplicados. Si score > 0.25, SKIP con razón "ya existe skill X" - **Awesome lists:** `awesome-*`, `Clone-Wars`, `*-awesome-*` → **siempre SKIP** sin análisis - **Repos personales del usuario (Ntizar/*):** siempre prioridad, crear skill aunque sea simple - **Agregación post-batch:** Mastermind debe verificar que los skills se crearon realmente (no confiar ciegamente en el subagente). Leer el registry post-ejecución. ### Patrón: Greenfield project con cron pipeline Cuando hay que construir un proyecto COMPLETO desde cero (no mejorar uno existente), usar crons one-shot secuenciales para cada fase del desarrollo. Cada cron construye una parte, hace commit+push, y el siguiente cron construye sobre lo anterior. ``` 1. SCAFFOLD → repositorio, estructura, README, ARCHITECTURE.md, ADR inicial 2. HACER YO (Mastermind) → Fase 0 de investigación: fuentes, zona piloto, mapa de datos, backlog 3. CRONs ONE-SHOT → cada hora/fase del desarrollo, en orden de dependencia 4. CANCELAR crons que ya no aplican → si adelantas trabajo manualmente, quitas el cron 5. AUDITORÍA → cron final para bugs, CHANGELOG, calidad ``` **Reglas específicas de greenfield:** - **Fase 0 la hace Mastermind** — investigación, documentación, decisiones de arquitectura. No delegar a cron las decisiones de diseño. - **Cada cron es autocontenido** — el prompt debe incluir: contexto del proyecto, archivos a modificar, qué verificar, y que haga commit+push. No asume nada del contexto del chat. - **Import paths en monorepos** — desde apps/web-viewer/src/main.js, el path relativo correcto a src/ocean/gerstner.js es ../../../src/ocean/gerstner.js (3 niveles), no ../../src/ (2 niveles). Esto es un pitfall común en monorepos Vite con estructura apps/web-viewer/src/ + src/ raíz. - **GH Actions + GH Pages** — usar peaceiris/actions-gh-pages@v4 para deploy automático desde GH Actions. La branch destino es gh-pages. Para repos privados, GitHub Pages requiere plan de pago. Si el usuario tiene plan gratuito, hacer el repo público o servir desde NaN.builders. - **Build local primero** — siempre verificar npm run build localmente antes del push. El GH Actions tarda ~2-3 min y si falla, hay que esperar otro ciclo. - **Cancelar crons solapados** — si Mastermind adelanta trabajo manualmente (ej: mejora UI mientras espera un cron), cancelar ese cron con cronjob(action='remove', job_id=...) para evitar que sobrescriba. - **Entregar resultados** — los crons deben tener deliver='origin' para que los resultados lleguen al chat actual. **Pipeline típico para proyecto web 3D (Three.js + Vite, ejemplo WaveThree):** ``` Cron 1 (17:18): Fase 1.1 — MVP visual (shader, escena, UI base, GH Pages) Cron 2 (18:18): Fase 1.2 — UI avanzada + selector escenarios Cron 3 (19:18): Fase 1.3 — Pipeline datos reales (GEBCO, NetCDF) Cron 4 (20:18): Fase 2.1 — Batimetría 3D en escena Cron 5 (21:18): Fase 2.2 — Escenarios reales + selector funcional Cron 6 (22:18): Fase 3 — Océano espectral (JONSWAP + iFFT) Cron 7 (23:18): Fase 4 — Estructuras costeras + espuma Cron 8 (00:18): Fase 5 — Producto técnico (comparador, exportación) Cron 9 (01:18): Auditoría final (bugs, CHANGELOG) ``` **Pitfalls del patrón greenfield:** - **WebGPU en Three.js r170** — WebGPURenderer no está disponible desde el bundle principal (three.module.js). Se necesita three/build/three.webgpu.js. Para el MVP inicial, usar WebGLRenderer con buena configuración y añadir WebGPU cuando se necesite compute shaders.