mastermind-setup

name	mastermind-setup
description	Configura y mantiene el sistema personal de agentes Mastermind — sincronización de repositorio GitHub, instalación de skills, configuración de SOUL.md y auto-configuración de cron para el segundo cerebro de Ntizar.
version	1.4.0
author	Ntizar + Hermes Agent
tags	["mastermind","setup","github","skills","soul","nan","identity"]

Mastermind Setup

Procedures for setting up and maintaining the Mastermind personal agent system — a private GitHub repo that serves as the agent's second brain (skills, notes, memory, config, scripts).

Cuándo usar

• Se configura un nuevo entorno de Hermes Agent para Ntizar
• Necesitas sincronizar skills desde el repositorio Mastermind al sistema local
• El SOUL.md se corrompió o truncó y necesita recuperación
• Se necesitan configurar cron jobs de sincronización automática

Cuándo NO usar

• Configurar un usuario diferente de Ntizar → el repo y las rutas son específicas
• Solo necesitas instalar un skill individual → usa skill_manage(action='create') directamente
• El sistema ya está configurado y funcionando → no reconfigurar sin necesidad

Identity

El nombre del agente es Mastermind, no "Hermes Agent". Hermes es el framework subyacente; Mastermind es el nombre que David (Ntizar) le dio a su sistema de agente personal. Al presentarte o referirte a ti mismo, usa "Mastermind".

• Framework: Hermes Agent (el motor subyacente)
• Nombre: Mastermind (el agente personal)
• Usuario: David Antizar (Ntizar)

Esta es la identidad preferida del usuario. Siempre presentarse como Mastermind.

Setup

1. Install GitHub CLI

curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg 2>/dev/null
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | tee /etc/apt/sources.list.d/github-cli.list > /dev/null
apt-get update -qq && apt-get install -y -qq gh

2. Authenticate with GitHub

# Read token from .env
token=$(grep GITHUB_TOKEN /hermes-home/.env 2>/dev/null | cut -d= -f2-)

# ⚠️ PITFALL: gh auth login fails when GITHUB_TOKEN env var is set
# Clear it first:
GITHUB_TOKEN="" echo "$token" | gh auth login --with-token

3. Clone the repo

cd /root/workspace
git clone https://github.com/Ntizar/mastermind.git

4. Configure Hermes to use it as a skills source

In /hermes-home/config.yaml:

skills:
  external_dirs:
    - /root/workspace/Mastermind/mastermind

Then /reset (new session) for Hermes to detect the new skills.

5. Copy skills to local directory

