GSD + Agent Teams — LABS

Cómo combinar GSD (meta-prompting y spec-driven development) con Agent Teams nativo de Claude Code para resolver el context rot y conseguir ejecución paralela real en proyectos complejos.

// 01 — Qué es GSD

Get Shit Done es un sistema de meta-prompting, context engineering y spec-driven development para Claude Code. Su función principal es resolver el context rot — la degradación de calidad que ocurre cuando Claude acumula demasiado contexto en una sola sesión.

Repositorio: https://github.com/gsd-build/get-shit-done

// 02 — Qué son los Agent Teams

Funcionalidad nativa de Claude Code para orquestar múltiples instancias trabajando en paralelo. Una sesión actúa como team lead y coordina a los teammates, que trabajan de forma independiente con su propio context window y se comunican via un sistema de inboxes.

A diferencia de los subagents, los teammates pueden mensajearse entre ellos, compartir una task list con dependencias y reclamar tareas automáticamente del pool.

⚠ WARN

Feature experimental. Activar con CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 en settings.json.

// 03 — Por qué combinarlos

Cada uno cubre lo que el otro no tiene. El CLAUDE.md es el pegamento — todos los teammates lo leen automáticamente al arrancar.

Capa	GSD	Agent Teams
Spec y contexto estructurado	✓	✗
Ejecución paralela real	✗	✓
Comunicación peer-to-peer entre agentes	✗	✓
Persistencia de estado entre sesiones	✓ STATE.md	✗
Commits atómicos por tarea	✓	manual
Context fresco por tarea	✓	✓

// 04 — Setup

1 — Instalar GSD

npx get-shit-done-cc@latest
# Elegir: Claude Code + global

Verificar dentro de Claude Code: /gsd:help

2 — Activar Agent Teams

// .claude/settings.json
{
  "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}

3 — Instalar el skill de integración

mkdir -p ~/.claude/skills/execute-phase-teams/
# Guardar SKILL.md en ese directorio (ver sección 07)

4 — Terminal recomendada

# Con tmux (ver teammates en paneles separados)
tmux new-session -s dev
claude

# O forzar backend
export CLAUDE_CODE_SPAWN_BACKEND=tmux

5 — Permisos

claude --dangerously-skip-permissions

O permisos granulares en .claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git add:*)", "Bash(git commit:*)",
      "Bash(git status:*)", "Bash(mkdir:*)",
      "Bash(cat:*)", "Bash(ls:*)"
    ]
  }
}

// 05 — Flujo completo

/gsd:new-project

Inicialización: preguntas → research → requirements → roadmap

/gsd:discuss-phase N

Captura tus decisiones de implementación antes de planificar

/gsd:plan-phase N

Research + planes XML atómicos + verificación automática

04
/execute-phase-teams N  ← nuestro skill
Reemplaza /gsd:execute-phase — usa Agent Teams nativo para ejecución paralela real

/gsd:verify-work N

UAT manual — confirmas que funciona de verdad

/gsd:complete-milestone

Archiva el milestone y tagea el release

/gsd:new-milestone [name]

Empieza la siguiente versión con el mismo flujo

// 06 — Comandos GSD

Flujo principal

Comando	Qué hace
/gsd:new-project	Inicialización: preguntas → research → requirements → roadmap
/gsd:discuss-phase [N]	Captura decisiones de implementación antes de planificar
/gsd:plan-phase [N]	Research + planes XML atómicos + verificación
/gsd:execute-phase <N>	Ejecución con subagents (versión original de GSD)
/gsd:verify-work [N]	UAT manual
/gsd:audit-milestone	Verifica definition of done del milestone
/gsd:complete-milestone	Archiva milestone y tagea release
/gsd:new-milestone [name]	Empieza la siguiente versión

Navegación

Comando	Qué hace
/gsd:progress	Dónde estoy, qué viene después
/gsd:help	Todos los comandos
/gsd:update	Actualizar GSD

Gestión de fases

Comando	Qué hace
/gsd:add-phase	Añadir fase al roadmap
/gsd:insert-phase [N]	Insertar fase urgente entre fases
/gsd:remove-phase [N]	Eliminar fase futura
/gsd:pause-work	Crear handoff al parar a mitad de fase
/gsd:resume-work	Restaurar desde última sesión

Utilidades

