Design Spec — Pending Review

VPS Maintenance Agent

Skill de Claude Code + trigger semanal que audita librerías, repos, tools y skills del VPS. Genera reporte con prioridades, limpia basura automáticamente, y notifica por Telegram + Email + Dashboard.

Pipeline de ejecución

🔍

Auditar

4 auditors en paralelo

🏷️

Clasificar

CRITICAL → LOW

🧹

Auto-clean

/tmp bundles, stale files

📊

Dashboard

HTML → playgrounds

📬

Notificar

TG + Email

4 Dominios de auditoría

📦

LibraryAuditor

npm outdated en 6 repos Node
pip list --outdated en venv + global
Version mismatches (venv vs global)
Paquetes innecesarios (CUDA en CPU)
143 packages Python, ~1.6GB node_modules

🗂️

RepoAuditor

npx tsc --noEmit compile checks
Branches stale sin merge (>7 días)
Disk: /tmp basura, node_modules size
Systemd services vs código actual
14 repos, 5 servicios custom

🔧

ToolsAuditor

Claude Code + 3 plugins + 35 skills
registry.json consistency
8 cron jobs health
3 SSL certs expiry (certbot)
API keys deprecated detection
Swap/disk usage thresholds

🧩

SkillsAuditor

npx autoskills --dry-run per repo
Diff suggested vs installed skills
Detect new skills (skills.sh registry)
Detect obsolete/archived skills
Detect skill updates available

S Clasificación de severidad

Severidad	Criterio	Notificación
CRITICAL	Servicio caído, disco >85%, swap >90%, SSL <14 días	Telegram + Email
HIGH	Major version outdated, new official skills, branches stale >7d, registry inconsistente	Telegram + Email
MEDIUM	Minor/patch outdated, venv mismatch, community skills, uncommitted changes	Email only
LOW	Informacional, deprecated keys, docker sin uso, pip global	Email only

3 Canales de entrega

📊

Playground Dashboard

HTML dark-theme con semáforos, historial de runs, detalle de findings y acciones propuestas

siempre

📱

Resumen corto a @ClaudeRob1Bot con link al dashboard. Solo findings críticos.

CRITICAL / HIGH

📧

Email

Reporte completo HTML a aguirrerjg@gmail.com via AgentMail API

siempre

Acciones automáticas (safe only)

🗑️

Webpack bundles en /tmp

Eliminar remotion-webpack-* dirs >24h. Libera ~50-300MB.

🧹

Archivos grandes en /tmp

Archivos >1GB con más de 7 días de antigüedad. Libera GBs.

📋

Deprecated .env keys

Reportar keys conocidas como deprecated (Oxylabs, etc.). Solo reporte.

🔒

SSL near expiry

Alertar si certs expiran en <30 días. Solo reporte.

Estructura del skill

~/.claude/skills/vps-maintenance/
├── SKILL.md                    ← Definición del skill
├── references/
│   ├── repos.json              ← Lista de repos + tipo (node/python)
│   ├── deprecated-keys.json    ← Patterns de keys obsoletas
│   └── services.json           ← Servicios systemd a verificar
├── auditors/
│   ├── libraries.sh            ← npm outdated + pip outdated
│   ├── repos.sh                ← tsc checks, branches, disk
│   ├── tools.sh                ← claude version, crons, SSL
│   └── skills.sh               ← autoskills + registry check
├── report/
│   ├── generate_dashboard.py   ← HTML dashboard generator
│   └── template.html           ← Dark-theme base template
└── notify/
    ├── telegram.sh             ← TG bot API notification
    └── email.py                ← AgentMail API delivery

Programación

📅

Domingos 7:00am + On-demand

Scheduled trigger semanal via Claude Code schedule. Alineado con SEO monitors (dom 6:07-6:27). Invocable manualmente con /vps-maintenance o desde Telegram.

cron: 0 7 * * 0 manual: /vps-maintenance telegram: "mantenimiento VPS"

Modo conservador

El agente audita y reporta todo, pero solo ejecuta acciones safe (limpiar /tmp). Las actualizaciones de packages, merge de branches, reinstalación de tools se proponen con el comando exacto en el reporte, pero NO se ejecutan sin confirmación manual.

Todo lo demás requiere aprobación explícita de Roberto.