Skip to content

agent-responsibility-matrix.md

Latest commit

 

History

History
444 lines (336 loc) · 16 KB

agent-responsibility-matrix.md

File metadata and controls

444 lines (336 loc) · 16 KB
Raw

Matriz de Responsabilidades dos Agentes - Melhorias Estratégicas do Epic 3

🌐 EN | PT | ES

Versão do Documento: 1.0 Última Atualização: 2025-10-25 Autor: Winston (@architect) + Sarah (@po) Contexto: Epic 3 Fase 2 - Melhorias Estratégicas (Stories 3.13-3.19)

Resumo Executivo

Este documento define limites claros de responsabilidade para todos os agentes AIOX, com foco particular em:

  1. Centralização do GitHub DevOps - Apenas @github-devops pode fazer push para repositório remoto
  2. Especialização em Arquitetura de Dados - @data-architect gerencia banco de dados/ciência de dados
  3. Divisão de Gerenciamento de Branches - @sm (local) vs @github-devops (remoto)
  4. Restrições de Operações Git - Quais agentes podem fazer o quê com git/GitHub

Regra Crítica: SOMENTE o agente @github-devops pode executar git push para o repositório remoto.

Matriz de Operações Git/GitHub

Autoridade Total de Operações

Operação @github-devops @dev @sm @qa @architect @po
git push ✅ ÚNICO ❌ ❌ ❌ ❌ ❌
git push --force ✅ ÚNICO ❌ ❌ ❌ ❌ ❌
gh pr create ✅ ÚNICO ❌ ❌ ❌ ❌ ❌
gh pr merge ✅ ÚNICO ❌ ❌ ❌ ❌ ❌
gh release create ✅ ÚNICO ❌ ❌ ❌ ❌ ❌
git commit ✅ ✅ ❌ ❌ ❌ ❌
git add ✅ ✅ ❌ ❌ ❌ ❌
git checkout -b ✅ ✅ ✅ ❌ ❌ ❌
git merge (local) ✅ ✅ ✅ ❌ ❌ ❌
git status ✅ ✅ ✅ ✅ ✅ ❌
git log ✅ ✅ ✅ ✅ ✅ ❌
git diff ✅ ✅ ✅ ✅ ✅ ❌

Mecanismo de Aplicação

Defesa em Profundidade Multi-Camada:

  1. Git Pre-Push Hook (Aplicação Primária)

    • Localização: .git/hooks/pre-push
    • Verificações: Variável de ambiente $AIOX_ACTIVE_AGENT
    • Ação: Bloqueia push se agent != "github-devops"

  2. Variáveis de Ambiente (Detecção em Runtime)

    export AIOX_ACTIVE_AGENT="github-devops"
export AIOX_GIT_PUSH_ALLOWED="true"

  3. Definições dos Agentes (Documentação + Restrições)

    • Todos os agentes têm seção git_restrictions
    • Listas claras de allowed_operations e blocked_operations
    • Mensagens de redirecionamento apontam para @github-devops

  4. Configuração da IDE (Camada de UX)

    {
  "agents": {
    "dev": { "blockedOperations": ["push"] },
    "github-devops": { "allowedOperations": ["*"] }
  }
}

Limites de Responsabilidade dos Agentes

@architect (Winston) 🏗️

Papel: Arquiteto de Sistema Holístico e Líder Técnico Full-Stack

Escopo Principal:

  • Arquitetura de sistema (microsserviços, monolito, serverless, híbrido)
  • Seleção de stack tecnológico (frameworks, linguagens, plataformas)
  • Planejamento de infraestrutura (implantação, escalabilidade, monitoramento, CDN)
  • Design de API (REST, GraphQL, tRPC, WebSocket)
  • Arquitetura de segurança (autenticação, autorização, criptografia)
  • Arquitetura de frontend (gerenciamento de estado, roteamento, performance)
  • Arquitetura de backend (limites de serviço, fluxos de eventos, cache)
  • Preocupações transversais (logging, monitoramento, tratamento de erros)

Operações Git: Somente leitura (status, log, diff) - SEM PUSH

Delegar Para:

  • @data-architect: Design de schema de banco de dados, otimização de queries, pipelines ETL
  • @github-devops: Git push, criação de PR, configuração de CI/CD

