metalicjames/teamwork

Orquestación de Múltiples Agentes Teamwork (/teamwork)

Teamwork coordina un equipo colaborativo de subagentes especializados con contexto nuevo para entregar proyectos grandes de ingeniería de software, migraciones de múltiples archivos, simulaciones de sistemas, críticas rigurosas de documentos y demostraciones matemáticas.

En lugar de sobrecargar un solo contexto de conversación o permitir que un agente implementador auto-certifique trabajo incompleto, Teamwork divide cada ejecución en dos fases estrictas:

1. Fase 1: Definición de Alcance y Especificación (Entrevista de Alcance) — Clarifica el alcance, define requisitos observables (qué, no cómo), establece verificación programática independiente o basada en rúbricas, mapea restricciones de atajos a un Modo de Integridad (development, demo, benchmark), establece el directorio de trabajo del proyecto y produce un artefacto de prompt revisable (prompt_draft.md) que requiere aprobación explícita del usuario.
2. Fase 2: Ejecución Autónoma (Transferencias Estructuradas y Puertas Adversariales) — Una vez aprobado, Project Sentinel registra ORIGINAL_REQUEST.md, ejecuta comprobaciones de dependencias previas al vuelo, enruta al Orquestador especializado para la ruta de ejecución elegida, coordina Exploradores y Trabajadores paralelos con propiedad exclusiva de archivos y aislamiento de espacio de trabajo por agente, impone puertas de verificación independientes (Crítico, Retador, Auditor) en cada hito y bloquea la finalización hasta que un Auditor de Victoria (VICTORIA CONFIRMADA) realice una verificación de extremo a extremo.

---

Delegación entre Arnés y Mapeo de Herramientas

Teamwork es independiente del arnés. Mapee cada acción abstracta a continuación a las herramientas nativas disponibles en su arnés de agente actual (consulte references/harness-delegation.md para obtener detalles completos):

