Scaffolding agent harness

Scaffold de harness .claude/ e .opencode/ específico do projeto

Você vai construir, do zero, um harness de agentes para o projeto em que esta skill está rodando. A arquitetura (a "forma") é fixa e comum aos dois runtimes; todo o conteúdo (quais domínios existem, que pastas cada agente controla, quais comandos rodam build/test/lint, quais são as regras invioláveis) é descoberto a partir deste projeto — nunca copiado de outro.

⚠️ Regra de ouro deste gerador: nada de hardcode de um projeto específico. Se você se pegar escrevendo "NFe", "SEFAZ", "multi-tenant", "Prisma", "Vercel" sem ter encontrado isso nos artefatos DESTE projeto, pare — você está copiando, não derivando. Cada domínio, escopo, comando e regra precisa ter origem rastreável no CLAUDE.md / SPEC / PLAN / código deste repositório.

$ARGUMENTS (ou o pedido do usuário) pode conter dicas (ex.: "foque em backend", "use opus no reviewer", "não crie skills", "só Claude Code", "só OpenCode"). Respeite-as.

Quando usar

• O usuário pede para gerar/criar/scaffoldar a estrutura de agentes do projeto.
• Há um CLAUDE.md / AGENTS.md / SPEC / PLAN e o usuário quer transformá-lo em um harness operacional de subagentes com escopo fechado.

Quando NÃO usar

• Para editar um único agent já existente (faça direto).
• Para tarefas de produto (escrever código de feature) — isto cria a infra de agentes.

Alvos de runtime

Esta skill materializa a mesma "forma" em um ou ambos os runtimes:

• Claude Code → .claude/ (agents .md com frontmatter, hooks shell .sh, rules, skills, commands). Detalhes em references/claude-code-target.md.
• OpenCode → .opencode/ + opencode.json (agents .md, plugins TypeScript para escopo/guard/stop, commands). Detalhes em references/opencode-target.md.

A topologia comum (orquestrador, agents de domínio, reviewer, gates) está em references/architecture.md. Leia o(s) reference(s) do(s) alvo(s) escolhido(s) antes de escrever arquivos.

---

Fase 0 — Descoberta (read-only, obrigatória antes de escrever)

Não escreva nenhum arquivo ainda. Primeiro entenda o projeto:

1. Leia os artefatos de especificação, na ordem em que existirem:
   • CLAUDE.md (raiz e aninhados), AGENTS.md, GEMINI.md
   • SPEC.md / spec.md, PLAN.md / plan.md, README.md
   • .cursor/rules, docs/ relevantes
2. Inspecione a estrutura real com Glob/Grep/Bash:
   • layout de pastas de topo (monorepo? app único? packages?)
   • package.json (workspaces, scripts: o que é build/test/lint/typecheck?)
   • linguagem(ns), framework(s), gerenciador de pacotes, runner de testes
   • se já existe .claude/ ou .opencode/ — leia o que houver e estenda/atualize em vez de duplicar
3. Detecte o ambiente de hook disponível (para o alvo Claude Code):
   • há python3? jq? (prefira jq, senão python3, senão fallback grep/sed — escolha UM e use consistente)
   • shell padrão; os scripts usam #!/usr/bin/env bash
   • Para OpenCode: confirme que há Node/Bun para os plugins TS (o runtime do OpenCode já provê; os plugins são .ts).
4. Derive o mapa de domínios. Liste os domínios reais e, para cada um: as pastas/globs que controla, sua responsabilidade, e os comandos de verificação que se aplicam. Exemplos do tipo de eixo (NÃO use estes nomes se não couberem): camada de dados, API/serviço, UI/frontend, lógica de domínio/núcleo, infra/build/config, testes/qualidade. Use os nomes e fronteiras reais do repo.
5. Derive as regras invioláveis. Procure "Nunca fazer", "Constraints", "Segurança", invariantes de arquitetura, fronteiras de pacote, contratos de API, convenções de nomenclatura/tipagem. Essas viram as rules/.

Ao final da Fase 0, apresente ao usuário um plano curto (em texto): a lista de agents com o escopo de cada um, as rules, skills e commands, o comando de verificação principal detectado, e qual(is) runtime(s) você vai gerar (Claude Code / OpenCode / ambos — pergunte se $ARGUMENTS não disser). Peça OK. Só prossiga após confirmação (a menos que $ARGUMENTS já autorize seguir sem perguntar).

Use a língua predominante dos artefatos do projeto para os textos gerados.

---

Arquitetura a reproduzir (a "forma")

Ver references/architecture.md para a topologia completa. Resumo: para cada runtime escolhido, sempre há um orquestrador (primário; coordena, não escreve código de produto), um agent por domínio real (escopo fechado por hooks/plugins), e um reviewer read-only (último a ser chamado). Adapte a quantidade de domínios ao projeto (2 num projeto pequeno; 6+ num monorepo). Não invente domínios que o projeto não tem; não funda dois domínios reais em um só.

