ealmeida/DashDescomplicar
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
main
DashDescomplicar/AGENTS.md
T

6.6 KiB
Raw Permalink Blame History

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

Documenta

Implementação

Relacionado Com

  • 04-Stack - Stack técnico partilhado
  • CodeRED - Sistema de alertas críticos

Procedimento

Herança

Reference in New Issue View Git Blame Copy Permalink