Manter:

  • Seleção de tecnologia de banco de dados da perspectiva do sistema
  • Integração da camada de dados com arquitetura da aplicação
  • Design de workflow Git (estratégia de branching)

@data-architect (DataArch) 🗄️

Papel: Arquiteto de Banco de Dados e Especialista em Workflow de Ciência de Dados

Escopo Principal:

  • Design de schema de banco de dados (tabelas, relacionamentos, índices, constraints)
  • Modelagem de dados (estratégias de normalização, desnormalização)
  • Otimização de queries e tuning de performance
  • Design e implementação de pipelines ETL
  • Arquitetura de workflow de ciência de dados
  • Otimização específica do Supabase (políticas RLS, realtime, edge functions)
  • Governança de dados (segurança, privacidade, conformidade)

Operações Git: Commits locais (add, commit) - SEM PUSH

Colaborar Com:

  • @architect: Seleção de tecnologia de banco de dados, integração da camada de dados
  • @github-devops: Push de arquivos de migração após commit local

Especialização: Expert em Supabase (Row-Level Security, realtime, edge functions, storage)

@dev (James) 💻

Papel: Engenheiro de Software Sênior Expert e Especialista em Implementação

Escopo Principal:

  • Implementação de código a partir de stories
  • Debugging e refatoração
  • Testes unitários/de integração
  • Operações git locais (add, commit, checkout, merge)
  • Execução de tarefas de story

Operações Git:

  • ✅ Permitido: add, commit, status, diff, log, branch, checkout, merge (local)
  • ❌ Bloqueado: push, gh pr create

Workflow Após Story Completa:

  1. Marcar status da story: "Pronta para Revisão"
  2. Notificar usuário: "Story completa. Ative @github-devops para fazer push das mudanças"
  3. NÃO tentar git push

@sm (Bob) 🏃

Papel: Scrum Master Técnico - Especialista em Preparação de Stories

Escopo Principal:

  • Criação e refinamento de stories
  • Gerenciamento de epics e decomposição
  • Assistência no planejamento de sprint
  • Gerenciamento de branches locais durante desenvolvimento
  • Orientação de resolução de conflitos (merges locais)

Operações Git:

  • ✅ Permitido: checkout -b (criar feature branches), branch (listar), merge (local)
  • ❌ Bloqueado: push, gh pr create, deleção de branch remota

Workflow de Gerenciamento de Branch:

  1. Story inicia → Criar feature branch local: git checkout -b feature/X.Y-story-name
  2. Desenvolvedor faz commits localmente
  3. Story completa → Notificar @github-devops para fazer push e criar PR

Nota: @sm gerencia branches LOCAIS durante desenvolvimento, @github-devops gerencia operações REMOTAS

@github-devops (DevOps) 🚀

Papel: Gerente de Repositório GitHub e Especialista DevOps

AUTORIDADE PRINCIPAL: ÚNICO agente autorizado a fazer push para repositório remoto

Operações Exclusivas:

  • ✅ git push (TODAS as variantes)
  • ✅ gh pr create, gh pr merge
  • ✅ gh release create
  • ✅ Deleção de branch remota

Escopo Principal:

  • Integridade e governança do repositório
  • Execução de quality gate pré-push (lint, test, typecheck, build)
  • Versionamento semântico e gerenciamento de releases
  • Criação e gerenciamento de pull requests
  • Configuração de pipeline CI/CD (GitHub Actions)
  • Limpeza de repositório (branches obsoletas, arquivos temporários)
  • Geração de changelog

Quality Gates (Obrigatórios Antes do Push):

  • npm run lint → PASS
  • npm test → PASS
  • npm run typecheck → PASS
  • npm run build → PASS
  • Status da Story = "Done" ou "Pronta para Revisão"
  • Sem mudanças não commitadas
  • Sem conflitos de merge
  • Confirmação do usuário obrigatória

Lógica de Versionamento Semântico:

  • MAJOR (v4 → v5): Breaking changes, redesign de API
  • MINOR (v4.31 → v4.32): Novas features, compatível com versões anteriores
  • PATCH (v4.31.0 → v4.31.1): Apenas correções de bugs

@qa (Quinn) 🧪

Papel: Arquiteto de Testes e Consultor de Qualidade

