docs/plans/mcp-engenharia.md

@@ -0,0 +1,108 @@
+# MCPs de engenharia de software para os agentes da Iara
+
+Status: rascunho
+Atualizado em: 2026-08-18
+Issue: #5
+Priority: P2
+Model: deepseek/deepseek-v4-flash
+Impeccable: A — N/A (sem UI)
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5 dia; opencode.json de repo + documentação no AGENTS.md
+Responsável: —
+
+## Intenção
+
+O teqo declara os MCPs do projeto num `opencode.json` na raiz (hoje: penpot, com
+token em `.opencode/secrets/` gitignored), e o `worktree next` provisiona os secrets
+nos worktrees. Além disso, os agentes usam o conjunto global de MCPs
+(`~/.config/opencode/opencode.jsonc`: forgejo, playwright, jina, stalwart e um
+postgres apontando para o banco local do teqo). A Iara não tem `opencode.json`
+nenhum — o contrato de quais ferramentas o agente usa para desenvolver o app é
+implícito (só os globais, incluindo o postgres do teqo que não faz sentido aqui).
+Queremos o contrato explícito e versionado: um `opencode.json` de repo com o
+conjunto de MCPs que serve ao desenvolvimento da Iara, e o AGENTS.md documentando a
+harness (skills + MCPs).
+
+## Persona e fluxo
+
+- **Persona / contexto:** o agente trabalhando Issues da Iara (`work-issue`) e o
+  humano supervisionando; terminal, worktrees.
+- **Job principal:** o agente ter a ferramenta certa para o job — navegador
+  (playwright) para inspecionar a UI em dev, web (jina) para pesquisar o protocolo
+  ZeroClaw/gateways, Forgejo para Issues — sem arrastar MCPs de outros projetos.
+- **Fluxo desejado:**
+  1. `bun run worktree next` → opencode lança no worktree com o conjunto MCP do repo.
+  2. O AGENTS.md diz, em uma seção curta, o que o agente pode usar (skills + MCPs).
+  3. Decisões de NÃO incluir ficam registradas (comentário no arquivo), para
+     ninguém re-adicionar por engano.
+
+## Objetivo e aceite
+
+- `opencode.json` na raiz da Iara declarando o conjunto MCP de engenharia do repo:
+  seleção dos globais que servem à Iara (candidatos: forgejo, playwright, jina) e
+  nada teqo-específico (sem postgres do teqo, sem penpot/secret). Forma exata
+  (entradas com `enabled`, seleção por comentário, ou apenas documentação) fica com
+  o plano de implementação — o contrato é "quais ferramentas, e quais não".
+- Decisão explícita de NÃO incluir, registrada: `postgres` (Iara não tem backend —
+  e o global aponta para o banco do teqo), `penpot` (sem fluxo de design; o
+  `plan-issue` da Iara é textual), `stalwart` (e-mail pessoal).
+- AGENTS.md ganha seção curta "Harness do agente" (skills + MCPs de repo + globais
+  usados), sem virar inventário completo.
+- Nenhum secret novo commitado; nenhum apontamento para infra do teqo.
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — item de infra do fluxo de agentes, sem superfície
+  de dados de produto.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `opencode.json` na raiz, `AGENTS.md` (seção Harness),
+  `.forgejo/worktree.env` (nada a mudar — provisioning de secrets só se entrar MCP
+  com token, que não é o caso).
+- **Precedente a olhar:** `~/Code/teqo/opencode.json` (padrão repo-level),
+  `~/.config/opencode/opencode.jsonc` (globais a selecionar), AGENTS.md da Iara
+  (onde a seção nova encaixa).
+- **Risco de acoplamento:** baixo; único cuidado é não quebrar o launch do opencode
+  nos worktrees (referência a arquivos inexistentes, como o teqo já apanhou com o
+  penpot-token).
+
+## Dependências
+
+- Nenhuma (independente da issue de skills; pode rodar em paralelo).
+
+## Fora de escopo
+
+- Mudanças nos MCPs globais (`~/.config/opencode/opencode.jsonc`) — o postgres do
+  teqo lá é problema do teqo, não deste item.
+- Provisionamento de secrets em worktrees (sem MCP com token neste conjunto).
+- MCPs novos de engenharia que não existem hoje (ex.: servidor de docs do ZeroClaw)
+  — se surgir necessidade, item separado.
+
+## Rabbit holes de produto
+
+- **Incluir postgres/penpot "para quando precisar".** Se alguém "só completar":
+  arrasta infra do teqo para um app local-first sem backend. **Corte neste item:**
+  só o que serve hoje; o resto nasce com a necessidade real.
+- **Inventário completo no AGENTS.md.** Se alguém "só documentar": doc incha e
+  desatualiza. **Corte neste item:** seção curta; o arquivo de config é a fonte.
+
+## Questões em aberto (produto)
+
+- **Playwright MCP vs "e2e só no CI"?** **Opções:** A) habilitar — o agente
+  inspeciona a UI do dev server no worktree (a regra proíbe é rodar o suite
+  `test:e2e` local no fluxo normal) | B) deixar desligado por consistência com a
+  regra. **Recomendação:** A — a regra é sobre o suite de testes do CI; o MCP é
+  verificação visual em dev, e o playwright.config.ts da Iara já existe.
+  _(assumido — validar no gate)_
+- **`opencode.json` de repo agora vs só documentação no AGENTS.md?** **Opções:**
+  A) arquivo repo-level já (padrão teqo, contrato versionado, nasce onde um MCP
+  futuro com secret encaixa) | B) só doc, já que os globais cobrem.
+  **Recomendação:** A — explícito e versionado. _(assumido — validar no gate)_
+
+## Referências
+
+- `~/Code/teqo/opencode.json` — padrão de config repo-level do teqo.
+- `~/.config/opencode/opencode.jsonc` — conjunto global de MCPs (a selecionar).
+- `AGENTS.md` da Iara — onde a seção Harness encaixa.
+- `docs/plans/README.md` — convenção de planos da Iara.