Comando	Qué hace
/gsd:quick	Tarea ad-hoc con commits atómicos
/gsd:map-codebase	Analizar proyecto existente antes de new-project
/gsd:debug [desc]	Debug sistemático con estado persistente
/gsd:settings	Configurar modelo y agentes

Nuestro skill

Comando	Qué hace
/execute-phase-teams <N>	Reemplaza /gsd:execute-phase usando Agent Teams nativo

// 07 — El Skill

Guardar en ~/.claude/skills/execute-phase-teams/SKILL.md

---
name: execute-phase-teams
description: Executes a GSD phase using Claude Code native Agent Teams
  (TeammateTool). Use when the user runs /execute-phase-teams or asks
  to execute a GSD phase with agent teams.
disable-model-invocation: false
---

## Step 1 — Read context
.planning/PROJECT.md · REQUIREMENTS.md · STATE.md
.planning/phase-$ARGUMENTS/ (todos los archivos)

## Step 2 — Parse PLAN files
Extraer <task> blocks: <n> <files> <action> <verify> <done>
Identificar dependencias → agrupar en waves paralelas

## Step 3 — Create team
Teammate({ operation: "spawnTeam",
  team_name: "gsd-phase-$ARGUMENTS" })

## Step 4 — Create tasks
TaskCreate({ subject, description, activeForm })
TaskUpdate({ taskId: "B", addBlockedBy: ["A"] })

## Step 5 — Spawn teammates
Task({
  team_name: "gsd-phase-$ARGUMENTS",
  name: "<descriptive-name>",
  subagent_type: "general-purpose",
  prompt: "Claim #id → execute → verify → complete → notify lead",
  run_in_background: true
})
// Wave 1: lanzar todos simultáneamente
// Wave 2+: prompt con instrucción de esperar desbloqueo

## Step 6 — Monitor
TaskList() · leer inboxes/team-lead.json

## Step 7 — Commit por tarea
git add -A && git commit -m 'feat(phase-N): <task>'

## Step 8 — Shutdown + cleanup
requestShutdown → esperar approvals → cleanup

⚡ KEY

La garantía de que usa Agent Teams está en los tool calls explícitos (Teammate, Task con team_name), no en instrucciones de lenguaje natural.

// 08 — Arquitectura Agent Teams

File structure

~/.claude/teams/{team}/ ├── config.json # miembros └── inboxes/ ├── team-lead.json ├── worker-1.json └── worker-2.json ~/.claude/tasks/{team}/ ├── 1.json # tarea #1 ├── 2.json └── 3.json

Backends

Backend	Visibilidad
in-process	Hidden (default)
tmux	Paneles visibles
iterm2	Split panes

Operaciones TeammateTool

Operación	Quién	Qué hace
spawnTeam	Lead	Crea el equipo
write	Any	Mensaje a un teammate específico
broadcast	Any	Mensaje a todos (caro, usar poco)
requestShutdown	Lead	Pide a un teammate que salga
approveShutdown	Teammate	Confirma y termina el proceso
cleanup	Lead	Elimina todos los recursos del equipo

// 09 — Archivos que genera GSD

Archivo	Qué contiene
PROJECT.md	Visión del proyecto, siempre cargado
REQUIREMENTS.md	Requisitos v1/v2 con trazabilidad de fases
ROADMAP.md	Fases y estado
STATE.md	Decisiones, blockers, posición actual
{phase}-CONTEXT.md	Decisiones capturadas en discuss-phase
{phase}-RESEARCH.md	Investigación del dominio
{phase}-{N}-PLAN.md	Plan atómico con estructura XML
{phase}-{N}-SUMMARY.md	Qué ocurrió, qué cambió
{phase}-VERIFICATION.md	Resultado de verificación automática
{phase}-UAT.md	Resultado del verify-work manual

// 10 — Cuándo usar qué

Situación	Usar
Tareas independientes en paralelo	Agent Teams
Research + implementación + tests simultáneos	Agent Teams
Bug fix, cambio pequeño, config	/gsd:quick
Tarea con muchas dependencias secuenciales	Sesión única
Proyecto nuevo, primera fase	GSD solo

// Fuentes

GSD — gsd-build/get-shit-done en GitHub
Agent Teams — Orchestrate teams of Claude Code sessions, documentación oficial
Claude Code — Settings y variables de entorno · Skills

GSD + Agent Teams_