dev-workflows/workflows/wf-architecture.md

name, description, version, author, license, platforms, metadata

name	description	version	author	license	platforms	metadata
wf-architecture	Use p/ arquitetura. Fluxo REQ→DESIGN→DOCS→REVIEW.	1.0.0	Hermes Agent	MIT	linux macos windows	hermes tags architecture design c4 adr arc42 threat-model workflow

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.

When to Use

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 do stack (carregar conforme a fase)

• 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

Fase 1 — REQUIREMENTS (entender antes de desenhar)

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.

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.

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)

# 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

Critérios de Aceite (checklist não-regressivo)

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

Exemplos de execução por fase (comandos reais)

Fase 1 — requisitos estruturados:

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 2 — diagrama C4 (definir estrutura antes):

# 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

Fase 3 — ADR curto:

# Criar ADR em docs/architecture/adr/0001-*.md (isaqb-architecture-governance)
# S-ADR em docs/security/adr/ quando a decisão for security-driven

Fase 4 — validação do conjunto:

# 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

Gates do workflow (anti-regressão):

python3 ~/.hermes/skills/software-development/wf-qa/test_quality.py
python3 ~/.hermes/skills/software-development/wf-qa/test_tests.py

Regras duras

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