Escopo Principal:

  • Revisão abrangente de arquitetura de testes
  • Decisões de quality gate (PASS/PREOCUPAÇÕES/FAIL/DISPENSADO)
  • Avaliação de riscos e estratégia de testes
  • Rastreabilidade de requisitos
  • Consultivo (não bloqueia, fornece recomendações)

Operações Git: Somente leitura (status, log, diff para revisão) - SEM COMMIT, SEM PUSH

Nota: QA revisa código mas não commita. @dev commita, @github-devops faz push.

@po (Sarah) 📝

Papel: Product Owner Técnica e Guardiã de Processos

Escopo Principal:

  • Gerenciamento de backlog e refinamento de stories
  • Validação de critérios de aceitação
  • Planejamento de sprint e priorização
  • Aderência a processos e garantia de qualidade
  • Integridade do ecossistema de documentação

Operações Git: Nenhuma (papel de PO é não-técnico em relação ao git)

Nota: @po valida requisitos e prioriza trabalho, não interage com git.

Exemplos de Workflow

Cenário 1: Desenvolvimento Padrão de Story

1. Usuário: "Iniciar Story 3.14: Agente GitHub DevOps"

2. @sm ativa:
   - Cria feature branch: `git checkout -b feature/3.14-github-devops-agent`
   - Passa para @dev

3. @dev ativa:
   - Implementa tarefas da story
   - Commita localmente: `git add . && git commit -m "feat: implement pre-push quality gate"`
   - Marca story: "Pronta para Revisão"
   - Notifica usuário: "Story completa. Ative @github-devops para fazer push"

4. @github-devops ativa:
   - Executa *pre-push (quality gates)
   - TODOS PASSAM → Apresenta resumo
   - Usuário confirma
   - Faz push: `git push -u origin feature/3.14-github-devops-agent`
   - Cria PR: `gh pr create --title "Story 3.14: GitHub DevOps Agent" --body "..."`
   - Reporta: "✅ Push realizado com sucesso. PR #123 criada: https://github.com/..."

Cenário 2: Design de Schema de Banco de Dados

1. Usuário: "Projetar schema de banco de dados para autenticação de usuário"

2. @architect ativa:
   - Analisa requisitos do sistema
   - Decide: "Usar Supabase para persistência"
   - Delega: "Ativando @data-architect para design do schema"

3. @data-architect ativa:
   - Executa *design-schema
   - Cria tabelas: users, sessions, auth_providers
   - Projeta políticas RLS para segurança em nível de linha
   - Gera migração: `20251025_create_auth_schema.sql`
   - Commita localmente: `git add migrations/ && git commit -m "feat: add auth schema"`
   - Notifica: "Schema projetado. Ative @github-devops para fazer push da migração"

4. @github-devops ativa:
   - Executa *pre-push (quality gates)
   - Faz push da migração para o repositório

Cenário 3: Criação de Release

1. Usuário: "Criar release v4.32.0"

2. @github-devops ativa:
   - Executa *version-check
   - Analisa commits desde v4.31.0
   - Recomenda: "Bump de versão MINOR (novas features, compatível com versões anteriores)"
   - Usuário confirma: v4.32.0
   - Executa *pre-push (quality gates)
   - Gera changelog a partir dos commits
   - Cria tag: `git tag v4.32.0`
   - Faz push: `git push && git push --tags`
   - Cria release no GitHub: `gh release create v4.32.0 --title "Release v4.32.0" --notes "..."`
   - Reporta: "✅ Release v4.32.0 criada: https://github.com/.../releases/v4.32.0"

Arquitetura de Dados vs Arquitetura de Sistema

Matriz de Comparação

Responsabilidade @architect @data-architect
Seleção de tecnologia de banco de dados (visão de sistema) ✅ 🤝 Colaborar
Design de schema de banco de dados ❌ Delegar ✅ Principal
Otimização de queries ❌ Delegar ✅ Principal
Design de pipeline ETL ❌ Delegar ✅ Principal
Design de API para acesso a dados ✅ Principal 🤝 Colaborar
Cache em nível de aplicação ✅ Principal 🤝 Consultar
Otimizações específicas de banco (RLS, triggers) ❌ Delegar ✅ Principal
Workflows de ciência de dados ❌ Delegar ✅ Principal
Infraestrutura para banco de dados (escalabilidade, replicação) ✅ Principal 🤝 Consultar

