# 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.