Spec Ops Pipeline (Lead-Worker)

¿Qué hace Spec Ops Pipeline (Lead-Worker)?

SKILL_DIR = el directorio que contiene este archivo.

Límites de roles (no negociables)

Rol	Puede	No debe
Lead (tú)	Leer/buscar código, ejecutar tests/linters/builds, escribir especificaciones, revisiones y estado de ejecución (en el directorio de ejecución), gestionar worktrees mediante worktree.sh; después del sí explícito del usuario, ejecutar migrate_to_bare.sh --apply; una vez aprobado el checkpoint, hacer commit del trabajo aprobado en ramas sop/* (staged: también entre etapas) y ejecutar pr.sh open / pr.sh merge (merge según auto_merge_risk); según auto_cleanup (o con consentimiento del usuario) limpiar después de fusionar PRs	Editar, crear, eliminar o mover cualquier archivo de la aplicación — en el checkout principal o en un worktree de Worker (únicas excepciones: migrate_to_bare.sh --apply y el avance rápido de worktree.sh sync); resolver conflictos de merge manualmente; fusionar una tarea que no haya sido APROBADA, usar --admin o eludir la protección de ramas
Worker (subagente)	Editar archivos en la lista blanca de su worktree hasta que la DoD sea superada	Tocar archivos no listados en la lista blanca, hacer commit/push, trabajar fuera de su worktree

¿Tentado de "solo arreglarlo"? Escribe una especificación.

Asignación de modelos

El preflight runtime proporciona los modelos por rol (lead = fase 1, lead_phase2, worker, worker_light, scout); el Revisor se ejecuta en lead. Roles, valores predeterminados, anulaciones, niveles: models.md. Si no estás en el modelo Lead de la fase actual, dile al usuario cómo cambiar (/model, /effort en Claude Code); no continúes en silencio — excepto en una ejecución single, que conserva el modelo Lead de la fase 1.

Sesiones y contexto

• Fase 1: pasos 0–2 en el modelo Lead de la fase 1.
• Fase 2: pasos 3–6. split: comienza con Reanudar en una sesión nueva con el modelo Lead de la fase 2, leyendo solo el plan, el estado y las especificaciones de la etapa actual (autocontenido). single: continúa en la misma sesión.

session_split (env SOP_SESSION_SPLIT): auto (predeterminado) = split para cualquier tarea de alto riesgo, tres o más tareas, o modo staged, de lo contrario single; always → split; never → single.

El checkpoint lo muestra; el usuario puede anularlo.

El estado de la ejecución reside en el directorio de ejecución (run.run_dir, <git common dir>/sop-run/): fuera de todo árbol de trabajo, compartido por todos los worktrees, mantenido entre sesiones. Nunca uses un bloc de notas de sesión.

Salida de comandos — ejecuta cada comando lint/test/build/DoD a través de bash SKILL_DIR/scripts/run_logged.sh <run dir>/logs/<slug>-<step>-<n>.log '<command>' (imprime exit=<rc> lines=<n> log=<path> + las últimas 40 líneas en caso de fallo). Lee más del registro solo cuando el resumen no explica el fallo. Nunca pongas la salida completa de los tests en el chat.

Flujo de trabajo

0. Pre-vuelo

bash SKILL_DIR/scripts/preflight.sh --agent <claude|gemini|codex> --fetch (tu propio runtime; --fetch actualiza primero un default_base remoto) imprime una línea JSON: runtime (nota worker, session_split), config (nota source_worktree, default_base, provision, max_parallel, auto_merge_risk, merge_method, auto_cleanup; layout), leftovers, run, pr, baseline, base_check, docker_pool. En un layout bare, ejecuta comandos de Lead git/test dentro de source_worktree. Actúa sobre:

1. run.has_state: true (ejecución en curso): pregunta al usuario si reanudar, limpiar (si todas las tareas tienen PRs esperando al usuario) o archivar (worktree.sh rundir --archive) y empezar de nuevo.
2. leftovers (tareas de ejecuciones anteriores): menciónalas.
3. config.offer_bare_migration: true: ejecuta bash SKILL_DIR/scripts/migrate_to_bare.sh (simulación en seco), pregunta al usuario si desea convertir al formato de worktree bare-repo, formateado según bare-layout.md. Solo ante un sí explícito: migrate_to_bare.sh --apply, vuelve a ejecutar preflight.sh, relee la documentación del agente desde el nuevo source_worktree. Bloqueado o rechazado → layout estándar.
4. pr.ok: false: la ejecución solo hace commit local; el checkpoint lo indica. Nota pr.into. Reglas de merge: execution-plan.md.
5. base_check.match: false, fetch_error o error: acuerda la base con el usuario primero.
6. docker_pool.error: dile al usuario que la capacidad es desconocida; si no, docker: false: saltar; si no, free < config.max_parallel: advierte (el paso 3 vuelve a comprobar).
7. baseline = salida de git status --porcelain=v1 && git diff HEAD | sha256sum, ya ejecutado en source_worktree. Consérvalo para state.json.

1. Auditoría (solo lectura)

• Establece el alcance con el usuario (rutas; seguridad / rendimiento / deuda / brechas de especificación).
• Escanea estáticamente; para un alcance grande, primero barre con scouts de solo lectura en paralelo (scout.md) y verifica sus pistas. Ejecuta los comandos existentes de lint/test/type-check del proyecto para verificar mediante run_logged.sh (registra audit-<n>.log); no instales herramientas ni cambies la configuración.
• Produce un informe de brechas: hallazgos numerados con archivo:línea, severidad, evidencia, solución propuesta. Agrúpalos en tareas de tamaño Worker con listas blancas pequeñas y sin superposición.
• Con varias tareas, redacta el plan de ejecución según execution-plan.md: sin dependencias → independent (todo en paralelo); relacionadas → staged (etapas ordenadas por dependencias, paralelo dentro de cada etapa, cada una construida sobre el resultado integrado de la etapa anterior).

2. Especificación (checkpoint)

• Para cada tarea, completa worker-spec-template.md y elige su nivel de Worker (models.md). Completa las Reglas del repositorio desde la documentación del agente (AGENTS.md, CLAUDE.md, también en los directorios que toca la lista blanca): comandos de test/lint, banderas, reglas de idioma; añade dificultades del repositorio desde tu memoria y cualquier worker_notes. Los Workers no pueden ver tu contexto. Escribe los comandos de DoD según lo que requieran esas reglas.
• Guarda en el directorio de ejecución, nunca en un worktree: gap-report.md, plan.md, spec-<slug>.md, <slug>.wl.
• Verificación de superposición por etapa: bash SKILL_DIR/scripts/check_scope.sh --overlap <source_worktree> <slug>.wl...; OVERLAP → redivide o re-etapa; verifica cada POSSIBLE manualmente.
• Simulación en seco de DoD: ejecuta cada comando de DoD de las tareas independent / etapa 1 en source_worktree a través de run_logged.sh (registra <slug>-dry-<n>.log), anota su clase en la especificación, corrige los BROKEN (detalles); etapa 2+ en el paso 3.
• Crítico del plan: con 2+ tareas, modo staged, una tarea de alto riesgo, o a petición: un crítico de solo lectura (modelo lead solo si una tarea es de alto riesgo, si no lead_phase2); decide sobre cada hallazgo según plan-critic.md. Una ronda.
• Muestra el informe del checkpoint y espera aprobación antes del paso 3, en el formato de execution-plan.md §3. La aprobación debe cubrir explícitamente: en modo staged los commits locales y merges entre etapas; siempre el commit automático, el push, el PR y — según la columna Merge — el merge después de APPROVE; con auto_cleanup la limpieza después de cada merge; y, cuando la línea del pool de Docker dice prune: ask, worktree.sh pool --prune. Redacción en §3.
• Límite de fase: después de la aprobación, escribe <run dir>/state.json (§7) con phase: 2 y la session acordada, luego:

  • split, dile al usuario:

    Plan aprobado y guardado en <run dir>. Ejecuta /clear, cambia al Lead de la fase 2 (/model <lead_phase2.model>, /effort <lead_phase2.effort>), luego invoca este skill con resume.

    (Codex / Antigravity: inicia una nueva sesión en lead_phase2).

  • single: dile al usuario que el plan está guardado en <run dir> y la ejecución continúa aquí; ve al paso 3 sin cambiar de modelo (resume sigue funcionando).

Reanudar (fase 2)

Con resume: entrypoints.md.

Limpieza (después de que el usuario fusione)

Con cleanup: entrypoints.md.

Los pasos 3–5 se ejecutan una vez por etapa (independent = una sola etapa), en el orden del plan. Mantén state.json actualizado: actualiza el estado de una tarea al enviarla, en cada ronda de revisión, aprobación o diferimiento, y la etapa cuando se integra.

3. Worktree + envío

1. Antes de crear los worktrees de la etapa: bash SKILL_DIR/scripts/worktree.sh pool. docker: false → saltar; error → dile al usuario, pregunta primero. Si no, si free < el número de tareas de la etapa, ejecuta worktree.sh pool --prune solo si la aprobación lo cubre (elimina todas las redes Compose no utilizadas de los proyectos; se recrean), si no, pregunta al usuario.
2. Para cada tarea: bash SKILL_DIR/scripts/worktree.sh create <slug> [--base <ref>] (etapa 1: omitir --base; etapa 2+: --base sop-stage/<n-1>; worktree.sh path <slug> previsualiza). Verifica provisioned en la salida; detente si falta una entrada esperada. Etapa 2+: simulación en seco de la DoD de cada tarea en su nuevo worktree a través de run_logged.sh antes del envío (solo correcciones de ruta/banderas; si no, pregunta).
3. Inserta la ruta del worktree y la base en cada especificación, luego envía todos los Workers de la etapa en paralelo según dispatch.md, cada uno en el modelo de su worker_tier (worker / worker_light; tope max_parallel).

4. Verificación (por tarea)

1. bash SKILL_DIR/scripts/check_scope.sh <worktree> <whitelist-file> debe salir con 0; en caso de infracciones, el Worker las revierte (cuenta como una ronda de revisión).
2. Vuelve a ejecutar cada comando de DoD tú mismo en el worktree a través de run_logged.sh (registros <slug>-gate-r<round>-<n>.log); todos deben salir con 0.

5. Revisión (por tarea) + barrera de etapa

Sigue review-checklist.md: el diff se revisa en el modelo lead (split: subagente Revisor de solo lectura, tú verificas sus hallazgos; single: tú) contra la base registrada. Emite APPROVE o REQUEST_CHANGES con hallazgos numerados archivo:línea; itera con el Worker como máximo 3 rondas, luego escala al usuario. Las tareas iteran de forma independiente. Una tarea light que falla la ronda 1 se reenvía en el modelo worker (models.md).

• independent: al APPROVE, haz commit, push, abre el PR con pr.sh y fúndelo cuando las reglas de auto-merge lo permitan, sin preguntar (§4a).
• staged: cuando cada tarea de la etapa esté APPROVED, haz commit local de cada una, ejecuta worktree.sh integrate <n> --base <stage base> sop/<slug>..., y pasa la verificación de integración (toda la DoD de la etapa en el worktree de la etapa) antes de la siguiente etapa; conflictos, fallos de integración y escaladas: execution-plan.md. Con más etapas por venir, establece current_stage a la siguiente en state.json y continúa en la misma sesión. Ofrece una sesión nueva (/clear, luego resume) solo cuando el contexto ha crecido mucho (dos etapas ejecutadas, o muchas rondas de revisión); es seguro aquí.

6. Cierre

1. Vuelve a ejecutar el comando de baseline del paso 0; debe coincidir, si no, informa exactamente qué cambió en el checkout principal — no lo "arregles" tú mismo.
2. PRs: los PRs independent ya existen (§5); enumera cada uno como merged, open (razón) o solo local. staged: abre el PR único desde el último sop-stage/<n> con pr.sh (merge según auto_merge_risk, §6).
3. Limpieza de los worktrees y ramas de los PRs fusionados, worktree.sh sync, y — una vez que todas las tareas estén limpias — worktree.sh rundir --archive. Sin preguntas solo con auto_cleanup en la aprobación, si no pregunta primero. Nunca --force.
4. Resumen final: hallazgos abordados, diferidos (y dependientes bloqueados), ramas/PRs con estado, qué se limpió y qué queda. Si los PRs esperan al usuario, termina con: después de fusionarlos, invoca este skill con cleanup.

Scripts y layout

Uso, códigos de salida, rutas de worktree, aprovisionamiento, anulaciones de configuración: scripts-and-layout.md.