170 lines
6.6 KiB
Markdown
170 lines
6.6 KiB
Markdown
---
|
|
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
|