vlv-code/manage-meta-project

Orquestração de Equipe de Agentes do Repositório (Orquestração de Equipe de Meta-Projeto)

Skill autônoma para compor, auditar e otimizar uma equipe de agentes especializados sob medida para o projeto. A skill analisa a estrutura do repositório, identifica especializações necessárias (Gerenciador GitHub, DevOps, QA, UI/UX, Segurança, Analista de Produto, Jurídico, Juiz de Consenso, etc.), materializa perfis isolados em .agents/team/ e estabelece protocolos de coordenação rigorosos (supervisão humana, transferências mediadas pelo usuário, notas imutáveis, arbitragem baseada em evidências).

---

Quando invocar a skill

• O usuário solicitar: "montar equipe de agentes", "alocar funções para o projeto", "configurar funções de agente", "auditar atividade da equipe", "revisar funções da equipe", "atualizar composição da equipe de agentes".
• Novas camadas de tecnologia importantes forem introduzidas no projeto (Docker, CI/CD, interface móvel, banco de dados, integrações de pagamento externas) que exigem governança de domínio dedicada.

---

Etapas de execução

Fase 1: Varredura Rápida do Repositório (Inspeção de Marcadores)

Antes de definir funções, o agente deve inspecionar os principais marcadores do projeto:

1. Infraestrutura de Hospedagem e CI: Presença de diretório .github/, workflows, modelos de pull request, modelos de issue.
2. Licenças e Governança de Código Aberto: Presença de LICENSE, copyrights, CONTRIBUTING.md, manifestos de dependências.
3. Containerização e Orquestração: Dockerfile, docker-compose*.yml, k8s/, helm/.
4. Infraestrutura de Teste: Diretório tests/, pytest.ini, vitest.config.*, fixtures de teste.
5. Segurança e Dados Sensíveis: Diretórios auth/, security/, manipulação de tokens, gerenciamento de sessão, lógica de criptografia.
6. Interface do Usuário e Design: Módulos frontend, HTML/CSS, layouts de teclado do bot, assets, design tokens.
7. Passaporte do Projeto Atual: Leitura de AGENTS.md e slices de .agents/project_knowledge/ (se já inicializado).
8. Stacks Secundárias / Poliglotas: Subdiretórios contendo arquivos fonte compilados ou de linguagens alternativas (ex.: .cpp, .c, .h, .rs, .go, .swift em client/, native/, core/, desktop/).

---

Fase 2: Dimensionamento Adaptável à Escala e Matriz de Competências Abertas

Antes de propor funções, o agente deve avaliar a escala do repositório e sintetizar uma equipe minimamente suficiente.

1. Dimensionamento do Repositório e Síntese de Funções

O agente estima o volume da base de código (LOC, profundidade de pastas, diversidade tecnológica):

• Repositório Micro / Pequeno (<10k linhas, desenvolvedor solo, 1–2 stacks principais): Sintetizar 2–3 funções combinadas agrupando blocos de competência da matriz em perfis unificados.

  • Trio Compacto Canônico:
    1. agent-dev-lead: Combina análise de entrada, decomposição de tarefas e implementação de código geral (agent-intake-dispatcher + agent-general-worker).
    2. agent-quality-guardian: Combina integridade do passaporte/conhecimento, suítes de teste unitário e auditoria de código morto (agent-meta-guardian + agent-qa-engineer + agent-deep-auditor).
    3. agent-github-steward: Higiene Git, commits convencionais, paridade Código-README e CI/CD.

• Repositório Médio (10k–50k linhas, equipe pequena, vários serviços): Implantar de 3 a 5 funções dedicadas adaptadas aos componentes principais.

• Repositório Grande / Empresarial (>50k linhas, monorepos, microsserviços): Implantar 6+ funções granulares com isolamento rigoroso de interesses.

