---
layer: wiki
type: Document
tags: [projecto, modelo, organizacao, ecosystem]
title: 2026 05 16 Ecosystem Alignment
description: >-
  > For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:exec…
timestamp: 2026-05-16T18:38:11.957939+00:00
---
# Ecosystem Alignment + PROC-DEV-STANDARD — Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [x]`) syntax for tracking.

**Goal:** Alinhar os 4 agentes do ecossistema (Claude, Gemini, Hermes, OpenCode) para operarem de forma consistente, e criar o PROC-DEV-STANDARD como protocolo de desenvolvimento partilhado.

**Architecture:** Criar ECOSYSTEM.md como fonte de verdade comum → actualizar cada config de agente com as secções em falta → criar PROC-DEV-STANDARD no Hub → criar resumo no modelo-organizacao.

**Tech Stack:** Markdown, Bash (chmod, validação), ficheiros de config YAML/JSON/MD

---

## Ficheiros a Criar/Modificar

| Acção | Ficheiro | Responsabilidade |
|-------|----------|-----------------|
| Criar | `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md` | Fonte de verdade comum — regras partilhadas por todos os agentes |
| Modificar | `~/.gemini/GEMINI.md` | Corrigir worklog HTML, adicionar STATUS.md, MEMORY.md criar, Gitea/Desk, Regra 48 |
| Modificar | `~/.hermes/AGENTS.md` | Adicionar STATUS.md, MEMORY.md criar, Gitea/Desk, worklog, CARL, Regra 48 |
| Modificar | `~/.config/opencode/AGENTS.md` | Adicionar tudo: MEMORY.md, STATUS.md, Sistema Triangular, CARL, Gitea/Desk, Regra 48 |
| Modificar | `~/.claude/CLAUDE.md` | Adicionar STATUS.md ao protocolo de sessão |
| Criar | `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md` | Protocolo de desenvolvimento ciclo completo |
| Criar | `Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md` | Resumo/referência do PROC |
| Criar | `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md` | Protocolo de auditoria (4 tipos) |
| Criar | `[projecto]/docs/audit/` | Estrutura de auditoria por projecto (template) |

---

## Task 1: Criar ECOSYSTEM.md — Fonte de Verdade Comum

**Files:**
- Criar: `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md`

- [x] **Step 1: Criar o ficheiro ECOSYSTEM.md**

```bash
cat > /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md << 'EOF'
---
title: Ecossistema Multi-Agente Descomplicar®
type: reference
status: active
date: 2026-05-16
tags: [ecossistema, agentes, protocolo, standard]
---

# ECOSYSTEM.md — Regras Comuns do Ecossistema Descomplicar®

**Fonte de verdade** para todos os agentes: Claude Code, Gemini CLI, Hermes/Izito, OpenCode.
Cada config de agente herda estas regras e pode adicionar as suas especificidades.

---

## 1. Identidade dos Agentes

| Agente | Config principal | staff_id Desk | Papel |
|--------|-----------------|---------------|-------|
| Claude Code | `~/.claude/CLAUDE.md` | 25 | Desenvolvimento, automação, orquestração |
| Gemini CLI | `~/.gemini/GEMINI.md` | — | Pesquisa, análise, tarefas longas |
| Hermes/Izito | `~/.hermes/SOUL.md` + `AGENTS.md` | 28 | Braço direito técnico, wiki, delegação |
| OpenCode | `~/.config/opencode/AGENTS.md` | — | Edição de código, contexto longo |
| Emanuel | — | 1 | Owner — timesheets sempre com staff_id=1 |

---

## 2. Protocolo de Sessão (todos os agentes)

### Início de sessão
1. Verificar data/hora actual (MCP `mcp-time` ou `date`)
2. Ler `.desk-project` se existir na raiz do projecto
3. Ler `MEMORY.md` se existir — se **não existir**, **criar** com cabeçalho:
   ```markdown
   # MEMORY.md — [Nome do Projecto]
   ```
4. Ler `STATUS.md` se existir — se **não existir**, **criar** com cabeçalho:
   ```markdown
   # STATUS.md — [Nome do Projecto]
   **Versão:** — | **Data:** YYYY-MM-DD | **Agente:** [nome]
   ## Estado actual
   - Em curso: —
   - Bloqueios: —
   - Próximos passos: —
   ```

### Fim de sessão
1. Actualizar `MEMORY.md` (topo, ordem cronológica inversa) com:
   - Decisões tomadas
   - Paths/IDs relevantes descobertos
   - Workarounds aplicados
2. Actualizar `STATUS.md` com estado actual, bloqueios e próximos passos
3. Registar tempo no Desk CRM se aplicável

---

## 3. Sistema Triangular

```
DESK CRM (Fonte Verdade) → Clientes, projectos, tarefas, tempo, facturas
HUB (Vault Obsidian)     → /media/ealmeida/Dados/Hub/ (00-Inbox a 99-Arquivo)
FICHEIROS (Local)        → /media/ealmeida/Dados/Dev/ (código)
```

---

## 4. Gitea vs Desk CRM — Routing Explícito

| O quê | Sistema | Nunca em |
|-------|---------|----------|
| Bugs, issues técnicas, PRs, releases | **Gitea** | Desk CRM |
| Código, commits, CI/CD | **Gitea** | — |
| Projectos, sprints, tarefas de gestão | **Desk CRM** | Gitea |
| Tempo (timesheets), facturação | **Desk CRM** | Gitea |
| Cliente 360, propostas, leads | **Desk CRM** | Gitea |

**Regra de sincronização:**
- Bug descoberto → criar issue Gitea → comentar na task Desk com URL
- Feature concluída → fechar issue Gitea → actualizar task Desk + registar tempo
- Deploy prod → task Desk fechada → `MEMORY.md` regista versão

---

## 5. Formato de Worklog (standard markdown PT-PT)

```markdown
## [Projecto] — YYYY-MM-DD

