dev-workflows/README.pt-BR.md

Dev Workflows

Plugin do Claude Code (também para opencode e Hermes Agent) que ajusta o processo ao tamanho do pedido: um roteador escolhe o nível, agentes com permissão mínima fazem o trabalho e um gate de qualidade determinístico decide quando terminou.

🇺🇸 Read in English

---

Por quê

Agentes escrevem código rápido e erram em duas coisas: saber quando uma tarefa merece mais processo e admitir o que não verificaram. Este plugin cuida das duas:

• Processo proporcional ao pedido. Typo não passa por revisão de design; mudança de auth passa.
• Prova, não afirmação. "Pronto" exige um relatório do gate sobre o diff atual. Ferramenta não instalada aparece como não verificado, nunca como aprovada.
• Menos código. Reaproveitar antes de escrever, apagar antes de somar, nenhuma dependência sem motivo.
• Segurança com fontes ao vivo. O conhecimento de CVEs de um modelo para na data de treino, então as revisões consultam o OSV.dev e registram a data.

Como funciona

O dev-router carrega primeiro e declara um nível:

Nível	Quando	O que roda
0, trivial	nenhum comportamento muda	a mudança + gate nível 0
1, pequeno	1 a 3 arquivos, sem superfície pública nova	wf-bugfix ou wf-refactor, teste de regressão, gate nível 1
2, feature	endpoint ou tela nova, contrato alterado, dependência nova	exploração, plano curto, TDD, revisão independente, gate nível 2
3, grande ou de risco	vários módulos, dados existentes, arquitetura, release	spec EARS + ADR aprovados por você, revisões, auditoria de segurança, gate nível 3

Gatilhos de segurança sobem o nível a qualquer momento: auth, dinheiro, dados pessoais, upload, SQL montado à mão, shell/exec, desserialização, migração de schema, dependência nova, feature que chama LLM.

O que tem dentro

Tipo	Itens
Roteador e regras	dev-router, lean-code
Workflows	wf-bugfix, wf-refactor, wf-frontend, wf-backend, wf-architecture, wf-security-review, wf-readme
Agentes	explorer (haiku, só leitura), planner (opus, só leitura), implementer (sonnet), reviewer (opus, só leitura, vê só o diff), security-auditor (opus, só leitura), ui-critic (sonnet, só leitura), verifier (haiku, roda o gate)
Hooks	Stop: bloqueia o "pronto" enquanto houver código alterado sem gate atual aprovado · PreToolUse: nega --no-verify e force-push, pergunta antes de reset --hard, clean -f, DROP TABLE · PostToolUse: formata o arquivo editado com o formatter do próprio projeto
Gate de qualidade	scripts/quality-gate: lint, typecheck, testes, gitleaks (nível 0); cobertura do diff, semgrep, código morto (nível 1); build, teste de mutação, osv-scanner, regras de arquitetura, duplicação (nível 2); trivy, rastreabilidade requisito→teste (nível 3)
Skills vendorizadas	pilar de segurança (OWASP secure-agent-playbook, UnitOneAI SecuritySkills, safedeps, hermaguard) e taste-skill para frontend. Origem e licença: skills/NOTICE.md

O gate roda só as checagens do nível pedido, só sobre o diff, e não usa IA: são ferramentas comuns. Checagens que precisam do app de pé (orçamento do Lighthouse CI, Playwright + axe, schemathesis, k6) entram por projeto no .dev-workflows.toml. Referência: skills/dev-router/references/quality-gate.md.

Instalação

git clone https://github.com/evandrodevbr/dev-workflows && cd dev-workflows

python3 scripts/install.py claude     # plugin: skills + agentes + hooks
python3 scripts/install.py opencode   # skills, agentes e plugin em ~/.config/opencode
python3 scripts/install.py hermes     # só skills, em ~/.hermes/skills

Claude Code sem clonar:

/plugin marketplace add evandrodevbr/dev-workflows
/plugin install dev-workflows@dev-workflows

Diferenças entre os agentes:

• opencode não consegue bloquear o fim do turno, então gate ausente ou falho vira aviso no log em vez de bloqueio. Os agentes viram subagentes do opencode com as mesmas permissões.
• Hermes recebe só as skills; rode o gate você mesmo.
• No opencode e no Hermes as cópias apontam para o seu clone: mantenha-o no lugar (ou rode a instalação de novo depois de mover).

Desligue o hook de Stop numa sessão com DW_GATE=off.

Skills externas (opcionais)

Os workflows usam estas quando instaladas e seguem as próprias regras quando não. Comandos de instalação: docs/SKILLS.md.

Área	Skills
Frontend	frontend-design (Anthropic), impeccable (pbakaus), vercel-react-best-practices, vercel-composition-patterns (Vercel Labs), animate (emilkowalski), web-design, avoid-ai-writing
Backend	secure-coding, bola-detector, auth-rbac-scaffold, injection-checker, openapi-hardener, security-test-generator (apisec-inc)
Arquitetura	system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance (Kotivskyi)
README	readme-crafter, good-readme, curating-readme

Qualidade deste repositório

python3 qa/lint_skills.py      # frontmatter, limites de tamanho, referências, links, caminhos de máquina
python3 qa/test_gate.py        # gate e hooks num repositório descartável
python3 qa/check_upstream.py   # skills vendorizadas atrás do upstream
claude plugin validate --strict .claude-plugin/plugin.json

O CI roda os dois primeiros em todo PR; a checagem de upstream roda todo mês.

Ainda não medido: se o kit melhora o código que um agente produz. Estudos públicos (SkillsBench, SWE-Skills-Bench) mostram que skills também podem piorar o resultado, então o próximo passo é um benchmark A/B (com e sem o kit) no Harbor, com testes ocultos, score de mutação e checagens de segurança.

Estrutura

.claude-plugin/     plugin.json, marketplace.json
skills/             dev-router, lean-code, workflows wf-*, skills vendorizadas (NOTICE.md)
agents/             explorer, planner, implementer, reviewer, security-auditor, ui-critic, verifier
hooks/hooks.json    Stop, PreToolUse, PostToolUse
scripts/            quality-gate, install.py, hooks/*.py
adapters/opencode/  plugin do opencode
qa/                 lint, testes do gate, checagem de upstream
docs/SKILLS.md      inventário de skills e comandos de instalação

Licença

MIT © 2026 Evandro Fonseca Junior. As skills vendorizadas mantêm as próprias licenças (skills/NOTICE.md).