---

Fase 1 — Agents

Crie um agent por domínio descoberto, mais o orquestrador e o reviewer.

• Claude Code: siga "Agents" em references/claude-code-target.md.
• OpenCode: siga "Agents" em references/opencode-target.md.

Para ambos, o corpo do agent contém: papel, skills a carregar antes (se houver), responsabilidades, os padrões DESTE projeto (extraídos do CLAUDE.md/rules), uma seção "NUNCA faça" com as violações do domínio, e uma seção "Verificação antes de concluir" com o comando real a rodar e exigência de evidência (saída real) antes de afirmar que passa.

O orquestrador mantém um "Mapa de agentes especializados" (domínio → quando chamar), o fluxo clarificação → plano (TodoWrite/todos) → execução via delegação → review → entrega com saída real; sabe contratar novos agentes quando um pedido cai em domínio não coberto (avisa, pede OK, cria agent + hooks + rule no mesmo padrão); nunca pede ao usuário para rodar comandos.

O reviewer é read-only: audita o diff contra as rules, roda build/lint/test/typecheck mas nada que mude o repo, e emite achados [SEVERIDADE] título / File / Rule / Detail / Fix (BLOQUEANTE / IMPORTANTE / SUGESTÃO) + Summary com saída real e veredito de merge. Além disso, o reviewer mede e reporta as métricas de qualidade sobre o código tocado pelo diff e as aplica como gate (BLOQUEANTE acima dos limiares):

• complexidade ciclomática, índice de manutenibilidade (0–100) e duplicação de código (%) — ver references/code-metrics.md;
• cobertura de código (do diff), pirâmide de testes (unit/integração/E2E conforme o domínio tocado) e segurança & dependências (audit de deps, SAST, secret scan) — ver references/test-and-quality-gates.md.

Ferramentas e limiares saem do projeto (derive, não hardcode).

---

Fase 2 — Hooks (Claude Code) / Plugins (OpenCode)

O mecanismo que torna o escopo real (não só texto no prompt):

