@fontdata/ai-harness 2.0.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "ai-harness",
+  "owner": {
+    "name": "Fontdata Tecnologia",
+    "url": "https://github.com/fontdata-tecnologia"
+  },
+  "metadata": {
+    "description": "Harness de engenharia com IA da Fontdata para Claude Code."
+  },
+  "plugins": [
+    {
+      "name": "fontdata",
+      "source": "./",
+      "description": "36 slash commands para conduzir spec, scaffold, harness, revisão e manutenção de projetos com Claude Code."
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "fontdata",
+  "version": "2.0.0",
+  "description": "Harness de engenharia com IA da Fontdata para Claude Code",
+  "author": { "name": "Fontdata" },
+  "commands": ["./templates/commands"],
+  "skills": ["./templates/skills"]
+}

package/README.md

@@ -0,0 +1,239 @@
+# @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.
+
+> Foco exclusivo em **Claude Code**.
+
+## 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.
+
+```bash
+# npm / npx
+npx @fontdata/ai-harness harness
+npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
+npx @fontdata/ai-harness versao minor
+
+# yarn
+yarn dlx @fontdata/ai-harness harness
+
+# pnpm
+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.
+
+O texto depois do nome do comando vira o `$ARGUMENTS` daquele prompt. 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:
+
+```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`).
+
+## 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>`.
+
+## Modo 3 — instalar no projeto (`init`)
+
+Quando você quer os comandos versionados junto com o repositório, em `.claude/commands/`:
+
+```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.
+
+## Outros comandos do CLI
+
+```bash
+npx @fontdata/ai-harness list     # lista todos os comandos do catálogo
+npx @fontdata/ai-harness --help   # ajuda
+```
+
+## 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 |
+|---|---|
+| `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
+```
+
+Os binários `ai-commands` e `fontdata-ai-commands` foram removidos: use `ai-harness` e `fontdata-ai-harness`.
+
+## O que o `init` faz
+
+Fluxo interativo:
+
+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`.
+
+## Skills instaláveis
+
+Algumas skills acompanham comandos e são instaladas junto com eles, em `.claude/skills/<id>/`.
+
+| Skill | Vem com | O que faz |
+|---|---|---|
+| `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. |
+
+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
+
+| 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`). |
+
+## Comandos instaláveis
+
+`⭐` = incluído no _Conjunto recomendado_.
+
+### 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
+
+> O plano do start inicial é gerado pelo `/nova-tarefa` (veja _Slash commands & dia a dia_).
+
+### 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
+
+### 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
+- `/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/`
+- `/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
+
+### 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
+
+### Comando-mestre
+- `/harness` — conduz a sequência de setup em ordem, validando entre etapas
+
+## Fluxo recomendado
+
+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.
+
+**Projeto novo** — sequência completa:
+
+```
+/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
+→ /executar-plan
+```
+
+> As skills vêm **antes** dos agents (os agents dependem delas).
+
+**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:
+
+```
+/gerar-spec → /gerar-claude-md → /gerar-ignore
+→ /configurar-comentarios → /criar-skill → /criar-agents → /criar-code-reviewer → /criar-rules → /criar-hooks → /configurar-orquestrador
+```
+
+No dia a dia: `/nova-tarefa`, `/resolver-bug`, `/git-commit-push` e `/versao` (para publicar uma nova versão).
+
+## Desenvolvimento
+
+```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
+```
+
+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`.
+
+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`).

package/bin/cli.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { loadCatalog, allCommands } from '../src/catalog.js';
+import { runCommand, runnableIds, suggestIds } from '../src/run.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const RESERVED = new Set(['init', 'list', 'run', 'help', '--help', '-h', '--version', '-v']);
+
+function pkgVersion() {
+  try {
+    const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
+    return pkg.version;
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function printHelp() {
+  console.log(`
+@fontdata/ai-harness — harness de engenharia com IA para Claude Code
+
+Uso:
+  npx @fontdata/ai-harness <comando> [contexto]     roda o comando na pasta atual
+  npx @fontdata/ai-harness init                     instala os comandos no projeto
+
+Executar sem instalar:
+  <comando>       Abre o Claude Code aqui já executando o comando (ex.: harness)
+  run <comando>   Forma explícita, útil quando o nome colide com uma palavra reservada
+
+Gerenciar:
+  init [caminho]  Instala os slash commands em .claude/commands do projeto (interativo)
+  list            Lista todos os comandos disponíveis no catálogo
+  --help, -h      Mostra esta ajuda
+  --version, -v   Mostra a versão
+
+Exemplos:
+  npx @fontdata/ai-harness harness
+  npx @fontdata/ai-harness resolver-bug "login 500 no refresh token"
+  npx @fontdata/ai-harness run versao minor
+  npx @fontdata/ai-harness harness -- --model claude-opus-5
+
+Tudo depois de \`--\` é repassado ao Claude Code (--model, --effort, -p, ...).
+`);
+}
+
+function printList() {
+  const catalog = loadCatalog();
+  console.log('\nComandos disponíveis:\n');
+  for (const group of catalog.groups) {
+    console.log(`  ${group.title}`);
+    for (const cmd of group.commands) {
+      const star = cmd.recommended ? ' *' : '  ';
+      console.log(`   ${star} ${cmd.title.padEnd(26)} ${cmd.description}`);
+    }
+    console.log('');
+  }
+  console.log(`  (* = conjunto recomendado · total: ${allCommands(catalog).length} comandos + /harness)\n`);
+}
+
+/** Separa os argumentos do comando dos flags destinados ao Claude Code. */
+function splitArgs(rest) {
+  const sep = rest.indexOf('--');
+  if (sep === -1) return { args: rest, claudeFlags: [] };
+  return { args: rest.slice(0, sep), claudeFlags: rest.slice(sep + 1) };
+}
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+
+  if (cmd === '--version' || cmd === '-v') {
+    console.log(pkgVersion());
+    return;
+  }
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') {
+    printHelp();
+    return;
+  }
+  if (cmd === 'list') {
+    printList();
+    return;
+  }
+  if (cmd === 'init') {
+    // Import dinâmico: só carrega @clack/prompts quando o init é realmente usado.
+    const { runInit } = await import('../src/init.js');
+    await runInit(argv[1]);
+    return;
+  }
+  if (cmd === 'run') {
+    const id = argv[1];
+    if (!id) {
+      console.error('Informe o comando a executar. Ex.: npx @fontdata/ai-harness run harness\n');
+      printHelp();
+      process.exit(1);
+    }
+    const { args, claudeFlags } = splitArgs(argv.slice(2));
+    process.exit(runCommand(id, args, claudeFlags));
+  }
+
+  const ids = runnableIds();
+  if (ids.includes(cmd.replace(/^\//, ''))) {
+    const { args, claudeFlags } = splitArgs(argv.slice(1));
+    process.exit(runCommand(cmd, args, claudeFlags));
+  }
+
+  if (!RESERVED.has(cmd)) {
+    const near = suggestIds(cmd.replace(/^\//, ''), ids);
+    console.error(`Comando desconhecido: ${cmd}`);
+    if (near.length) console.error(`\nVocê quis dizer: ${near.join(', ')}`);
+    console.error('');
+  }
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error('Erro:', err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@fontdata/ai-harness",
+  "version": "2.0.0",
+  "description": "Harness de engenharia com IA da Fontdata para Claude Code: roda os slash commands direto na pasta do projeto via npx, sem instalar nada — ou instala-os em .claude/commands.",
+  "type": "module",
+  "bin": {
+    "ai-harness": "bin/cli.js",
+    "fontdata-ai-harness": "bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".claude-plugin/",
+    "bin/",
+    "src/",
+    "templates/",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/cli.js",
+    "version": "node scripts/sync-plugin-version.mjs && git add .claude-plugin/plugin.json"
+  },
+  "keywords": [
+    "claude-code",
+    "ai",
+    "harness",
+    "slash-commands",
+    "scaffold",
+    "fontdata"
+  ],
+  "author": "Fontdata Tecnologia",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fontdata-tecnologia/ai-harness.git"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+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);
+}
+
+/** 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 }))
+  );
+}
+
+/** Apenas os comandos marcados como recomendados (conjunto núcleo). */
+export function recommendedCommands(catalog) {
+  return allCommands(catalog).filter((cmd) => cmd.recommended);
+}