refactor(skills): cut the workflows to ~100 lines and scale phases by tier

Each workflow was ~300 lines of grep-count "VERIFICAR" steps and ran every
phase for every request. Phases now state their minimum tier, checks are the
quality gate plus real tools, detail moved to references/, and machine-specific
paths and non-public skills are gone. Security references move to OWASP Top
10:2025, ASVS 5.0 and the OWASP LLM Top 10.

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

skills/wf-architecture/SKILL.md

@@ -1,294 +1,107 @@
 ---
 name: wf-architecture
-description: "Use p/ arquitetura. Fluxo REQ→DESIGN→DOCS→REVIEW."
-version: 1.0.0
-author: Hermes Agent
+description: Use para decisões de arquitetura - desenho de sistema ou serviço novo, escolha de stack, mudança de fronteira entre módulos, migração com dado existente, troca de auth, diagrama C4, ADR, threat model, "isso é uma boa ideia arquitetonicamente?". É o workflow do nível 3 do dev-router (e do nível 2 quando surge uma decisão difícil de desfazer). Não use para bug, refactor local, tela ou endpoint isolado sem decisão estrutural (use wf-bugfix, wf-refactor, wf-frontend ou wf-backend).
 license: MIT
-platforms: [linux, macos, windows]
 metadata:
-  hermes:
-    tags: [architecture, design, c4, adr, arc42, threat-model, workflow]
+  dev-workflows:
+    uses: []
+    external: [system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance]
 ---
 
 # Workflow Arquitetura
 
-Orquestrador obrigatório para todo trabalho de arquitetura: desenho de
-sistemas, decisões (ADR), diagramas C4, threat modeling, revisão de
-arquitetura. Processo de 4 fases com skills fixas.
+**Nível 3** do `dev-router`, ou nível 2 quando aparece uma decisão difícil de desfazer (banco,
+protocolo, fronteira de serviço, modelo de auth). No nível 2, faça só a Fase 3 (um ADR para a decisão)
+e siga com `wf-backend`/`wf-frontend`. Abaixo disso, este workflow não roda.
 
-## When to Use
+Cada fase produz um arquivo versionado. O que não virou arquivo não foi decidido.
 
-Sempre que a tarefa envolver: arquitetura/design de sistema, escolha de
-stack, diagramas, ADR, threat model, revisão estrutural, ou "é uma boa
-ideia arquitetonicamente?".
+Skills externas, se instaladas: `system-design` (raciocínio de design), `c4-architecture` (diagramas),
+`isaqb-architecture-governance` (arc42 e ADR), `secure-architecture-governance` (STRIDE e S-ADR).
+Sem elas, os modelos em [references/](references/) bastam.
 
-## Skills do stack (carregar conforme a fase)
+## Fase 1: REQUIREMENTS
 
-- Design de sistema (raciocínio): `system-design` (HelloInterview framework)
-- Diagramas: `c4-architecture` (Context/Container/Component/Deployment)
-- Documentação: `isaqb-architecture-governance` (arc42 + ADR)
-- Segurança: `secure-architecture-governance` (STRIDE+CIA, S-ADR)
-- Qualidade de documentação: `avoid-ai-writing` (remove AI-isms de ADRs,
-  docs de arquitetura, RFCs — registros que vão durar anos não devem soar
-  gerados por IA)
-- Locais: `security-threat-model`, `architecture-diagram` (SVG),
-  `excalidraw`, `brainstorming`, `writing-plans`
+Entender antes de desenhar. Use o agente `planner` com o mapa do `explorer`.
 
-## Fase 1 — REQUIREMENTS (entender antes de desenhar)
+1. Requisitos funcionais em **EARS com ID** (`REQ-001: WHEN ... THE SYSTEM SHALL ...`).
+   Modelo e padrões: [references/ears.md](references/ears.md).
+2. Não funcionais **com número**: SLO (ex.: p95 < 250 ms, 99,9% ao mês), orçamento de performance
+   (LCP, tamanho de bundle, custo mensal), nível ASVS 5.0 (L2 por padrão no nível 3).
+   "Rápido" ou "escalável" sem número não é requisito.
+3. Atores, entidades centrais e fronteiras de confiança.
+4. Stack ou framework novo: consulte a documentação atual e registre URL e data. Não decida pela memória.
 
