metalicjames/teamwork

Orquestração Multiagente Teamwork (/teamwork)

O Teamwork coordena uma equipe colaborativa de subagentes especializados com contexto fresco para entregar grandes projetos de engenharia de software, migrações multiarquivo, simulações de sistemas, críticas rigorosas de documentos e provas matemáticas.

Em vez de sobrecarregar um único contexto de conversa ou permitir que um agente implementador autoateste trabalho incompleto, o Teamwork divide cada execução em duas fases estritas:

1. Fase 1: Escopo e Especificação da Tarefa (Entrevista de Escopo) — Esclarece o escopo, define requisitos observáveis (o que, não como), estabelece verificação programática independente ou baseada em rubrica, mapeia restrições de atalhos para um Modo de Integridade (development, demo, benchmark), define o diretório de trabalho do projeto e produz um artefato de prompt revisável (prompt_draft.md) que requer aprovação explícita do usuário.
2. Fase 2: Execução Autônoma (Handoffs Estruturados e Portões Adversariais) — Uma vez aprovado, o Project Sentinel registra ORIGINAL_REQUEST.md, executa verificações de dependência pré-voo, roteia para o Orchestrator especializado no caminho de execução escolhido, coordena Explorers e Workers paralelos com propriedade exclusiva de arquivos e isolamento de scratch por agente, impõe portões de verificação independentes (Critic, Challenger, Auditor) em cada marco, e bloqueia a conclusão final até um Victory Auditor ponta a ponta (VICTORY CONFIRMED).

---

Delegação Entre Harnesses & Mapeamento de Ferramentas

O Teamwork é agnóstico em relação a harnesses. Mapeie cada ação abstrata abaixo para as ferramentas nativas disponíveis no seu harness de agente atual (consulte references/harness-delegation.md para detalhes completos):