• Claude Code: crie .claude/hooks/<dominio>/ com pre-edit-scope.sh, pre-bash-guard.sh, post-edit-test.sh (se há testes), stop-<gate>.sh, e o pre-tool-use.sh do reviewer. Especificação completa em references/claude-code-target.md. chmod +x em todos os .sh.
• OpenCode: crie .opencode/plugin/*.ts com os equivalentes usando os hooks de evento (tool.execute.before para escopo/guard, tool.execute.after/event para o gate de stop, negação total de mutação no plugin do reviewer). Especificação completa em references/opencode-target.md.

Em ambos: bloquear = impedir a ação com mensagem clara em stderr/erro dizendo o porquê e para qual agente redirecionar; permitir = deixar passar. Garanta que os caminhos declarados nos agents batem com os arquivos criados.

---

Fase 3 — Rules

Crie .claude/rules/ (e/ou referencie nas prompts dos agents OpenCode):

• Rules incondicionais na raiz: uma para constraints/segurança invioláveis (cada regra com o porquê — o que quebra se violar), e uma de convenções gerais (tipagem, nomenclatura, formato de resposta/erro, fonte de verdade de tipos, fronteiras de pacote, política de testes). Não invente constraints que o projeto não tem.
• Rule de métricas de código (rules/metricas-de-codigo.md): os limiares de complexidade ciclomática, índice de manutenibilidade, duplicação, cobertura de código (do diff), pirâmide de testes (que tipo de teste cada domínio exige) e segurança & dependências (deps com HIGH/CRITICAL, SAST, segredos), além das ferramentas escolhidas — fonte de verdade compartilhada pelo reviewer e pelo command de entrega. Use os limiares do projeto se ele declarar algum; senão, os padrões de references/code-metrics.md e references/test-and-quality-gates.md.
• Rules de domínio em rules/<dominio>/<regra>.md: os gotchas de cada domínio que não se inferem lendo um arquivo isolado.
• Cada rule: título curto, bullets densos, links [[nome]] para rules relacionadas. Só o que não é óbvio do código.

No OpenCode, como não há diretório rules/ nativo equivalente, materialize as rules como arquivos em .opencode/rules/ e cite-as explicitamente no prompt de cada agent (e no reviewer), já que o carregamento condicional difere — ver reference do OpenCode.

---

Fase 4 — Skills

Crie skills para operações recorrentes e arriscadas DESTE projeto — onde vale um procedimento guiado (criar um artefato no padrão da casa, um "guarda" que audita as regras antes de finalizar, um fluxo com ordem/contratos rígidos). Não crie skills genéricas.

• Claude Code: .claude/skills/<nome>/SKILL.md.
• OpenCode: .opencode/skill/<nome>/SKILL.md (mesmo formato de frontmatter).

Cada SKILL.md: frontmatter com name e description (gatilhos concretos); corpo com "Quando usar"/"Quando NÃO usar", procedimento passo a passo, red flags ✅/🚩, exemplo input→output, checklist final. Material de apoio em references/ dentro da skill.

Se $ARGUMENTS pedir para pular skills, pule esta fase.

---

Fase 5 — Commands

Crie commands que despacham o orquestrador para os fluxos recorrentes:

• um comando de implementação ponta-a-ponta (clarificação → plano → execução TDD → verificação → review);
• um comando de review read-only do diff (despacha só o reviewer) que, além dos achados, mede e reporta complexidade ciclomática, índice de manutenibilidade, duplicação, cobertura do diff, pirâmide de testes e segurança & dependências, bloqueando acima dos limiares;
• comandos de diagnóstico de bug (read-only) e correção de bug (corrige na causa-raiz com TDD, fecha com reviewer);
• um comando de deploy/entrega que roda os verificadores reais e todos os medidores de métricas antes de qualquer publicação, não libera se alguma métrica estourar o limiar, e só faz git/deploy sob pedido explícito.

Os medidores, limiares e a detecção de ferramenta por linguagem estão em references/code-metrics.md (complexidade, manutenibilidade, duplicação) e em references/test-and-quality-gates.md (cobertura, pirâmide de testes, segurança & dependências) — leia ambos antes de gerar os commands de review e entrega.

Locais: Claude Code .claude/commands/<nome>.md; OpenCode .opencode/command/<nome>.md. Cada command: frontmatter com description; corpo com fases, Uso (/<comando> <args>) e agentes/refs envolvidos. Nada de passos manuais para o usuário — tudo via ferramenta.

---

Fase 6 — Fechamento

1. Valide os hooks/plugins: confira que cada .sh é executável, tem shebang, parseia o stdin pelo método detectado, e que os caminhos nos agents existem; teste rápido de um hook de scope com JSON de exemplo (path dentro vs fora do escopo) → exit 0 vs exit 2. Para OpenCode, confira que os .ts exportam o plugin no formato esperado e referenciam os globs corretos.
2. Não rode build/test/deploy do projeto inteiro (a menos que o usuário peça) — você só criou a infra de agentes.
3. Relate: a árvore gerada (por runtime), o que cada agent cobre, os comandos de verificação detectados e ligados aos gates, e decisões em aberto (model, skills futuras). Aponte como contratar um novo domínio depois (o orquestrador já sabe).

---

Red flags ✅/🚩

• ✅ Cada domínio/glob/comando/regra tem origem rastreável neste projeto.
• 🚩 Você escreveu um nome de domínio/tecnologia que não encontrou nos artefatos → está copiando.
• ✅ O escopo fechado é imposto por hook/plugin, não só por texto no prompt.
• 🚩 O reviewer tem Edit/Write, ou seu guard não bloqueia mutação de fato.
• ✅ Os gates de stop exigem verde real (test/build/validate) com saída colada.
• ✅ Os commands de review e entrega medem e reportam complexidade ciclomática, manutenibilidade, duplicação, cobertura do diff, pirâmide de testes e segurança & dependências, com saída real, e bloqueiam acima dos limiares.
• 🚩 Você "estimou" as métricas de cabeça em vez de rodar um medidor real → meça, cole a saída.
• 🚩 Você gerou um technical-debt ratio composto (Sonar) como gate → não é padrão deste harness; só se o projeto já o usa e o usuário pediu.
• 🚩 Você criou domínio/skill/command que o projeto não justifica → menos, porém certo.
• ✅ Se já existe .claude//.opencode/, você estendeu preservando customizações.

Checklist final

• Fase 0 feita e plano aprovado pelo usuário (com runtime(s) escolhido(s)).
• Orquestrador + 1 agent por domínio real + reviewer read-only, por runtime.
• Hooks (CC) e/ou plugins TS (OpenCode) de escopo/guard/stop criados e ligados.
• Reviewer impedido de mutar o repo por hook/plugin (não só prompt).
• Rules incondicionais + de domínio criadas (e citadas nos agents OpenCode).
• Skills e commands só onde o projeto justifica.
• Commands de review e entrega medem complexidade ciclomática, manutenibilidade, duplicação, cobertura do diff, pirâmide de testes e segurança & dependências (ferramenta detectada do projeto) e bloqueiam acima dos limiares; rule metricas-de-codigo criada e citada no reviewer.
• Hooks validados (shebang, +x, parse, scope test); plugins TS no formato correto.
• Relatório final entregue ao usuário com a árvore por runtime.