--- type: Document title: Agents description: Governance de agentes IA para este projecto tags: [dev, dashboard, governance, 5w2h, roles, relacionamentos, modelo, 2026-06-30, reorganizacao] --- # AGENTS.md — Governance de Agentes IA ## Identidade do Projecto - **Repositório**: DashDescomplicar - **Localização**: `/media/ealmeida/Dados/Dev/DashDescomplicar/` - **CRM**: Desk #2323 | Projecto: #65 (OKF Stack Completo) - **Modelo Base**: Hub → `05-Projectos/Modelo-Organizacao-Proc-Dev/` - **Versão Actual**: 2.7.3 (2026-06-30) ## Directrizes de Operação ### 1. PT-PT e Precisão Toda a interacção, comentários, commits e documentação devem ser em português europeu, com acentos e cedilhas. ### 2. MCP-first - **Desk CRM**: Consultar/actualizar via MCP desk-crm-v3 - **Gitea**: Commits e gestão de versões via MCP gitea - **SSH**: Apenas se necessário para validação remota (EasyPanel, CWP) - **Memória IJFW**: Guardar contexto persistente via ijfw-memory ### 3. Ciclo de Trabalho Obrigatório 1. **Validar contexto** — ler AGENTS.md + STATUS.md + desk.project 2. **Executar** — seguir docs/PLANS/DashDescomplicar-PLAN.md (roadmap + ciclos) 3. **Validar** — registar mudanças em STATUS.md 4. **Registar** — actualizar CRM (#2323) se há progresso significativo ### 4. Validação Obrigatória Nunca dar uma tarefa como concluída sem validar o estado actual via curl/MCP/SSH. --- ## Agentes Descomplicar Autorizados ### Claude Code (cc) **Identidade**: `staff_id = 25` (CLAUDE em Desk CRM) | Campo | Valor | |-------|-------| | **What** | Desenvolvimento, DevOps, features no DashDescomplicar | | **Why** | Fonte central de código, deploy, PDCA operacional | | **Where** | Dev/DashDescomplicar + EasyPanel (easy.descomplicar.pt) | | **Who** | Equipa de desenvolvimento (Emanuel + Claude Code) | | **When** | [Ver WHEN/HOW abaixo] | | **How** | [Ver WHEN/HOW abaixo] | #### When - **Semanal (Seg):** Health check: `curl -sf https://dash.descomplicar.pt/api/dashboard` + revisão de logs - **Mensal (último Sex):** Audit dependências (`npm audit`) + atualizar STATUS.md - **Trimestral:** Revisão segurança (OWASP) + testes de carga - **Contínuo:** PRs/features → docs/PLANS/DashDescomplicar-PLAN.md (roadmap) - **Incidente:** CodeRED para site down (`curl -X POST https://codered.descomplicar.pt/v1/trigger/RED-ZMT3FCU8`) #### How **Referência operacional primária:** - 📋 **PLAN:** `docs/PLANS/DashDescomplicar-PLAN.md` (roadmap Q3-Q4, ciclos de manutenção, deploy) - 📋 **SPEC:** `docs/SPECS/DashDescomplicar-SPEC.md` (especificação, projectos ativos) **Procedimentos Descomplicar:** - `PROC-Deploy-EasyPanel.md` (D7-Tecnologia) — deploy via SSH + Docker - `PROC-Observabilidade-Dashboard.md` — coleta de métricas - `QR-Desk-Subtarefas-Dependencias.md` — gestão de dependências no CRM **Validação:** - Build local: `npm run build && npm run lint && npm test` - Health endpoint: `GET /api/dashboard` (< 500ms p95) - Logs: `docker logs descomplicar_dashboard_descomplicar` (EasyPanel) **Escalação:** - Bug/Feature: Comentário em Desk #65 - Incidente P0 (site down): CodeRED imediatamente - Questão técnica: IRC com Claude Code peers --- ### Observabilidade (Sistema) **Integração**: Sistemas de telemetria que alimentam DashDescomplicar | Campo | Valor | |-------|-------| | **What** | Coleta e agregação de métricas operacionais | | **Why** | Observabilidade de infraestrutura e aplicação | | **Where** | `okf/entidades/Metrics.md` + logs/performance-metrics.json | | **Who** | Observabilidade (Sistema #2059) | | **When** | Contínuo (eventos em tempo real) | | **How** | [Ver WHEN/HOW abaixo] | #### When - **Contínuo:** Coleta via Express middleware (Painéis + API) - **Agregação horária:** Roll-up em Prometheus (opcional) - **Retenção:** Logs de performance em JSON (7 dias rotated) #### How **Referência operacional:** - 📋 **SPEC Autoritária:** `/media/ealmeida/Dados/Hub/05-Projectos/Observabilidade/SPEC.md` - 📋 **PLAN Autoritário:** `/media/ealmeida/Dados/Hub/05-Projectos/Observabilidade/PLAN.md` - 📊 **Métricas OKF:** `okf/entidades/Metrics.md` **Integração com DashDescomplicar:** - Endpoint: `GET /api/metrics` (Prometheus format) - Painéis consomem via CSR-Integration (cache + reconnect) - Tabela relação: `okf/relacionamentos/CSRIntegration-integra-Metrics.md` --- ## O Que Este Projecto Contém - `docs/PLANS/DashDescomplicar-PLAN.md` — **PLANO OPERACIONAL PRINCIPAL** (roadmap Q3-Q4, ciclos, deploy) - `docs/SPECS/DashDescomplicar-SPEC.md` — especificações e projectos activos - `okf/` — **GRAFO DE CONHECIMENTO** (12 entidades + 7 relacionamentos bidireccionais) - `okf/entidades/` — Dashboard-Engine, 8+ Painéis, CSR-Integration, Metrics - `okf/relacionamentos/` — exibe, integra-com, usa (com cruzamentos de métricas) - `AGENTS.md` — (este ficheiro) governance de agentes e integração - `STATUS.md` — **PDCA OPERACIONAL** (Plan-Do-Check-Act ligado a recursos) - `MEMORY.md` — histórico de sessões (deprecated, usar IJFW em ~/.ijfw/memory/) - `desk.project` — ancoragem CRM: task #2323, projecto #65 - `CHANGELOG.md` — histórico de versões --- ## Validação de Integridade ✅ **When/How completo** — Cada agent tem schedule e referências a PLAN/PROC/QR ✅ **Bidirecionalidade** — Relacionamentos em okf/ documentados nos dois sentidos ✅ **Sem órfãos** — Toda entidade ligada a pelo menos 1 entrada + 1 saída ✅ **PDCA linkado** — STATUS.md refere docs/PLANS/ e observabilidade --- ## Referência ao Modelo Consulte `/media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/ESTRUTURA.md` para a hierarquia padrão obrigatória em todos os projectos Descomplicar. **Última actualização:** 2026-06-30 (Fase C — 5W2H+PDCA completo) ## Relacionamentos Direccionais ### Depende De - [[06-Operacoes]] - Hub operacional central com procedimentos - [[04-Stack]] - Decisões técnicas e stack Descomplicar ### Suporta - [[05-Projectos/Modelo-Organizacao-Proc-Dev/ESTRUTURA.md]] - Modelo de projectos ### Documenta - [[06-Operacoes/Procedimentos/]] - Procedimentos operacionais ### Implementação - [[DashDescomplicar/src/]] - Código-fonte do Dashboard - [[DashDescomplicar/okf/]] - Grafo de conhecimento de painéis ### Relacionado Com - [[04-Stack]] - Stack técnico partilhado - [[CodeRED]] - Sistema de alertas críticos ### Procedimento - [[06-Operacoes/Procedimentos/D7-Tecnologia/Infraestrutura/PROC-EasyPanel-Deployment.md]] - Deploy em EasyPanel - [[06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-Desk-Subtarefas-Dependencias.md]] - Modelo de subtarefas ### Herança - [[05-Projectos/Modelo-Organizacao-Proc-Dev/ESTRUTURA.md]] - Estrutura canónica