@fontdata/ai-commands

CLI interativa que instala o harness de engenharia com IA da Fontdata (slash commands do Claude Code) na pasta .claude/ de qualquer projeto — novo ou existente. Em vez de copiar e adaptar prompts manualmente toda vez, rode um comando e escolha o que instalar.

Foco exclusivo em Claude Code. Os comandos são instalados em .claude/commands/.

Como executar

Não precisa instalar nada — use o runner do seu gerenciador de pacotes:

# npm / npx
npx @fontdata/ai-commands init

# yarn
yarn dlx @fontdata/ai-commands init

# pnpm
pnpm dlx @fontdata/ai-commands init

Ou instale globalmente uma vez:

# npm
npm i -g @fontdata/ai-commands
fontdata-ai-commands init

# yarn
yarn global add @fontdata/ai-commands
fontdata-ai-commands init

# pnpm
pnpm add -g @fontdata/ai-commands
fontdata-ai-commands init

Outros comandos do CLI:

# npm / npx
npx @fontdata/ai-commands list     # lista todos os comandos do catálogo
npx @fontdata/ai-commands --help   # ajuda

# yarn
yarn dlx @fontdata/ai-commands list
yarn dlx @fontdata/ai-commands --help

# pnpm
pnpm dlx @fontdata/ai-commands list
pnpm dlx @fontdata/ai-commands --help

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 — por exemplo /versao, que usa o /gerar-changelog — 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.

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/
• /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)

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 (gate de aprovação, sem push). Instala e usa o /gerar-changelog.
• /revisar-pr — revisa um PR ou o diff atual, classificando os achados
• /gerar-changelog ⭐ — gera changelog amigável dos commits (autossuficiente). Tem modo compacto (3 categorias) e modo "apenas gerar" (sem salvar), usados pelo /versao

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
→ /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
→ /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

npm install
node bin/cli.js list
node bin/cli.js init ./caminho-de-teste

Os templates ficam em templates/ (commands/*.md + CLAUDE.md + catalog.json). Para adicionar um comando: crie o .md em templates/commands/ e registre-o em templates/catalog.json.