qwen3-6-lora/data/raw/sanitized/plans/puedes-ver-la-skill-silly-jellyfish.md

Segmentar background-orchestrator en skills más pequeñas

Context

El SKILL.md actual de background-orchestrator tiene ~470 líneas y 31KB. Contiene TODO el flujo: lanzar agentes, monitorear, generar instrucciones, validar y archivar. Es difícil de navegar y mantener. La idea es segmentarlo en skills más pequeñas que el orchestrator orqueste en secuencia.

Nota importante: Las skills de Claude Code son user-invoked (se invocan con /skill-name), no se pueden llamar programáticamente desde otra skill. El orchestrator no "llama" a las otras skills como funciones — lo que hace es guiar el flujo de conversación en fases, y en cada fase ejecuta los pasos correspondientes (o le dice al usuario que invoque la skill correspondiente).

Propuesta de segmentación

~/.claude/skills/
  background-orchestrator/       # Coordinador del flujo (reducido a ~80 líneas)
  agent-launcher/                # Flujo completo de lanzamiento de agente
  agent-monitor/                 # Monitoreo y control de agentes
  agent-instructions/            # Template TASK.md para agentes
  agent-archiver/                # Validación y archivo de agentes
  agent-safety/                  # Reglas de seguridad compartidas
  agent-troubleshooting/         # Tabla de troubleshooting

1. agent-launcher — Flujo de lanzamiento (Section A)

• Detectar proyecto (package.json → pyproject.toml → basename)
• Pedir tarea al usuario
• Generar AGENT_NAME (slug agente-*)
• Crear worktree en .worktrees/
• Configurar permisos (settings.local.json con allow-list de MCP)
• Instalar dependencias (npm install en worktree)
• Lanzar sesión tmux (sin | tee, con pipe-pane para log)
• Capturar SESSION_ID desde JSONL
• Registrar en Docmost (página "Agentes Activos" + subpágina)
• Confirmar al usuario

2. agent-monitor — Monitoreo y control (Section B)

• Verificar transcript JSONL (líneas, tiempo de actividad)
• Detectar bloqueos (grep "Do you want to proceed")
• Extraer últimas acciones del agente (jq en JSONL)
• Medir progreso en rama (commits sobre base)
• Mostrar panel limpio (sin ANSI escapes)
• Instrucciones para tmux send-keys (desbloquear)
• Distinguir "Ruminating" real de bloqueo real
• Leer subpágina en Docmost para resumen

3. agent-instructions — Template TASK.md (Section C)

• Bloque de instrucciones para el agente hijo
• Permisos y autonomía
• Reglas de git (commits atómicos, no merge, no Claude attribution)
• Guidelines de subagentes (Task tool, MCP access)
• Checkpoints de Docmost (por fase)
• Pasos obligatorios al terminar (web-ui-test, aleleba-pr, email)
• Template de correo de finalización

4. agent-archiver — Validación y archivo (Section D)

• Leer subpágina del agente en Docmost
• Integrar trabajo en documentación temática del proyecto
• Borrar subpágina de "Agentes Activos"
• Quitar bloque de la lista activa
• Preguntar al usuario sobre merge (advertir deploy a producción)
• Preguntar sobre eliminación de rama
• Eliminar worktree, rama, sesión tmux, artefactos
• Confirmar archival con links

5. agent-safety — Reglas de seguridad (Section REGLAS)

• Política de merge (agentes nunca mergean, madre solo con validación explícita)
• Prohibición de atribución a Claude
• Aislamiento de worktrees
• Protección de credenciales
• Referencia centralizada — otras skills citan esta en vez de duplicar

6. agent-troubleshooting — Lecciones aprendidas (Section Troubleshooting)

• Tabla de 12 problemas conocidos con causa y solución
• Regla de oro post-lanzamiento
• Referencia para diagnóstico

7. background-orchestrator — Coordinador (reducido a ~80 líneas)

• TRIGGER: cuándo activarse (frases exactas)
• Referencia a agent-safety: reglas de seguridad
• Guía de flujo de conversación:
  • FASE 1: Lanzar → ejecutar pasos de agent-launcher
  • FASE 2: Monitoreo → ejecutar pasos de agent-monitor
  • FASE 3: Archivar → ejecutar pasos de agent-archiver
• Referencias cruzadas: "para lanzamiento, ver /agent-launcher", etc.

Mapa de dependencias

background-orchestrator (entry point)
├── references → agent-safety (reglas de seguridad)
├── ejecuta → agent-launcher (flujo de lanzamiento)
│   ├── usa → agent-instructions (contenido de TASK.md)
│   └── usa → agent-safety (reglas de seguridad)
├── ejecuta → agent-monitor (checks de estado)
│   └── usa → agent-safety (reglas de seguridad)
├── ejecuta → agent-archiver (flujo de aprobación)
│   └── usa → agent-safety (reglas de seguridad)
└── referencia → agent-troubleshooting (referencia de debugging)

Migración

1. Crear directorios para las 6 nuevas skills
2. Extraer contenido de cada sección del SKILL.md actual a su skill correspondiente
3. Reescribir orchestrator — mantener solo trigger, guía de flujo y referencias
4. Verificar que cada skill sea invocable de forma independiente
5. Asegurar que cada SKILL.md tenga frontmatter correcto (name, description, effort)

Resultado esperado

Skill	Líneas	Descripción
background-orchestrator	~80	Coordinador del flujo
agent-launcher	~120	Lanzamiento de agente
agent-monitor	~60	Monitoreo y control
agent-instructions	~90	Template TASK.md
agent-archiver	~80	Validación y archivo
agent-safety	~40	Reglas de seguridad
agent-troubleshooting	~50	Troubleshooting
Total	~420	7 archivos (vs 1 de 470)

Cada archivo es más corto, más enfocado y más fácil de navegar.