@fontdata/ai-harness 2.0.0 → 2.2.0

package/templates/skills/evoluir-harness/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: evoluir-harness
+description: Cria ou ajusta peças do harness no projeto — agents, skills, rules, hooks, code-reviewer e design system — ou audita a pasta .claude e sugere o que mudar. Use de vez em quando, conforme o projeto cresce.
+argument-hint: "[agent|skill|rule|hook|code-reviewer|design-system|auditar]"
+---
+
+# Evoluir o harness
+
+Pedido: $ARGUMENTS
+
+O harness entrega os fluxos e as garantias; as peças específicas do projeto (agents de domínio, skills, rules,
+hooks) nascem aqui, quando uma dor recorrente justifica. Cada tipo tem uma referência própria: **leia só a do tipo
+escolhido**, quando ele for escolhido.
+
+> **🚦 Há um GATE de aprovação** antes de gravar qualquer arquivo. Esta skill **não faz commit nem push**.
+
+## Passo 0 — Escolher o caminho
+
+A primeira palavra do pedido é o tipo; o resto é contexto (nome, domínio, URL de referência).
+
+| Tipo | Referência | O que sai |
+|---|---|---|
+| vazio ou `auditar` | `references/auditoria.md` | Diagnóstico da pasta `.claude` e as listas manter, ajustar, remover e criar |
+| `agent` | `references/agent.md` | Agents de domínio em `.claude/agents/` e o mapa na rule de projeto |
+| `skill` | `references/skill.md` | Skill do projeto em `.claude/skills/<nome>/` |
+| `rule` | `references/rule.md` | Rules incondicionais, escopadas por path e de código legado |
+| `hook` | `references/hook.md` | Hooks por agent sobre a biblioteca do harness |
+| `code-reviewer` | `references/code-reviewer.md` | Agent de review somente leitura e o portão extra |
+| `design-system` | a referência `design-system.md` em `references/` | Agent, skill e rules da identidade visual |
+
+Tipo desconhecido: mostre a tabela e pergunte. Não carregue as outras referências.
+
+## Passo 1 — Contexto (somente leitura)
+
+1. Leia o `CLAUDE.md` e o `SPEC.md` da raiz e `.claude/rules/harness-projeto.md`. Faltando `SPEC.md` ou
+   `CLAUDE.md`, sugira `/sincronizar-claude-md` antes; siga só se o usuário quiser usar o código como fonte.
+2. Liste `.claude/agents/`, `.claude/skills/`, `.claude/rules/`, `.claude/hooks/` e `.claude/commands/`; leia
+   `.claude/settings.json` e `.ai-harness/config.json`.
+3. Havendo trabalho em curso, leia o `PLAN.md`, o `DECISOES.md` e o `BLOQUEIOS.md` em `docs/trabalhos/<id>/`.
+4. Rode `npx @fontdata/ai-harness doctor` e guarde os achados: eles alimentam a auditoria e a conferência final.
+
+## Passo 2 — Sem tipo: auditar
+
+Siga `references/auditoria.md`. Entregue as quatro listas (**manter / ajustar / remover / criar**), cada item com
+o motivo, e pergunte o que aplicar. Para cada item escolhido, leia então a referência do tipo dele e siga do Passo 3.
+
+## Passo 3 — Com tipo: desenhar (sem gravar)
+
+Siga a referência do tipo. Rascunhe o conteúdo completo de cada arquivo e o que muda nos arquivos existentes.
+Toda peça proposta precisa apontar a dor recorrente que resolve; sem ela, não proponha.
+
+## Passo 4 — 🚦 GATE de aprovação
+
+Mostre ao usuário, antes de gravar:
+
+- os caminhos exatos a criar e a alterar;
+- o conteúdo proposto de cada arquivo novo e o trecho de cada alteração (merge);
+- o que fica de fora de propósito (peças do harness, arquivos já existentes).
+
+**Não grave nada sem o "ok".** Ajuste e mostre de novo quando o usuário pedir mudança.
+
+## Passo 5 — Gravar e conferir
+
+1. Grave só o que foi aprovado, com **merge, não sobrescrita**, em `settings.json`, `config.json`, frontmatter
+   de agents e `.claude/rules/harness-projeto.md`.
+2. Rode `npx @fontdata/ai-harness doctor` de novo e confirme que não surgiu achado novo.
+3. Mostre como usar cada peça: invocar o agent, disparar a skill, demonstrar o hook com uma entrada de exemplo.
+4. Agent novo muda a orquestração: sugira `/sincronizar-claude-md` para reconciliar o `CLAUDE.md`.
+5. Pare aqui. Para versionar, o usuário roda `/git-commit-push` quando quiser.
+
+## Guardrails
+
+- **Nunca** gravar antes do GATE; **nunca** fazer commit ou push.
+- **Não recriar, renomear nem editar** as peças do harness: os agents `revisor-testes`, `qa`, `investigador` e
+  `auditor-plano`, `.claude/hooks/ai-harness/`, `.claude/hooks/comentarios/` e `.claude/rules/comentarios.md`. O
+  `update` as mantém; o que é específico do projeto vai para `.claude/rules/harness-projeto.md`.
+- Todo agent declara `tools:` mínimo e `model:`; hook novo nasce em `aviso`.
+- Uma fonte por assunto: não repetir em rule, skill ou agent o que já está no `CLAUDE.md` ou em outra rule.
+- Não criar skill ou comando que repita os fluxos `/nova-tarefa`, `/resolver-bug`, `/executar-plan` ou `/harness`.
+- Documento de trabalho só em `docs/trabalhos/<id>/`.
+- Conteúdo em **pt-BR**.

