Fase 2: 04_sanitize.py - scrubbing de secretos de skills/agentes/plans (10 secretos unicos, gate en verde)

2026-07-29 00:35:59 +00:00
parent 21bc219f31
commit 837f91060f
79 changed files with 10153 additions and 0 deletions
@@ -0,0 +1,120 @@
+# 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.