DashDescomplicar/AGENTS.md

type, title, description, tags

type	title	description	tags
Document	Agents	Governance de agentes IA para este projecto	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