### O que foi feito
- [alteração concreta]

### Ficheiros alterados
- `path/ficheiro.ext`

### Próximos passos
- [próxima acção]
```

---

## 6. Regras Core

| Regra | Descrição |
|-------|-----------|
| **PT-PT Strict** | Português europeu SEMPRE — acentos, cedilhas, 95EUR. Zero brasileirismos em tudo |
| **Zero Assumptions** | Verificar via ficheiros ou MCP antes de afirmar. Confiança <80% → dizer explicitamente |
| **Dados Reais** | MCPs → Ficheiros → WebFetch. Nunca simular, nunca inventar URLs/paths/IDs |
| **Causa Raiz** | Resolver sempre a causa, não o sintoma |
| **Regra 48 — Dev Local** | Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop). CT 102 extinto em 20-04-2026. Nunca usar `ssh_execute(server="dev")` |
| **PDCA** | Plan → Do → Check → Act. Nunca agir sem plano |
| **Segurança** | Confirmação obrigatória antes de: `rm -rf`, `DROP TABLE`, force-push, comandos destrutivos em produção |

---

## 7. Sistema CARL

Domínios contextuais em `/media/ealmeida/Dados/.carl/carl.json`.
Consultar antes de responder sobre: desenvolvimento, CRM, WordPress, Hub, infraestrutura, qualidade, skills.

---

## 8. LLM Wiki

`~/wiki/` — base de conhecimento compilada do stack.
- **Ler:** qualquer agente pode ler (`~/wiki/index.md`, `grep -ril "termo" ~/wiki/`)
- **Escrever:** apenas Hermes/Izito
- **Protocolo ao iniciar:** `~/wiki/SCHEMA.md` → `~/wiki/index.md` → `~/wiki/log.md` (últimas 20 linhas)

---

## 9. MCPs Essenciais por Agente

| MCP | Claude | Gemini | Hermes | OpenCode |
|-----|--------|--------|--------|----------|
| desk-crm-v3 | ✅ | ✅ | ✅ | activar |
| gitea | ✅ | ✅ | ✅ | ✅ |
| memory-supabase | ✅ | ✅ | ✅ | ✅ |
| mcp-time | ✅ | adicionar | adicionar | ✅ |
| ssh-unified | ✅ | ✅ | ✅ | ✅ |
| notebooklm | ✅ | ✅ | — | ✅ (wrapper) |

---

**Última actualização:** 2026-05-16
**Mantido por:** Emanuel Almeida
EOF
```

- [x] **Step 2: Verificar que o ficheiro foi criado correctamente**

```bash
wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
head -5 /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md
```
Esperado: >80 linhas, cabeçalho frontmatter visível.

---

## Task 2: Actualizar GEMINI.md

**Files:**
- Modificar: `~/.gemini/GEMINI.md`

Problemas a corrigir: worklog HTML → markdown, adicionar STATUS.md, MEMORY.md criar se não existe, Gitea/Desk routing, Regra 48.

- [x] **Step 1: Fazer backup**

```bash
cp ~/.gemini/GEMINI.md ~/.gemini/GEMINI.md.bak-2026-05-16
```

- [x] **Step 2: Ler o ficheiro actual**

```bash
cat ~/.gemini/GEMINI.md
```

- [x] **Step 3: Substituir secção de Memória e adicionar secções em falta**

Localizar a secção `## 3. Autonomia e Ferramentas` → subsecção `**Memória:**` e substituir:

```
**Memória:** 
  - **Sessão:** `MEMORY.md` na raiz do projecto (partilhado com Claude Code e OpenCode). Ler ao iniciar, escrever ao terminar. Formato: secções por data, ordem cronológica inversa.
```

Por:

```
**Memória:**
  - **Sessão:** `MEMORY.md` na raiz do projecto (partilhado com todos os agentes).
    - Ler ao iniciar sessão
    - Se **não existir**, criar com cabeçalho `# MEMORY.md — [Nome Projecto]`
    - Escrever no fim com factos novos (topo, ordem cronológica inversa)
  - **STATUS.md:** ficheiro de estado vivo do projecto.
    - Ler ao iniciar sessão
    - Se **não existir**, criar com cabeçalho e campos: Versão, Data, Agente, Em curso, Bloqueios, Próximos passos
    - Actualizar no fim de sessão com estado actual
  - **Referência:** `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md` — regras comuns a todos os agentes
```

- [x] **Step 4: Substituir formato de worklog (HTML → markdown)**

Localizar:
```
`<h4>[Projecto] - Descrição</h4><ul><li>Alteração</li></ul><p><strong>Ficheiros:</strong> <code>path</code></p><hr><p><strong>Data:</strong> YYYY-MM-DD</p>`
```

Substituir por:
```
```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`
### Próximos passos
- [próxima acção]
```
```

- [x] **Step 5: Adicionar secção Gitea vs Desk CRM**

Após a secção `## 2. Sistema CARL`, adicionar:

```markdown
## 5. Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues, PRs, código | **Gitea** |
| Tarefas gestão, tempo, facturação, clientes | **Desk CRM** |

Bug descoberto → issue Gitea primeiro → comentar Desk com URL.
Feature concluída → fechar Gitea → actualizar Desk + registar tempo.
```

- [x] **Step 6: Adicionar Regra 48**

Na secção de regras core, adicionar:

```markdown
- **Regra 48 — Dev Local:** Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop local). CT 102 extinto em 20-04-2026. **Nunca** usar `ssh_execute(server="dev")`.
```

- [x] **Step 7: Verificar resultado**

```bash
grep -n "STATUS.md\|MEMORY.md\|Gitea\|Regra 48\|markdown" ~/.gemini/GEMINI.md
```
Esperado: todas as strings presentes.

---

## Task 3: Actualizar Hermes AGENTS.md

**Files:**
- Modificar: `~/.hermes/AGENTS.md`

Problemas a corrigir: adicionar STATUS.md, MEMORY.md criar se não existe, Gitea/Desk routing, worklog, CARL domínios, Regra 48.

- [x] **Step 1: Fazer backup**

```bash
cp ~/.hermes/AGENTS.md ~/.hermes/AGENTS.md.bak-2026-05-16
```

- [x] **Step 2: Actualizar secção MEMORY.md**

Localizar:
```markdown
## MEMORY.md

Cada projeto pode ter um `MEMORY.md` na raiz. Se existir:
- **Ler** ao iniciar sessão no projeto
- **Escrever** no final com factos novos (topo, ordem cronológica inversa)
- **Formato:** secções por data, markdown simples, decisões + técnico + IDs
```

Substituir por:
```markdown
## Protocolo de Sessão

### MEMORY.md
Cada projecto tem (ou deve ter) um `MEMORY.md` na raiz:
- **Ler** ao iniciar sessão no projecto
- Se **não existir**, **criar** com cabeçalho: `# MEMORY.md — [Nome Projecto]`
- **Escrever** no final com factos novos (topo, ordem cronológica inversa)
- **Formato:** secções por data, markdown simples, decisões + técnico + IDs

### STATUS.md
Ficheiro de estado vivo do projecto:
- **Ler** ao iniciar sessão
- Se **não existir**, **criar** com estrutura:
  ```
  # STATUS.md — [Nome Projecto]
  **Versão:** — | **Data:** YYYY-MM-DD | **Agente:** Izito
  ## Estado actual
  - Em curso: —
  - Bloqueios: —
  - Próximos passos: —
  ```
- **Actualizar** no fim de sessão com estado actual e próximos passos
```

- [x] **Step 3: Adicionar Gitea vs Desk CRM**

Após a secção `## Sistema Triangular`, adicionar:

```markdown
## Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues técnicas, PRs, código | **Gitea** |
| Tarefas gestão, tempo, facturação, leads | **Desk CRM** |

**Fluxo:** Bug → issue Gitea → comentar Desk com URL → fix → fechar Gitea → actualizar Desk + tempo.
```

- [x] **Step 4: Adicionar worklog standard**

Adicionar secção:

```markdown
## Worklog (formato standard)

```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`
### Próximos passos
- [próxima acção]
```

Registar também como comentário na task Desk CRM correspondente.
```

- [x] **Step 5: Actualizar referência CARL**

Localizar referência ao CARL e expandir:

```markdown
## Sistema CARL

Domínios contextuais em `/media/ealmeida/Dados/.carl/carl.json`.
Usar MCP `carl` para recall por keyword antes de responder sobre:
- DEVELOPMENT, CRM, WORDPRESS, HUB, INFRASTRUCTURE, QUALITY, SKILLS