package/templates/skills/evoluir-harness/references/agent.md

@@ -0,0 +1,83 @@
+# Referência — agent
+
+Cria os **agents de domínio** do projeto em `.claude/agents/`.
+
+## Leitura
+
+`CLAUDE.md` e `SPEC.md` da raiz, o `PLAN.md` do trabalho em curso em `docs/trabalhos/<id>/`,
+`.claude/rules/harness-projeto.md` e os agents que já existem.
+
+## O que já vem com o harness
+
+`revisor-testes`, `qa`, `investigador` e `auditor-plano` são agents somente leitura do harness, instalados pelo
+`init` ou disponíveis no plugin como `fontdata:<nome>`. **Não os recrie nem crie agent com esses nomes**: um agent
+do projeto com o mesmo nome substitui o do harness e quebra os gates. Se o projeto precisa que o `qa` rode a suíte
+de outro jeito, isso vai para a seção "Suíte de testes" da rule de projeto, não para um agent novo.
+
+Crie aqui só agents de domínio: implementação por módulo, design system, parser, integração.
+
+## Quando vale um agent
+
+- Área com padrões próprios e tasks recorrentes (API, frontend, módulo Delphi, integração fiscal).
+- Trabalho que precisa de contexto limpo ou de ferramentas diferentes das da sessão.
+
+Contra-exemplos: agent por task ou por arquivo; agent "generalista" que faz tudo; agent que só repete o
+`CLAUDE.md`.
+
+## Para cada agent
+
+1. **Nome e descrição:** `kebab-case`; a `description` diz quando usar, com o domínio e a pasta. O orquestrador
+   delega por ela.
+2. **`tools:` mínimo**, sempre declarado. Sem `tools:`, o agent herda todas as ferramentas da sessão, inclusive
+   edição e `Bash`. Não dê `Write` a quem só precisa de `Read`.
+3. **Modelo:** `haiku` para tarefa simples, `sonnet` para implementação, `opus` para arquitetura.
+4. **Skills do projeto** que o agent deve carregar.
+5. **System prompt** com papel e responsabilidades, escopo de pastas, restrições explícitas (o que nunca fazer),
+   padrões do projeto, como rodar os testes (o comando da rule de projeto) e o que devolver ao orquestrador.
+
+```markdown
+---
+name: backend-dev
+description: Implementa tasks de API e regras de negócio em apps/api/. Use quando a task do plano for do domínio backend.
+tools: Read, Grep, Glob, Edit, Write, Bash
+model: sonnet
+---
+```
+
+## Obrigatório em todo agent que escreve código
+
+Implementação, testes, refactor e design system levam no system prompt, literalmente, o bloco abaixo. A rule
+`.claude/rules/comentarios.md` é carregada sozinha em toda sessão; o bloco repete só o orçamento e diz **onde** a
+rastreabilidade mora — não use `@import` da rule.
+
+```markdown
+## Comentários
+
+O padrão é **não comentar**; a regra completa está em `.claude/rules/comentarios.md`. Orçamento: bloco interno
+<= 3 linhas · docstring pública <= 5 · cabeçalho de arquivo proibido · densidade <= 10%.
+Nunca colocar no código: banner/separador de seção, task/fase/plano/spec, data, hash de commit, achado de
+review, narração do passo a passo, código comentado.
+Isso mora na mensagem de commit e em `docs/trabalhos/<id>/` — nunca em comentário.
+```
+
+> Foi aqui que o padrão falhou antes: os agents eram instruídos a rastrear plano, spec e task e despejavam essa
+> rastreabilidade em comentário, porque nada dizia onde ela deveria morar.
+
+Agent que toca código legado leva também uma linha sobre a precedência: na área legada tocada, vale o padrão local
+do arquivo (ver `rule.md`).
+
+## Mapa domínio → agent
+
+O mapa vai para a seção "Mapa de agents por domínio" de `.claude/rules/harness-projeto.md` (merge, sem apagar
+linhas existentes). É por ele que o `/executar-plan` e o `/resolver-bug` delegam cada task.
+
+| Domínio ou pasta | Agent | Observação |
+|---|---|---|
+| `apps/api/` | `backend-dev` | mudança estrutural passa antes pelo `arquiteto` |
+
+## Depois de gravar
+
+- Mostre como invocar cada agent manualmente ("use o agent `backend-dev` para ...") e como o orquestrador delega
+  sozinho, pela `description` e pelo mapa.
+- Sugira `/sincronizar-claude-md` para reconciliar a seção de orquestração do `CLAUDE.md`.
+- Guardas por agent: `/evoluir-harness hook`. Rules do domínio: `/evoluir-harness rule`.

