Evolucionar un Equipo Existente

Mejora, reestructura o crea una variante especializada de un equipo que fue creado originalmente con create-team. Este procedimiento cubre el lado de mantenimiento del ciclo de vida del equipo: evaluar brechas frente a la plantilla y los patrones de coordinación, aplicar mejoras específicas a la composición y el flujo de trabajo, actualizar versiones y mantener sincronizados el registro y las referencias cruzadas.

Cuándo Usar

• El roster de miembros de un equipo está desactualizado tras añadir, eliminar o evolucionar agentes
• Los comentarios de usuarios revelan cuellos de botella en el flujo de trabajo, traspasos poco claros o perspectivas faltantes
• El patrón de coordinación ya no encaja en el flujo de trabajo real del equipo (p.ej., hub-and-spoke debería ser parallel)
• Se necesita una variante especializada junto a la original (p.ej., r-package-review y r-package-review-security-focused)
• Las responsabilidades de los miembros del equipo se superponen y necesitan límites más claros
• El bloque CONFIG está desincronizado con la descripción en prosa o la lista de miembros
• Un equipo necesita dividirse en dos equipos más pequeños o dos equipos necesitan fusionarse

Entradas

• Requerido: Ruta al archivo de equipo existente que se va a evolucionar (p.ej., teams/r-package-review.md)
• Requerido: Disparador de evolución (comentario, nuevos agentes, desajuste de coordinación, solapamiento de alcance, problemas de rendimiento, evolución de agentes)
• Opcional: Magnitud objetivo del incremento de versión (parche, menor, mayor)
• Opcional: Si crear una variante especializada en lugar de refinar en el lugar (por defecto: refinar en el lugar)

Procedimiento

Paso 1: Evaluar el Equipo Actual

Leer el archivo de equipo existente y evaluar cada sección frente a la plantilla de equipo (teams/_template.md):

Sección	Qué verificar	Problemas comunes
Frontmatter	Todos los campos requeridos (name, description, lead, version, author, coordination, members[])	Falta tags, version obsoleta, coordination incorrecta
Purpose	Justificación clara de múltiples agentes (al menos dos especialidades distintas)	Podría manejarse por un solo agente
Team Composition	La tabla coincide con los miembros del frontmatter, sin responsabilidades superpuestas	Tabla obsoleta, áreas de enfoque duplicadas
Coordination Pattern	Coincide con el flujo de trabajo real, diagrama ASCII presente	Patrón incorrecto para el flujo de trabajo
Task Decomposition	Desglose por fases con tareas concretas por miembro	Tareas vagas, fases faltantes
CONFIG Block	YAML válido entre marcadores, coincide con frontmatter y prosa	Desincronizado, falta blocked_by, YAML inválido
Usage Scenarios	2-3 prompts de activación realistas	Texto de marcador
Limitations	3-5 restricciones honestas	Faltantes o demasiado genéricas
See Also	Enlaces válidos a agentes miembros, equipos relacionados, guías	Enlaces obsoletos

# Leer el archivo del equipo
cat teams/<team-name>.md

# Verificar que todos los agentes miembros aún existen
grep "id:" teams/<team-name>.md | while read line; do
  agent=$(echo "$line" | grep -oP '(?<=id: )[\w-]+')
  grep "id: $agent" agents/_registry.yml || echo "MISSING: $agent"
done

