Distintos agents no deben compartir el mismo árbol

Un problema frecuente con agents paralelos

s09–s11 permiten lanzar varios teammates a la vez, pero hay una trampa: todos trabajan en el mismo directorio. alice modifica auth.py y bob hace lo mismo al mismo tiempo — conflictos de git, archivos mezclados, tests que se contaminan entre sí.

La solución de s12 es git worktree: en el mismo repositorio, git worktree add permite hacer checkout de ramas distintas en directorios diferentes. Cada agent recibe su propio worktree y trabaja en su directorio sin ver lo que hacen los demás.

my-repo/                           # espacio de trabajo principal (para el lead)
.worktrees/
  alice-auth/                      # directorio aislado de alice
    (branch: wt/alice-auth)
  bob-api/                         # directorio aislado de bob
    (branch: wt/bob-api)
  index.json                       # registro de worktrees
  events.jsonl                     # log de eventos del ciclo de vida

Dos planos bien diferenciados

s12 divide explícitamente el sistema en dos planos:

• Plano de control (control plane): los archivos JSON en .tasks/. La task es la unidad abstracta de «qué hacer», con dependencias, owner y status.
• Plano de ejecución (execution plane): los directorios en .worktrees/. El worktree es el contenedor físico de «dónde hacerlo»: un directorio + una rama.

Ambos planos están vinculados de forma bidireccional mediante task.worktree y worktree.task_id.

Este desacoplamiento permite: reutilizar el mecanismo de gestión de tasks cambiando el entorno de ejecución (p. ej., contenedores Docker en lugar de git worktrees), o bien cambiar el mecanismo de tasks reutilizando los worktrees (p. ej., base de datos en lugar de archivos JSON).

Demostración del ciclo de vida

A continuación se recorre el flujo completo: create task → create worktree → run commands → keep o remove. Cada paso queda registrado en el event log (events.jsonl), que en producción sirve para la observabilidad.

keep vs remove

Cuando un worktree completa su misión hay dos finales posibles:

• remove: git worktree remove --force elimina el directorio. La rama también suele limpiarse. Equivale a «este experimento no sirve, lo descarto».
• keep: solo se marca status: kept en .worktrees/index.json; el directorio físico permanece. Equivale a «este resultado vale, espera a que lo fusione».

Patrón habitual: un subagent ejecuta un refactor experimental → sale bien → keep → revisión humana → merge a la rama principal → remove manual. ¿Salió mal? remove directamente y a empezar de cero.