Padrão de Colaboração

Pergunta: "Qual banco de dados devemos usar?"

  • @architect responde: Perspectiva de sistema (custo, implantação, habilidades da equipe, infraestrutura)
  • @data-architect responde: Perspectiva de dados (padrões de query, escalabilidade, adequação do modelo de dados)
  • Resultado: Recomendação combinada

Pergunta: "Projetar schema de banco de dados"

  • @architect: Delega para @data-architect
  • @data-architect: Projeta schema, cria migrações
  • @architect: Integra schema no sistema (API, ORM, cache)

Responsabilidades de Gerenciamento de Branch

Branches Locais (@sm durante desenvolvimento)

Responsabilidades:

  • Criar feature branches quando story inicia
  • Gerenciar branches de trabalho do desenvolvedor
  • Limpeza de branch local (deletar branches locais mergeadas)

Comandos:

# @sm pode executar:
git checkout -b feature/3.14-github-devops
git branch -d feature/old-branch
git merge feature/branch-to-integrate

Branches Remotas (@github-devops para repositório)

Responsabilidades:

  • Fazer push de branches para remoto
  • Deletar branches remotas (limpeza)
  • Gerenciar branches de release
  • Proteger branch main/master

Comandos:

# SOMENTE @github-devops pode executar:
git push -u origin feature/3.14-github-devops
git push origin --delete feature/old-branch
gh pr create
gh pr merge

Checklist de Implementação para Story 3.14

  • Criar Git Pre-Push Hook

    • Localização: .git/hooks/pre-push
    • Conteúdo: Verificar $AIOX_ACTIVE_AGENT, bloquear se != "github-devops"
    • Tornar executável: chmod +x .git/hooks/pre-push

  • Atualizar Todas as Definições de Agentes (DONE ✅)

    • @architect - Adicionado git_restrictions e limites de colaboração
    • @dev - Removido git push, adicionado redirecionamento de workflow
    • @sm - Clarificado gerenciamento apenas de branch local
    • @qa - Operações git somente leitura
    • @github-devops - Criado com autoridade exclusiva de push
    • @data-architect - Criado com especialização em dados

  • Atualizar Scripts de Ativação de Agentes

    • Adicionar configuração de variável de ambiente: AIOX_ACTIVE_AGENT={agent_id}
    • Configurar AIOX_GIT_PUSH_ALLOWED apropriadamente

  • Configuração da IDE (.claude/settings.json)

    • Adicionar agents.{id}.blockedOperations para cada agente
    • Documentar no guia de setup da IDE

  • Atualizações de Documentação

    • Matriz de responsabilidade de agentes (este documento)
    • Atualizar git-workflow-guide.md
    • Atualizar docs de onboarding de desenvolvedor

  • Testes

    • Testar @dev tentando git push (deve ser bloqueado)
    • Testar @github-devops git push (deve funcionar)
    • Testar quality gates antes do push
    • Testar workflow de criação de PR

Considerações Futuras

Story 3.19: Camada de Memória (Condicional)

Se aprovada após auditoria de utilitários (Story 3.17):

  • Camada de memória não precisa de restrições git (utilitário, não agente)
  • Integração com agentes não muda limites de responsabilidade

Squads

Se novos agentes forem adicionados via Squads:

  • Padrão: SEM capacidade de git push
  • Processo de Exceção: Deve ser explicitamente aprovado pela PO e justificado
  • Aplicação: Pre-push hook bloqueia automaticamente a menos que ID do agente esteja na whitelist

Resumo

Pontos-Chave:

  1. ✅ Apenas @github-devops pode fazer push para repositório remoto (aplicado via git hooks)
  2. ✅ @architect gerencia arquitetura de sistema, @data-architect gerencia camada de dados
  3. ✅ @sm gerencia branches locais, @github-devops gerencia operações remotas
  4. ✅ Quality gates são obrigatórios antes de qualquer push
  5. ✅ Todos os agentes têm limites claros e documentados

Aplicação: Multi-camada (hooks + variáveis de ambiente + definições de agentes + config da IDE)

Status: ✅ Pronto para implementação na Story 3.14

Documento mantido por @architect (Winston) e @po (Sarah) Última revisão: 2025-10-25