dev-workflows/workflows/wf-architecture.md

---
name: wf-architecture
description: "Use p/ arquitetura. Fluxo REQ→DESIGN→DOCS→REVIEW."
version: 1.0.0
author: Hermes Agent
license: MIT
platforms: [linux, macos, windows]
metadata:
  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)

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

## 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:

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

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

Fase 3 — ADR curto:

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

Fase 4 — validação do conjunto:

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

Gates do workflow (anti-regressão):

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