mkdir -p /hermes-home/skills/mastermind
cp /root/workspace/Mastermind/mastermind/*.md /hermes-home/skills/mastermind/

Create a SKILL.md umbrella in /hermes-home/skills/mastermind/SKILL.md listing the individual skills.

6. Actualizar SOUL.md

Configurar /hermes-home/SOUL.md con: identidad del agente, reglas, sistema de conocimiento en 3 capas, estructura del repo, modelo de subagentes, stack actual y lista de skills.

8. Arrancar ChromaDB local (skills vector search)

ChromaDB corre en localhost:8000 para búsqueda semántica de skills. Debe arrancar tras cada reinicio de la VM:

# Arranque manual
bash /hermes-home/scripts/start-chromadb.sh

# Verificar
curl http://localhost:8000/api/v1/version
# → "1.5.9"

Script de arranque: El script start-chromadb.sh está en el skill chromadb-skills-vector-search:

skill_view(name='chromadb-skills-vector-search', file_path='scripts/start-chromadb.sh')
# O directamente:
bash /hermes-home/skills/chromadb-skills-vector-search/scripts/start-chromadb.sh

Datos persistentes: /hermes-home/chromadb-data/

Pitfall: ChromaDB NO arranca automáticamente al reiniciar la VM. Si el agente nota que las consultas semánticas fallan, debe ejecutar start-chromadb.sh o reportarlo.

Ver skill chromadb-skills-vector-search para detalles completos de indexación y consulta.

Create a cron job that runs daily:

# Schedule: 0 9 * * * (daily at 09:00 UTC)
# Prompt:
cd /root/workspace/Mastermind && git pull origin main
cp /root/workspace/Mastermind/mastermind/*.md /hermes-home/skills/mastermind/
gh auth status || re-authenticate from /hermes-home/.env

See scripts/mastermind-autoconfig.sh for the ready-to-use sync script (includes SOUL.md size guard). See scripts/restore-soul.sh for SOUL.md sync check and recovery. See scripts/backup-hermes-memory.sh for manual backup of memory to repo. See references/backup-hermes-complete.md for the complete backup procedure (vulnerability assessment → copy → commit → auto-sync cron). See references/backup-pitfalls-2026-06-22.md for backup pitfalls: double nesting with cp, duplicate commits, .hub/quarantine exclusion, skill-learning.log gitignore. See references/backup-rsync-fallback.md for rsync fallback: Python shutil-based implementation when rsync binary is not available on the VM. See references/backup-cp-nesting.md for the complete cp -r / cp -a double-nesting pitfall and safe copy patterns.

Estructura del Repositorio

Mastermind/
├── README.md                          ← Visión general del sistema
├── ARCHITECTURE.md                    ← Documentación técnica (capas, flujos)
├── mastermind/                             ← Skills CORE del sistema
│   ├── SKILL.md                       ← Índice umbrella de skills propios
│   ├── SOUL.md                        ← Plantilla de identidad
│   └── (skills .md individuales)
├── learning/                          ← Sistema de aprendizaje autónomo
│   ├── MEGA-PLAN-LECTURA-ESCRITURA.md ← Plan maestro del curso
│   ├── README.md                      ← Cómo funciona el sistema
│   ├── sesiones/                      ← HTMLs de lecciones generadas
│   └── indices/                       ← Índices temáticos (autores, vocab...)
├── improvement/                       ← Mejora continua de Mastermind
│   ├── skills-desapavechadas.md       ← Skills que no uso y debería
│   ├── skills-nuevas-proyecto.md      ← Skills que debería crear
│   └── INDEX.md                       ← Índice unificado de mejoras
├── skills/                            ← Skills de referencia (hub externo)
│   └── INDEX.md                       ← Catálogo completo
├── config/
│   └── skill-priority.json            ← Prioridad HIGH/MEDIUM/LOW
├── scripts/                           ← Automatizaciones
│   ├── mastermind-autoconfig.sh            ← Autoconfiguración diaria
│   ├── generate-skill-index.sh        ← Generador de índice
│   └── (otros scripts)
├── memory/                            ← Respaldo de memoria
├── notes/                             ← Notas de sesiones
│   └── _template.md                   ← Template con frontmatter YAML
└── .deploy/                           ← Deploy configs (nginx, Docker)

Reglas

1. Nunca borrar del repositorio — solo crear nuevos archivos o modificar archivos que creaste
2. Formato de notas: YYYY-MM-DD-titulo.md en notes/
3. Skills: cada skill tiene su propio archivo en mastermind/
4. Commit tras aprender: lecciones importantes → commit al repositorio
5. Sin secretos en notas/commits/chat
6. SOUL.md es la fuente de verdad para la identidad del agente — mantenerlo sincronizado con el repo

Backup automático de Hermes al repo (MANTENER ACTUALIZADO)

Este es el procedimiento estándar de backup completo al repo Mastermind. Ejecutar cuando se pida o como cron.

Pasos

1. Verificar que el destino existe:

   test -d /root/workspace/Mastermind/hermes-home/ || mkdir -p /root/workspace/Mastermind/hermes-home/
   

2. Copiar archivos/carpetas (rsync o fallback):

   # OPCIÓN A: rsync (si está disponible)
   rsync -av /hermes-home/skills/ /root/workspace/Mastermind/hermes-home/skills/
   rsync -av /hermes-home/memories/ /root/workspace/Mastermind/hermes-home/memories/
   rsync -av /hermes-home/notes/ /root/workspace/Mastermind/hermes-home/notes/
   rsync -av /hermes-home/scripts/ /root/workspace/Mastermind/hermes-home/scripts/
   
   # OPCIÓN B: rm -rf + cp -a (cuando rsync no está disponible — confirmado 2026-06-29)
   rm -rf /root/workspace/Mastermind/hermes-home/skills/
   cp -a /hermes-home/skills/ /root/workspace/Mastermind/hermes-home/skills/
   rm -rf /root/workspace/Mastermind/hermes-home/memories/
   cp -a /hermes-home/memories/ /root/workspace/Mastermind/hermes-home/memories/
   rm -rf /root/workspace/Mastermind/hermes-home/notes/
   cp -a /hermes-home/notes/ /root/workspace/Mastermind/hermes-home/notes/
   rm -rf /root/workspace/Mastermind/hermes-home/scripts/
   cp -a /hermes-home/scripts/ /root/workspace/Mastermind/hermes-home/scripts/
   
   cp /hermes-home/config.yaml /root/workspace/Mastermind/hermes-home/config.yaml
   

   Por qué rsync y no cp -r: cp -r /hermes-home/memories/ /dest/hermes-home/memories/ cuando el destino ya existe produce /dest/hermes-home/memories/memories/. rsync -av no tiene este problema. Si rsync no está, usar rm -rf + cp -a como fallback confirmado.

3. Verificar que no hay nesting:

   find /root/workspace/Mastermind/hermes-home/ -mindepth 2 -maxdepth 2 -type d | while read dir; do
     parent=$(basename "$(dirname "$dir")")
     child=$(basename "$dir")
     if [ "$parent" = "$child" ]; then
       echo "NESTED: $dir"
     fi
   done
   

   Si hay nesting, aplicar el fix cascading (ver pitfall 2026-06-28).

4. Contar archivos copiados:

   find /root/workspace/Mastermind/hermes-home/skills -type f | wc -l
   

5. git add, commit, push:

   cd /root/workspace/Mastermind
   git add -A
   git commit -m "Backup semanal: $(date +%Y-%m-%d)"
   git push origin HEAD:master
   

Pitfalls críticos del backup

• DOBLE NESTING con cp -r (recurrente): cp -r /hermes-home/memories/ /dest/hermes-home/memories/ cuando /dest/hermes-home/memories/ ya existe produce /dest/hermes-home/memories/memories/. SOLUCIÓN OBLIGATORIA: usar rsync -av en lugar de cp -r. Siempre.

• Cascading nesting en skills: Cuando el nesting raíz se corrige (skills/skills/ → skills/), CADA categoría top-level puede tener el mismo patrón: ai-patterns/ai-patterns/, creative/creative/, stem/stem/ — 70+ directorios. Fix: loop sistemático find . -mindepth 2 -maxdepth 2 -type d | while read dir; do parent=$(basename "$(dirname "$dir")"); child=$(basename "$dir"); if [ "$parent" = "$child" ]; then mv "$dir"/* "$dir"/.* . 2>/dev/null; rm -rf "$dir"; fi; done.

• skill-learning.log: puede no existir (gitignore, puede haber sido eliminado). No fallar si no está.

• Comparación de skills: usar find -name 'SKILL.md' en ambos lados, EXCLUYENDO .hub/. El repo puede tener más skills que Hermes (skills propios del sistema, STEM, etc.). No es problema.

• .hub/quarantine/ no va al backup. Contiene installs fallidas.

• .lock files: los archivos .lock de memories (MEMORY.md.lock, USER.md.lock) van al backup pero son inertes. Limpiarlos con find -name '*.lock' -delete antes de commit si se quiere repos limpio.

• .hub/ en conteo: no incluir .hub/ al comparar conteos de SKILL.md.

• rsync --delete es destructivo: solo usar si se quiere espejo exacto. Para backup incremental seguro, usar rsync -av SIN --delete.

• Hermes no detecta external_dirs mid-session — reiniciar sesión (/reset) tras cambiar config.yaml

• SKILL.md requerido — archivos .md individuales no se detectan sin un SKILL.md umbrella

• gh auth falla con GITHUB_TOKEN set — limpiar primero: GITHUB_TOKEN="" echo "$token" | gh auth login --with-token

• SOUL.md debe actualizarse — instalar skills no es suficiente; la identidad debe estar en SOUL.md

• SOUL.md puede truncarse — puede reducirse a ~48 bytes. Detección: wc -c /hermes-home/SOUL.md — si <1000, está corrupto. Recuperación: cp /root/workspace/Mastermind/mastermind/SOUL.md /hermes-home/SOUL.md

• Hermes memory drifts from repo — el cron NO hace backup de memoria. Usar scripts/backup-hermes-memory.sh manualmente.

• SOUL.md size guard (ACTUALIZADO 2026-06-03) — mastermind-autoconfig.sh usa lógica de 3 vías: (1) si local < 1000 bytes → SIEMPRE restaurar desde repo (truncado), (2) si repo > local → restaurar, (3) si local > repo y local > 1000 → subir al repo. El guard anterior solo comparaba repo > local, lo que permitía corrupción parcial silenciosa.

• Config drift silencioso — tts.edge.voice y display.language pueden perderse tras updates de Hermes o reconfiguraciones. Verificar periódicamente: grep "voice:" /hermes-home/config.yaml | head -1 debe mostrar es-ES-AlvaroNeural, y grep "language:" /hermes-home/config.yaml debe mostrar es en sección display. Si están en inglés → el agente responde en inglés y TTS suena raro.

• Hermes path quirk — algunos deployments usan /hermes-home/ en vez de ~/.hermes/. Verificar $HERMES_HOME.

• No crear skills con write_file manual — usar skill_manage(action='create').

• Duplicate workspace clones — solo una copia de Mastermind repo en /root/workspace/Mastermind/.

• gh CLI no instalado — git push funciona sin gh.

• ChromaDB no sobrevive a reinicios — la VM de NaN puede reiniciarse. ChromaDB no tiene systemd unit. Si el agente detecta que curl localhost:8000/api/v1/version falla, debe ejecutar bash /hermes-home/scripts/start-chromadb.sh para re-arrancarlo. Los datos persisten en /hermes-home/chromadb-data/.

• Debian Node.js stub crashes — /usr/bin/node es un stub que crashea. Usar nvm o shebang directo al path nvm.

Patrón de Sincronización Bidireccional

Orquestación de Cron Jobs (Multi-Sesión con Plan Maestro)

Cuando el usuario pide generar un proyecto grande que requiere múltiples sesiones/entregas (curso de 10 sesiones, serie de informes, batch de archivos), usar este patrón.

Pasos

1. Crear MEGA-PLAN.md en el directorio de trabajo

   • Estructura general del proyecto
   • Diseño visual unificado (paleta, CDN, estilo)
   • Contenido detallado por sesión/archivo
   • Requisitos técnicos
   • Checklist de calidad

2. Crear archivo principal (INDEX.html, README, etc.) con navegación entre entregas

3. Crear cron jobs con:

   • deliver: origin (entregar al chat actual)
   • Schedule espaciado (cada 12h o 24h para no saturar)
   • repeat: once (ejecutar una sola vez)
   • Cada cron con prompt autocontenido que referencie el MEGA-PLAN.md
   • Nombre descriptivo: NombreProyecto SNN — Descripción

4. Verificar que los crons se crearon con cronjob action=list

Reglas

• El MEGA-PLAN.md es la fuente de verdad: TODOS los crons lo referencian
• Cada cron debe ser autocontenido (no depende del contexto del chat)
• Espaciar crons para evitar saturación de tokens
• Límite de líneas por archivo para evitar truncamiento

Pitfalls

• NO crear crons en bucle infinito (repeat: forever) para proyectos de una sola vez
• NO usar openrouter como provider en crons de Mastermind (401 error) — usar qwen3.6 vía custom
• NO olvidar que los crons corren en sesión aislada: el prompt debe ser completamente autocontenido