Operación Abstracta	Arnés Nativo / Herramienta	Claude Code / Cowork	Codex / ChatGPT Work	Cursor / omp / Otros Arnés
Generar Nuevo Subagente	invoke_subagent (con TypeName, Role, Prompt)	Herramienta Agent (Task)	spawn_agent (fork_context: false o fork_turns: "none")	Herramienta task / subagente nativa (contexto limpio)
Definir Subagente Personalizado	define_subagent (o agents/*.md)	./skills/ o agents/*.md	El subagente de propósito general lee agents/*.md	Cargar agents/*.md o pasar ruta del archivo de persona en el prompt
Enviar Mensaje / Despertar Subagente	send_message	Reanudar/despachar nuevo Agent con estado del artefacto	send_message / wait	Pasar estado actualizado del artefacto a un nuevo subagente
Pregunta Estructurada al Usuario	ask_question	AskUserQuestion (o chat simple)	Herramienta de pregunta estructurada (o chat simple)	Herramienta de pregunta estructurada o pregunta en texto plano
Verificación Periódica de Progreso	schedule (CronExpression)	Verificar entre despachos de hitos	Verificar entre despachos de hitos	Verificar entre despachos de hitos

Resolución de Persona de Subagente: Todas las personas de los subagentes de Teamwork se definen en agents/<nombre-persona>.md (relativo a este directorio de habilidad o a la raíz del plugin ../../agents/<nombre-persona>.md).

• Si su arnés registra subagentes nombrados desde agents/, invoque el subagente por su name en el frontmatter (por ejemplo, teamwork-sentinel, teamwork-interviewer, teamwork-orchestrator, teamwork-swe-light, teamwork-doc-orchestrator, teamwork-proof-orchestrator, teamwork-colosseum, teamwork-explorer, teamwork-worker, teamwork-critic, teamwork-challenger, teamwork-auditor, teamwork-victory-auditor, teamwork-dependency-auditor).
• Si su arnés no registra subagentes nombrados, regístrelos dinámicamente en tiempo de ejecución (por ejemplo, mediante define_subagent) o genere un subagente de propósito general con contexto nuevo e indíquele que lea agents/<nombre-persona>.md como su persona de sistema antes de comenzar su tarea.
• Si su arnés no puede anidar subagentes (subagentes que generan subagentes), el agente principal actúa como Sentinel y Orquestador, despachando Exploradores, Trabajadores, Críticos, Retadores, Auditores y el Auditor de Victoria directamente como subagentes planos de profundidad 1, preservando todas las transferencias de artefactos y los límites de contexto nuevo.

---

Rutas de Ejecución y Tabla de Enrutamiento

Teamwork selecciona automáticamente la arquitectura del equipo, la profundidad de verificación y el rol del orquestador según el trabajo descrito en el prompt aprobado (consulte references/orchestration-patterns.md):

Ruta de Ejecución	Persona del Orquestador	Mejor Para	Disparador / Señal de Adhesión	Auditoría de Dependencias Pre-Vuelo?	Auditoría de Victoria Final
1. Patrón de Proyecto (SWE Distribuido General)	teamwork-orchestrator (agents/teamwork-orchestrator.md)	SWE de múltiples archivos, refactorización a gran escala, simulación de sistemas y desarrollo desde cero.	Predeterminado (seleccionado automáticamente para tareas de múltiples componentes o archivos).	Sí (teamwork-dependency-auditor)	teamwork-victory-auditor
2. SWE Ligero (Refinamiento Secuencial)	teamwork-swe-light (agents/teamwork-swe-light.md)	Un cambio autónomo: una corrección de errores localizada, una función pequeña o una refactorización contenida (4 reglas estrictas).	Señal de prompt explícita (p. ej., "mantenlo pequeño", "mantenlo enfocado", "ejecútalo como un cambio contenido").	Sí (teamwork-dependency-auditor)	teamwork-victory-auditor
3. Revisión de Documento (document_review)	teamwork-doc-orchestrator (agents/teamwork-doc-orchestrator.md)	Crítica desde múltiples ángulos, árboles de revisión RSA y síntesis de artículos, RFC y documentos de diseño.	Solicitudes de revisión (p. ej., "revisa este artículo", "critica este documento de diseño").	No	teamwork-victory-auditor (modo Revisión de Documento)
4. Matemáticas / Demostración (proof)	teamwork-proof-orchestrator (agents/teamwork-proof-orchestrator.md)	Resolución de problemas matemáticos, derivación de lemas en 5 fases y demostración de teoremas.	Prompts matemáticos (p. ej., "demuestra el teorema X", "deriva y verifica límites matemáticos").	Opcional (si se necesita CAS/Lean/Python)	Verificador de demostración integrado en la tubería + teamwork-victory-auditor
5. Matemáticas / Demostración — Equipo Grande (colosseum)	teamwork-colosseum (agents/teamwork-colosseum.md)	Redes de torneos a gran escala para conjeturas difíciles, búsqueda de contraejemplos y optimización combinatoria.	Señal de escala explícita (p. ej., "Usa un equipo muy grande de agentes").	Opcional (si se necesitan herramientas de cómputo)	teamwork-victory-auditor (modo Demostración/Colosseum)

---

Modos de Integridad

Teamwork aplica uno de tres modos de integridad internos para alinear el rigor de la verificación con los requisitos del proyecto. Durante la entrevista de la Fase 1, pregunte al usuario qué atajos deben estar prohibidos (sin exponer los nombres de los modos internos en la pregunta) y mapee su respuesta al modo correspondiente en el artefacto del prompt:

Modo de Integridad	Propósito	Prácticas Permitidas	Límites Operativos / Atajos No Permitidos	Aplicación del Auditor
development (Predeterminado)	Iteración rápida	Reutilización de código, bibliotecas de terceros y marcos preconstruidos permitidos.	Fabricar resultados, devolver implementaciones de fachada/placeholder, o simular/falsificar pases de pruebas.	Señala resultados fabricados, pases de pruebas codificados/simulados y placeholders no implementados.
demo	Presentación reproducible	Bibliotecas estándar y utilidades generales permitidas; la lógica central debe implementarse genuinamente.	Todas las prohibiciones de development más: copiar lógica central de código abierto, delegar trabajo central a herramientas/binarios externos y leer código fuente/oráculos de pruebas para realizar ingeniería inversa del comportamiento esperado.	Audita importaciones, llamadas a subprocesos y acceso a git/archivos para garantizar que la lógica central sea original y que los oráculos de prueba no hayan sido objeto de ingeniería inversa.
benchmark	Evaluación exhaustiva	Implementación totalmente independiente desde cero utilizando solo la biblioteca estándar del lenguaje.	Todas las prohibiciones de demo más: usar cualquier biblioteca de terceros o marco externo para la implementación.	Máximo rigor: rechaza cualquier dependencia no estándar, cualquier delegación externa, cualquier mirada furtiva al oráculo y valida los resultados de ejecución de la verdad fundamental con veto binario.

---

Fase 1: Definición de Alcance y Especificación (Entrevista de Alcance)

Antes de generar el equipo de ejecución, alinee con el usuario sobre qué construir y cómo se verificará de forma independiente. Lea references/interview-protocol.md para obtener detalles completos y casos extremos.

Principio Central: Definir Objetivos e Invariantes Observables, No Mecanismos Internos

No prescriba jerarquías de clases internas, divisiones de archivos o algoritmos de implementación en el artefacto del prompt a menos que el usuario lo solicite explícitamente. Restringir demasiado el cómo impide que los Exploradores y Trabajadores se adapten a las limitaciones reales del código base; especificar insuficientemente la verificación permite que los agentes auto-certifiquen trabajo incompleto.

El Protocolo de Definición de Alcance en 9 Pasos

1. Paso 1 — Recepción y Triaje:
   • Inspeccione la solicitud inicial /teamwork del usuario y cualquier archivo referenciado en el espacio de trabajo. Soporte el parámetro [skip-interview] para omitir directamente a la Fase 2; registre los parámetros de corchetes no reconocidos como ignorados.
   • Identifique lo que ya está claro frente a lo que falta en: (a) Alcance y Propósito, (b) Adhesiones a la Ruta de Ejecución, (c) Límites Operativos / Modo de Integridad, (d) Verificación y Criterios de Aceptación, y (e) Directorio de Trabajo.
   • Respete el enfoque del usuario: Minimice los intercambios con el usuario agrupando todas las consultas necesarias en un único cuestionario enfocado (o como máximo dos en dominios altamente multifacéticos). Use ask_question cuando las opciones sean discretas, o preguntas numeradas claras en el chat.
2. Paso 2 — Alcance, Propósito y Adhesiones a la Ruta de Ejecución:
   • Clarifique el propósito del entregable: showcase / demo, production, eval / benchmark, o exploration / research.
   • Capture las adhesiones explícitas (p. ej., "mantenlo pequeño y enfocado" o "Usa un equipo muy grande de agentes") en la primera oración del artefacto del prompt.
3. Paso 3 — Restricciones de Atajos y Mapeo del Modo de Integridad:
   • Obtenga las restricciones del usuario sobre la copia de código abierto, la delegación CLI externa, la mirada furtiva al oráculo y las bibliotecas de terceros.
   • Mapee a development, demo o benchmark.
4. Paso 4 — Requisitos (R1, R2, ...) :
   • Redacte bloques de requisitos modulares que describan el comportamiento observable, entradas/salidas, invariantes y restricciones — qué debe hacer el entregable, no cómo codificarlo.
5. Paso 5 — Verificación Independiente y Pruebas de Doble Vía:
   • Los agentes de software autónomos tienden a reclamar prematuramente la finalización cuando carecen de verificación ejecutable externa. Establezca criterios de aceptación inequívocos basados en pruebas automatizadas repetibles que se ejecuten de manera confiable y resistan los pases simulados.
   • Para proyectos SWE de ruta general, requiera la Arquitectura de Pruebas de Doble Vía, donde un conjunto de pruebas independiente satisfaga la fórmula de nivel mínimo: $$\text{Total de Pruebas Mínimas} \ge 11N + \max\left(5, \left\lfloor \frac{N}{2} \right\rfloor\right)$$
6. Paso 6 — Criterios de Aceptación:
   • Convierta las comprobaciones de verificación en elementos - [ ] marcables agrupados por categoría bajo ## Criterios de Aceptación.
7. Paso 7 — Restricciones de Infraestructura (Condicional):
   • Especifique límites controlados de API/sistema de archivos solo cuando se trate de restricciones de zona de pruebas o trabajos externos.
8. Paso 8 — Directorio de Trabajo del Proyecto:
   • Código base existente: use el directorio existente (no pregunte). Nuevo proyecto: pregunte, con valor predeterminado ~/teamwork_projects/<nombre_proyecto>.
9. Paso 9 — Ensamblar, Validar y Solicitar Aprobación:
   • Escriba prompt_draft.md usando el esquema estándar y presente el texto completo directamente al usuario en el chat.
   • Presente la ruta anticipada: "Anticipando la ejecución a través de la ruta de ingeniería general de múltiples hitos; indique si prefiere un único cambio ligero."
   • DETÉNGASE y espere la aprobación explícita del usuario antes de comenzar la Fase 2.

---

Fase 2: Ejecución Autónoma (Protocolo de Sentinel y Orquestador)

Una vez que el usuario aprueba explícitamente el artefacto del prompt, transicione inmediatamente al modo PROJECT SENTINEL. Lea references/orchestration-patterns.md, references/verification-gates.md y references/operational-protocols.md.

Responsabilidades Centrales de Sentinel

Como Sentinel (agents/teamwork-sentinel.md), usted es el administrador permanente del proyecto de nivel superior. NO DEBE escribir código de producción, depurar detalles de implementación o tomar decisiones técnicas de bajo nivel usted mismo — mantenga su contexto ultra-ligero para supervisar todo el ciclo de vida del proyecto.

Responsabilidad 1: Ingestión de Línea Base y Persistencia de Solicitudes

1. Asegúrese de que el Directorio de trabajo objetivo exista (p. ej., mkdir -p <directorio_trabajo>/.teamwork/scratch).
2. Escriba el artefacto del prompt aprobado textualmente en <directorio_trabajo>/ORIGINAL_REQUEST.md (verdad fundamental inmutable).
3. Inicialice <directorio_trabajo>/BRIEFING.md para rastrear la ruta de ejecución activa, los IDs de subagentes, el hito actual y los invariantes de estado.

Responsabilidad 2: Monitoreo Autónomo de Salud y Progreso

1. Programe un monitor periódico no intrusivo mediante schedule (o transiciones de turno) para escanear <directorio_trabajo>/PROGRESS.md y rastrear los latidos de actividad (Última visita: [marca de tiempo]).
2. Proporcione resúmenes de progreso concisos y fácticos al usuario sin volcar registros sin procesar en el chat.

Responsabilidad 3: Auditoría del Entorno y Enrutamiento de la Ruta de Ejecución

1. Seleccione la ruta de ejecución de la Tabla de Rutas de Ejecución y Enrutamiento.
2. Auditoría de Dependencias Pre-Vuelo (Bloqueante):
   • Para ejecuciones de SWE General, SWE Ligero o Matemáticas que requieran cadenas de herramientas locales, genere teamwork-dependency-auditor (agents/teamwork-dependency-auditor.md).
   • En LISTO: Genere el Orquestador de la ruta designada.
   • En FALTANTE

…

[truncado para traducción]