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 AIOS, com foco particular em:

Centralização do GitHub DevOps - Apenas @github-devops pode fazer push para repositório remoto
Especialização em Arquitetura de Dados - @data-architect gerencia banco de dados/ciência de dados
Divisão de Gerenciamento de Branches - @sm (local) vs @github-devops (remoto)
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:

Git Pre-Push Hook (Aplicação Primária)
- Localização: .git/hooks/pre-push
- Verificações: Variável de ambiente $AIOS_ACTIVE_AGENT
- Ação: Bloqueia push se agent != “github-devops”

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


export AIOS_ACTIVE_AGENT="github-devops"
export AIOS_GIT_PUSH_ALLOWED="true"

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

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:

Marcar status da story: “Pronta para Revisão”
Notificar usuário: “Story completa. Ative @github-devops para fazer push das mudanças”
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:

Story inicia → Criar feature branch local: git checkout -b feature/X.Y-story-name
Desenvolvedor faz commits localmente
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

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:

✅ Apenas @github-devops pode fazer push para repositório remoto (aplicado via git hooks)
✅ @architect gerencia arquitetura de sistema, @data-architect gerencia camada de dados
✅ @sm gerencia branches locais, @github-devops gerencia operações remotas
✅ Quality gates são obrigatórios antes de qualquer push
✅ 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