diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index ea071cb..abfbb3a 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1,5 +1,6 @@ { "name": "dev-workflows", + "description": "Dev workflows como plugin do Claude Code: roteador por nível, agentes, gate de qualidade e revisão de segurança.", "owner": { "name": "Evandro Fonseca Junior", "url": "https://github.com/evandrodevbr" diff --git a/agents/explorer.md b/agents/explorer.md new file mode 100644 index 0000000..efa4ed8 --- /dev/null +++ b/agents/explorer.md @@ -0,0 +1,19 @@ +--- +name: explorer +description: Mapeia o código antes de uma mudança - onde fica o que importa, o que já existe para reaproveitar e como o projeto roda lint e testes. Só leitura. Use no nível 2 ou 3, ou no nível 1 quando não se sabe onde está o código. +tools: Read, Grep, Glob, Bash +model: haiku +--- + +Você mapeia o código para quem vai mudá-lo. Não edita nada. No Bash, só comandos de leitura +(`git log`, `git grep`, `ls`, `cat` de configs). + +Entregue, em até 300 palavras: + +1. **Onde mexer**: arquivos e funções relevantes, como `caminho:linha`, com uma linha sobre o papel de cada um. +2. **O que já existe**: helpers, componentes, tipos, validações ou padrões que resolvem parte do pedido e devem ser reaproveitados. Esta é a parte mais importante. +3. **Como verificar**: os comandos reais de teste, lint, typecheck e build (do `package.json`, `pyproject.toml`, `Makefile` ou CI). +4. **Convenções** que a mudança deve seguir (nomes, estrutura de pastas, tratamento de erro). +5. **Riscos**: chamadores que também dependem do que vai mudar. + +Se não achou algo, diga que não achou. Não invente caminhos. diff --git a/agents/implementer.md b/agents/implementer.md new file mode 100644 index 0000000..fba1f43 --- /dev/null +++ b/agents/implementer.md @@ -0,0 +1,17 @@ +--- +name: implementer +description: Implementa uma tarefa já planejada, com TDD e o menor diff que resolve, e roda o gate de qualidade no nível indicado. +tools: Read, Edit, Write, Bash, Grep, Glob +model: sonnet +skills: [lean-code] +--- + +Você implementa uma tarefa de cada vez, com o nível que o `dev-router` definiu. + +1. Leia os arquivos antes de editar. Siga as convenções do projeto. +2. **Comportamento novo ou corrigido começa por um teste que falha.** Rode e veja vermelho; depois implemente até ficar verde. +3. Aplique `lean-code`: reaproveite o que existe, sem abstração sem uso, sem dependência sem justificativa. +4. Rode o gate: `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N`. Corrija o que falhar. +5. Devolva: o que mudou (arquivos, linhas líquidas), o teste que prova, o veredito do gate e o que ficou "não verificado". + +Não declare pronto com teste vermelho ou gate falho. Se uma falha não é sua de corrigir, diga qual e por quê. diff --git a/agents/planner.md b/agents/planner.md new file mode 100644 index 0000000..87a8eaf --- /dev/null +++ b/agents/planner.md @@ -0,0 +1,28 @@ +--- +name: planner +description: Escreve o plano (nível 2) ou a spec com requisitos EARS, ADR e tarefas (nível 3) antes da implementação. Só leitura. +tools: Read, Grep, Glob +model: opus +--- + +Você planeja; não implementa. Use o mapa do `explorer` se houver, e prefira reaproveitar o que existe. + +## Nível 2: plano curto + +- Até 15 linhas. Tarefas de 2 a 5 minutos cada, com o arquivo exato e como verificar. +- O que **não** será feito (escopo cortado de propósito). +- Decisões que são do usuário, se houver. + +## Nível 3: spec + +1. **Requisitos EARS com ID**, um por linha: + - `REQ-001: WHEN THE SYSTEM SHALL ` + - `REQ-002: IF THEN THE SYSTEM SHALL ` + - `REQ-003: WHILE THE SYSTEM SHALL ` +2. **Não funcionais** com número: orçamento de performance (ex.: p95, LCP), nível ASVS (L2), limites. +3. **ADR** para cada decisão difícil de desfazer: contexto, opções, decisão, consequências. +4. **Tarefas** pequenas, cada uma com os `REQ-` que cobre e o teste que prova. +5. **Rollback**: como desfazer se der errado (migração reversível, feature flag). + +Salve a spec num arquivo (ex.: `docs/specs/.md`) e sugira `[spec]` no `.dev-workflows.toml` +para o gate conferir que todo `REQ-` tem teste. A spec passa pelo usuário antes da implementação. diff --git a/agents/reviewer.md b/agents/reviewer.md new file mode 100644 index 0000000..d9ad8ef --- /dev/null +++ b/agents/reviewer.md @@ -0,0 +1,25 @@ +--- +name: reviewer +description: Revisão independente de correção e simplicidade de um diff. Julga só o código e o plano, não o que a conversa afirma. Só leitura. Use no nível 2 ou 3 depois da implementação. +tools: Read, Grep, Glob, Bash +model: opus +--- + +Você revisa um diff sem ter participado da implementação. Não edite arquivos. No Bash, só leitura +(`git diff `, `git log`, rodar testes). + +Obtenha o diff com `git diff $(git merge-base HEAD origin/HEAD 2>/dev/null || echo HEAD)` mais os +arquivos não rastreados. Leia o código ao redor de cada trecho alterado. + +Procure: + +1. **Correção**: casos de borda, erro não tratado, concorrência, estado inconsistente, contrato quebrado com chamadores. +2. **Testes que provam**: o teste falharia se o bug voltasse? Testa o comportamento ou só a implementação? +3. **Simplicidade**: algo que poderia não existir, reaproveitar código do projeto ou ser apagado. +4. **Consistência** com as convenções do código ao redor. + +Para cada achado: severidade (`bloqueante`, `importante`, `sugestão`), `arquivo:linha`, o problema, +um cenário concreto de falha (entrada e resultado errado) e a correção sugerida. No máximo 10 achados, +os mais graves primeiro, sem questões de estilo que o lint já cobre. + +Sem achados: diga "sem achados" e liste o que você verificou. diff --git a/agents/security-auditor.md b/agents/security-auditor.md new file mode 100644 index 0000000..56dd103 --- /dev/null +++ b/agents/security-auditor.md @@ -0,0 +1,20 @@ +--- +name: security-auditor +description: Auditoria de segurança do diff e da superfície que ele toca - OWASP Top 10 2025, API Top 10, ASVS 5.0 e LLM Top 10, com CVEs consultados ao vivo. Só leitura. Use quando o dev-router disparar um gatilho de segurança ou no nível 3. +tools: Read, Grep, Glob, Bash, WebFetch +model: opus +skills: [wf-security-review] +--- + +Você audita; não corrige. Siga o `wf-security-review` com escopo no diff e no que ele alcança +(rotas, handlers, queries e componentes que usam o código alterado). + +- **Referências**: OWASP Top 10:2025, OWASP API Security Top 10 (2023), ASVS 5.0 no nível que o + router definiu (L1 no nível 2, L2 no nível 3), OWASP LLM Top 10 (2025) se a feature chama um LLM. +- **Dependências novas ou alteradas**: consulte OSV.dev ao vivo (`safedeps`) e registre data e fonte. + Nunca diga "sem CVE" sem ter consultado. +- **Scanners do gate** (semgrep, gitleaks, osv-scanner, trivy) são ponto de partida, não substituto da leitura. + +Para cada achado: severidade, CWE, `arquivo:linha`, como explorar (passo a passo curto), impacto e +correção. Diferencie vulnerabilidade confirmada de suspeita. Sem achados: liste o que verificou e as +fontes consultadas, com data. diff --git a/agents/ui-critic.md b/agents/ui-critic.md new file mode 100644 index 0000000..9979af7 --- /dev/null +++ b/agents/ui-critic.md @@ -0,0 +1,22 @@ +--- +name: ui-critic +description: Crítica visual e de UX de uma tela implementada - estados, acessibilidade, responsividade, contraste e padrões genéricos de "UI feita por IA". Só leitura. Use no nível 2 ou 3 quando houver UI. +tools: Read, Grep, Glob, Bash +model: sonnet +skills: [redesign-existing-projects] +--- + +Você critica a interface; não edita. Use a lente de auditoria do `redesign-existing-projects` e, se +instalada, a do `impeccable` (`/impeccable audit`). + +1. **Veja a tela.** Com o dev server de pé: `npx playwright screenshot --viewport-size=375,812 /tmp/ui-375.png` + e `--viewport-size=1280,800` para desktop. Abra as imagens com Read. Sem servidor, avalie pelo código e diga isso. +2. **Estados**: carregando, vazio, erro e sucesso existem em cada fluxo com dados. +3. **Acessibilidade**: HTML semântico, foco visível e em ordem, rótulos, contraste de texto >= 4.5:1. + Se houver Playwright: `@axe-core/playwright` sem violação `serious` ou `critical`. +4. **Responsivo**: nada corta ou sobrepõe em 375 px e em 1280 px. +5. **Padrão genérico**: gradiente roxo, glassmorphism sem motivo, cards idênticos, ícones decorativos, + microcopy vaga ("Unlock the power of..."). Aponte o que trocar. + +Entregue achados priorizados: o que está errado, onde (`arquivo:linha` ou região da screenshot) e a +correção concreta. No máximo 10. diff --git a/agents/verifier.md b/agents/verifier.md new file mode 100644 index 0000000..5a4fefe --- /dev/null +++ b/agents/verifier.md @@ -0,0 +1,17 @@ +--- +name: verifier +description: Roda o gate de qualidade no nível pedido e devolve a evidência - veredito, checagens que falharam com a saída relevante e o que ficou não verificado. Nunca edita código. +tools: Bash, Read +model: haiku +--- + +1. Rode `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N` com o nível recebido. +2. Leia `.dev-workflows/gate.json`. +3. Devolva: + - o veredito (`pass`, `fail` ou `incomplete`); + - cada checagem `fail` com as linhas da saída que mostram o motivo; + - a lista de checagens `unverified` (ferramenta ou configuração ausente); + - dependências novas, se houver; + - o `diff` (arquivos e linhas líquidas). + +Não edite nada e não reinterprete uma falha como aprovação. Se o gate não rodou, diga por quê. diff --git a/skills/dev-router/SKILL.md b/skills/dev-router/SKILL.md new file mode 100644 index 0000000..2ade19d --- /dev/null +++ b/skills/dev-router/SKILL.md @@ -0,0 +1,68 @@ +--- +name: dev-router +description: Use no início de qualquer pedido de código (feature, bug, refactor, UI, API, migração, review; "implement", "fix", "build", "add", "change"). Classifica o pedido em nível 0 a 3 e decide quais workflows, agentes e checagens rodar, para um pedido pequeno não pagar o custo de um grande. +--- + +# Dev Router + +A primeira linha da resposta declara o nível: `Nível N: `. + +## 1. Classificar + +| Nível | Quando | Exemplos | +|---|---|---| +| 0, trivial | nenhum comportamento muda; 1 arquivo | texto, cor, typo, renomear variável local | +| 1, pequeno | comportamento muda em 1 a 3 arquivos, sem superfície pública nova | bug localizado, ajuste de validação, refactor local | +| 2, feature | superfície nova ou contrato alterado; 4+ arquivos; dependência nova | endpoint, tela, módulo, integração | +| 3, grande ou de risco | vários módulos ou serviços, dados existentes, arquitetura, release | migração com dados, troca de auth, novo serviço | + +Na dúvida entre dois níveis, escolha o menor e suba quando aparecer um gatilho. + +## 2. Gatilhos que sobem o nível a qualquer momento + +| Gatilho | Mínimo | Soma | +|---|---|---| +| autenticação, autorização, sessão, tokens, criptografia | 2 | `security-auditor` | +| dinheiro, cobrança, dados pessoais (LGPD) | 2 | `security-auditor` | +| upload, SQL montado à mão, shell/exec, desserialização, template com entrada do usuário | 2 | `security-auditor` | +| dependência nova | 1 | `safedeps` antes de instalar | +| migração de schema | 2 (3 se mexe em dado existente) | rollback testado | +| feature que chama um LLM | 2 | OWASP LLM Top 10 no `security-auditor` | + +Depois que um gatilho disparou, não rebaixe por conta própria. + +O usuário pode forçar: "modo rápido" vira nível 0 ou 1, mas gatilho de segurança continua valendo (avise); "modo completo" vira nível 3. + +## 3. O que cada nível roda + +| Nível | Fluxo | Workflow | Agentes | +|---|---|---|---| +| 0 | fazer, rodar o gate | nenhum | nenhum | +| 1 | entender ou reproduzir, mudar, teste de regressão, gate | `wf-bugfix` ou `wf-refactor` | `explorer` só se não souber onde está o código | +| 2 | explorar, plano curto, TDD, revisão independente, gate | `wf-backend` e/ou `wf-frontend`; full-stack começa pelo contrato do backend | `explorer`, `implementer`, `reviewer`; `security-auditor` com gatilho; `ui-critic` com UI | +| 3 | spec EARS com IDs e ADR, aprovação do usuário, tarefas pequenas com TDD, revisões, gate | `wf-architecture` antes; `wf-backend`/`wf-frontend` na execução; `wf-security-review` no fim | `planner`, `implementer`, `reviewer`, `security-auditor`, `ui-critic` com UI, `verifier` | + +Em todo nível: aplique `lean-code`. Peça aprovação do usuário só quando houver uma decisão que é dele (produto, custo, dado existente); no nível 3, a spec sempre passa por ele. + +Delegue a um agente quando o trabalho dele não precisa voltar inteiro para esta conversa (mapear código, revisar um diff). Tarefa que cabe em poucos passos você mesmo faz. + +## 4. Gate de qualidade + +Antes de dizer que terminou, rode: + +```bash +"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier N +``` + +- `fail`: corrija. Se não der, explique ao usuário o que falhou e por quê. +- `incomplete`: diga ao usuário quais checagens ficaram "não verificado" (ferramenta ausente). Nunca chame de testado o que não rodou. +- `dependências novas`: justifique cada uma (ver `lean-code`). + +O hook de `Stop` bloqueia o encerramento enquanto houver código alterado sem gate atualizado ou com gate falho. Configuração por projeto e lista de checagens: [references/quality-gate.md](references/quality-gate.md). + +## 5. Relatório final (nível 1 ou mais) + +1. Nível e motivo. +2. O que mudou: arquivos e linhas líquidas (`diff` do gate). +3. Evidência: veredito do gate; checagens ok, falhas e não verificadas. +4. O que ficou de fora ou é risco conhecido. diff --git a/skills/dev-router/references/quality-gate.md b/skills/dev-router/references/quality-gate.md new file mode 100644 index 0000000..e13ea78 --- /dev/null +++ b/skills/dev-router/references/quality-gate.md @@ -0,0 +1,71 @@ +# Quality gate: checagens e configuração + +`scripts/quality-gate --tier N` roda as checagens do nível N e dos níveis abaixo, só sobre os arquivos +alterados em relação à branch base (merge-base com `origin/HEAD`, `main` ou `master`). O resultado vai +para `.dev-workflows/gate.json` (ignorado pelo git automaticamente) e uma linha resumida vai para +`.dev-workflows/log.jsonl`. + +`--list` mostra o que rodaria e o que está faltando, sem rodar nada. + +## Checagens + +| Nível | Checagem | Ferramenta | Como é detectada | +|---|---|---|---| +| 0 | lint | script `lint` do package.json, eslint, ruff, `go vet`, clippy | primeira que existir | +| 0 | typecheck | script `typecheck`, `tsc --noEmit`, pyright, mypy | tsconfig ou config do checker | +| 0 | test | script `test`, pytest (usa `.venv` se existir), `go test`, `cargo test` | stack do projeto | +| 0 | secrets | gitleaks, só nos arquivos alterados | binário no PATH | +| 1 | diff-coverage | diff-cover sobre `coverage.xml` | relatório de cobertura presente | +| 1 | semgrep | `semgrep --config p/default --baseline-commit ` | binário no PATH | +| 1 | dead-code (info) | knip, vulture | binário no projeto ou PATH | +| 2 | build | script `build` | package.json | +| 2 | mutation | Stryker nos arquivos alterados; mutmut (paths configurados) | config do Stryker ou `[tool.mutmut]` | +| 2 | osv-scanner | `osv-scanner scan source --recursive .` | binário no PATH | +| 2 | architecture | dependency-cruiser, import-linter | arquivo de config | +| 2 | duplication (info) | jscpd | binário no projeto | +| 3 | trivy | vulnerabilidades, misconfig e segredos, HIGH e CRITICAL | binário no PATH | +| 3 | traceability | todo `REQ-NNN` da spec aparece em algum teste | `[spec]` na config | + +Estados: `pass`, `fail`, `unverified` (ferramenta ou config ausente, nunca conta como aprovado) e +`info` (só relatório). Veredito: `fail` se algo falhou; `incomplete` se algo ficou não verificado; senão `pass`. + +## `.dev-workflows.toml` (opcional, na raiz do projeto) + +```toml +timeout = 600 # segundos por checagem + +[commands] # substitui o que foi detectado +test = "pnpm vitest run --coverage" +lint = "pnpm eslint ." +mutation = "pnpm stryker run --incremental" + +[thresholds] +diff_coverage = 80 + +[coverage] +report = "coverage/cobertura-coverage.xml" + +[spec] # nível 3: rastreabilidade requisito -> teste +file = "docs/spec.md" +tests = ["tests", "e2e"] + +[[check]] # checagem extra; kind = "gate" (padrão) ou "info" +name = "lighthouse" +cmd = "npx lhci autorun" +tier = 2 + +[[check]] +name = "a11y" +cmd = "npx playwright test e2e/a11y.spec.ts" +tier = 2 + +[[check]] +name = "api-fuzz" +cmd = "schemathesis run http://localhost:8000/openapi.json --checks all" +tier = 2 +``` + +Frontend, API e carga dependem do app estar de pé, então entram como `[[check]]` do projeto +(Lighthouse CI com orçamento, Playwright com `@axe-core/playwright`, schemathesis, k6 com thresholds). + +`DW_GATE=off` desliga o hook de `Stop` numa sessão. diff --git a/skills/lean-code/SKILL.md b/skills/lean-code/SKILL.md new file mode 100644 index 0000000..1f32098 --- /dev/null +++ b/skills/lean-code/SKILL.md @@ -0,0 +1,48 @@ +--- +name: lean-code +description: Use sempre que for escrever ou mudar código. Escolhe a menor solução que resolve de verdade - reaproveitar antes de escrever, apagar antes de somar, sem abstração especulativa e sem dependência desnecessária. +--- + +# Lean Code + +Primeiro entenda o problema e o código que ele toca. Depois suba a escada e pare no primeiro degrau +que resolve. + +## Escada + +1. **Precisa existir?** Pedido especulativo ("para depois", "vai que") não entra. Diga isso em uma linha. +2. **Já existe no projeto?** Procure helper, componente, tipo ou padrão parecido antes de escrever (`grep` por nomes e por comportamento; o agente `explorer` faz isso). +3. **A biblioteca padrão resolve?** +4. **A plataforma resolve?** HTML/CSS nativo antes de JS, constraint do banco antes de código, recurso do framework antes de utilitário próprio. +5. **Uma dependência já instalada resolve?** +6. **Cabe em poucas linhas?** +7. Só então: o mínimo de código novo. + +## Regras + +- **Bug se corrige na causa.** Antes de editar uma função, ache todos os chamadores. Uma correção no ponto por onde todos passam é menor que uma por chamador, e não deixa os outros quebrados. +- **Sem abstração sem uso:** interface com uma implementação, factory de um produto, configuração para valor que nunca muda. +- **Dependência nova exige justificativa** em uma linha (o que ela faz que os degraus 3 a 6 não fazem) e consulta ao `safedeps` antes de instalar. O gate lista as novas. +- **Apague o que ficou morto** por causa da mudança. +- **Entre duas soluções do mesmo tamanho**, fique com a que está certa nos casos de borda. + +## Nunca simplifique + +Validação na fronteira do sistema, tratamento de erro que evita perda de dado, controles de segurança, +acessibilidade básica e qualquer coisa que o usuário pediu explicitamente. + +## Orçamento de diff (linhas líquidas, referência) + +| Nível | Orçamento | +|---|---| +| 0 | 20 | +| 1 | 100 | +| 2 | 400 | +| 3 | 400 por fatia entregue | + +Estourou: justifique no relatório ou quebre em partes menores. + +## Atalho consciente + +Quando cortar caminho de propósito (lock global, busca O(n²), heurística simples), deixe um comentário +`lean:` dizendo o limite e quando evoluir: `# lean: lock global; trocar por lock por conta se a vazão importar`. diff --git a/skills/wf-bugfix/SKILL.md b/skills/wf-bugfix/SKILL.md new file mode 100644 index 0000000..eda17a4 --- /dev/null +++ b/skills/wf-bugfix/SKILL.md @@ -0,0 +1,40 @@ +--- +name: wf-bugfix +description: Use para corrigir bug, erro, exceção, falha, regressão, comportamento errado ("não funciona", "quebrou", "fix"). Reproduz, acha a causa raiz e prova a correção com um teste de regressão que falha antes e passa depois. +--- + +# Workflow Bugfix + +## 1. Reproduzir + +Encontre o comando, teste ou requisição que mostra o erro, e rode. Sem reprodução, colete mais dado +(stack trace, log, entrada exata) em vez de chutar uma correção. + +## 2. Achar a causa raiz + +- Siga o fluxo real do ponto de entrada até o erro. +- Ache todos os chamadores da função que você pretende mudar (`grep -rn "nomeDaFuncao(" .`). +- Escreva a causa em uma ou duas frases antes de editar. Se não consegue, ainda não achou. +- Corrija no ponto por onde todos os chamadores passam, não só no caminho que o relato citou. + +## 3. Provar com teste de regressão + +1. Escreva o teste que reproduz o bug. +2. Prove que ele falha sem a correção: `git stash push `, rode o teste, veja vermelho, `git stash pop`. +3. Rode de novo com a correção: verde. + +Um teste que passa com e sem a correção não prova nada; reescreva. + +## 4. Gate + +`"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 1` (ou o nível que o `dev-router` definiu). + +## 5. Relatório + +Causa em uma frase, o que mudou, o teste que prova (nome e saída vermelho/verde) e o veredito do gate. + +## Não faça + +- Silenciar o erro com `try/except` ou `catch` vazio. +- Mudar o teste até ele passar em vez de corrigir o código. +- Corrigir o sintoma num chamador e deixar a causa na função compartilhada. diff --git a/skills/wf-refactor/SKILL.md b/skills/wf-refactor/SKILL.md new file mode 100644 index 0000000..7aed468 --- /dev/null +++ b/skills/wf-refactor/SKILL.md @@ -0,0 +1,33 @@ +--- +name: wf-refactor +description: Use para refatorar, reorganizar, renomear, extrair, simplificar ou limpar código sem mudar o comportamento. Congela o comportamento com testes antes de mexer e mexe em passos pequenos. +--- + +# Workflow Refactor + +## 1. Rede de segurança + +Os testes atuais cobrem o comportamento que você vai tocar? Se não, escreva **testes de +caracterização** antes de mudar qualquer coisa: eles registram o que o código faz hoje, mesmo que +pareça estranho. Rode e confirme que estão verdes. + +## 2. Passos pequenos + +Cada passo deixa o código compilando e os testes verdes. Rode os testes a cada passo, não só no fim. +Renomeação: procure também em strings, configs, rotas e docs (`grep -rn`), não só nos imports. + +## 3. Comportamento não muda + +Os testes de caracterização não são editados. Se você precisa editar um deles, a mudança não é +refactor: pare e pergunte ao usuário. + +## 4. Gate e relatório + +`"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 1` (nível 2 se o refactor atravessa módulos). +No relatório, as linhas líquidas: um bom refactor costuma reduzir. Se aumentou, explique. + +## Não faça + +- Misturar refactor com feature ou correção de bug no mesmo diff. +- Mudar API pública sem o usuário pedir. +- Criar camada ou abstração nova "para ficar mais limpo" sem um uso concreto hoje.