Consultar sempre que o prompt contiver keywords técnicas do stack.
```

- [x] **Step 6: Adicionar Regra 48**

Adicionar à secção de Convenções ou Regras:

```markdown
## Regra 48 — Desenvolvimento Local

Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop local).
CT 102 extinto em 20-04-2026. **Nunca** usar `ssh_execute(server="dev")`.
Automações migradas para systemd user timers no desktop.
```

- [x] **Step 7: Verificar resultado**

```bash
grep -n "STATUS.md\|criar\|Gitea\|worklog\|Regra 48\|CARL" ~/.hermes/AGENTS.md
```
Esperado: todas as strings presentes.

---

## Task 4: Actualizar OpenCode AGENTS.md

**Files:**
- Modificar: `~/.config/opencode/AGENTS.md`

O OpenCode é o mais nu — precisa de tudo.

- [x] **Step 1: Fazer backup**

```bash
cp ~/.config/opencode/AGENTS.md ~/.config/opencode/AGENTS.md.bak-2026-05-16
```

- [x] **Step 2: Ler o ficheiro actual**

```bash
cat ~/.config/opencode/AGENTS.md
```

- [x] **Step 3: Adicionar protocolo de sessão completo**

Adicionar após o cabeçalho existente (PT-PT + Wiki):

```markdown
## Sistema Triangular

```
DESK CRM (Fonte Verdade) → Clientes, projectos, tarefas, tempo, facturas
HUB (Vault Obsidian)     → /media/ealmeida/Dados/Hub/
FICHEIROS (Local)        → /media/ealmeida/Dados/Dev/ (código)
```

## Protocolo de Sessão

### Início
1. Verificar data actual
2. Ler `.desk-project` se existir na raiz do projecto
3. Ler `MEMORY.md` — se **não existir**, criar:
   ```
   # MEMORY.md — [Nome Projecto]
   ```
4. Ler `STATUS.md` — se **não existir**, criar:
   ```
   # STATUS.md — [Nome Projecto]
   **Data:** YYYY-MM-DD | **Agente:** OpenCode
   ## Estado actual
   - Em curso: —
   - Bloqueios: —
   - Próximos passos: —
   ```

### Fim
1. Actualizar `MEMORY.md` (topo) com decisões, paths e IDs relevantes
2. Actualizar `STATUS.md` com estado actual e próximos passos

## Gitea vs Desk CRM

| O quê | Sistema |
|-------|---------|
| Bugs, issues técnicas, PRs, código | **Gitea** |
| Tarefas, tempo, facturação, leads | **Desk CRM** |

Bug → issue Gitea → comentar Desk com URL → fix → fechar Gitea → actualizar Desk.

## Worklog (formato standard)

```markdown
## [Projecto] — YYYY-MM-DD
### O que foi feito
- [alteração concreta]
### Ficheiros alterados
- `path/ficheiro.ext`
```

## Sistema CARL

Domínios contextuais em `/media/ealmeida/Dados/.carl/carl.json`.
Consultar antes de responder sobre: desenvolvimento, CRM, Hub, infraestrutura.

## Regra 48 — Desenvolvimento Local

Todo o desenvolvimento em `/media/ealmeida/Dados/Dev/` (desktop).
CT 102 extinto em 20-04-2026. **Nunca** usar SSH para servidor dev remoto.

## Staff IDs Desk CRM

- **Emanuel:** staff_id=1 (timesheets sempre com este ID)
- **Claude Code:** staff_id=25
- **Hermes/Izito:** staff_id=28
```

- [x] **Step 4: Activar desk-crm-v3 no opencode.json**

```bash
python3 -c "
import json
with open('/home/ealmeida/.config/opencode/opencode.json', 'r') as f:
    d = json.load(f)
d['mcp']['desk-crm-v3']['enabled'] = True
with open('/home/ealmeida/.config/opencode/opencode.json', 'w') as f:
    json.dump(d, f, indent=2)
print('desk-crm-v3 activado')
"
```

- [x] **Step 5: Verificar resultado**

```bash
grep -n "STATUS.md\|MEMORY.md\|Gitea\|CARL\|Regra 48\|staff_id" ~/.config/opencode/AGENTS.md
python3 -c "import json; d=json.load(open('/home/ealmeida/.config/opencode/opencode.json')); print('desk-crm-v3:', d['mcp']['desk-crm-v3']['enabled'])"
```
Esperado: todas as strings presentes; `desk-crm-v3: True`.

---

## Task 5: Actualizar CLAUDE.md — Adicionar STATUS.md

**Files:**
- Modificar: `~/.claude/CLAUDE.md`

- [x] **Step 1: Localizar a Regra 19 (Data Sessão) no CLAUDE.md**

```bash
grep -n "STATUS\|Data Sessão\|MEMORY\|sessão" ~/.claude/CLAUDE.md | head -20
```

- [x] **Step 2: Adicionar STATUS.md à tabela de regras**

Na tabela de REGRAS CORE, após a linha da Regra 19, adicionar:

```markdown
| 20 | **STATUS.md** — Ler ao iniciar sessão de projecto. Criar se não existir. Actualizar no fim com estado actual, bloqueios e próximos passos |
```

- [x] **Step 3: Verificar**

```bash
grep -n "STATUS.md" ~/.claude/CLAUDE.md
```
Esperado: pelo menos 1 ocorrência.

---

## Task 6: Criar PROC-DEV-STANDARD.md

**Files:**
- Criar: `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md`

- [x] **Step 1: Criar o PROC completo**

```bash
cat > /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md << 'PROCEOF'
---
title: Desenvolvimento Standard — Protocolo de Ciclo Completo
type: procedure
code: D7-SIS-006
department: D7-Tecnologia
subdepartment: Sistema
status: active
date: 2026-05-16
tags: [desenvolvimento, ciclo, protocolo, standard, gitea, desk-crm]
---