# Comprobar si alguna guía referencia este equipo
grep -r "<team-name>" guides/*.md

Esperado: Una lista de brechas específicas, debilidades u oportunidades de mejora organizadas por sección.

En caso de fallo: Si el archivo del equipo no existe o no tiene frontmatter, esta habilidad no aplica — usar create-team en su lugar para crearlo desde cero.

Paso 2: Reunir los Requisitos de Evolución

Identificar y categorizar qué desencadenó la evolución:

Disparador	Ejemplo	Alcance típico
Comentario del usuario	"Las revisiones tardan demasiado, los agentes duplican esfuerzo"	Afinar responsabilidades o cambiar patrón
Nuevo agente disponible	Se creó el agente api-security-analyst	Añadir miembro
Agente evolucionado	code-reviewer ganó nuevas habilidades	Actualizar responsabilidades del miembro
Agente eliminado	deprecated-agent fue retirado	Eliminar miembro, reasignar tareas
Desajuste de coordinación	Equipo secuencial tiene subtareas independientes	Cambiar a parallel
Expansión de alcance	El equipo necesita cubrir el despliegue, no solo la revisión	Añadir miembro o crear variante
Equipo demasiado grande	6+ miembros causando sobrecarga de coordinación	Dividir en dos equipos
Equipo demasiado pequeño	Un solo miembro hace la mayor parte del trabajo	Fusionar con otro equipo o añadir miembros

Documentar los cambios específicos necesarios antes de editar:

- Frontmatter: añadir nuevo miembro `api-security-analyst` con rol "API Security Reviewer"
- Team Composition: añadir fila a la tabla de composición
- Task Decomposition: añadir tareas de revisión de seguridad API a la fase de ejecución
- CONFIG block: añadir entradas de miembro y tareas
- See Also: añadir enlace al nuevo archivo de agente

Esperado: Una lista concreta de cambios, cada uno mapeado a una sección específica del archivo del equipo.

En caso de fallo: Si los cambios no están claros, consultar al usuario para aclaración antes de proceder. Los objetivos de evolución vagos producen mejoras vagas.

Paso 3: Elegir el Alcance de la Evolución

Usar esta matriz de decisión para determinar si refinar en el lugar o crear una variante:

Criterios	Refinamiento (en el lugar)	Variante Especializada (nuevo equipo)
ID del equipo	Sin cambios	Nuevo ID: <team>-<specialty>
Ruta del archivo	Mismo archivo .md	Nuevo archivo en teams/
Incremento de versión	Parche o menor	Comienza en 1.0.0
Coordinación	Puede cambiar	Puede diferir del original
Registro	Actualizar entrada existente	Nueva entrada añadida
Equipo original	Modificado directamente	Intacto, gana referencia cruzada en Ver También

Refinamiento: Elegir al ajustar miembros, afinar responsabilidades, corregir el bloque CONFIG o cambiar el patrón de coordinación. El equipo mantiene su identidad.

Variante: Elegir cuando la versión evolucionada serviría a un caso de uso sustancialmente diferente, requeriría un patrón de coordinación diferente o apuntaría a una audiencia diferente. El original permanece como está para su caso de uso existente.

Decisiones adicionales de alcance:

Situación	Acción
El equipo tiene 6+ miembros y es lento	Dividir en dos equipos enfocados
Dos equipos de 2 cubren dominios adyacentes	Fusionar en un equipo de 3-4
El patrón de coordinación del equipo es incorrecto	Refinamiento — cambiar patrón en el lugar
El equipo necesita un líder completamente diferente	Refinamiento si el líder existe; crear agente primero si no

Esperado: Una decisión clara — refinamiento, variante, división o fusión — con justificación.

En caso de fallo: Si no estás seguro, por defecto optar por refinamiento. Dividir o fusionar equipos tiene mayor radio de impacto y debe confirmarse con el usuario.

Paso 4: Aplicar los Cambios al Archivo del Equipo

Para Refinamientos

Editar el archivo de equipo existente directamente. Mantener la consistencia en todas las secciones que hacen referencia a la composición del equipo:

1. members[] del frontmatter: Añadir, eliminar o actualizar entradas de miembros (cada uno con id, role, responsibilities)
2. Tabla de Team Composition: Debe coincidir exactamente con los miembros del frontmatter
3. Coordination Pattern: Actualizar la prosa y el diagrama ASCII si el patrón cambia
4. Task Decomposition: Revisar las fases y las tareas por miembro para reflejar la nueva composición
5. Bloque CONFIG: Actualizar las listas de members y tasks para que coincidan (ver Paso 5)
6. Usage Scenarios: Revisar si los disparadores de activación del equipo cambiaron
7. Limitations: Actualizar para reflejar nuevas restricciones o eliminar las resueltas
8. See Also: Actualizar los enlaces de agentes y añadir referencias a nuevos equipos o guías relacionados

Seguir estas reglas de edición:

• Preservar todas las secciones existentes — añadir contenido, no eliminar secciones
• Al añadir un miembro, añadirlo a TODOS: frontmatter, tabla de composición, descomposición de tareas y bloque CONFIG
• Al eliminar un miembro, eliminarlo de TODOS esos lugares y reasignar sus tareas
• Verificar que cada agente miembro existe: grep "id: agent-name" agents/_registry.yml
• Mantener al líder en la lista de miembros — el líder siempre es un miembro

Para Variantes

# Copiar el original como punto de partida
cp teams/<team-name>.md teams/<team-name>-<specialty>.md

# Editar la variante:
# - Cambiar `name` a `<team-name>-<specialty>`
# - Actualizar `description` para reflejar el alcance especializado
# - Ajustar el patrón `coordination` si es necesario
# - Restablecer `version` a "1.0.0"
# - Modificar miembros, tareas y bloque CONFIG para el caso de uso especializado
# - Referenciar el original en Ver También como alternativa de propósito general

Esperado: El archivo del equipo (refinado o nueva variante) pasa la lista de verificación de evaluación del Paso 1, con todas las secciones internamente consistentes.

En caso de fallo: Si una edición rompe la consistencia interna (p.ej., el bloque CONFIG lista un miembro no en el frontmatter), comparar el members[] del frontmatter con la tabla de Team Composition, Task Decomposition y el bloque CONFIG para encontrar el desajuste.

Paso 4.5: Sincronizar Variantes Traducidas

Obligatorio cuando existen traducciones. Este paso se aplica tanto a autores humanos como a agentes de IA que siguen este procedimiento. No omitir — los valores obsoletos de source_commit hacen que npm run validate:translations informe advertencias falsas de obsolescencia en todas las localizaciones.

Comprobar si existen traducciones para el equipo evolucionado y actualizarlas para reflejar el nuevo estado de la fuente:

# Comprobar las traducciones existentes
ls i18n/*/teams/<team-name>.md 2>/dev/null

