From bcfb71a27059f03799dfa9eff648da92eb7f8005 Mon Sep 17 00:00:00 2001 From: Francisco Solla Date: Tue, 18 Aug 2026 07:55:50 -0300 Subject: [PATCH] docs(planos): skills e MCPs de engenharia para a harness da Iara (I2, I3) --- docs/plans/mcp-engenharia.md | 108 +++++++++++++++++++++++++++ docs/plans/skills-engenharia.md | 128 ++++++++++++++++++++++++++++++++ 2 files changed, 236 insertions(+) create mode 100644 docs/plans/mcp-engenharia.md create mode 100644 docs/plans/skills-engenharia.md diff --git a/docs/plans/mcp-engenharia.md b/docs/plans/mcp-engenharia.md new file mode 100644 index 0000000..e6f16bd --- /dev/null +++ b/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. diff --git a/docs/plans/skills-engenharia.md b/docs/plans/skills-engenharia.md new file mode 100644 index 0000000..63125af --- /dev/null +++ b/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/.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 `), 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. -- 2.45.2