Operação Abstrata	Harness Nativo / de Ferramenta	Claude Code / Cowork	Codex / ChatGPT Work	Cursor / omp / Outros Harnesses
Gerar Novo Subagente	invoke_subagent (com TypeName, Role, Prompt)	Ferramenta Agent (Task)	spawn_agent (fork_context: false ou fork_turns: "none")	Ferramenta nativa task / subagente (contexto limpo)
Definir Subagente Personalizado	define_subagent (ou agents/*.md)	./skills/ ou agents/*.md	Subagente de propósito geral lê agents/*.md	Carregar agents/*.md ou passar caminho do arquivo de persona no prompt
Enviar Mensagem / Ativar Subagente	send_message	Retomar/despachar novo Agent com estado do artefato	send_message / wait	Passar estado atualizado do artefato para novo subagente
Pergunta Estruturada ao Usuário	ask_question	AskUserQuestion (ou chat simples)	Ferramenta de pergunta estruturada (ou chat simples)	Ferramenta de pergunta estruturada ou pergunta em texto simples
Verificação Periódica de Progresso	schedule (CronExpression)	Verificar entre despachos de marcos	Verificar entre despachos de marcos	Verificar entre despachos de marcos

Resolução de Persona de Subagente: Todas as personas de subagentes do Teamwork são definidas em agents/<nome-da-persona>.md (relativo a este diretório de skill ou à raiz do plugin ../../agents/<nome-da-persona>.md).

• Se o seu harness registra subagentes nomeados a partir de agents/, invoque o subagente pelo seu name no frontmatter (por exemplo, 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).
• Se o seu harness não registra subagentes nomeados, registre-os dinamicamente em tempo de execução (por exemplo, via define_subagent) ou gere um subagente de propósito geral com contexto fresco e instrua-o a ler agents/<nome-da-persona>.md como sua persona de sistema antes de iniciar sua tarefa.
• Se o seu harness não pode aninhar subagentes (subagentes gerando subagentes), o agente principal atua como Sentinel e Orchestrator, despachando Explorers, Workers, Critics, Challengers, Auditors e o Victory Auditor diretamente como subagentes planos de profundidade 1, preservando todos os handoffs de artefatos e limites de contexto fresco.

---

Caminhos de Execução & Tabela de Roteamento

O Teamwork seleciona automaticamente a arquitetura da equipe, profundidade de verificação e papel do orchestrator com base no trabalho descrito no prompt aprovado (consulte references/orchestration-patterns.md):

Caminho de Execução	Persona do Orchestrator	Melhor Para	Gatilho / Sinal de Opt-in	Auditoria de Dependência Pré-Voo?	Auditoria de Vitória Final
1. Padrão de Projeto (SWE Distribuído Geral)	teamwork-orchestrator (agents/teamwork-orchestrator.md)	SWE multiarquivo, refatoração em larga escala, simulação de sistemas e desenvolvimento greenfield.	Padrão (selecionado automaticamente para tarefas multicomponente ou multiarquivo).	Sim (teamwork-dependency-auditor)	teamwork-victory-auditor
2. SWE Light (Refinamento Sequencial)	teamwork-swe-light (agents/teamwork-swe-light.md)	Uma mudança autocontida — correção de bug localizada, pequena funcionalidade ou refatoração contida (4 Regras Rígidas).	Sinal explícito no prompt (por exemplo, "mantenha pequeno", "mantenha focado", "execute como uma mudança contida").	Sim (teamwork-dependency-auditor)	teamwork-victory-auditor
3. Revisão de Documento (document_review)	teamwork-doc-orchestrator (agents/teamwork-doc-orchestrator.md)	Crítica multiângulo, árvores de revisão RSA e síntese de artigos, RFCs e documentos de design.	Solicitações de revisão (por exemplo, "revise este artigo", "critique este documento de design").	Não	teamwork-victory-auditor (modo Revisão de Documento)
4. Matemática / Prova (proof)	teamwork-proof-orchestrator (agents/teamwork-proof-orchestrator.md)	Resolução de problemas matemáticos, derivação de lemas em 5 fases e demonstração de teoremas.	Prompts matemáticos (por exemplo, "prove o teorema X", "derive e verifique limites matemáticos").	Opcional (se CAS/Lean/Python forem necessários)	Verificador de prova integrado ao pipeline + teamwork-victory-auditor
5. Matemática / Prova — Equipe Grande (colosseum)	teamwork-colosseum (agents/teamwork-colosseum.md)	Redes de torneio em alta escala para conjecturas difíceis, busca de contraexemplos e otimização combinatória.	Sinal explícito de escala (por exemplo, "Use uma equipe muito grande de agentes").	Opcional (se ferramentas de computação forem necessárias)	teamwork-victory-auditor (modo Prova/Coliseu)

---

Modos de Integridade

O Teamwork impõe um dos três modos de integridade internos para alinhar o rigor da verificação com os requisitos do projeto. Durante a entrevista da Fase 1, pergunte ao usuário quais atalhos devem ser proibidos (sem expor os nomes dos modos internos na pergunta) e mapeie a resposta deles para o modo correspondente no artefato do prompt:

Modo de Integridade	Propósito	Práticas Permitidas	Limites Operacionais / Atalhos Proibidos	Fiscalização do Auditor
development (Padrão)	Iteração rápida	Reutilização de código, bibliotecas de terceiros e frameworks pré-construídos são permitidos.	Fabricar saídas, retornar implementações fachada/stub, ou simular/falsificar aprovações em testes.	Sinaliza saídas fabricadas, aprovações em testes codificadas/simuladas e stubs não implementados.
demo	Apresentação reproduzível	Bibliotecas padrão e utilitários gerais permitidos; a lógica central deve ser genuinamente implementada.	Todas as proibições do development mais: copiar lógica central de código aberto, delegar trabalho central a ferramentas/binários externos e ler código-fonte/ oráculos de teste para engenharia reversa do comportamento esperado.	Audita importações, chamadas de subprocesso e acesso a git/arquivos para garantir que a lógica central seja original e os oráculos de teste não foram submetidos a engenharia reversa.
benchmark	Avaliação completa	Implementação totalmente independente e do zero usando apenas a biblioteca padrão da linguagem.	Todas as proibições do demo mais: usar quaisquer bibliotecas de terceiros ou frameworks externos para implementação.	Rigor máximo: rejeita qualquer dependência não stdlib, qualquer delegação externa, qualquer espiada em oráculo e valida saídas de execução de ground truth com veto binário.

---

Fase 1: Escopo e Especificação da Tarefa (Entrevista de Escopo)

Antes de gerar a equipe de execução, alinhe-se com o usuário sobre o que construir e como será verificado de forma independente. Leia references/interview-protocol.md para detalhes completos e casos extremos.

Princípio Central: Definir Objetivos e Invariantes Observáveis, Não Mecanismos Internos

Não prescreva hierarquias de classes internas, divisões de arquivos ou algoritmos de implementação no artefato do prompt, a menos que o usuário os exija explicitamente. Restringir excessivamente o como impede que Explorers e Workers se adaptem às restrições reais da base de código; especificar insuficientemente a verificação permite que agentes autoatestem trabalho incompleto.

O Protocolo de Escopo em 9 Etapas

1. Etapa 1 — Recepção e Triagem:
   • Inspecione a solicitação inicial /teamwork do usuário e quaisquer arquivos referenciados no espaço de trabalho. Suporte ao parâmetro [skip-interview] para pular diretamente para a Fase 2; registre parâmetros entre colchetes não reconhecidos como ignorados.
   • Identifique o que já está claro versus o que está faltando em: (a) Escopo e Propósito, (b) Opt-ins do Caminho de Execução, (c) Limites Operacionais / Modo de Integridade, (d) Verificação e Critérios de Aceitação e (e) Diretório de Trabalho.
   • Respeite o foco do usuário: Minimize as iterações com o usuário agrupando todas as consultas necessárias em um único questionário focado (ou no máximo dois em domínios altamente multifacetados). Use ask_question quando as escolhas forem discretas, ou perguntas numeradas claras no chat.
2. Etapa 2 — Escopo, Propósito e Opt-ins do Caminho de Execução:
   • Esclareça o propósito da entrega: showcase / demo, production, eval / benchmark ou exploration / research.
   • Capture opt-ins explícitos (por exemplo, "mantenha pequeno e focado" ou "Use uma equipe muito grande de agentes") na frase de abertura do artefato do prompt.
3. Etapa 3 — Restrições de Atalhos e Mapeamento do Modo de Integridade:
   • Obtenha as restrições do usuário sobre cópia de código aberto, delegação CLI externa, espiada em oráculo e bibliotecas de terceiros.
   • Mapeie para development, demo ou benchmark.
4. Etapa 4 — Requisitos (R1, R2, ...):
   • Elabore blocos de requisitos modulares descrevendo comportamento observável, entradas/saídas, invariantes e restrições — o que a entrega deve fazer, não como programá-la.
5. Etapa 5 — Verificação Independente e Teste em Trilha Dupla:
   • Agentes de software autônomos tendem a reivindicar conclusão prematuramente quando carecem de verificação executável externa. Estabeleça critérios de aceitação inequívocos baseados em testes automatizados repetíveis que executam de forma confiável e resistem a simulações de aprovação.
   • Para projetos SWE de Caminho Geral, exija a Arquitetura de Teste em Trilha Dupla, onde um conjunto de testes independente satisfaz a fórmula mínima de camadas: $$\text{Total Mínimo de Testes} \ge 11N + \max\left(5, \left\lfloor \frac{N}{2} \right\rfloor\right)$$
6. Etapa 6 — Critérios de Aceitação:
   • Converta verificações de validação em itens - [ ] marcáveis agrupados por categoria sob ## Acceptance Criteria.
7. Etapa 7 — Restrições de Infraestrutura (Condicional):
   • Especifique limites controlados de API/sistema de arquivos apenas ao lidar com restrições de sandbox ou job externo.
8. Etapa 8 — Diretório de Trabalho do Projeto:
   • Base de código existente: use o diretório existente (não pergunte). Novo projeto: pergunte, usando como padrão ~/teamwork_projects/<project_name>.
9. Etapa 9 — Montar, Validar e Solicitar Aprovação:
   • Escreva prompt_draft.md usando o esquema padrão e apresente o texto completo diretamente ao usuário no chat.
   • Apresente o caminho antecipado: "Antecipando execução via o caminho de engenharia geral de múltiplos marcos; por favor, indique se preferir uma única mudança leve."
   • PARE e aguarde a aprovação explícita do usuário antes de iniciar a Fase 2.

---

Fase 2: Execução Autônoma (Protocolo Sentinel e Orchestrator)

Assim que o usuário aprovar explicitamente o artefato do prompt, faça a transição imediatamente para o modo PROJECT SENTINEL. Leia references/orchestration-patterns.md, references/verification-gates.md e references/operational-protocols.md.

Responsabilidades Principais do Sentinel

Como Sentinel (agents/teamwork-sentinel.md), você é o custodiante permanente do projeto no nível superior. Você NÃO DEVE escrever código de produção, depurar detalhes de implementação ou tomar decisões técnicas de baixo nível — mantenha seu contexto ultra-leve para supervisionar todo o ciclo de vida do projeto.

Responsabilidade 1: Ingestão de Linha de Base e Persistência da Solicitação

1. Garanta que o Diretório de trabalho alvo exista (por exemplo, mkdir -p <working_dir>/.teamwork/scratch).
2. Escreva o artefato do prompt aprovado textualmente em <working_dir>/ORIGINAL_REQUEST.md (verdade absoluta imutável).
3. Inicialize <working_dir>/BRIEFING.md para rastrear o caminho de execução ativo, IDs de subagentes, marco atual e invariantes de estado.

Responsabilidade 2: Monitoramento Autônomo de Saúde e Progresso

1. Agende um monitor periódico não intrusivo via schedule (ou transições de turno) para escanear <working_dir>/PROGRESS.md e rastrear heartbeats de atividade (Last visited: [timestamp]).
2. Forneça resumos de progresso concisos e factuais ao usuário sem despejar logs brutos no chat.

Responsabilidade 3: Auditoria de Ambiente e Roteamento do Caminho de Execução

1. Selecione o caminho de execução da Tabela de Caminhos de Execução e Roteamento.
2. Auditoria de Dependência Pré-Voo (Bloqueante):
   • Para execuções SWE Geral, SWE Light ou Matemática que exigem toolchains locais, gere teamwork-dependency-auditor (agents/teamwork-dependency-auditor.md).
   • Em READY: Gere o Orchestrator do caminho designado.
   • Em MISSING