docs/plans/skills-engenharia.md

@@ -0,0 +1,128 @@
+# Skills de engenharia de software para os agentes da Iara
+
+Status: rascunho
+Atualizado em: 2026-08-18
+Issue: #4
+Priority: P2
+Model: deepseek/deepseek-v4-flash
+Impeccable: A — N/A (sem UI)
+Rascunho UI: N/A — sem UI
+Appetite: ~0,5–1 dia; pack instalado + lockfile + integração no plan-issue
+Responsável: —
+
+## Intenção
+
+Os agentes da Iara hoje só conhecem o fluxo: as 5 skills custom herdadas do teqo no
+bootstrap (`plan-issue`, `work-issue`, `worktree-next-issue`, `capture-review-debts`,
+`code-simplification`). Quando um executor precisa de craft — TDD, clean code,
+segurança, performance, frontend, code review, debugging — ele improvisa ou vai ler o
+repo do teqo. O teqo resolveu isso com um pack de skills de engenharia versionado
+(`skills-lock.json` + skills de `addyosmani/agent-skills` e `wondelai/skills`).
+Queremos a mesma infraestrutura na Iara: o pack de engenharia (não o de
+produto/marketing), com lockfile commitado, e o `plan-issue` ensinado a absorver os
+princípios dessas skills em silêncio (skills-map, como no teqo).
+
+## Persona e fluxo
+
+- **Persona / contexto:** o agente que executa Issues da Iara (`work-issue`,
+  `/simplify`) e o humano que planeja (`/plan-issue`); terminal, sessions paralelas
+  em worktrees.
+- **Job principal:** ter o repertório de engenharia carregável sob demanda, sem
+  depender do repo do teqo como referência viva.
+- **Fluxo desejado:**
+  1. No worktree de uma Issue, o executor carrega a skill certa quando precisa
+     (ex.: `test-driven-development` antes de escrever testes,
+     `security-and-hardening` ao tocar token/key, `frontend-ui-engineering` em UI).
+  2. O `plan-issue` continua produzindo um artefato só (`docs/plans/<slug>.md`),
+     mas absorve princípios de spec/planning/incremental/doubt em silêncio.
+  3. Máquina nova ou CI: `bun install` e o pack já está lá (lockfile commitado).
+- **Anti-goals de produto:** o planejamento não vira um tour de skills (o
+  `plan-issue` não abre jornadas guiadas); não trazer o ruído de produto/marketing
+  do teqo (hundred-million-offers, storybrand, traction-eos…); não criar
+  dependência de ferramenta de sync no runtime do repo.
+
+## Objetivo e aceite
+
+- O pack de engenharia está em `.agents/skills/` com `skills-lock.json` commitado
+  (mesmo formato do `~/Code/teqo/skills-lock.json`) — instalação reprodutível.
+- Pack = `addyosmani/agent-skills` completo (24 skills: TDD, code review, debugging,
+  performance, security, frontend UI, git workflow, CI/CD, docs/ADRs,
+  context-engineering, spec-driven, incremental, etc.) + subset de engenharia do
+  `wondelai/skills` (clean-code, clean-architecture, system-design, ddia-systems,
+  domain-driven-design, pragmatic-programmer, refactoring-patterns, refactoring-ui,
+  remove-technical-debt, software-design-philosophy, high-perf-browser, web-typography,
+  ux-heuristics, microinteractions, working-with-legacy-code, team-topologies — lista
+  exata validada na implementação pelo critério "relevante para Vite+React+TS+PWA+WS+
+  local-first, time pequeno").
+- As 5 skills de fluxo existentes continuam como estão (são custom, já adaptadas ao
+  Forgejo); `code-simplification` já existe — não instalar duplicado.
+- `plan-issue` ganha o `skills-map.md` (adaptado do teqo para Forgejo/`bun run`):
+  o planejamento absorve spec-driven, planning-and-task-breakdown,
+  incremental-implementation, doubt-driven-development, DDD/clean-architecture sob
+  demanda — e o que fica fora (build/review = `work-issue`).
+- Nada do pack de produto/marketing do wondelai na Iara. Referência do que foi
+  cortado: `skills-lock.json` do teqo (86 skills no total).
+- Textos de skills que referenciem GitHub/teqo ajustados para a convenção da Iara
+  (Forgejo, `bun run`).
+
+## Dados (intenção)
+
+- **Vou apresentar dados?** Não — item de infra do fluxo de agentes, sem superfície
+  de dados de produto.
+
+## Direção no codebase (hipótese)
+
+- **Áreas prováveis:** `.agents/skills/` (novas pastas de skill), `skills-lock.json`
+  na raiz, `.agents/skills/plan-issue/skills-map.md`, `AGENTS.md` (menção única ao
+  pack, sem virar inventário).
+- **Precedente a olhar:** `~/Code/teqo/skills-lock.json`, `~/Code/teqo/.agents/skills/`
+  (instalação real), `~/Code/teqo/.agents/skills/plan-issue/skills-map.md` (fonte do
+  mapa), PR #1 da Iara (como o pack de skills de fluxo foi herdado).
+- **Mecanismo de instalação:** hipótese — CLI de skills do ecossistema
+  vercel-labs/skills (`npx skills add <owner/repo>`), mesma origem do lockfile do
+  teqo; cópia a partir do teqo é alternativa aceitável. Decisão fica com o plano de
+  implementação.
+- **Risco de acoplamento:** nenhum com o produto; cuidado apenas para não duplicar
+  as 5 skills existentes nem editar as de fluxo.
+
+## Dependências
+
+- Nenhuma (superfície independente da issue de MCPs; pode rodar em paralelo).
+
+## Fora de escopo
+
+- Pack de produto/marketing do wondelai (fica só no teqo; nada a portar).
+- Skills específicas do teqo (`payload-migrations`, `local-database`, `solla-*`,
+  agentes de design) — Iara não tem backend/design.
+- Melhorias de conteúdo dos SKILL.md upstream (fork/edição) — se alguém quiser,
+  vira débito separado com `depends` aqui.
+
+## Rabbit holes de produto
+
+- **Paridade total (86 skills).** Se alguém "só copiar o teqo": contexto de agente
+  inflado com ruído de campanha/marketing. **Corte neste item:** só o pack de
+  engenharia, critério de stack da Iara.
+- **Aperfeiçoar os SKILL.md.** Se alguém "só melhorar": vira projeto de escrita e o
+  lockfile quebra o rastreio. **Corte neste item:** copiar como vem; melhoria =
+  débito separado.
+- **Inventário no AGENTS.md.** Se alguém "só documentar": o AGENTS.md incha e
+  desatualiza. **Corte neste item:** menção única + lockfile como fonte de verdade.
+
+## Questões em aberto (produto)
+
+- **Pack completo (86) vs engenharia-only?** **Opções:** A) só engenharia
+  (addyosmani 24 + subset wondelai de engenharia) | B) paridade total com o teqo.
+  **Recomendação:** A — a Iara é um app enxuto sem vertical de campanha; contexto de
+  agente menor = decisões melhores. _(assumido — validar no gate)_
+- **Integrar o skills-map no plan-issue agora?** **Opções:** A) sim, no mesmo item |
+  B) depois, quando o pack assentar. **Recomendação:** A — é o que faz o pack ter
+  efeito no fluxo (sem o mapa, as skills viram acervo morto). _(assumido — validar
+  no gate)_
+
+## Referências
+
+- `~/Code/teqo/skills-lock.json` — lockfile de origem (86 skills, fontes + hashes).
+- `~/Code/teqo/.agents/skills/plan-issue/skills-map.md` — mapa a adaptar.
+- `~/Code/teqo/.agents/skills/` — instalação de referência.
+- PR #1 da Iara (bootstrap do fluxo) — como as 5 skills de fluxo entraram.
+- `docs/plans/README.md` — convenção de planos da Iara.