# PROC-DEV-STANDARD — Protocolo de Desenvolvimento (Ciclo Completo)

**Última actualização:** 2026-05-16
**Aplicável a:** todos os projectos Descomplicar®
**Fonte:** Extraído da experiência WhatSMS v2 + auditoria de ecossistema 2026-05-16

---

## Princípios

1. **Pesquisa antes de spec** — nunca especificar sem investigar
2. **Spec antes de código** — nada entra em código sem spec aprovada (excepções: bugfix, operação unitária)
3. **CI verde é gate obrigatório** — nunca deployar sobre CI vermelho
4. **Issue-First para bugs** — todo o bug tem issue Gitea antes do fix
5. **Contexto partilhado** — MEMORY.md e STATUS.md actualizados em cada sessão
6. **Causa raiz** — resolver sempre a causa, não o sintoma

---

## Fluxo Completo

```
Ideia
  → Pesquisa (deep research + NLM)
  → Spec (SPEC.md aprovado)
  → Plan (docs/PLANS/)
  → Desenvolvimento (feat/* → commits atómicos)
  → Quality Gates (pre-commit → CI)
  → Code Review & PR (Gitea)
  → Deploy & Validação (PROC-DEPLOY-STANDARD D7-SIS-005)
```

---

## Estrutura de Projecto Obrigatória

```
/ (root)
├── docs/
│   ├── PLANS/       # Planos de implementação
│   └── SPECS/       # Specs técnicas + notas de pesquisa
├── AGENTS.md        # Directrizes para agentes (obrigatório)
├── CHANGELOG.md     # Histórico de versões
├── MEMORY.md        # Contexto cross-agent (obrigatório)
├── STATUS.md        # Estado vivo do projecto (obrigatório)
└── .desk-project    # Ligação Desk CRM (JSON, obrigatório)
```

---

## Ficheiros Cross-Agent

| Ficheiro | Quem lê | Quem escreve | Quando |
|----------|---------|--------------|--------|
| `MEMORY.md` | Todos | Todos | Início (ler/criar) + fim (escrever) |
| `STATUS.md` | Todos | Agente activo | Início (ler/criar) + fim (actualizar) |
| `AGENTS.md` | Todos | Owner | Quando mudam as regras |
| `CHANGELOG.md` | Todos | Agente activo | A cada versão/sprint |

**Protocolo de sessão (qualquer agente):**
1. Início → ler `MEMORY.md` + `STATUS.md` (criar se não existem)
2. Durante → registar decisões relevantes em `MEMORY.md`
3. Fim → actualizar `STATUS.md` + `MEMORY.md`

---

## Fase 1 — Ideia

**Entrada:** pedido ou ideia
**Saída:** decisão de avançar + âmbito inicial

- Verificar que não existe funcionalidade equivalente
- Verificar alinhamento com MASTER-PLAN
- Âmbito suficientemente claro para pesquisar

---

## Fase 2 — Pesquisa

**Entrada:** ideia com âmbito definido
**Saída:** `docs/SPECS/research-YYYY-MM-DD-tema.md`

1. Identificar domínio
2. Verificar NLMs existentes via `/knowledge` (65 notebooks)
   - Domínio coberto → usar NLM existente
   - Domínio novo + pesquisa extensa → criar NLM dedicado (apenas se estritamente necessário)
3. Deep research: WebSearch + WebFetch + NLM
4. Sintetizar: decisões, alternativas descartadas, riscos
5. Guardar nota em `docs/SPECS/`

---

## Fase 3 — Spec

**Entrada:** nota de pesquisa aprovada
**Saída:** SPEC.md aprovado em `docs/SPECS/`

- Usar `/brainstorm` → `/spec` para trabalho não-trivial
- Design doc salvo em `docs/SPECS/YYYY-MM-DD-tema-design.md`
- Excepções: bugfix, operação unitária, continuação de plano

---

## Fase 4 — Plan

**Entrada:** spec aprovada
**Saída:** plano em `docs/PLANS/YYYY-MM-DD-tema.md`

- Usar `/writing-plans` para decompor em tarefas executáveis
- Cada tarefa com critério de aceitação claro

---

## Fase 5 — Desenvolvimento