package/templates/skills/evoluir-harness/references/auditoria.md

@@ -0,0 +1,107 @@
+# Auditoria da pasta .claude
+
+Diagnóstico de commands, agents, skills, rules e hooks do projeto. **Explique o motivo** de cada avaliação — nada
+de veredito sem justificativa — e não altere nada antes do GATE.
+
+## Como coletar
+
+1. Parta dos achados de `npx @fontdata/ai-harness doctor`. Ele já aponta, entre outros, `comando-sombreia-skill`,
+   `comando-legado`, `bloco-comentarios-antigo`, hook que aponta para script inexistente e documento fora do
+   contrato. Não refaça à mão o que ele já checou; explique o achado e proponha a correção.
+2. Leia cada arquivo de `.claude/agents/`, `.claude/commands/`, `.claude/skills/*/SKILL.md` e `.claude/rules/`, os
+   hooks registrados em `.claude/settings.json`, `.claude/settings.local.json` e no frontmatter dos agents, e o
+   lock e a config em `.ai-harness/`.
+
+## 1. Agents — modelo e ferramentas
+
+- **Modelo:** Haiku para trabalho mecânico (checagem por lista, renomeação, formatação); Sonnet para implementação,
+  testes e revisão; Opus para arquitetura, planejamento e investigação difícil. Aponte sub e superdimensionamento
+  (Opus numa task mecânica, Haiku desenhando arquitetura). Agent sem `model:` herda o da sessão: declare.
+- **`tools:`:** agent sem `tools:` herda todas as ferramentas da sessão, inclusive edição e `Bash`. Revisor,
+  auditor e code-reviewer não têm `Write` nem `Edit`; `Bash` só quando precisam rodar a suíte. Implementador recebe
+  só as ferramentas do seu escopo.
+- **Descrição:** o orquestrador delega pela `description`. Descrição vaga ("ajuda no backend") faz o agent nunca
+  ser chamado ou ser chamado para tudo.
+- **Comentários:** agent que escreve código sem o bloco de comentários no system prompt (ver `agent.md`).
+- **Mapa:** agent de domínio fora do mapa em `.claude/rules/harness-projeto.md` não recebe task do `/executar-plan`.
+
+## 2. Agent do projeto com nome de agent do harness
+
+`qa`, `investigador`, `revisor-testes` e `auditor-plano` vêm com o harness. Para cada `.claude/agents/<nome>.md`
+com um desses nomes:
+
+- registrado no lock e sem edição: é a cópia do harness, mantenha;
+- personalizado ou criado pelo projeto: ele substitui o do harness, e os fluxos passam a depender de um contrato que
+  ninguém garante (por exemplo, um `qa` que não registra `suite_verde` trava o fechamento das tasks). Leve o que é
+  do projeto (comando da suíte, verificação manual, portões) para `.claude/rules/harness-projeto.md` e restaure a
+  cópia com `npx @fontdata/ai-harness update`; se o papel é outro, renomeie (ex.: `qa-mobile`).
+
+## 3. Guardas de agent inoperantes
+
+Hook que existe mas não protege nada é pior que hook nenhum: dá falsa segurança. Procure:
+
+- **Lê argumentos em vez do JSON da stdin** (`$1`, `process.argv`, `$ARGUMENTS`, variável de ambiente inventada):
+  o Claude Code entrega o evento pela stdin, então a guarda nunca vê o comando. Refaça sobre `runHook` (`hook.md`).
+- **Caminho absoluto de outra máquina** (`C:\Users\fulano\...`, `/home/fulano/...`): falha em qualquer outra
+  máquina. Use `$CLAUDE_PROJECT_DIR`.
+- **Dependência de binário ausente** (`pwsh`, `php`, `python`, `jq`): confira com `command -v <binário>`. Sem ele,
+  o hook quebra calado ou trava tudo. Reescreva em Node, que existe onde o harness roda.
+- **Protocolo à mão:** `exit 2` ou JSON montado no script, com efeito diferente em cada evento.
+- **Hooks do harness em dobro:** plugin habilitado e, ao mesmo tempo, os scripts de `.claude/hooks/ai-harness/`
+  registrados no `settings.json` — cada hook roda duas vezes.
+
+Para confirmar que uma guarda funciona, rode o script com uma entrada de exemplo (ver `hook.md`).
+
+## 4. Commands — uso, redundância e legado
+
+- Diga quais commands tendem a ser **mais usados** neste projeto e quais são **pouco úteis** no contexto dele.
+- Aponte **sobreposição** entre commands e com as skills do harness (`/nova-tarefa`, `/resolver-bug`,
+  `/executar-plan`, `/harness`, `/evoluir-harness`, `/auditar-seguranca`, `/auditar-performance`, `/auditar-ui`) e
+  com `/sincronizar-claude-md`. Comando que repete um fluxo sai; a parte específica vira rule. Review a cada task
+  vira portão extra na rule de projeto.
+- Comando com o mesmo nome de uma skill vence e o fluxo da skill nunca roda: renomeie ou apague.
+- **Comandos `*-legado.md`:** versões personalizadas que o `update` renomeou. Para cada um, extraia o que é do
+  projeto (mapa de domínio, comando da suíte, portões, verificação manual, restrições) para
+  `.claude/rules/harness-projeto.md` ou para a rule do domínio, e só então proponha apagar o arquivo. Nunca apague
+  antes de a extração ser aprovada.
+
+## 5. Citações ao layout anterior à 2.1
+
+Antes da 2.1, os documentos ficavam em pastas separadas por tipo de documento (specs, planos, bugs e investigações,
+cada tipo na sua pasta dentro de `docs/`). Hoje cada trabalho mora em `docs/trabalhos/<id>/`, com `SPEC.md`,
+`PLAN.md`, `DECISOES.md`, `BLOQUEIOS.md` e `relatorios/`.
+
+- Procure as citações com `grep -rnE 'docs/(specs|plans|bugs|investigacoes)' CLAUDE.md .claude`.
+- Cada citação em `CLAUDE.md`, rule, agent, skill ou command vira ajuste para `docs/trabalhos/<id>/`.
+- Documentos ainda nas pastas antigas: `npx @fontdata/ai-harness migrar` mostra o plano e `--yes` aplica. O
+  `migrar` reescreve os links dentro dos documentos migrados, mas só lista as citações do `.claude/` e do
+  `CLAUDE.md` — essas são desta auditoria.
+
+## 6. Rules
+
+- **Rule de projeto ausente:** o `init` instala o esqueleto de `.claude/rules/harness-projeto.md` quando ele falta.
+- **Rule de projeto vazia:** só com os exemplos em itálico (`_ex.: ..._`), ou sem mapa de agents e sem comando da
+  suíte, embora o projeto tenha agents de domínio e testes. Proponha o preenchimento a partir dos agents, dos
+  scripts de teste e do CI; apague as seções que não valem.
+- **Comentários:** `.claude/rules/comentarios.md` ausente (o `init` e o `update` a instalam); outra rule que repete
+  regra de comentário; bloco antigo de comentários no `CLAUDE.md`.
+- Rule com mais de 30 linhas, que repete o `CLAUDE.md`, descreve o que o código já mostra ou contradiz outra rule.
+- Projeto com código legado sem a rule de precedência do padrão local (ver `rule.md`).
+
+## 7. Skills e hooks do projeto
+
+- Skill sem `description` que diga quando disparar, sem exemplos ou sem critério de quando não usar.
+- Skill que repete fluxo do harness ou que ninguém dispara.
+- Hook em `bloqueio` sem histórico de avisos pertinentes no rastro (`docs/eventos/*.jsonl`).
+
+## 8. O que criar
+
+Sugira peças novas para dores recorrentes. Busque evidência em `docs/trabalhos/*/DECISOES.md`, `BLOQUEIOS.md`,
+relatórios, achados de review repetidos e `npx @fontdata/ai-harness memoria --arquivo <arquivo>`. Para cada
+sugestão: tipo (`agent`, `skill`, `rule`, `hook`, `code-reviewer`, `design-system`), o que faria, quando seria
+usada e qual **dor recorrente** elimina.
+
+## Fechamento
+
+Consolide em quatro listas — **manter / ajustar / remover / criar** —, cada item com motivo e o tipo que o trata, e
+**pergunte o que aplicar**. Cada item escolhido segue a referência do seu tipo e passa pelo GATE.

