docs: migrar SPEC/PLAN para docs/SPECS e docs/PLANS e adicionar ficheiros de contexto do projecto
This commit is contained in:
@@ -0,0 +1,169 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user