From ac8efb816eb18fb1aadf3f049c40f76eaaefb73f Mon Sep 17 00:00:00 2001 From: Francisco Solla Date: Tue, 18 Aug 2026 11:38:56 -0300 Subject: [PATCH] =?UTF-8?q?feat(agentes):=20contrato=20MCP=20do=20repo=20?= =?UTF-8?q?=E2=80=94=20opencode.jsonc=20desligando=20postgres/stalwart=20d?= =?UTF-8?q?os=20globais=20+=20se=C3=A7=C3=A3o=20Harness=20no=20AGENTS.md?= =?UTF-8?q?=20(I3)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 11 +++ docs/plans/mcp-engenharia-impl.md | 108 ++++++++++++++++++++++++++++++ opencode.jsonc | 18 +++++ 3 files changed, 137 insertions(+) create mode 100644 docs/plans/mcp-engenharia-impl.md create mode 100644 opencode.jsonc diff --git a/AGENTS.md b/AGENTS.md index 0b8fa54..5cc7b14 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,6 +28,17 @@ usuário. nunca logado/commitado; aprovações nunca auto-aprovadas; copy pt-BR / identificadores em inglês; assets offline em `globPatterns` do PWA. +## Harness do agente + +- **Skills:** `.agents/skills/` — fluxo custom + pack de engenharia (fonte de + verdade: `skills-lock.json`; detalhes no Workflow de trabalho). +- **MCPs:** contrato em `opencode.jsonc` na raiz — seleção sobre os globais + (`~/.config/opencode/opencode.jsonc`). Em uso: `forgejo`, `playwright`, + `jina`. Desligados no repo: `postgres` (sem backend; global aponta pro banco + do teqo) e `stalwart` (e-mail pessoal). `penpot`/secrets do teqo nunca + entram. MCP novo ou re-habilitado passa por lá, com comentário registrando o + porquê. + ## Workflow de trabalho (fluxo tipo teqo) **Pack de skills de engenharia:** em `.agents/skills/` (além das 5 de fluxo custom), com proveniência/hashes em `skills-lock.json` na raiz — fonte de verdade; upgrade deliberado via `npx skills update -y`. diff --git a/docs/plans/mcp-engenharia-impl.md b/docs/plans/mcp-engenharia-impl.md new file mode 100644 index 0000000..c75d6f1 --- /dev/null +++ b/docs/plans/mcp-engenharia-impl.md @@ -0,0 +1,108 @@ +# Impl: MCPs de engenharia de software para os agentes da Iara + +Status: aprovado +Atualizado em: 2026-08-18 +Issue: #5 +Intenção: docs/plans/mcp-engenharia.md +Appetite restante: herdado (~0,5 dia — item pequeno, sem UI) + +## Leitura da intenção + +- **Outcome:** contrato explícito e versionado de MCPs de engenharia do repo + (`opencode.json(c)` na raiz) + seção curta "Harness do agente" no AGENTS.md; + seleção dos globais que servem à Iara; nada teqo-específico; sem secret novo. +- **O que NÃO negociar:** exclusões registradas de forma visível (`postgres`, + `penpot`, `stalwart`); AGENTS.md curto (não inventário); sem secret commitado; + sem apontamento para infra do teqo. +- **O que reavaliar:** a "forma exata" (entradas com `enabled` vs seleção por + comentário vs só doc) é delegada ao impl; hipótese de "provisioning de + secrets em `.forgejo/worktree.env`" confirmada como N/A (nenhum MCP com token + no conjunto — o arquivo só tem repo/worktrees root). + +## Abordagem recomendada + +```mermaid +flowchart LR + G[globais ~/.config/opencode/opencode.jsonc] -->|deep merge| M[opencode.jsonc do repo] + M -->|pin exclusions| P[postgres: enabled false
stalwart: enabled false] + M -->|comentários| X[por quê cada exclusão
penpot: sem fluxo de design
github: já off global] + G -->|herda ligado| E[forgejo / playwright / jina] + M -->|lido por| A[AGENTS.md — seção Harness do agente] +``` + +**Opções consideradas:** + +- **A — `opencode.jsonc` mínimo (pin só exclusions) + comentários + AGENTS.md** +- **B — `opencode.json` re-declarando as definições completas dos 3 habilitados + disables** +- **C — doc-only: sem arquivo de config, só AGENTS.md** + +**Recomendação:** A — porque o contrato fica versionado e ativo (o arquivo +efetivamente desliga o que não serve), as definições dos habilitados continuam +com fonte única nos globais (sem fork que drift com mudança global), e os +comentários no arquivo registram o "porquê" das exclusões — o schema oficial +(`https://opencode.ai/config.json`) aceita comentários (`allowComments: true`) e +a forma mínima `{ "enabled": false }` para desligar MCP herdado de config +anterior (`required: [enabled]`, `additionalProperties: false`). + +**Rejeitadas:** B porque duplica definições (comando do playwright, URL do +jina…) que mudam nos globais e a cópia do repo apodrece — e porque um dia alguém +edita só um dos dois lugares; C porque o contrato não é ativo (um MCP global +novo entraria em silêncio) nem versionado no sentido que o merge honra. + +### Componentes / mudanças + +- **`opencode.jsonc`** (novo, raiz): `$schema` + `mcp` com `postgres` e + `stalwart` em `enabled: false`; comentários pt-BR registrando o porquê de cada + exclusão (postgres: Iara não tem backend e o global aponta pro banco do teqo; + stalwart: e-mail pessoal; penpot: sem fluxo de design, e é config de repo do + teqo — nem chega a carregar; github: já off nos globais). Nada de + `environment`/secrets/URLs. Playwright MCP fica habilitado — a regra "e2e só + no CI" cobre o suite `test:e2e`, não o MCP de verificação visual em dev. +- **`AGENTS.md`**: nova seção `## Harness do agente` entre "Arquitetura do + código" e "Workflow de trabalho" — skills (`.agents/skills/`, fonte + `skills-lock.json`) + MCPs (contrato no `opencode.jsonc`: usados + `forgejo`/`playwright`/`jina` dos globais, desligados `postgres`/`stalwart`, + `penpot`/secrets do teqo nunca entram; `opencode.jsonc` é a fonte). +- **Migration:** N/A. **Access/Consent:** N/A (config, sem dados). +- **UI:** N/A — Impeccable A. +- `.forgejo/worktree.env`: **sem mudança** (sem MCP com token). + +## Fases verificáveis + +1. **Config** — criar `opencode.jsonc` na raiz (shape validado contra o schema + oficial; comentários documentam exclusões). +2. **AGENTS.md** — seção "Harness do agente" curta. +3. **Gates** — `bun run gate` (config não é TS, mas valida que nada quebrou) + + parse do JSONC; lembrar ao humano que config não é hot-reload — restart do + opencode para valer; validação real acontece no próximo launch em worktree + (escape: `OPENCODE_DISABLE_PROJECT_CONFIG=1`). +4. **Fechamento** — /simplify → capture-review-debts autônomo → PR `Closes #5` + com auto-merge. + +## Rabbit holes / Não escopo (engenharia) + +- Re-declarar definições completas dos MCPs habilitados (drift com globais). +- Provisioning de secrets em worktrees / `.opencode/secrets/` (sem MCP com token). +- Mudar os globais (postgres do teqo lá é problema do teqo). +- Inventário completo de ferramentas no AGENTS.md (a config é a fonte). +- `opencode.json` duplicado ao lado do `.jsonc` (escolha um só). + +## Riscos e mitigação + +- **opencode local não aceitar a config** (versão divergente do schema): baixo — + forma validada no schema publicado hoje e no skill `customize-opencode` da + versão instalada; se falhar, escape `OPENCODE_DISABLE_PROJECT_CONFIG=1` e + fallback barato: migrar comentários para o AGENTS.md e manter `.json` puro. +- **Alguém re-adicionar MCP excludente "para quando precisar"**: mitigado pelos + comentários no próprio arquivo + menção na seção Harness do AGENTS.md. +- **Drift silencioso de global novo**: contrato do repo pin só exclusões; um MCP + global novo entra — o humano revisa na hora de usá-lo e o arquivo é o lugar + para registrar a decisão (custo barato, reversível). + +## Aceite de engenharia + +- [ ] Aceite de produto da intenção coberto: contrato versionado, exclusões + registradas no arquivo, AGENTS.md curto, sem secret/infra do teqo +- [ ] Invariantes AGENTS/engineering-standards: sem secret commitado; copy pt-BR + nos comentários; nada de servidor/produto novo +- [ ] Testes de domínio: N/A (config de ferramenta; sem path de dados/access) diff --git a/opencode.jsonc b/opencode.jsonc new file mode 100644 index 0000000..41d9459 --- /dev/null +++ b/opencode.jsonc @@ -0,0 +1,18 @@ +{ + "$schema": "https://opencode.ai/config.json", + "mcp": { + // Harness MCP da Iara — seleção sobre os globais + // (~/.config/opencode/opencode.jsonc). O conjunto habilitado (forgejo, + // playwright, jina) é herdado dos globais por design; aqui se desligam os + // que NÃO devem carregar, para ninguém re-adicionar por engano. + // + // postgres: o global aponta pro banco do teqo; Iara é local-first sem + // backend — não faz sentido no desenvolvimento da Iara. + "postgres": { "enabled": false }, + // stalwart: e-mail pessoal; fora do fluxo de dev da Iara. + "stalwart": { "enabled": false } + // penpot: config de repo do teqo (design); sem fluxo de design na Iara — + // nem chega a carregar, então não há entrada aqui. + // github: já desligado nos globais (fluxo migrou para o Forgejo). + } +} -- 2.45.2