feat: add the dev-router, lean-code, bugfix/refactor workflows and agents

Every workflow used to run all of its phases for any request, so a one-line
fix paid the cost of a feature. dev-router classifies the request into tiers
0-3 with security triggers that raise the tier, and picks the workflow,
agents and gate tier. Agents get only the tools their role needs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

.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"

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.

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ê.

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 <evento> THE SYSTEM SHALL <resposta>`
+   - `REQ-002: IF <condição indesejada> THEN THE SYSTEM SHALL <resposta>`
+   - `REQ-003: WHILE <estado> THE SYSTEM SHALL <resposta>`
+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/<nome>.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.

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 <base>`, `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.

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.

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 <url> /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.

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ê.

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: <motivo em uma frase>`.
+
+## 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.

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 <base>` | 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.

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`.

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 <arquivos da correção>`, 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.

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.