Evolucionar un Equipo Existente

Mejora, reestructura o crea una variante especializada de un equipo que fue creado originalmente con

create-team

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

name

description

lead

version

author

coordination

members[]

tags

version

coordination

blocked_by

# 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

Paso 2: Reunir los Requisitos de Evolución

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

api-security-analyst

code-reviewer

deprecated-agent

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:

<team>-<specialty>

.md

teams/

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:

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[]

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

npm run translation:status

En caso de fallo: Si

sed

source_commit

npm run translate:scaffold -- teams

Paso 5: Actualizar el Bloque CONFIG

El bloque CONFIG entre

<!-- CONFIG:START -->

<!-- CONFIG:END -->

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

En caso de fallo: Analizar el YAML del bloque CONFIG por separado para encontrar errores de sintaxis. Verificar cada

assignee

members

Paso 6: Actualizar la Versión y los Metadatos

Incrementar el campo

version

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

updated

"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

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

Actualizar los campos

description

lead

members

coordination

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

total_teams

En caso de fallo: Si el recuento del registro es incorrecto, contar entradas con

grep -c "^  - id:" teams/_registry.yml

package.json

js-yaml

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

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