121 lines
5.5 KiB
Markdown
121 lines
5.5 KiB
Markdown
# 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.
|