**Entrada:** plano aprovado
**Saída:** commits atómicos em branch dedicada

### Branch strategy
- `main` — produção (protegida)
- `feat/N-descricao` — novas funcionalidades
- `fix/N-descricao` — bugs (N = número da issue Gitea)

### Commits (Conventional Commits)
```
tipo(scope): descrição breve (#N)

Closes #N
Co-Authored-By: [Agente] <noreply@anthropic.com>
```

Tipos: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`

---

## Fase 6 — Quality Gates

| Gate | Momento | O que verifica |
|------|---------|----------------|
| Pre-commit | Automático | Formatação, lint |
| Pre-push | Manual | Build, testes, cobertura, segurança |
| CI | Automático (push) | Tudo + report cobertura |

Thresholds definidos no `CONTRIBUTING.md` do projecto.
**Regra:** nunca PR sem CI verde.

---

## Fase 7 — Code Review & PR

### Checklist PR
- [x] Branch actualizada com `main`
- [x] Testes passam localmente
- [x] Cobertura acima do threshold
- [x] Build sem erros
- [x] Auditoria segurança sem vulnerabilidades críticas/altas
- [x] `CHANGELOG.md` actualizado
- [x] `STATUS.md` reflecte novo estado

---

## Fase 8 — Deploy & Validação

Ver `PROC-DEPLOY-STANDARD.md` (D7-SIS-005) na íntegra.

Após deploy:
- Actualizar `STATUS.md` com versão deployada
- Registar em `MEMORY.md`: versão, data, o que foi deployado
- Fechar task Desk CRM + registar tempo

---

## Gestão de Ferramentas: Gitea vs Desk CRM

| O quê | Onde |
|-------|------|
| Bugs, issues técnicas, PRs, releases, código | **Gitea** |
| Projectos, sprints, tempo, facturação, cliente | **Desk CRM** |

### Sincronização manual
1. Bug → issue Gitea → comentar Desk com URL
2. Feature concluída → fechar Gitea → actualizar Desk + tempo
3. PR merged → `CHANGELOG.md` + `STATUS.md` actualizados
4. Deploy → task Desk fechada → `MEMORY.md` regista versão

### Referências cruzadas
- `.desk-project`: `task_id` Desk + `gitea_repo`
- `MEMORY.md`: IDs de ambos os sistemas
- Commits: `(#N)` da issue Gitea

---

## Gate Obrigatório — Issue-First (Bugs)

**Regra não-negociável:** todo o bug tem issue Gitea antes do fix.

1. Descoberta → criar issue com labels: `Bug` + severidade + área
2. Branch `fix/N-descricao`
3. Commits com `(#N)` + `Fixes #N`
4. **Hotfix urgente:** criar issue post-hoc com label `Backfill`, fechada à criação

---

## Excepções

| Situação | Excepção | Condições |
|----------|----------|-----------|
| Bug crítico prod | Hotfix sem PR | Fix trivial e reversível; issue post-hoc |
| Re-deploy sem código | workflow_dispatch | Após mudança env vars |
| Bugfix simples | Sem spec/plan | 1-2 ficheiros, causa raiz clara |
| Continuação de plano | Sem nova spec | Plano aprovado, âmbito inalterado |

---

## Referências

- `PROC-DEPLOY-STANDARD.md` — D7-SIS-005
- `ECOSYSTEM.md` — `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md`
- `ESTRUTURA.md` — hierarquia de projecto standard
- `scripts/validate-structure.sh` — validação automática
- WhatSMS v2 `CONTRIBUTING.md` — implementação de referência

---

**Desk CRM:** Modelo-Organizacao-Proc-Dev · Task #2134 · Domínio CARL: MODELO-ORGANIZACAO
PROCEOF
```

- [x] **Step 2: Verificar criação**

```bash
wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
grep "^code:" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
```
Esperado: >150 linhas; `code: D7-SIS-006`

---

## Task 7: Criar PROC-DEV-STANDARD-ref.md no Modelo

**Files:**
- Criar: `Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md`

- [x] **Step 1: Criar ficheiro de referência**

```bash
cat > /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md << 'EOF'
# PROC-DEV-STANDARD — Referência Rápida

**Fonte de verdade:** `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md` (D7-SIS-006)

---

## Fluxo

```
Ideia → Pesquisa → Spec → Plan → Dev → Quality Gates → PR → Deploy
```

## Estrutura Mínima de Projecto

```
MEMORY.md / STATUS.md / AGENTS.md / CHANGELOG.md / .desk-project
docs/PLANS/ + docs/SPECS/
```

## Gitea vs Desk

| Gitea | Desk CRM |
|-------|----------|
| Bugs, PRs, código | Tarefas, tempo, clientes |

## Gate de Bugs

Bug → issue Gitea → branch fix/N → fix → Closes #N → actualizar Desk

## Excepções ao pipeline

Bugfix simples, hotfix, continuação de plano existente.

---

**Ver PROC completo para todos os detalhes.**
EOF
```

- [x] **Step 2: Verificar**

```bash
cat /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md
```

---

## Task 8: Actualizar MEMORY.md e CARL

**Files:**
- Modificar: `Modelo-Organizacao-Proc-Dev/MEMORY.md`
- Verificar: domínio CARL `MODELO-ORGANIZACAO`

- [x] **Step 1: Actualizar MEMORY.md do projecto**

Adicionar ao topo do `MEMORY.md`:

```markdown
## 2026-05-16
- **Auditoria ecossistema:** questionários directos a Gemini, Hermes, OpenCode via aionui. Relatório em `docs/SPECS/2026-05-16-ecosystem-audit.md`
- **Segurança OpenCode:** credenciais NotebookLM movidas para `~/.opencode-secrets` (600). Wrapper em `~/.opencode-wrappers/`. Permissões claude.json + settings.json corrigidas para 600.
- **ECOSYSTEM.md criado:** `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md` — fonte de verdade comum
- **PROC-DEV-STANDARD criado:** D7-SIS-006 em `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/`
- **Configs actualizadas:** GEMINI.md, Hermes/AGENTS.md, OpenCode/AGENTS.md, CLAUDE.md
- **skill brainstorming:** caminho docs/SPECS/ corrigido (era docs/superpowers/specs/)
- **Task Desk #2134:** Em Curso
```

- [x] **Step 2: Verificar domínio CARL**

```bash
cat /media/ealmeida/Dados/.carl/carl.json | python3 -m json.tool | grep -A5 "MODELO-ORGANIZACAO"
```
Esperado: domínio com 7+ regras presente.

---

## Task 9: Criar PROC-AUDIT-STANDARD.md

**Files:**
- Criar: `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md`

- [x] **Step 1: Criar o PROC de auditoria**

```bash
cat > /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md << 'EOF'
---
title: Auditoria Standard — Protocolo de 4 Tipos
type: procedure
code: D7-SIS-007
department: D7-Tecnologia
subdepartment: Sistema
status: active
date: 2026-05-16
tags: [auditoria, segurança, qualidade, ecossistema, projecto]
---

# PROC-AUDIT-STANDARD — Protocolo de Auditoria (4 Tipos)

**Última actualização:** 2026-05-16
**Aplicável a:** todos os projectos Descomplicar®

---

## Tipos de Auditoria

| Tipo | Código | Frequência | Gatilho adicional |
|------|--------|------------|-------------------|
| Código | AUDIT-CODE | Mensal | Antes de cada deploy prod |
| Segurança | AUDIT-SEC | Mensal | Antes de cada deploy prod |
| Ecossistema | AUDIT-ECO | Trimestral | Após mudança de agente/config |
| Projecto | AUDIT-PROJ | Semanal/sprint | Início de sprint |

---

## Estrutura de Findings

Cada projecto com auditorias activas mantém:

```
docs/audit/
├── audit.md          # Log master de todas as auditorias
├── security.md       # Findings de segurança activos
├── tech-debt.md      # Dívida técnica registada
└── findings/
    └── F-NNN-descricao.md   # Um ficheiro por finding
```

### Formato de Finding (F-NNN-descricao.md)

```markdown
# F-NNN — Título do Finding

**Data:** YYYY-MM-DD
**Tipo:** CODE | SEC | ECO | PROJ
**Severidade:** Critical | High | Medium | Low
**Estado:** Open | In Progress | Resolved | Accepted Risk

## Descrição
[O que foi encontrado]

## Impacto
[Consequência se não resolvido]

## Resolução
[O que foi feito ou planear fazer]

## Referências
- Issue Gitea: #N
- Commit: [hash]
```

---

## AUDIT-CODE — Auditoria de Código

**Checklist:**
- [x] Lint sem erros (`npm run lint` / equivalente stack)
- [x] Build sem erros (`npm run build` / equivalente)
- [x] Testes passam (`npm test` / equivalente)
- [x] Cobertura acima do threshold do projecto
- [x] Sem `TODO` / `FIXME` não rastreados em issues Gitea
- [x] `CHANGELOG.md` actualizado
- [x] Dependências sem versões muito desactualizadas (major version lag >2)

**Output:** entrada em `docs/audit/audit.md` + findings em `docs/audit/findings/` se aplicável.

---

## AUDIT-SEC — Auditoria de Segurança

**Checklist:**
- [x] Auditoria de dependências (`npm audit --audit-level=high` / equivalente)
- [x] Scan de credenciais: nenhum secret em código ou configs com permissões >600
- [x] Verificar ficheiros de config de agentes: permissões 600
- [x] OWASP Top 10 — verificar inputs validados, sem SQL injection, sem XSS
- [x] Tokens/API keys — rotação se >90 dias sem rotação
- [x] Variáveis de ambiente — todas em `.env` (gitignored), nunca hardcoded

**Output:** entrada em `docs/audit/security.md` + findings críticos em issues Gitea com label `Security`.

---

## AUDIT-ECO — Auditoria de Ecossistema

**Frequência:** trimestral ou após mudança de agente/config.

**Checklist:**
- [x] Todos os agentes conhecem STATUS.md e MEMORY.md
- [x] Todos os agentes têm Regra 48 (dev local, sem CT 102)
- [x] Todos os agentes têm regras Gitea vs Desk CRM
- [x] Worklog em formato markdown PT-PT em todos
- [x] MCPs essenciais activos: desk-crm-v3, gitea, memory-supabase, mcp-time
- [x] Credenciais em plaintext — nenhuma em ficheiros com permissões >600
- [x] Referências extintas removidas (servidores, paths, IDs obsoletos)
- [x] CARL domínios actualizados e correctos

**Método:** questionário directo a cada agente (ver modelo em `docs/SPECS/2026-05-16-ecosystem-audit.md`).

**Output:** relatório em `docs/SPECS/YYYY-MM-DD-ecosystem-audit.md` + findings em `docs/audit/findings/`.

---

## AUDIT-PROJ — Auditoria de Projecto

**Frequência:** semanal ou início de sprint.

**Checklist:**
- [x] `MEMORY.md` actualizado (última entrada ≤7 dias)
- [x] `STATUS.md` actualizado (última entrada ≤7 dias)
- [x] Issues Gitea abertas sem PR associado há >14 dias → rever prioridade
- [x] Tasks Desk CRM em "Em Curso" há >14 dias sem actividade → rever ou fechar
- [x] Timesheets registados para todo o trabalho da semana
- [x] `CHANGELOG.md` reflecte o que foi deployado
- [x] Sem branches `feat/*` ou `fix/*` com >30 dias sem merge → limpar ou fechar

**Output:** entrada em `docs/audit/audit.md`.

---

## Integração com PROC-DEV-STANDARD

- AUDIT-CODE + AUDIT-SEC correm automaticamente em CI (pre-deploy)
- AUDIT-PROJ corre no início de cada sprint (manual)
- AUDIT-ECO corre trimestralmente (manual, via questionário aionui ou directo)
- Findings com severidade Critical/High → issue Gitea obrigatória (Issue-First Gate)

---

## Referências

- `PROC-DEV-STANDARD.md` — D7-SIS-006
- `ECOSYSTEM.md` — `Hub/06-Operacoes/Documentacao/ECOSYSTEM.md`
- WhatSMS v2 `docs/audit/` — implementação de referência

---

**Desk CRM:** Modelo-Organizacao-Proc-Dev · Task #2134
EOF
```

- [x] **Step 2: Verificar criação**

```bash
wc -l /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md
grep "^code:" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-AUDIT-STANDARD.md
```
Esperado: >120 linhas; `code: D7-SIS-007`

---

## Task 10: Adicionar Secção de Auditoria ao PROC-DEV-STANDARD

**Files:**
- Modificar: `Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md`

- [x] **Step 1: Adicionar estrutura docs/audit/ à secção de estrutura de projecto**

Localizar a secção `## Estrutura de Projecto Obrigatória` e adicionar `docs/audit/` ao tree:

```
├── docs/
│   ├── PLANS/       # Planos de implementação
│   ├── SPECS/       # Specs técnicas + notas de pesquisa
│   └── audit/       # Auditorias e findings (se projecto activo)
│       ├── audit.md
│       ├── security.md
│       ├── tech-debt.md
│       └── findings/
```

- [x] **Step 2: Adicionar referência à secção de Referências**

Na secção `## Referências`, adicionar:

```markdown
- `PROC-AUDIT-STANDARD.md` — D7-SIS-007 (auditoria: código, segurança, ecossistema, projecto)
```

- [x] **Step 3: Verificar**

```bash
grep -n "audit\|AUDIT\|D7-SIS-007" /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md
```
Esperado: 3+ ocorrências.

---

## Validação Final

- [x] **Verificar todos os ficheiros criados**

```bash
ls -la \
  /media/ealmeida/Dados/Hub/06-Operacoes/Documentacao/ECOSYSTEM.md \
  /media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/Sistema/PROC-DEV-STANDARD.md \
  /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/docs/SPECS/PROC-DEV-STANDARD-ref.md
```

- [x] **Verificar configs actualizadas**

```bash
grep -l "STATUS.md" ~/.gemini/GEMINI.md ~/.hermes/AGENTS.md ~/.config/opencode/AGENTS.md ~/.claude/CLAUDE.md
```
Esperado: 4 ficheiros listados.

- [x] **Executar validate-structure.sh**

```bash
bash /media/ealmeida/Dados/Hub/05-Projectos/Modelo-Organizacao-Proc-Dev/scripts/validate-structure.sh
```
Esperado: 0 falhas, 0 avisos.

---

**Criado:** 2026-05-16 | **Baseado em:** auditoria multi-agente via aionui