package/templates/skills/evoluir-harness/references/code-reviewer.md

@@ -0,0 +1,68 @@
+# Referência — code-reviewer
+
+Cria o agent de review **somente leitura** em `.claude/agents/code-reviewer.md` e o declara como portão extra.
+
+## Leitura
+
+`CLAUDE.md`, `SPEC.md`, as rules em `.claude/rules/` e `.claude/rules/harness-projeto.md`. Se já existe um
+`code-reviewer`, ajuste-o em vez de criar outro.
+
+## O agent
+
+- `tools: Read, Grep, Glob` — nunca escrita nem execução. Sem `tools:`, o agent herda todas as ferramentas da
+  sessão, inclusive edição e `Bash`.
+- `model: sonnet`; `opus` quando o domínio tem regra de negócio densa ou isolamento de dados crítico.
+- System prompt focado em revisar a task contra o `SPEC.md` e o `PLAN.md` do trabalho em `docs/trabalhos/<id>/`,
+  olhando só o diff da task.
+- Classificação: **BLOQUEANTE**, **IMPORTANTE**, **SUGESTÃO**. Com BLOQUEANTE, o veredito é `REPROVADO`;
+  IMPORTANTE é corrigido antes de a task fechar, salvo decisão registrada em `DECISOES.md`; SUGESTÃO não segura.
+- Saída: veredito e achados com `arquivo:linha`, severidade, problema e correção sugerida.
+- O agent não corrige nada: identifica e reporta.
+
+## Checklist no system prompt
+
+Sem checklist explícito, o agent revisa o que lhe parecer relevante e ignora o resto.
+
+1. **Correção** — bugs, casos de borda, erros silenciados.
+2. **Aderência** ao `SPEC.md` e ao `PLAN.md` do trabalho.
+3. **Testes** — existem e cobrem o crítico da task?
+4. **Segurança e isolamento de dados** — multi-tenant, autorização, segredos.
+5. **Rules do projeto** em `.claude/rules/`.
+6. **Código legado** — na área antiga tocada, o padrão local do arquivo foi preservado?
+7. **Comentários** — classificar como **IMPORTANTE** (nunca SUGESTÃO): bloco interno acima de 3 linhas, docstring
+   pública acima de 5, cabeçalho de arquivo, banner ou separador de seção, task/fase/plano/data/hash de
+   commit/achado de review dentro do código, narração do passo a passo, código comentado. Ver
+   `.claude/rules/comentarios.md`.
+8. **Legibilidade e simplicidade.**
+
+## Guarda extra
+
+Hook `PreToolUse` com `matcher: Edit|Write|MultiEdit|NotebookEdit` que bloqueia qualquer modificação, criado sobre a
+biblioteca do harness conforme `hook.md`. O handler devolve sempre `{ motivo: 'o code-reviewer é somente leitura' }`.
+Por pedido explícito, este nasce em `bloqueio` em `.ai-harness/config.json`. O `tools:` já impede a edição; o hook
+cobre um `tools:` alterado por engano.
+
+## Portão extra na rule de projeto
+
+O code-reviewer só entra no fluxo quando declarado na seção "Portões extras" de `.claude/rules/harness-projeto.md`
+(merge). Ele roda **depois de `revisor-testes` e `qa`**:
+
+```markdown
+- `code-reviewer` em contexto limpo ao fim de cada task, depois de `revisor-testes` e `qa`
+```
+
+O `/executar-plan` lê essa seção e aplica o portão. Como o agent não tem `Bash`, quem registra o veredito no rastro é
+o orquestrador:
+
+```bash
+npx @fontdata/ai-harness evento agent_veredito --trabalho <id> --task <T-SS.NN> --nome code-reviewer \
+  --dados '{"veredito":"aprovado","motivo":"<resumo em uma linha>"}'
+```
+
+Reprovado, a task volta ao implementador com os achados, dentro do limite de voltas do `/executar-plan`.
+
+## Contra-exemplos
+
+- Reviewer com `Edit` "para corrigir o óbvio": quem implementa não aprova, e quem aprova não implementa.
+- Portão declarado antes do `qa`: o review gasta tempo em código que ainda não passa na suíte.
+- Checklist genérico copiado de outro projeto, sem as rules e os riscos deste.

