@fontdata/ai-harness 2.0.0 → 2.1.0

package/.claude-plugin/marketplace.json

@@ -11,7 +11,7 @@
     {
       "name": "fontdata",
       "source": "./",
-      "description": "36 slash commands para conduzir spec, scaffold, harness, revisão e manutenção de projetos com Claude Code."
+      "description": "19 slash commands para conduzir spec, contexto, harness, revisão e manutenção de projetos com Claude Code."
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,8 +1,15 @@
 {
   "name": "fontdata",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Harness de engenharia com IA da Fontdata para Claude Code",
   "author": { "name": "Fontdata" },
   "commands": ["./templates/commands"],
-  "skills": ["./templates/skills"]
+  "skills": ["./templates/skills"],
+  "hooks": "./templates/hooks/hooks.json",
+  "agents": [
+    "./templates/agents/auditor-plano.md",
+    "./templates/agents/investigador.md",
+    "./templates/agents/qa.md",
+    "./templates/agents/revisor-testes.md"
+  ]
 }

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fontdata Tecnologia
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,12 +1,32 @@
 # @fontdata/ai-harness
 
-O **harness de engenharia com IA da Fontdata** (slash commands do Claude Code) para qualquer projeto — novo ou existente. Você pode **rodar os comandos direto na pasta do projeto, sem instalar nada**, ou instalá-los em `.claude/commands/` quando quiser versioná-los junto com o código.
+O **harness de engenharia com IA da Fontdata** para o [Claude Code](https://claude.com/claude-code): fluxos de
+trabalho, agents, hooks e contratos de documentação que fazem o agente planejar antes de implementar, provar com
+testes o que entregou e deixar rastro do que fez — em qualquer stack, inclusive Delphi/Pascal e .NET.
 
 > Foco exclusivo em **Claude Code**.
 
+## Por que um harness
+
+Um agente de IA sem restrições toma decisões sozinho no meio da implementação, entrega diffs grandes fora do padrão
+do projeto e escreve testes que passariam com o código errado. As regras escritas num prompt ajudam, mas nada
+garante que sejam seguidas. O harness se apoia em cinco apostas:
+
+1. **Planejar antes de executar.** Uma pergunta durante a execução é falha do plano: dúvida vira bloqueio
+   registrado, não improviso.
+2. **Nada avança sem critério verificável.** TDD com pelo menos 2 testes críticos por task; a task só fecha com a
+   suíte verde registrada.
+3. **Documentação como contrato.** Cada trabalho tem a sua pasta, com spec, plano, decisões, bloqueios e relatórios
+   num formato que ferramentas conseguem ler e validar.
+4. **Quem implementa não aprova.** Agents somente leitura revisam os testes, validam os critérios de aceite e
+   auditam o plano.
+5. **Garantias fora do prompt.** Hooks avisam ou bloqueiam de forma determinística, e o rastro de eventos mostra o
+   que aconteceu — inclusive quando um aviso já pode virar bloqueio.
+
 ## Modo 1 — rodar sem instalar (recomendado)
 
-Na pasta do projeto, chame o comando pelo nome. O Claude Code abre já executando aquele prompt, e o pacote é carregado como plugin **só daquela sessão** — nenhum arquivo é escrito no repositório.
+Na pasta do projeto, chame o comando pelo nome. O Claude Code abre já executando aquele fluxo, com o pacote
+carregado como plugin **só daquela sessão** — nenhum arquivo do harness é escrito no repositório.
 
 ```bash
 # npm / npx
@@ -21,219 +41,233 @@ yarn dlx @fontdata/ai-harness harness
 pnpm dlx @fontdata/ai-harness harness
 ```
 
-Durante a sessão, todos os 36 comandos ficam disponíveis com o prefixo do plugin — `/fontdata:gerar-spec`, `/fontdata:criar-agents` etc. — assim como a skill `lgpd-checker`. É isso que faz o `/harness`, que encadeia 14 comandos, funcionar sem instalação prévia.
+Durante a sessão, todos os 19 comandos ficam disponíveis com o prefixo do plugin — `/fontdata:nova-tarefa`,
+`/fontdata:resolver-bug` etc. —, junto com os hooks e os agents do harness.
+É isso que faz o `/harness`, que encadeia 4 comandos, funcionar sem instalação prévia.
 
-O texto depois do nome do comando vira o `$ARGUMENTS` daquele prompt. Tudo depois de `--` é repassado ao Claude Code:
+O texto depois do nome do comando vira o argumento do fluxo. Tudo depois de `--` é repassado ao Claude Code:
 
 ```bash
 npx @fontdata/ai-harness harness -- --model claude-opus-5
 npx @fontdata/ai-harness auditar-seguranca -- -p     # headless, para CI
 ```
 
-Use `run <comando>` quando o nome puder colidir com uma palavra reservada do CLI:
+Use `run <comando>` quando o nome colidir com um subcomando do CLI:
 
 ```bash
 npx @fontdata/ai-harness run git-commit-push
 ```
 
-**Requisito:** o [Claude Code](https://claude.com/claude-code) precisa estar no `PATH` (`npm i -g @anthropic-ai/claude-code`).
+**Requisito:** o Claude Code no `PATH` (`npm i -g @anthropic-ai/claude-code`) e Node.js 22 ou superior.
 
 ## Modo 2 — instalar como plugin global
 
-Se você usa os comandos com frequência e não quer o `npx` a cada vez, registre o marketplace uma vez:
-
 ```bash
 claude plugin marketplace add fontdata-tecnologia/ai-harness
 claude plugin install fontdata@ai-harness
 ```
 
-Os comandos passam a existir em qualquer sessão do Claude Code como `/fontdata:<comando>`.
+Os comandos passam a existir em qualquer sessão como `/fontdata:<comando>`, os agents como `fontdata:<agent>` e os
+hooks ficam ativos em todos os projetos.
 
 ## Modo 3 — instalar no projeto (`init`)
 
-Quando você quer os comandos versionados junto com o repositório, em `.claude/commands/`:
+Para versionar comandos, skills, agents e hooks junto com o código:
 
 ```bash
-# npm / npx
 npx @fontdata/ai-harness init
-
-# yarn
-yarn dlx @fontdata/ai-harness init
-
-# pnpm
-pnpm dlx @fontdata/ai-harness init
-```
-
-Ou instale o CLI globalmente uma vez:
-
-```bash
-npm i -g @fontdata/ai-harness
-fontdata-ai-harness init
 ```
 
-Instalados assim, os comandos são invocados sem prefixo: `/harness`, `/gerar-spec`, etc.
+O `init` interativo detecta se o projeto é novo ou existente, pergunta o que instalar e grava um lock com o hash de
+cada arquivo em `.ai-harness/lock.json`. Instalados assim, os comandos são invocados sem prefixo: `/harness`,
+`/resolver-bug`...
 
-## Outros comandos do CLI
+Sem terminal interativo (em CI, por exemplo), o `init` só simula; `--yes` aplica:
 
 ```bash
-npx @fontdata/ai-harness list     # lista todos os comandos do catálogo
-npx @fontdata/ai-harness --help   # ajuda
+npx @fontdata/ai-harness init --escopo recomendado --yes
+npx @fontdata/ai-harness init --comandos resolver-bug,nova-tarefa --sem-harness --yes
 ```
 
-## Migrando do `@fontdata/ai-commands`
-
-O pacote foi renomeado de `@fontdata/ai-commands` para `@fontdata/ai-harness` na versão 2.0.0. Os comandos continuam os mesmos; muda o nome do pacote, o nome do plugin e o prefixo.
-
-| Você usava | Passe a usar |
+| Flag | Efeito |
 |---|---|
-| `npx @fontdata/ai-commands <comando>` | `npx @fontdata/ai-harness <comando>` |
-| `/ai-commands:<comando>` | `/fontdata:<comando>` |
-| Plugin `ai-commands@fontdata` | Plugin `fontdata@ai-harness` (veja abaixo) |
-| `npm i -g @fontdata/ai-commands` + `fontdata-ai-commands init` | `npm uninstall -g @fontdata/ai-commands && npm i -g @fontdata/ai-harness` + `fontdata-ai-harness init` |
-| Comandos instalados via `init` | Nada muda — os arquivos em `.claude/commands/` não têm prefixo |
-
-Para trocar o plugin global:
-
-```bash
-claude plugin uninstall ai-commands@fontdata
-claude plugin marketplace remove fontdata
-claude plugin marketplace add fontdata-tecnologia/ai-harness
-claude plugin install fontdata@ai-harness
-```
+| `--escopo recomendado\|tudo` | Conjunto de comandos |
+| `--comandos a,b,c` | Seleção manual |
+| `--sem-harness` | Não inclui o comando-mestre `/harness` |
+| `--sem-hooks` / `--sem-agents` | Não instala hooks / agents |
+| `--sem-comentarios` | Não instala a rule de comentários, o hook e a catraca do legado |
+| `--claude-md criar\|manter\|backup\|sobrescrever` | O que fazer com o `CLAUDE.md` (padrão: `criar`) |
+| `--conflito sobrescrever\|pular` | Arquivos que já existem (padrão: `pular`) |
+| `--yes` | Aplica; sem ele, só simula |
 
-Os binários `ai-commands` e `fontdata-ai-commands` foram removidos: use `ai-harness` e `fontdata-ai-harness`.
+Com o plugin `fontdata@ai-harness` habilitado, o `init` não instala os hooks no projeto, para eles não rodarem
+duas vezes.
 
-## O que o `init` faz
+## Subcomandos do CLI
 
-Fluxo interativo:
+| Subcomando | O que faz |
+|---|---|
+| `init [caminho]` | Instala comandos, skills, agents e hooks no projeto |
+| `doctor [caminho]` | Diagnostica instalação, contrato dos documentos, rastro, bloqueios antigos e versão do Node |
+| `update [caminho]` | Atualiza o que foi instalado sem sobrescrever alterações locais (`--check`, `--yes`, `--forcar`) |
+| `migrar [caminho]` | Move os documentos do layout anterior para `docs/trabalhos/<id>/` (`--yes`) |
+| `memoria [caminho]` | Índice de quem mexeu em cada arquivo (`--arquivo <caminho>`, `--regressao <id>`) |
+| `evento <evento>` | Grava no rastro do trabalho (usado por fluxos e agents) |
+| `comentarios [caminho]` | Instala o hook do padrão de comentários com a catraca do legado (`--yes`) |
+| `list` | Lista o catálogo |
+
+## Modelo de arquivos
+
+| Arquivo | Papel |
+|---|---|
+| `SPEC.md` (raiz) | Definição **principal** do projeto |
+| `CLAUDE.md` (raiz) | Context file lido em toda sessão |
+| `docs/trabalhos/AAAA-MM-DD-<slug>/SPEC.md` | Spec do trabalho |
+| `docs/trabalhos/<id>/PLAN.md` | Plano: sprints, fases e tasks (as tasks também no frontmatter) |
+| `docs/trabalhos/<id>/DECISOES.md` | Decisões tomadas no planejamento e na execução |
+| `docs/trabalhos/<id>/BLOQUEIOS.md` | Dúvidas que pararam uma task |
+| `docs/trabalhos/<id>/relatorios/TECNICO.md` e `CLIENTE.md` | Relatório para engenharia e para cliente ou gestão |
+| `docs/eventos/<id>.jsonl` | Rastro de eventos (não versionado por padrão) |
+| `.ai-harness/lock.json` e `config.json` | Lock da instalação e configuração dos hooks (versionar) |
 
-1. Pergunta a **pasta do projeto** (padrão: pasta atual).
-2. **Detecta se o projeto é novo ou existente** (manifestos de stack, arquivos `.sln/.csproj`, pastas de código com conteúdo) e avisa o que isso muda na seleção manual.
-3. Pergunta **o que instalar**: _Conjunto recomendado_, _Tudo_ ou _Escolher manualmente_ (seleção por categoria).
-   - Em _Escolher manualmente_, **projeto novo** já vem com os comandos recomendados marcados; **projeto existente** vem vazio (ideal para cadastrar comandos avulsos).
-4. Pergunta se quer o **comando-mestre `/harness`** (conduz a sequência de setup em ordem). Se escolhido, o init **inclui automaticamente** os comandos que o `/harness` depende, mesmo que não tenham sido marcados. O mesmo vale para **dependências entre comandos** (campo `requires` no catálogo): ao instalar um comando que depende de outro, o dependente entra junto automaticamente.
-5. Pergunta se deve criar/atualizar o **`CLAUDE.md` base** na raiz (com opção de `.bak` se já existir).
-6. Copia os comandos para `.claude/commands/` e mostra um resumo. Em caso de conflito, pergunta se sobrescreve ou pula.
-7. Instala em `.claude/skills/` as **skills exigidas** pelos comandos escolhidos (campo `requiresSkills` no catálogo) — hoje, `/auditar-seguranca` puxa a skill `lgpd-checker`.
+Os formatos estão em [`docs/contratos/ARTEFATOS.md`](docs/contratos/ARTEFATOS.md) e
+[`docs/contratos/EVENTOS.md`](docs/contratos/EVENTOS.md); o `doctor` valida os dois.
 
-## Skills instaláveis
+## Garantias
 
-Algumas skills acompanham comandos e são instaladas junto com eles, em `.claude/skills/<id>/`.
+### Hooks
 
-| Skill | Vem com | O que faz |
+| Hook | Quando | Modo inicial |
 |---|---|---|
-| `lgpd-checker` | `/auditar-seguranca` | Analisa conformidade com a LGPD (Lei nº 13.709/2018) em 11 categorias, com checklist, artigos de referência e template de relatório. |
+| `lembrete` | O pedido parece bug, funcionalidade nova, risco de segurança ou problema de performance: sugere o fluxo certo | aviso |
+| `segredo-no-commit` | `git commit` com chave de acesso, token, chave privada ou senha no diff | **bloqueio** |
+| `proteger-contratos` | SPEC, PLAN ou CLAUDE.md reescritos durante a execução de um trabalho | aviso |
+| `task-so-fecha-verde` | Task marcada como concluída sem suíte verde no rastro | aviso |
+| `sem-jargao` | Termo técnico no relatório para o cliente | aviso |
 
-A skill `lgpd-checker` é uma cópia vendorizada de
-[bittencourtthulio/lgpd-checker](https://github.com/bittencourtthulio/lgpd-checker); veja
-`templates/skills/lgpd-checker/ORIGEM.md` para créditos e instruções de atualização.
-
-## Modelo de arquivos do harness
+O modo de cada hook (`aviso`, `bloqueio` ou `desligado`) fica em `.ai-harness/config.json`. Hook que falha
+internamente não atrapalha o trabalho — exceto o de segurança em modo bloqueio.
 
-| Arquivo | Local | Papel |
-|--------|-------|-------|
-| `SPEC.md` | raiz | Definição **principal** e completa do projeto (única). |
-| `CLAUDE.md` | raiz | Context file lido em toda sessão. |
-| `docs/specs/AAAA-MM-DD-*.md` | `docs/specs/` | Specs **complementares**: o start inicial e cada nova tarefa. |
-| `docs/plans/AAAA-MM-DD-*.md` | `docs/plans/` | Plano de implementação de cada spec complementar. |
-| `docs/bugs/AAAA-MM-DD-<slug>.md` | `docs/bugs/` | Plano de correção de bugs (via `/resolver-bug`). |
+### Agents somente leitura
 
-## Comandos instaláveis
+| Agent | Papel |
+|---|---|
+| `revisor-testes` | Os testes da task falhariam com a implementação errada? |
+| `qa` | Critérios de aceite com evidência e suíte completa antes do gate |
+| `investigador` | Causa raiz de um bug, comprovada ou marcada como hipótese |
+| `auditor-plano` | O plano pode ser executado sem ninguém perguntar nada no meio? |
 
-`⭐` = incluído no _Conjunto recomendado_.
+## Catálogo
 
-### Setup inicial
-- `/validar-ideia` ⭐ — valida se a ideia cabe em ~4h com multi-agents
-- `/gerar-spec` ⭐ — entrevista e gera o `SPEC.md` principal na raiz
-- `/gerar-claude-md` ⭐ — gera o `CLAUDE.md` a partir do SPEC
-- `/gerar-ignore` — gera `.claudeignore` e `.gitignore`
-- `/scaffold` ⭐ — estrutura inicial, rota `/health` e testes de smoke
+`⭐` = incluído no conjunto recomendado. **(skill)** = fluxo publicado como skill: invocado pelo mesmo nome e
+também acionado pelo modelo quando o pedido combina.
 
-> O plano do start inicial é gerado pelo `/nova-tarefa` (veja _Slash commands & dia a dia_).
+### Setup e contexto
+- `/sincronizar-claude-md` ⭐ — gera o `SPEC.md` e o `CLAUDE.md` que faltam e reconcilia os existentes com o código e os agents, inclusive a seção de orquestração
+- `/evoluir-harness` ⭐ **(skill)** — audita a pasta `.claude` e cria agents, skills, rules, hooks, code-reviewer e design system do projeto
 
 ### Orquestração & implementação
-- `/executar-plan` ⭐ — orquestra a execução do plano com sub-agents em paralelo
-- `/configurar-orquestrador` — configura o agente orquestrador no `CLAUDE.md`
-- `/corrigir-review` — organiza correções em sprints/fases/tasks com TDD
-- `/review-por-task` — enforça implementação → review isolado → correção
-
-### Harness (agents/skills/hooks/rules)
-- `/criar-skill` — cria skills do projeto em `.claude/skills/`
-- `/criar-agents` — cria agents especializados em `.claude/agents/`
-- `/criar-hooks` — cria hooks por agent em `.claude/hooks/`
-- `/criar-rules` — cria rules em `.claude/rules/`
-- `/configurar-comentarios` ⭐ — instala o padrão de comentários em três camadas: a rule `.claude/rules/comentarios.md` (orçamento duro e contra-exemplos), o bloco autossuficiente no `CLAUDE.md` e o hook `PostToolUse` bloqueante com **catraca** sobre o código legado — em qualquer linguagem, inclusive Delphi/Pascal
-- `/criar-code-reviewer` ⭐ — cria o agent `code-reviewer` (somente leitura)
-
-### Slash commands & dia a dia
-- `/resolver-bug` ⭐ — investiga, planeja em `docs/bugs` e corrige um bug
-- `/nova-tarefa` ⭐ — gera spec+plano em `docs/` (start inicial ou nova tarefa) e, se confirmado, dispara o orquestrador
+- `/executar-plan` ⭐ **(skill)** — executa o plano com sub-agents, gates de `revisor-testes` e `qa`, portões extras do projeto, bloqueios e retomada
+
+### Dia a dia
+- `/resolver-bug` ⭐ **(skill)** — investiga a causa raiz, corrige com teste de regressão e entrega relatório técnico e para o cliente
+- `/nova-tarefa` ⭐ **(skill)** — verifica se já existe, gera SPEC e PLAN do trabalho, audita o plano e dispara a execução
 
 ### Qualidade & manutenção de código
-- `/gerar-testes` — detecta cobertura faltante e escreve testes seguindo TDD (RED→GREEN)
-- `/refatorar` — refatora usando os testes como rede de segurança, sem mudar comportamento
-- `/codigo-morto` — varre o projeto em busca de código morto e propõe remoção segura
+- `/gerar-testes` — escreve testes para o que não está coberto, sem alterar o código de produção
+- `/refatorar` — refatora em passos pequenos com os testes como rede de segurança, inclusive a remoção de código morto
 - `/atualizar-deps` — atualiza dependências em lotes, testando a cada passo
 
 ### Documentação & onboarding
-- `/sincronizar-claude-md` — aponta onde o `CLAUDE.md`/`SPEC.md` divergiu do código
-- `/diagrama` — gera diagramas Mermaid de arquitetura/fluxo a partir do código
-- `/onboarding` — gera um guia de onboarding (rodar, entender e contribuir) em `docs/`
+- `/diagrama` — gera diagramas Mermaid fiéis ao código
+- `/onboarding` — gera um guia verificado para quem chega no projeto
 - `/gerar-env` — monta o `.env.example` a partir das variáveis lidas no código
 
 ### Avançado
-- `/criar-rag` — sistema de RAG (SQLite + sqlite-vec) para capturar aprendizados
-- `/auditar-ui` — navega a app via Playwright MCP e audita UX/UI e/ou acessibilidade (a11y)
-- `/design-system` — cria o agent de design system com skills e rules
-- `/auditar-performance` — audita gargalos de performance (queries, bundle, renders)
-- `/auditar-seguranca` — auditoria defensiva (segredos, deps, inputs, configs) **+ conformidade LGPD** via skill `lgpd-checker`
-
-### Manutenção & validação
-- `/validar-commands` — audita `.claude`: valida models dos agents, aponta redundâncias e sugere novos commands
+- `/memoria` **(skill)** — mostra quem já mexeu num arquivo e por quê e aponta regressões candidatas de um bug
+- `/auditar-ui` **(skill)** — navega a aplicação via Playwright MCP e audita UX/UI e acessibilidade
+- `/auditar-performance` **(skill)** — mede e audita gargalos de performance
+- `/auditar-seguranca` **(skill)** — auditoria defensiva de segurança e conformidade com a LGPD
 
 ### Utilitário
-- `/git-commit-push` ⭐ — gera mensagem (PT-BR, Conventional Commits) e faz add/commit/push
-- `/versao` ⭐ — detecta o versionamento da stack atual (React+Vite/Next, Node, Delphi, .NET, Flutter…) e aplica o bump de versão + changelog + commit de release (gate de aprovação, sem push). **Autossuficiente**: gera o changelog amigável dos commits internamente, sem depender de outros comandos.
-- `/configurar-auto-tag` ⭐ — detecta o padrão de versionamento (qualquer stack, inclusive Delphi) e gera a GitHub Action que cria a tag automaticamente quando a versão chega na `main`. Separa **versionar** (`/versao`, humano) de **taguear/deployar** (automático). Documenta a pegadinha `GITHUB_TOKEN` × `RELEASE_PAT`.
-- `/revisar-pr` — revisa um PR ou o diff atual, classificando os achados
+- `/git-commit-push` ⭐ — gera a mensagem (PT-BR, Conventional Commits) e faz add, commit e push
+- `/versao` ⭐ — detecta o versionamento da stack e aplica bump e changelog, com aprovação e sem push
+- `/revisar-pr` — revisa um PR ou o diff atual, classifica os achados e, se pedido, organiza as correções num trabalho
 
-### Comando-mestre
-- `/harness` — conduz a sequência de setup em ordem, validando entre etapas
+### Setup guiado
+- `/harness` **(skill)** — conduz o setup em etapas (ideia, contexto, ignores, plano do start, scaffold, peças do harness, auto-tag e execução); `/harness <etapa>` roda uma etapa isolada
 
-## Fluxo recomendado
+O padrão de comentários não é um comando: a rule, o hook e a catraca do legado vêm do `init` e do `update`.
+
+A skill `lgpd-checker`, usada pela auditoria de segurança, é uma cópia vendorizada de
+[bittencourtthulio/lgpd-checker](https://github.com/bittencourtthulio/lgpd-checker); veja
+`templates/skills/lgpd-checker/ORIGEM.md`.
 
-A forma mais simples é rodar o comando-mestre **`/harness`**, que conduz toda a sequência abaixo em ordem, parando para validar entre as etapas. Ele pergunta logo no início se o projeto é **novo** ou **existente** e ajusta o fluxo.
+## Fluxo recomendado
 
-**Projeto novo** — sequência completa:
+O jeito mais simples é rodar **`/harness`**, que pergunta se o projeto é novo ou existente e conduz as etapas:
 
 ```
-/validar-ideia → /gerar-spec → /gerar-claude-md → /gerar-ignore
-→ /nova-tarefa (plano do start) → /scaffold
-→ /configurar-comentarios → /criar-skill → /criar-agents → /criar-code-reviewer → /criar-rules → /criar-hooks → /configurar-orquestrador
+ideia → /sincronizar-claude-md → ignores → /nova-tarefa (start) → scaffold
+→ /evoluir-harness (skills, agents, code-reviewer, rules, hooks e rule de projeto) → auto-tag
 → /executar-plan
 ```
 
-> As skills vêm **antes** dos agents (os agents dependem delas).
+Em projeto existente, o `/harness` pula a ideia, o scaffold e a execução, e começa pelo `npx @fontdata/ai-harness doctor`.
 
-**Projeto existente** — documenta e monta o harness sobre o código que já existe, pulando validação de ideia, plano do start, scaffold e execução:
+No dia a dia: `/nova-tarefa` → `/executar-plan` para funcionalidades, `/resolver-bug` para defeitos,
+`/git-commit-push` e `/versao`. De vez em quando: `/sincronizar-claude-md` e `/evoluir-harness`.
 
-```
-/gerar-spec → /gerar-claude-md → /gerar-ignore
-→ /configurar-comentarios → /criar-skill → /criar-agents → /criar-code-reviewer → /criar-rules → /criar-hooks → /configurar-orquestrador
-```
+## Exemplos
+
+A pasta [`exemplos/`](exemplos/) traz trabalhos gerados em sessões reais do Claude Code sobre um projeto demo: uma
+funcionalidade nova, uma correção de bug e uma auditoria de segurança, com os documentos de cada um.
+
+## Migrando da 2.0 (ou da 1.x) para a 2.1
+
+**Node.js 22** ou superior passa a ser exigido. Num branch do projeto, siga esta ordem:
+
+1. `npx @fontdata/ai-harness update --check` e depois `update --yes`. O `update` faz o seguinte:
+   - reconhece a instalação de qualquer versão anterior, mesmo sem lock;
+   - troca os comandos que viraram skill ou saíram do catálogo, e renomeia para `<id>-legado.md` os que você editou;
+   - instala agents, hooks, o padrão de comentários e a rule de projeto.
+2. Leve o que for do projeto nos arquivos `-legado` para `.claude/rules/harness-projeto.md`, ou para skills do projeto
+   com `/evoluir-harness`, e apague os arquivos.
+3. `npx @fontdata/ai-harness migrar`, que só simula, e depois `migrar --yes`: move os documentos do layout anterior
+   para `docs/trabalhos/<id>/`.
+4. `npx @fontdata/ai-harness doctor` até não sobrar erro.
+
+O que quebra: os fluxos viraram **skills**, o `/criar-rag` foi substituído pela `/memoria`, o catálogo passou de 36
+para 19 comandos e o `/configurar-comentarios` saiu (veja o `CHANGELOG.md`). O
+[guia de migração](docs/guias/migracao-2.1.md) explica cada aviso do `doctor` e a ordem sugerida para vários
+projetos.
 
-No dia a dia: `/nova-tarefa`, `/resolver-bug`, `/git-commit-push` e `/versao` (para publicar uma nova versão).
+## Migrando do `@fontdata/ai-commands`
+
+O pacote foi renomeado de `@fontdata/ai-commands` para `@fontdata/ai-harness` na versão 2.0.0.
+
+| Você usava | Passe a usar |
+|---|---|
+| `npx @fontdata/ai-commands <comando>` | `npx @fontdata/ai-harness <comando>` |
+| `/ai-commands:<comando>` | `/fontdata:<comando>` |
+| Plugin `ai-commands@fontdata` | Plugin `fontdata@ai-harness` (veja abaixo) |
+| `npm i -g @fontdata/ai-commands` + `fontdata-ai-commands init` | `npm uninstall -g @fontdata/ai-commands && npm i -g @fontdata/ai-harness` + `fontdata-ai-harness init` |
+| Comandos instalados via `init` | Nada muda no nome — rode `update` para receber a 2.1 |
 
-## Desenvolvimento
+Para trocar o plugin global:
 
 ```bash
-npm install
-node bin/cli.js list
-node bin/cli.js harness                    # roda na pasta atual, com o plugin local
-node bin/cli.js init ./caminho-de-teste
-claude plugin validate .                   # valida o manifesto do plugin
+claude plugin uninstall ai-commands@fontdata
+claude plugin marketplace remove fontdata
+claude plugin marketplace add fontdata-tecnologia/ai-harness
+claude plugin install fontdata@ai-harness
 ```
 
-Os templates ficam em `templates/` (`commands/*.md` + `skills/` + `CLAUDE.md` + `catalog.json`). Para adicionar um comando: crie o `.md` em `templates/commands/` e registre-o em `templates/catalog.json`.
+## Contribuindo
+
+Veja o [`CONTRIBUTING.md`](CONTRIBUTING.md): ambiente, estrutura do repositório e como criar comando, skill, hook e
+agent. As mudanças de cada versão estão no [`CHANGELOG.md`](CHANGELOG.md).
+
+## Licença
 
-A raiz do pacote também é um plugin do Claude Code: `.claude-plugin/plugin.json` aponta `commands` e `skills` para dentro de `templates/`, então **não há duplicação de arquivos** — a mesma pasta serve o `init` (cópia) e o modo sem instalação (`--plugin-dir`). O `npm version` sincroniza a `version` do `plugin.json` automaticamente (script `version` → `scripts/sync-plugin-version.mjs`).
+MIT — veja [`LICENSE`](LICENSE).

package/{src → dist}/catalog.js

@@ -1,26 +1,19 @@
 import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
-
+import { fileURLToPath } from 'node:url';
 const __dirname = dirname(fileURLToPath(import.meta.url));
-
 /** Raiz da pasta de templates do pacote. */
 export const templatesDir = join(__dirname, '..', 'templates');
-
 /** Carrega e retorna o catálogo de comandos (templates/catalog.json). */
 export function loadCatalog() {
-  const raw = readFileSync(join(templatesDir, 'catalog.json'), 'utf8');
-  return JSON.parse(raw);
+    const raw = readFileSync(join(templatesDir, 'catalog.json'), 'utf8');
+    return JSON.parse(raw);
 }
-
 /** Lista achatada de todos os comandos do catálogo, com o grupo anexado. */
 export function allCommands(catalog) {
-  return catalog.groups.flatMap((group) =>
-    group.commands.map((cmd) => ({ ...cmd, group: group.title }))
-  );
+    return catalog.groups.flatMap((group) => group.commands.map((cmd) => ({ ...cmd, group: group.title })));
 }
-
 /** Apenas os comandos marcados como recomendados (conjunto núcleo). */
 export function recommendedCommands(catalog) {
-  return allCommands(catalog).filter((cmd) => cmd.recommended);
+    return allCommands(catalog).filter((cmd) => cmd.recommended);
 }