• Regra de Isolamento de Stack Poliglota (Sem Combinações Tóxicas): Proibir estritamente agrupar stacks secundárias compiladas ou especializadas (C/C++, Rust, Go, GUI nativa) em agent-general-worker sem skills dedicadas. Quando uma stack poliglota for detectada, sintetizar uma função dedicada (ex.: agent-native-desktop com compiladores e toolchains nativos) ou mapear explicitamente os diretórios nativos para Zona Vermelha com um gatilho de Handoff obrigatório.

• Regra de Despachante Obrigatória (Sem Caos de Múltiplas Funções): Ao implantar 3 ou mais funções especializadas, é estritamente obrigatório implantar um despachante de entrada (agent-intake-dispatcher ou um despachante integrado em agent-dev-lead). Proibir deixar o usuário com um conjunto não roteado de várias funções isoladas sem um ponto de entrada único.

2. Catálogo de Competências Abertas (Matriz de Funções)

[!IMPORTANT] A tabela abaixo é um Catálogo de Competências Abertas, não uma enumeração imutável fechada. Agentes têm autonomia total para sintetizar funções combinadas ou inventar funções personalizadas e específicas de domínio (ex.: agent-solana-smart-contracts, agent-3d-designer, agent-data-pipeline) que correspondam à arquitetura real do repositório.

Categoria	Bloco de Competência / Função	Marcadores de Repositório	Habilidades Especializadas	Limites de Responsabilidade
Função Base	agent-general-worker(Trabalhador Padrão / Generalista)	Qualquer projeto (função padrão fundamental)	clean-codecode-reviewersystematic-debugging + habilidades de stack	Verde: implementação de funcionalidades, scripts, testes, correções de bugs.Amarelo: modificação de contratos de API e dependências.Vermelho: ações destrutivas e módulos de domínio especializados sem Handoff.
Orquestração	agent-intake-dispatcher(Despachante de Entrada)	Qualquer projeto com 2+ funções	prompt-engineeringbrainstorming	Verde: decomposição de requisições, preparação de prompt, execução Fast-Track.Vermelho: modificação direta do código fonte do projeto.
Orquestração	agent-meta-guardian(Guardião do Meta-Projeto)	Presença de estrutura meta-project	clean-codecode-reviewer	Verde: auditoria de passaporte, telemetria de funções, manutenção da base de conhecimento.Amarelo: arquivamento de funções inativas.Vermelho: exclusão da base de conhecimento sem confirmação do usuário.
Orquestração	agent-consensus-judge(Árbitro e Juiz de Consenso)	Projetos com decisões contestadas	architecture-decision-recordsapi-design-principles	Verde: comparação de argumentos, verificação empírica de testes.Amarelo: redação de ADRs.Vermelho: tomada de decisões sem evidências empíricas.
Orquestração	agent-deep-auditor(Auditor Profundo do Repositório Completo)	Base de código madura (>500 linhas)	systematic-debuggingcode-reviewer	Verde: geração de relatórios de auditoria, detecção de código morto, verificação de integridade de links/âncoras.Amarelo: registro de descobertas em observações.Vermelho: refatorações destrutivas, exclusão autônoma de arquivos.
Produto & Negócios	agent-product-roaster(Analista de Produto e Crítico)	Serviços de produto, startups	search_webbrainstorming	Verde: análise competitiva, teste de resistência de hipóteses.Vermelho: alteração da lógica de negócios sem especificações.
Produto & Negócios	agent-creative-director(Diretor Criativo)	Componentes de UI, web, temas, ícones	image-generatorcss-tokens	Verde: geração de paletas de cores, ícones, banners.Amarelo: edição de estilos globais.Vermelho: substituição da identidade da marca sem confirmação.
Produto & Negócios	agent-ui-ux-engineer(Engenheiro de UI/UX)	Frontend, bots, interfaces	semantic-htmlcss-coderui-ux-invariants	Verde: layout de componentes, estados FSM.Amarelo: alterações na navegação da tela.Vermelho: remoção de confirmações para ações destrutivas.
Produto & Negócios	agent-legal-compliance(Auditor Jurídico e de Conformidade)	LICENSE, repositórios públicos	Auditoria SPDX/SBOM	Verde: auditoria de licenças de dependências.Amarelo: atualização de NOTICE e copyrights de cabeçalho.Vermelho: alteração da licença do repositório.
Engenharia	agent-github-steward(Guru GitHub e Capitão de Release)	.github/, remotos git	github-managementgithub-actions-creatorclean-codecode-reviewer	Verde: higiene Git, commits convencionais, gerenciamento de branches, triagem de issues, rascunhos de release.Amarelo: verificação de paridade Código-README (garantir que instruções/CLI do README correspondem ao código real), ajuste de CI/CD.Vermelho: force-push, merge na main sem revisão, modificação de secrets.
Engenharia	agent-devops-infra(Arquiteto de Infraestrutura)	Dockerfile, docker-compose*	docker-expertkubernetes-architectbash-linux	Verde: contêineres de desenvolvimento, linting de configuração.Amarelo: otimização de build multi-estágios.Vermelho: secrets de produção, .env*, k8s de produção.
Engenharia	agent-qa-engineer(Engenheiro de Confiabilidade e QA)	tests/, frameworks de teste	test-driven-developmentverification-before-completion	Verde: escrita de testes unitários/integração, verificação de execução de testes.Amarelo: configuração de executores de teste e asserções de contrato.Vermelho: desativação de testes no CI.
Engenharia	agent-tech-writer(Redator Técnico)	docs/, OpenAPI, Swagger	mermaid-diagram-specialistopenapigoogle-style-guide	Verde: documentação de funções, README, diagramas.Amarelo: edição de especificações de API.Vermelho: publicação de documentos não revisados.