package/templates/skills/evoluir-harness/references/design-system.md

@@ -0,0 +1,56 @@
+# Referência — design system
+
+Cria o **agent responsável pelo design system**, que trabalha principalmente com o agent de frontend, e as skills e
+rules que guardam a conformidade da identidade visual. O agent vai em `.claude/agents/`, as skills em
+`.claude/skills/` e as rules em `.claude/rules/`.
+
+Nomes sugeridos: agent `identidade-visual`, skill `conformidade-visual`, rule `visual.md` escopada nos arquivos de
+interface. Ajuste aos nomes que o projeto já usa.
+
+## Origem da identidade visual
+
+O contexto que veio depois do tipo decide a fonte:
+
+- **Com URL:** trate-a como referência externa. Acesse o site e extraia cores, fontes e padrões visuais —
+  principalmente do CSS; quando a página só traz o texto, busque as folhas de estilo que ela referencia.
+- **Sem URL:** **não acesse a internet.** Extraia o design system que já existe no projeto, pelo código: CSS e SCSS,
+  variáveis CSS, tokens de tema, `tailwind.config`, bibliotecas de UI e componentes.
+
+Em qualquer caso, o que o código já usa tem precedência: referência externa orienta o que falta, não apaga o que
+existe sem decisão registrada.
+
+## O que extrair
+
+| Grupo | O que registrar |
+|---|---|
+| Cores | primária, secundária, neutros, estados (sucesso, alerta, erro, info), contraste mínimo AA |
+| Tipografia | famílias com fallback, escala de tamanhos, pesos, altura de linha |
+| Espaçamento | escala (ex.: 4, 8, 12, 16, 24, 32) e onde cada passo se aplica |
+| Forma | raios, bordas, sombras, camadas (`z-index`) |
+| Layout | breakpoints, larguras máximas, grid |
+| Componentes | botões, campos, cards, tabelas, modais: variantes e estados (hover, foco, desabilitado) |
+| Movimento e ícones | durações, curvas, biblioteca de ícones |
+
+Aponte as divergências encontradas (três azuis parecidos, tamanhos soltos) como decisões a tomar, não como
+correção automática.
+
+## As peças
+
+- **Agent:** `tools:` com edição só nas pastas de interface e de tokens; `model: sonnet`. System prompt com os
+  tokens, os componentes base, as restrições e o bloco de comentários obrigatório (ver `agent.md`).
+- **Skill:** passo a passo para criar ou alterar tela conforme o sistema — usar token, reaproveitar componente,
+  conferir estados e contraste —, com exemplos de entrada e saída e quando não usar.
+- **Rule escopada** nos arquivos de interface, em até 30 linhas: nada de cor, tamanho ou espaçamento literal fora
+  dos tokens; componente existente antes de componente novo; foco visível e contraste AA.
+- **Mapa:** acrescente o domínio de interface e o agent em `.claude/rules/harness-projeto.md`.
+
+## Contra-exemplos
+
+- Copiar logotipo, imagem ou fonte licenciada da referência externa: ela orienta estilo, não fornece assets.
+- Tokens soltos no prompt do agent, sem arquivo de tokens no código: o sistema diverge na primeira tela.
+- Rule que repete o design system inteiro: ela aponta para os tokens, não os transcreve.
+
+## Depois de gravar
+
+Mostre onde ficaram os tokens e como o agent de frontend delega ao de design system. Para conferir telas existentes
+contra o sistema, sugira `/auditar-ui`.