-1. `brainstorming` — explorar intenção, requisitos funcionais e NFRs
-   (latência, escala, disponibilidade, custo) antes de qualquer desenho.
-2. Identificar entidades centrais, limites, fluxos de dados e atores.
-3. Estado da arte: checar evolução/relevância de stack/framework.
-4. VERIFICAR: rodar `hermaguard` conceitual no escopo (o que pode dar
-   errado com esta arquitetura?) e validar com o usuário que cada NFR é
-   mensurável (ex: "p95 < 250ms" e não "rápido").
-5. Checkpoint: listar requisitos validados e SÓ seguir ao DESIGN com
-   aprovação explícita.
-6. VERIFICAR (comandos de requisitos): escrever FRs/NFRs em
-   `docs/requirements.md` e rodar `grep -c "NFR" docs/requirements.md`
-   para garantir que TODOS os NFRs viraram critério mensurável.
-7. VERIFICAR (cobertura): usar `search_files` para confirmar que nenhum
-   requisito levantado ficou órfão (cada FR/NFR tem dono e número).
-8. VERIFICAR (comandos de estado da arte): consultar fontes atuais para
-   stack/framework antes de decidir — usar `web_search`/consultas técnicas
-   e registrar URL + data no requirements.md (não decidir stack do nada).
-9. VERIFICAR (pontos de risco): listar os 3 maiores riscos técnicos do
-   escopo e checar com `hermaguard` conceitual se algum deles muda a
-   decisão de arquitetura — risco conhecido não vira surpresa depois.
-10. CHECKPOINT final da Fase 1: apresentar requisitos para aprovação; sem
-    OK explícito não avança para DESIGN.
-11. VERIFICAR (comandos de requisitos): `python3 -c "import yaml,sys; yaml.safe_load(open('docs/requirements.md'))"` se requisitos em YAML
-    (ou parser equivalente) para provar que o formato é válido; e
-    `curl -s -o /dev/null -w "%{http_code}" URL` quando houver fonte
-    externa de referência citada.
-12. VERIFICAR (critério de requisito): conferir que cada requisito tem
-    "critério de aceite" ou número alvo — sem requisito "aberto" sem
-    definição de pronto.
+**Artefato:** `docs/specs/<nome>.md` com os `REQ-` e os não funcionais.
+**Gate da fase:** o usuário aprova a spec antes do DESIGN.
 
-**Checklist da fase 1 (validar requisitos):**
-- [ ] Requisitos funcionais e NFRs (latência, escala, disponibilidade, custo)
-      coletados e mensuráveis (ex: "p95 < 250ms" ao invés de "rápido").
-- [ ] Entidades centrais, limites e atores identificados.
-- [ ] Estado da arte de stack/framework verificado.
-- [ ] Requisitos aprovados pelo usuário antes de desenhar.
+Rastreabilidade: adicione ao `.dev-workflows.toml` do projeto
 