Si existen traducciones

1. Obtener el hash del commit de la fuente actual:

SOURCE_COMMIT=$(git rev-parse HEAD)

2. Actualizar source_commit en el frontmatter de cada archivo traducido:

for locale_file in i18n/*/teams/<team-name>.md; do
  sed -i "s/^source_commit: .*/source_commit: $SOURCE_COMMIT/" "$locale_file"
done

3. Marcar archivos para re-traducción incluyendo las localizaciones afectadas en el mensaje de commit:

evolve-team(<team-name>): <descripción de los cambios>

Translations flagged for re-sync: de, zh-CN, ja, es
Changed sections: <lista de secciones que cambiaron>

4. Regenerar los archivos de estado de traducción:

npm run translation:status

Si no existen traducciones

No se requiere ninguna acción. Continuar al Paso 5.

Para Variantes

Aplazar la traducción de nuevas variantes hasta que la variante se estabilice (1-2 versiones). Traducir una variante v1.0 que puede cambiar sustancialmente para v1.2 desperdicia esfuerzo. Añadir traducciones después de que la variante haya sido refinada al menos una vez.

Esperado: Todos los archivos traducidos tienen source_commit actualizado al commit actual. El mensaje de commit indica qué localizaciones necesitan re-traducción y qué secciones cambiaron. npm run translation:status sale con 0.

En caso de fallo: Si sed no coincide con el campo del frontmatter, el archivo traducido puede tener un formato no estándar. Abrirlo manualmente y verificar que tiene source_commit en su frontmatter YAML. Si el campo falta, el archivo no se generó correctamente — regenerar con npm run translate:scaffold -- teams.

Paso 5: Actualizar el Bloque CONFIG

El bloque CONFIG entre <!-- CONFIG:START --> y <!-- CONFIG:END --> debe mantenerse sincronizado con las secciones en prosa. Tras cualquier cambio de miembro o tarea:

1. Verificar que cada agent en los members del CONFIG coincide con un miembro en el frontmatter
2. Verificar que cada assignee en las tasks del CONFIG coincide con un ID de agente miembro
3. Actualizar las dependencias blocked_by si el orden de las tareas cambió
4. Asegurar que la tarea de síntesis/final hace referencia a todas las tareas prerequisito

team:
  name: <team-name>
  lead: <lead-agent>
  coordination: <pattern>
  members:
    - agent: <agent-id>
      role: <role-title>
      subagent_type: <agent-id>
  tasks:
    - name: <task-name>
      assignee: <agent-id>
      description: <one-line>
    - name: synthesize-results
      assignee: <lead-agent>
      description: Collect and synthesize all member outputs
      blocked_by: [<prior-task-names>]

Esperado: El YAML del CONFIG es válido, todos los agentes y tareas son consistentes con el resto del archivo, y blocked_by forma un DAG válido.

En caso de fallo: Analizar el YAML del bloque CONFIG por separado para encontrar errores de sintaxis. Verificar cada assignee frente a la lista de members.

Paso 6: Actualizar la Versión y los Metadatos

Incrementar el campo version en el frontmatter siguiendo el versionado semántico:

Tipo de cambio	Incremento de versión	Ejemplo
Corrección de redacción, actualización de Ver También	Parche: 1.0.0 → 1.0.1	Enlace de agente obsoleto corregido
Nuevo miembro añadido, tareas revisadas	Menor: 1.0.0 → 1.1.0	Añadido miembro security-analyst
Patrón de coordinación cambiado, equipo reestructurado	Mayor: 1.0.0 → 2.0.0	Cambiado de hub-and-spoke a parallel

También actualizar:

• Fecha updated a la fecha actual
• tags si la cobertura de dominio del equipo cambió
• description si el propósito del equipo es materialmente diferente
• coordination si el patrón cambió

Esperado: version y updated del frontmatter reflejan la magnitud y fecha de los cambios. Las nuevas variantes comienzan en "1.0.0".

En caso de fallo: Si olvidas incrementar la versión, la próxima evolución no tendrá forma de distinguir el estado actual del anterior. Siempre incrementar antes de confirmar.

Paso 7: Actualizar el Registro y las Referencias Cruzadas

Para Refinamientos

Actualizar la entrada existente en teams/_registry.yml para que coincida con el frontmatter revisado:

# Encontrar la entrada del registro del equipo
grep -A 10 "id: <team-name>" teams/_registry.yml

Actualizar los campos description, lead, members y coordination para que coincidan con el archivo del equipo. No se necesita cambio de recuento.

Para Variantes

Añadir el nuevo equipo a teams/_registry.yml:

- id: <team-name>-<specialty>
  path: <team-name>-<specialty>.md
  lead: <lead-agent>
  members: [agent-1, agent-2, agent-3]
  coordination: <pattern>
  description: One-line description of the specialized variant

Luego:

1. Incrementar total_teams al inicio del registro
2. Añadir referencia cruzada Ver También en el equipo original apuntando a la variante
3. Añadir referencia cruzada Ver También en la variante apuntando al original

Ejecutar la automatización de README:

npm run update-readmes

Esperado: La entrada del registro coincide con el frontmatter del archivo del equipo. npm run update-readmes termina con 0. Para variantes, total_teams es igual al número real de entradas de equipos.

En caso de fallo: Si el recuento del registro es incorrecto, contar entradas con grep -c "^ - id:" teams/_registry.yml y corregir el recuento. Si la automatización de README falla, verificar que package.json existe y js-yaml está instalado.

Paso 8: Validar el Equipo Evolucionado

Ejecutar la lista de verificación de validación completa:

• El archivo del equipo existe en la ruta esperada
• El frontmatter YAML se analiza sin errores
• version fue incrementada (refinamiento) o establecida en "1.0.0" (variante)
• La fecha updated refleja hoy
• Todas las secciones requeridas presentes: Purpose, Team Composition, Coordination Pattern, Task Decomposition, Configuration, Usage Scenarios, Limitations, See Also
• El members[] del frontmatter coincide con la tabla de Team Composition
• Los miembros del bloque CONFIG coinciden con los miembros del frontmatter
• Las tareas del bloque CONFIG tienen asignados válidos y referencias blocked_by
• Todos los IDs de agentes miembros existen en agents/_registry.yml
• El agente líder aparece en la lista de miembros
• Ningún dos miembros comparten la misma responsabilidad principal
• La entrada del registro existe y coincide con el frontmatter
• Para variantes: el recuento total_teams coincide con el recuento real en disco
• Las referencias cruzadas son bidireccionales (original ↔ variante)
• git diff no muestra eliminaciones accidentales del contenido original

# Verificar frontmatter
head -25 teams/<team-name>.md

# Verificar que todos los agentes miembros existen
for agent in agent-a agent-b agent-c; do
  grep "id: $agent" agents/_registry.yml
done

# Contar equipos en disco vs registro
ls teams/*.md | grep -v template | wc -l
grep total_teams teams/_registry.yml

# Revisar todos los cambios
git diff

Esperado: Todos los elementos de la lista de verificación pasan. El equipo evolucionado está listo para confirmar.

En caso de fallo: Abordar cada elemento fallido individualmente. Los problemas más comunes tras la evolución son la desviación del bloque CONFIG (miembros o tareas que no coinciden con la prosa) y una fecha updated olvidada.

Validación

• El archivo del equipo existe y tiene frontmatter YAML válido
• El campo version refleja los cambios realizados
• La fecha updated es actual
• Todas las secciones presentes e internamente consistentes
• El members[] del frontmatter, la tabla de Team Composition y el bloque CONFIG están sincronizados
• Todos los IDs de agentes miembros existen en agents/_registry.yml
• El agente líder está en la lista de miembros
• El YAML del bloque CONFIG es válido y analizable
• La entrada del registro coincide con el archivo del equipo
• Para variantes: nueva entrada en teams/_registry.yml con la ruta correcta
• Para variantes: recuento total_teams actualizado
• Las referencias cruzadas son válidas (sin enlaces rotos en Ver También)
• git diff confirma que no se eliminó contenido accidentalmente

Errores Comunes

• Desviación del bloque CONFIG: El bloque CONFIG, el frontmatter y las secciones en prosa deben coincidir en miembros y tareas. Actualizar uno sin los demás es el error más común de evolución de equipos. Tras cada cambio, verificar los tres.
• Olvidar incrementar la versión: Sin incrementos de versión, no hay forma de rastrear qué cambió o cuándo. Siempre actualizar version y updated en el frontmatter antes de confirmar.
• Referencias de miembro huérfanas: Al eliminar un miembro, sus tareas en Task Decomposition y el bloque CONFIG deben reasignarse o eliminarse. Dejar asignados huérfanos causa fallos de activación.
• Patrón de coordinación incorrecto tras la evolución: Añadir miembros con capacidad parallel a un equipo secuencial, o hacer un equipo hub-and-spoke donde los agentes necesitan la salida de los demás. Reevaluar la decisión de patrón de create-team Paso 4 tras cualquier cambio estructural.
• Equipo demasiado grande tras añadir miembros: Los equipos con más de 5 miembros se vuelven difíciles de coordinar. Si la evolución empuja al equipo más allá de 5, considerar dividirlo en dos equipos enfocados en su lugar.
• Ver También obsoleto tras la creación de variante: Al crear una variante, tanto el original como la variante necesitan referenciarse mutuamente. Las referencias unidireccionales dejan el grafo incompleto.

Habilidades Relacionadas

• create-team — base para la creación de nuevos equipos; evolve-team asume que esto se siguió originalmente
• evolve-skill — el procedimiento paralelo para evolucionar archivos SKILL.md
• evolve-agent — el procedimiento paralelo para evolucionar definiciones de agentes
• commit-changes — confirmar el equipo evolucionado con un mensaje descriptivo