---

Fase 3: Auditoria da Equipe Existente (Poda de Funções e Coleta de Lixo)

Se o diretório .agents/team/ já existir:

1. Escanear todas as pastas: .agents/team/*/profile.md.
2. Inspecionar a tabela Registro de Chamadas de Função (Telemetria) em cada perfil.
3. Identificar funções inativas ou obsoletas:
   • Função foi inicializada, mas o registro contém apenas entrada inicial e nenhuma invocação real ocorreu por >30 dias.
   • A stack de tecnologia subjacente da função foi completamente removida do projeto (ex.: Docker foi descomissionado, mas agent-devops-infra permaneceu).
4. Compilar uma lista de candidatos para arquivamento em .agents/team/archive/<role_id>/.
5. Proibição de exclusão autônoma: Arquivar funções requer aprovação explícita do usuário!

---

Fase 4: Diálogo e Alinhamento com o Usuário

Gerar uma proposta de consultoria concisa para o usuário:

1. Marcadores detectados: Listar componentes do projeto identificados.
2. Funções recomendadas para ativar: Trabalhador base (agent-general-worker) + 2–4 funções de domínio mais críticas correspondentes aos marcadores detectados com breves justificativas.
3. Candidatos a arquivamento: (se existirem funções inativas).
4. Prompt de aprovação: "Aprovar o provisionamento das seguintes funções: [...]?"

---

Fase 5: Materialização de Perfis e Registro no Passaporte

Após a confirmação do usuário, realizar a gravação de produção:

1. Criar diretórios para cada função aprovada: .agents/team/<role_id>/.
2. Estruturar .agents/team/<role_id>/profile.md usando o modelo de referência templates/team/profile.md (ou o modelo incorporado abaixo):
   • Preencher ID da função, escopo, gatilhos de invocação, skills ativas e permissões de limite.
   • Inicializar tabela de telemetria com a data atual.
3. Criar um arquivo de notas privado: .agents/team/<role_id>/notes.md usando o modelo de referência templates/team/notes.md (ou o modelo incorporado abaixo).
4. Gerar o prompt de sistema inicial pronto para uso .agents/team/<role_id>/system_prompt.md usando templates/team/system_prompt.md (ou o modelo incorporado abaixo):
   • Preencher nome da função, propósito, stack de habilidades e permissões de limite canônicas (Verde / Amarelo / Vermelho).
5. Registrar funções no AGENTS.md raiz sob a seção:

   ## 6. Equipe de Agentes do Projeto (.agents/team/)
   - [{{ROLE_TITLE}}](.agents/team/{{ROLE_ID}}/profile.md) — {{ROLE_SCOPE}} (invocado por: {{ROLE_TRIGGERS}})
   

6. Gerar e exibir uma Tabela de Inicialização Rápida compacta para o usuário sem inundar o chat com texto de prompt longo:

   | Função | Propósito | Caminho do Prompt de Sistema | Palavras-chave de Gatilho |
   | :--- | :--- | :--- | :--- |
   | `agent-qa-engineer` | Teste e verificação | `.agents/team/agent-qa-engineer/system_prompt.md` | "executar testes", "verificar validação" |
   

---

Fase 6: Regras de Engajamento da Equipe

Todo agente da equipe deve aderir aos princípios centrais de coordenação:

1. Passividade Orientada pelo Usuário: Agentes nunca realizam ações em segundo plano sem instruções explícitas do usuário.
2. Transferências Mediadas pelo Usuário: Agentes não transferem controle diretamente uns aos outros, ignorando o usuário. Se uma tarefa exigir outro domínio, o agente retorna um pacote de transferência estruturado ao usuário:

   ### Pacote de Transferência de Tarefa: [agent-A -> agent-B]
   - Objetivo original: <o que foi solicitado>
   - Trabalho concluído: <lista de arquivos tocados>
   - Limite de transferência: <por que o agente atual parou>
   - Prompt recomendado para agent-B: <texto de prompt pronto para uso>
   

3. Limite de Cadeia de Transferência: Máximo de 2 transferências consecutivas (saltos = 2). Na 3ª etapa, o controle deve retornar ao humano.
4. Santidade das Anotações de Arquivos Compartilhados: Proibido editar anotações de outros em tasks.md, observations.md e architecture.md. Apenas próprio status/tarefas podem ser atualizados. Em caso de conflito, apresentar uma descrição clara da compensação ao usuário.
5. Propriedade Exclusiva de notes.md: Apenas o proprietário da função pode modificar .agents/team/<role>/notes.md.
6. Arbitragem Baseada em Evidências: agent-consensus-judge emite vereditos estritamente com base em resultados de teste, medições de benchmark e especificações oficiais.
7. Delegação de Subagentes Paralelos (dispatching-parallel-agents): Ao lidar com cargas de trabalho repetitivas, paralelas ou em lote de múltiplos diretórios (ex.: migrações de vários arquivos, geração de múltiplas suítes de teste, linting/auditorias em massa), agentes primários DEVEM invocar a skill dispatching-parallel-agents. O agente pai particiona a carga de trabalho entre subagentes transitórios por diretórios ou tarefas não sobrepostas, transmitindo invariantes do projeto de AGENTS.md e limites de função. O pai coordena a conclusão, executa testes de integridade e retorna um relatório consolidado ao usuário sem sobrecarregar o humano com transferências intermediárias de subagentes.
8. Disjuntor (Parada de Trabalho na 2ª Iteração): Se uma correção de bug exigir uma 2ª edição consecutiva no mesmo módulo ou produzir uma regressão secundária em código adjacente, cessar a escrita de código. Recuar, rastrear todo o ciclo de vida dos dados desde a origem até o consumidor, identificar a causa raiz arquitetural e apresentar análise sistêmica antes de propor qualquer novo diff.
9. Auditoria de Estado Alvo: Antes de modificar módulos não triviais em zonas Amarela ou Vermelha, determinar: Único

…

[truncado para tradução]