package/templates/skills/evoluir-harness/references/hook.md

@@ -0,0 +1,95 @@
+# Referência — hook
+
+Cria hooks por agent em `.claude/hooks/<agent>/` sobre a biblioteca comum do harness. A biblioteca já cuida do
+protocolo do Claude Code, dos **modos** (`aviso`, `bloqueio`, `desligado`), da **falha aberta** e do **registro no
+rastro** de eventos.
+
+## Pré-checagem (somente leitura)
+
+1. Liste os agents em `.claude/agents/` e leia o `PLAN.md` do trabalho em curso em `docs/trabalhos/<id>/`, se houver.
+2. Confira a biblioteca em `.claude/hooks/ai-harness/lib/hook.mjs`. O `init` a copia junto com os hooks do harness.
+   Faltando, `npx @fontdata/ai-harness init --claude-md manter` mostra o que instalaria (`--yes` aplica). Com o
+   plugin habilitado, o `init` não copia os hooks para o projeto, para não rodarem duas vezes: leve essa pendência
+   ao GATE e decida com o usuário antes de escrever o hook.
+3. Leia `.ai-harness/config.json` e `.claude/settings.json` para saber os modos e os hooks já registrados.
+4. **Hooks existentes não são recriados nem removidos:** `.claude/hooks/ai-harness/` (`lembrete`,
+   `segredo-no-commit`, `proteger-contratos`, `task-so-fecha-verde`, `sem-jargao`) e
+   `.claude/hooks/comentarios/check.mjs` (catraca em `baseline.json`).
+
+## Desenhar por tipo de agent
+
+**Antes de qualquer hook, restrinja o agent pelo `tools:` do frontmatter.** É a garantia estrutural; o hook é
+proteção a mais, não substituto.
+
+| Tipo de agent | `tools:` sugerido | Hooks que fazem sentido |
+|---|---|---|
+| Somente leitura (revisor, auditor) | `Read, Grep, Glob` (+ `Bash` só para rodar testes) | `PreToolUse` em `Bash` que avisa sobre comando que altera estado (`git commit`, `rm`, `npm install`) |
+| Implementação (backend, frontend, parser) | as ferramentas de edição do seu escopo | `PreToolUse` que avisa sobre arquivo fora do escopo; `PostToolUse` que lembra de rodar os testes do módulo |
+| Testes | `Read, Grep, Glob, Bash` | `PreToolUse` em `Bash` que avisa sobre comando que não é de teste |
+
+Para cada hook: nome (`kebab-case`), evento, `matcher`, o que verifica e a mensagem de motivo.
+**Todo hook novo nasce em `aviso`**; hook de segurança pode nascer em `bloqueio` se o usuário pedir.
+
+## Script
+
+`.claude/hooks/<agent>/<hook>.mjs`:
+
+```js
+// @ts-check
+import { runHook } from '../ai-harness/lib/hook.mjs';
+
+await runHook('<hook>', (input) => {
+  const command = String(input.tool_input?.command ?? '');
+  if (!/\bgit\s+push\b/.test(command)) return null;
+  return { motivo: 'o agent de backend não publica código; deixe o push para o fechamento do trabalho.' };
+});
+```
+
+- O `runHook` **lê o JSON do evento pela stdin**: `tool_name`, `tool_input`, `prompt`, `cwd`, `hook_event_name`.
+  Nunca leia `$1`, `process.argv` ou variável de ambiente para obter o comando — a guarda fica cega.
+- O handler devolve `null` quando está tudo certo, ou `{ motivo }` para avisar ou bloquear.
+- **Não** use `exit 2` nem escreva JSON à mão: o `runHook` responde no formato de cada evento e modo, falha aberta
+  em erro interno e registra `hook_aviso` ou `hook_bloqueio` no rastro.
+- Só Node e módulos nativos: nada de `pwsh`, `php`, `python` ou `jq`, que podem não existir na outra máquina.
+- Caminho sempre relativo ao projeto, pelo `root` que o `runHook` entrega; nunca caminho absoluto.
+
+Registro no frontmatter do agent, com `$CLAUDE_PROJECT_DIR`:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: Bash
+      hooks:
+        - type: command
+          command: node "$CLAUDE_PROJECT_DIR/.claude/hooks/<agent>/<hook>.mjs"
+```
+
+Modo em `.ai-harness/config.json` (merge): `{ "hooks": { "<hook>": "aviso" } }`.
+
+## GATE
+
+Mostre a tabela (agent, hook, evento, matcher, o que verifica, modo inicial), o `tools:` proposto para cada agent e
+os caminhos exatos a criar ou alterar.
+
+## Depois de gravar
+
+1. Demonstre cada hook sem abrir uma sessão:
+
+   ```bash
+   echo '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"git push"},"cwd":"'"$PWD"'"}' \
+     | CLAUDE_PROJECT_DIR="$PWD" node .claude/hooks/<agent>/<hook>.mjs
+   ```
+
+   A saída mostra o aviso ou o bloqueio exatamente como o Claude Code o recebe. Sem saída, a guarda não disparou.
+2. Rode `npx @fontdata/ai-harness doctor` e confirme que nenhum hook aponta para script inexistente.
+
+## Promoção de aviso para bloqueio
+
+Só quando o rastro mostra avisos pertinentes e nenhum falso positivo:
+
+```bash
+grep -h '"nome":"<hook>"' docs/eventos/*.jsonl
+```
+
+Se o usuário decidir promover, troque o modo em `.ai-harness/config.json` e registre a decisão no `DECISOES.md` do
+trabalho em curso.

package/templates/skills/evoluir-harness/references/rule.md

@@ -0,0 +1,67 @@
+# Referência — rule
+
+Cria rules em `.claude/rules/` que complementam o system prompt dos agents.
+
+`.claude/rules/` é **carregada automaticamente** em toda sessão, com subpastas: não importe rule no `CLAUDE.md`
+nem no agent. Rule com `paths:` no frontmatter só entra quando o trabalho toca arquivos que casam com o padrão.
+
+## O que já vem com o harness
+
+- **`comentarios.md`** — padrão de comentários, instalado e atualizado pelo `init` e pelo `update`, junto com o hook
+  e a catraca do legado. **Não crie rule de comentários** nem repita regra de comentário em outra rule: duas fontes
+  divergentes é pior que uma. Se ela faltar, rode `npx @fontdata/ai-harness update`.
+- **`harness-projeto.md`** — convenção lida pelos fluxos e pelos agents `qa` e `revisor-testes`: mapa de agents,
+  portões extras, suíte de testes e verificação manual. O que é disso vai lá, não numa rule paralela.
+
+## Leitura
+
+Os agents em `.claude/agents/`, o `CLAUDE.md`, o `SPEC.md` e as rules que já existem.
+
+## O que criar
+
+1. **Rules incondicionais**, que valem para qualquer agent:
+   - `seguranca.md` — o que nunca fazer;
+   - `convencoes-gerais.md` — padrões universais do projeto.
+
+2. **Rules escopadas por path**, uma por domínio coberto pelos agents:
+
+   ```markdown
+   ---
+   paths:
+     - "apps/api/**/*.ts"
+   ---
+
+   # Backend
+   ```
+
+   Exemplos: `backend.md` com `backend/**/*.py`, `frontend.md` com `frontend/src/**`, `testes.md` com `tests/**`.
+
+3. **Rule de precedência em código legado** (`legado.md`, incondicional), quando o projeto tem código antigo com
+   padrões próprios:
+   - na área de código legado tocada, vale o **padrão local** do arquivo — nomenclatura, estrutura e estilo de
+     tratamento de erro —, mesmo que difira das convenções novas;
+   - as convenções novas valem para arquivo novo;
+   - não "modernizar" arquivo antigo fora do escopo da task.
+
+   Identifique as áreas legadas (pastas, extensões como `.pas` e `.dfm`, módulos antigos) e cite-as na rule.
+
+4. **Rule que teria evitado um bug**, quando o `/resolver-bug` sugerir: padrão proibido, validação obrigatória ou
+   teste exigido.
+
+## Cada rule deve
+
+- Ser concisa — máximo de 30 linhas.
+- Conter apenas o que o agent não descobriria sozinho lendo o código.
+- Complementar o system prompt do agent, não repetir o que já está lá nem no `CLAUDE.md`.
+- Focar em restrições e padrões específicos do domínio, não em comportamento geral.
+
+## Contra-exemplos
+
+- "Escreva código limpo e bem testado": genérico, não muda nada.
+- Rule que copia a configuração do linter, que já é aplicada pela ferramenta.
+- Duas rules que dizem coisas diferentes sobre o mesmo assunto.
+- Rule que manda gravar documento fora de `docs/trabalhos/<id>/`.
+
+## Depois de gravar
+
+Confirme que nenhuma rule nova contradiz outra e, para rule escopada, cite um arquivo real que casa com o `paths:`.

package/templates/skills/evoluir-harness/references/skill.md

@@ -0,0 +1,63 @@
+# Referência — skill
+
+Cria uma skill do projeto em `.claude/skills/<nome>/` para um problema **recorrente** que os agents enfrentam.
+
+## Leitura
+
+`CLAUDE.md` e `SPEC.md` da raiz, as skills que já existem (do projeto e do harness) e, como evidência de
+recorrência, `DECISOES.md`, `BLOQUEIOS.md` e relatórios em `docs/trabalhos/*/`.
+
+## Skill, rule, agent ou hook?
+
+| Peça | Serve para | Carregada |
+|---|---|---|
+| Rule | Restrição curta que vale sempre ou num conjunto de paths | Automaticamente |
+| Skill | Procedimento com passos, exemplos e material de apoio | Sob demanda, quando a `description` casa com o pedido |
+| Agent | Papel com ferramentas e contexto próprios | Quando o orquestrador delega |
+| Hook | Garantia que não depende de o modelo lembrar | Em todo evento do matcher |
+
+Se a necessidade é "nunca faça X", é rule. Se é "quando precisar de Y, siga estes passos", é skill.
+
+## Sugerir antes de criar
+
+Apresente opções de skills úteis para este projeto, cada uma com:
+
+- o que a skill faria;
+- quando dispararia automaticamente (as palavras e situações que casam com a `description`);
+- que tarefa resolveria sem precisar repetir instruções no prompt;
+- a evidência da recorrência (pedido repetido, achado de review que volta, bloqueio parecido).
+
+Espere a escolha do usuário.
+
+## Estrutura
+
+```
+.claude/skills/<nome>/
+├── SKILL.md          # enxuto: quando usar, passos, guardrails
+├── references/       # detalhe lido só quando o passo pede
+└── templates/        # documentos que a skill gera, quando houver
+```
+
+A skill deve ter:
+
+1. **Frontmatter** com `name` (igual ao nome da pasta, `kebab-case`) e `description` que diz o que faz e quando
+   usar, com gatilhos concretos, em até ~250 caracteres; `argument-hint` quando aceitar argumento.
+2. **Instruções claras** baseadas nas convenções do `CLAUDE.md`, sem copiá-lo.
+3. **Exemplos de input e output** esperados.
+4. **Critério de quando NÃO usar** a skill.
+5. **GATE com 🚦** antes de gravar algo relevante, e guardrails no fim.
+
+Mantenha o `SKILL.md` curto e leve o detalhe para `references/`, citado no passo em que é necessário.
+
+## Contra-exemplos
+
+- `description` genérica ("ajuda com o backend"): dispara em tudo ou em nada.
+- Skill que repete um fluxo do harness (`/nova-tarefa`, `/resolver-bug`, `/executar-plan`, `/harness`) ou o texto
+  do `CLAUDE.md`.
+- Skill com o mesmo nome de um arquivo em `.claude/commands/`: o comando vence e a skill nunca roda.
+- Skill que grava documento de trabalho fora de `docs/trabalhos/<id>/`.
+
+## Depois de gravar
+
+Mostre como disparar (`/<nome>` ou por um pedido que casa com a `description`) e sugira testar com um pedido real
+do projeto. Se algum agent deve carregá-la, ajuste o agent com `/evoluir-harness agent`.