-**Anti-padrões desta fase:**
-- NUNCA desenhar sem requisito mensurável.
-- NUNCA inventar NFR ("ser escalável") — exigir número e critério.
-- NÃO pular a aprovação do usuário para "andar logo".
-- NÃO decidir stack antes de validar requisitos (viés de ferramenta).
-
-## Fase 2 — DESIGN (modelar o sistema)
-
-1. `system-design` — percorrer o framework: requisitos → entidades → API →
-   data flow → high-level design → deep dives. Documentar trade-offs.
-2. `c4-architecture` — gerar diagramas (Context → Container → Component)
-   em Mermaid/Structurizr. Declarar elementos em ordem de leitura, evitar
-   cruzamentos (research-backed).
-3. `secure-architecture-governance` — mapear trust boundaries e rodar
-   STRIDE+CIA nas decisões de segurança (auth, dados sensíveis).
-4. VERIFICAR: rodar `c4-architecture` de novo para audit — cada diagrama
-   tem IDs estáveis, setas com rótulo e <=20 elementos por view? Validar
-   com o usuário antes de documentar.
-5. VERIFICAR (comandos de design): se Structurizr, validar com
-   `python3 -c "import json; json.load(open('workspace.json'))"` que o
-   modelo é parseável; para Mermaid, conferir que os blocos ```mermaid
-   fecham corretamente (contar crases ímpares = erro).
-6. VERIFICAR (trade-offs): `grep -c "alternativa" docs/design.md` — cada
-   decisão tem pelo menos 1 alternativa documentada com o porquê?
-7. VERIFICAR (limites): `grep -n "boundary\|trust" docs/design.md` —
-   trust boundaries explícitos nos diagramas; todo fluxo de dado sensível
-   cruza boundary documentada.
-8. VERIFICAR (comandos de render): se Mermaid, rodar `npx @mermaid-js/mermaid-cli -i d.mmd -o d.svg` (ou Playwright) para provar que o
-   diagrama renderiza sem erro de sintaxe.
-9. VERIFICAR (comandos de contagem): `grep -c "component\|container" docs/c4.md` — todo container mapeado tem representação; `wc -l docs/c4.md > 10` garante diagrama não-vazio.
-10. VERIFICAR (critério de design): confirmar com o usuário que cada view
-    reflete os requisitos da Fase 1 (rastreabilidade view→requisito) e
-    que os trade-offs estão anotados — sem view "solta".
-
-**Checklist da fase 2 (validar o modelo):**
-- [ ] `system-design` percorrido: requisitos → entidades → API → data flow →
-      high-level → deep dives.
-- [ ] Diagramas C4 (Context → Container → Component) com IDs estáveis, setas
-      rotuladas e <=20 elementos por view.
-- [ ] Trust boundaries mapeados; STRIDE+CIA aplicado nas decisões sensíveis.
-- [ ] Trade-offs documentados (as 2 soluções alternativas + por quê a escolha).
-
-**Anti-padrões desta fase:**
-- NUNCA diagramar sem requisitos (Fase 1) — diagrama sem base vira enfeite.
-- NUNCA deixar seta sem rótulo ou elemento sem ID estável.
-- NÃO desenhar >20 elementos por view (ilegível = não é documento).
-- NÃO ignorar trust boundary ao desenhar fluxo de dados sensível.
-
-## Fase 3 — DOCS (decisões em registros)
-
-1. `isaqb-architecture-governance` — criar ADR (e S-ADR se decisão for
-   security-driven) com alternativas e consequências. ID estável e
-   reutilizado nos diagramas/docs.
-2. `avoid-ai-writing` — pós-escrever QUALQUER doc/ADR/RFC: detect+rewrite
-   dos AI-isms (tiers 1/2/3, em-dash, "crucial", "robust", transições
-   genéricas). Arquitetura documentada é lida por anos — não deve soar IA.
-3. Estrutura de saída: `docs/architecture/` (ADRs, views arc42) e
-   `docs/security/` (S-ADRs, threat models) — sem colisão de nomes.
-4. NFRs virarem critérios mensuráveis (não frase de efeito).
-5. VERIFICAR: rodar `avoid-ai-writing` em modo detect em cada ADR (0 AI-isms
-   restantes), confirmar arquivos criados em `docs/architecture/adr/` e
-   `docs/security/adr/` e conferir que IDs de ADR/S-ADR são únicos.
-6. VERIFICAR (comandos de docs): `ls docs/architecture/adr/ docs/security/adr/`
-   para listar os registros criados e `grep -rL "Consequências" docs/` para
-   achar ADR que esqueceu a seção de consequências.
-7. VERIFICAR (rastreabilidade): `grep -rc "AD-...-NNN" docs/architecture/`
-   — cada ADR aparece referenciado em pelo menos um diagrama ou decision log.
-8. VERIFICAR (comandos de docs): confirmar com `find docs/ -name "*.md" -o -name "*.mmd" | sort` que a árvore está organizada; e `wc -l docs/architecture/adr/*.md` para garantir ADR com corpo (não só título).
-9. VERIFICAR (estilo consistente): `grep -rn "em dash\|—" docs/architecture/adr/ | wc -l` — em-dash em excesso = AI-ism residual (rodar avoid-ai-writing).
-10. VERIFICAR (comandos de validação de docs): `python3 -m json.tool docs/workspace.json > /dev/null` para Structurizr; `curl -s -o /dev/null -w "%{http_code}" http://localhost:8080/...` se houver visualização local; e `git diff --stat docs/` para conferir o que foi documentado.
-11. VERIFICAR (critério de aceite de doc): cada ADR responde "por que essa decisão?" e lista consequências — `grep -L "Consequências" docs/architecture/adr/*.md` deve ser vazio.
-
-**Checklist da fase 3 (documentação):**
-- [ ] ADR (ou S-ADR se security-driven) criado com alternativas + consequências.
-- [ ] `avoid-ai-writing` em detect = 0 em cada ADR/RFC.
-- [ ] Arquivos em `docs/architecture/adr/` e `docs/security/adr/`; IDs únicos.
-- [ ] NFRs viram critérios mensuráveis no documento (não frase solta).
-
-**Anti-padrões desta fase:**
-- NUNCA publicar ADR sem alternativas consideradas.
-- NUNCA publicar doc com AI-isms não tratados.
-- NÃO criar 2 ADRs para a mesma decisão; NÃO duplicar decisão geral e S-ADR.
-- NÃO deixar ID solto (decisão precisa ser rastreável ao diagrama/código).
-
-## Fase 4 — REVIEW (verificar antes de aprovar)
-
-1. `secure-architecture-governance` — auditar decisões contra ISO/IEC
-   25010 (performance, segurança, confiabilidade, manutenibilidade).
-2. Threat model final + gaps de trust boundary (unauthenticated internal
-   paths, implicit service trust) priorizados.
-3. Checar consistência: IDs batem entre diagramas, ADRs e docs?
-4. Verdict objetivo: Approved / Approved-with-changes / Needs-revision,
-   com evidência por finding — não gosto pessoal.
-5. VERIFICAR (gate final): rodar `secure-architecture-governance` como
-   checklist, validar a árvore de arquivos com `search_files`, e dar o
-   verdict com base na evidência — se houver gap de security, reverter ao
-   DESIGN.
-6. VERIFICAR (comandos de revisão): usar `grep -r "AD-...-NNN" docs/` para
-   provar que IDs aparecem nos diagramas, e `git status` para conferir que
-   tudo que foi modelado virou arquivo versionado.
-7. VERIFICAR (anti-slop de docs): rodar `node .../avoid-ai-writing/detector/validate.js`
-   nos ADRs e `test_quality.py` no workflow — sem regressão.
-8. VERIFICAR (todos os arquivos versionados): `git status --porcelain` deve
-   mostrar só o esperado; `find docs/ -name "*.md" | wc -l` confere a
-   contagem de docs criados vs planejados na Fase 1.
-9. VERIFICAR (comandos de evidência por finding): para cada finding,
-   `grep -rn "<id-do-finding>" docs/security/` deve retornar a evidência —
-   sem achado "sem referência".
-10. VERIFICAR (conclusão): `git diff --stat` + `git status` para conferir
-    o que o ciclo produziu; nada de diagrama/doc não versionado sendo
-    citado como entregue.
-11. VERIFICAR (comandos de revisão final): rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py` (gate) e conferir o
-    `git diff --stat` — a revisão só fecha com gate verificado e sem
-    pendências de arquivo.
-12. VERIFICAR (não-regressão de nomes): conferir que nenhuma skill do stack
-    foi renomeada/quebrada — rodar o harness (G4) e `test_tests.py`.
-
-**Checklist da fase 4 (revisão):**
-- [ ] Auditoria contra ISO/IEC 25010 por decisão (performance, segurança,
-      confiabilidade, manutenibilidade).
-- [ ] Threat model final com gaps de trust boundary priorizados.
-- [ ] Consistência de IDs: diagramas × ADRs × docs batem.
-- [ ] Verdict objetivo emitido: Approved / Approved-with-changes /
-      Needs-revision, com evidência por finding.
-
-**Anti-padrões desta fase:**
-- NUNCA dar verdict "approved" sem evidência em cada finding.
-- NUNCA ignorar gap de trust boundary (unauthenticated internal path).
-- NÃO confundir opinião estética com achado — achado exige referência.
-- NÃO deixar segurança como "nota mental" — virar S-ADR ou finding listado.
-
-## Comandos de Verificação (executáveis)
-
-```bash
-# Gate de qualidade do próprio workflow (sem regressão)
-python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
-
-# Verifica consistência da documentação (IDs estáveis em diagramas/docs)
-# (skill isaqb-architecture-governance + c4-architecture)
-
-# Threat model: auditoria STRIDE+CIA contra ISO 25010
-# (skill secure-architecture-governance)
-
-# Audit de AI-isms nos ADRs/RFCs (detect = só mostra)
-node ~/.hermes/skills/avoid-ai-writing/detector/validate.js adr.md adr-limp.md
+```toml
+[spec]
+file = "docs/specs/<nome>.md"
+tests = ["tests"]
 ```
 
-## Critérios de Aceite (checklist não-regressivo)
+e o gate nível 3 falha se algum `REQ-` não aparecer em um teste
+(ver `skills/dev-router/references/quality-gate.md`).
 
-- [ ] Fase 1 concluída com requisitos/NFRs mensuráveis aprovados pelo usuário.
-- [ ] Fase 2 gerou diagramas C4 com IDs estáveis e rótulos; validados.
-- [ ] Fase 3 gerou ADR/S-ADR em `docs/architecture/` e `docs/security/`;
-      `avoid-ai-writing` detect = 0 AI-isms.
-- [ ] Fase 4 auditou contra ISO 25010 + threat model; verdict emitido.
-- [ ] Nenhuma skill do stack removida do arquivo.
-- [ ] Rodar `python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py`
-      → exit 0 (sem regressão).
+## Fase 2: DESIGN
 
-## Exemplos de execução por fase (comandos reais)
+1. Fluxo de design: requisitos, entidades, API, fluxo de dados, visão geral, pontos críticos.
+2. **C4** em Mermaid: Context e Container sempre; Component só onde houver decisão.
+   Até 20 elementos por view, setas rotuladas, IDs estáveis. Modelo: [references/c4.md](references/c4.md).
+3. Modelo de dados e estratégia de migração (reversível; com dado existente, plano de backfill e rollback).
+4. **Pelo menos uma alternativa** por decisão importante, com o motivo da escolha.
 
-Fase 1 — requisitos estruturados:
+**Artefato:** `docs/architecture/design.md` com os diagramas.
+Confira que o Mermaid renderiza: `npx -y @mermaid-js/mermaid-cli -i docs/architecture/c4.mmd -o /tmp/c4.svg`.
 
-```bash
-cat > docs/requirements.md <<'EOF'
-# Requisitos
-FR1: usuário cria e gerencia listas
-NFR1: p95 < 250ms (API)
-NFR2: disponibilidade 99.9%
-NFR3: custo mensal < R$ 500
-EOF
-```
+## Fase 3: DOCS (ADR)
 
-Fase 2 — diagrama C4 (definir estrutura antes):
+Um ADR por decisão difícil de desfazer: contexto, opções, decisão, consequências (boas e ruins).
+Modelo: [references/adr.md](references/adr.md).
 
-```bash
-# Estrutura do C4 em texto (depois renderizar com c4-architecture/Mermaid)
-cat > docs/c4.md <<'EOF'
-Context: [Usuário] -> [Sistema X]
-Container: [Web] -> [API] -> [Postgres] -> [Redis]
-EOF
-```
+- `docs/architecture/adr/NNNN-<titulo>.md`, numeração sequencial, nunca reescrever um ADR aceito
+  (substitua por um novo com `Substitui: ADR-NNNN`).
+- Decisão motivada por segurança vira S-ADR em `docs/security/adr/`.
+- Todo ADR citado no design (`ADR-0003`) existe como arquivo.
 
-Fase 3 — ADR curto:
+## Fase 4: THREAT MODEL
 
-```bash
-# Criar ADR em docs/architecture/adr/0001-*.md (isaqb-architecture-governance)
-# S-ADR em docs/security/adr/ quando a decisão for security-driven
-```
+STRIDE por fronteira de confiança, cada ameaça ligada a um controle ASVS 5.0 L2.
+Tabela e mapeamento: [references/stride.md](references/stride.md).
 
-Fase 4 — validação do conjunto:
+1. Liste as fronteiras (internet/app, app/banco, serviço/serviço, app/terceiros, app/LLM).
+2. Para cada fronteira, as seis categorias STRIDE: ameaça concreta, controle, capítulo ASVS, status.
+3. Caminhos internos sem autenticação e confiança implícita entre serviços são achados, não detalhes.
+4. Feature que chama LLM: inclua OWASP LLM Top 10 (prompt injection, excessive agency).
 
-```bash
-# Consistência de IDs entre diagramas, ADRs e docs (search_files)
-grep -r "ADR-" docs/ | wc -l            # cada referência existe
-grep -rn "S-ADR" docs/security/ | wc -l # decisões security-driven têm S-ADR
-# "audite a arquitetura" (secure-architecture-governance: ISO 25010)
-python3 -m json.tool docs/workspace.json > /dev/null  # Structurizr válido?
-# "rode o avoid-ai nos ADRs" (modo detect)
-node ~/.hermes/skills/avoid-ai-writing/detector/validate.js adr.md adr-limp.md
-find docs/ -name "*.md" -o -name "*.mmd" | sort  # árvore organizada
-```
+**Artefato:** `docs/security/threat-model.md`.
 
-Gates do workflow (anti-regressão):
+## Fase 5: REVIEW
 
-```bash
-python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
-python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py
-```
+1. Agente `reviewer` sobre spec, design e ADRs: consistência entre `REQ-`, diagramas e ADRs,
+   requisito sem dono, decisão sem alternativa.
+2. Agente `security-auditor` sobre o threat model e as decisões de segurança.
+3. Veredito por escrito: `Aprovado`, `Aprovado com mudanças` ou `Revisar`, cada achado com evidência
+   (arquivo e trecho). Gap de fronteira de confiança volta para o DESIGN.
+4. O usuário aprova. A implementação segue com `wf-backend`/`wf-frontend`, tarefa a tarefa,
+   e fecha com `"${CLAUDE_PLUGIN_ROOT}/scripts/quality-gate" --tier 3`.
 
-## Regras duras
+## Não faça
 
-- NUNCA diagramar antes de requisitos claros (Fase 1).
-- NUNCA entregar ADR sem alternativas consideradas e consequências.
-- NUNCA publicar ADR/RFC/doc com AI-isms não tratados (passar por
-  `avoid-ai-writing` antes de dar como entregue).
-- Decisão com load-bearing security → S-ADR em `docs/security/`, nunca nos
-  ADRs gerais.
-- Diagrama tem que ter declaração em ordem de leitura + alvo de
-  cruzamentos — legibilidade é requisito, não luxo.
+- Desenhar antes de ter requisito mensurável.
+- ADR sem alternativa ou sem consequências.
+- Mais de um ADR para a mesma decisão.
+- Tratar segurança como nota mental: vira ameaça no threat model ou S-ADR.
+- Decidir stack sem fonte atual.
+
+## Checklist de entrega
+
+- [ ] `docs/specs/<nome>.md` com `REQ-` em EARS e não funcionais com número, aprovado pelo usuário.
+- [ ] `[spec]` no `.dev-workflows.toml` do projeto.
+- [ ] `docs/architecture/design.md` com C4 que renderiza e alternativas registradas.
+- [ ] Um ADR por decisão difícil de desfazer, com consequências.
+- [ ] `docs/security/threat-model.md` com STRIDE por fronteira e controles ASVS L2.
+- [ ] Revisão do `reviewer` e do `security-auditor` com veredito e evidência.