evandro/dev-workflows
1
0 Fork 0
Code Issues 2 Pull Requests Actions Packages Projects Releases Wiki Activity

wip: snapshot das alterações não commitadas (2026-10-20)

Browse Source 
Origem: D:/Documents/Github/dev-workflows
Arquivos omitidos (segredos, bancos de dados, logs, >50 MB): 0
This commit is contained in:
evandro committed 2026-10-20 00:49:23 -03:00
1 parent c17192c9fe
commit 2ef6f6be10
61 files changed
+7892
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

skills/wf-architecture/SKILL.md
+107
View File
@@ -0,0 +1,107 @@
---
name: wf-architecture
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
metadata:
dev-workflows:
uses: []
external: [system-design, c4-architecture, isaqb-architecture-governance, secure-architecture-governance]
---
# Workflow Arquitetura
**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.
Cada fase produz um arquivo versionado. O que não virou arquivo não foi decidido.
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.
## Fase 1: REQUIREMENTS
Entender antes de desenhar. Use o agente `planner` com o mapa do `explorer`.
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.
**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.
Rastreabilidade: adicione ao `.dev-workflows.toml` do projeto
```toml
[spec]
file = "docs/specs/<nome>.md"
tests = ["tests"]
```
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 2: DESIGN
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.
**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`.
## Fase 3: DOCS (ADR)
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).
- `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 4: THREAT MODEL
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).
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).
**Artefato:** `docs/security/threat-model.md`.
## Fase 5: REVIEW
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`.
## Não faça
- 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.
skills/wf-architecture/references/adr.md
+31
View File
@@ -0,0 +1,31 @@
# Modelo de ADR
Arquivo: `docs/architecture/adr/NNNN-titulo-curto.md` (S-ADR de segurança em `docs/security/adr/`).
Numeração sequencial. ADR aceito não é reescrito: uma decisão nova cria outro ADR com `Substitui:`.
```markdown
# ADR-0003: PostgreSQL como banco de pedidos
- Status: proposto | aceito | substituído por ADR-NNNN
- Data: 2026-09-24
- Requisitos: REQ-002, REQ-010
- Substitui: (se houver)
## Contexto
O que força a decisão agora. Restrições reais (volume, equipe, custo, prazo), com números.
## Opções
1. PostgreSQL gerenciado: prós, contras.
2. MongoDB: prós, contras.
3. Manter o SQLite atual: prós, contras.
## Decisão
A opção escolhida e o motivo principal, em duas ou três frases.
## Consequências
- Boas: o que fica mais fácil.
- Ruins: o que fica mais difícil ou caro, e o que foi aceito conscientemente.
- Como desfazer, se precisar, e quanto custa.
```
Um ADR por decisão. Se duas decisões dependem uma da outra, dois ADRs que se referenciam.
skills/wf-architecture/references/c4.md
+45
View File
@@ -0,0 +1,45 @@
# C4 em Mermaid
Regras: até 20 elementos por view, toda seta com rótulo (o que trafega e por qual protocolo),
IDs estáveis reaproveitados em ADRs e no threat model, declaração na ordem de leitura
(de quem usa para o que é usado).
## Context
```mermaid
C4Context
title Contexto: Sistema de Pedidos
Person(cliente, "Cliente", "Compra pelo site")
System(pedidos, "Sistema de Pedidos", "Cria e acompanha pedidos")
System_Ext(pagamento, "Gateway de pagamento", "Cobra o cartão")
Rel(cliente, pedidos, "Cria pedido", "HTTPS")
Rel(pedidos, pagamento, "Autoriza cobrança", "HTTPS/REST")
```
## Container
```mermaid
C4Container
title Containers: Sistema de Pedidos
Person(cliente, "Cliente")
System_Boundary(sp, "Sistema de Pedidos") {
Container(web, "Web", "Next.js", "Interface")
Container(api, "API", "FastAPI", "Regras de pedido")
ContainerDb(db, "Banco", "PostgreSQL", "Pedidos e itens")
Container(worker, "Worker", "Celery", "Cobrança assíncrona")
}
System_Ext(pagamento, "Gateway de pagamento")
Rel(cliente, web, "Usa", "HTTPS")
Rel(web, api, "Chama", "HTTPS/JSON")
Rel(api, db, "Lê e grava", "SQL/TLS")
Rel(api, worker, "Enfileira cobrança", "Redis")
Rel(worker, pagamento, "Autoriza", "HTTPS")
```
## Render
```bash
npx -y @mermaid-js/mermaid-cli -i docs/architecture/c4.mmd -o /tmp/c4.svg
```
Se o comando falhar, o diagrama tem erro de sintaxe e não está pronto.
skills/wf-architecture/references/ears.md
+35
View File
@@ -0,0 +1,35 @@
# EARS: requisitos com ID
EARS (Easy Approach to Requirements Syntax) força cada requisito a ter gatilho e resposta
verificáveis. Um requisito por linha, ID estável `REQ-NNN`, nunca reaproveitado.
| Padrão | Forma | Exemplo |
|---|---|---|
| Ubíquo | THE SYSTEM SHALL <resposta> | `REQ-001: THE SYSTEM SHALL registrar toda alteração de preço com autor e data.` |
| Evento | WHEN <evento> THE SYSTEM SHALL <resposta> | `REQ-002: WHEN o usuário envia o formulário de cadastro THE SYSTEM SHALL responder 201 com o ID criado.` |
| Indesejado | IF <condição> THEN THE SYSTEM SHALL <resposta> | `REQ-003: IF o token expirou THEN THE SYSTEM SHALL responder 401 sem revelar se a conta existe.` |
| Estado | WHILE <estado> THE SYSTEM SHALL <resposta> | `REQ-004: WHILE a fila tiver mais de 1000 itens THE SYSTEM SHALL recusar novos jobs com 429.` |
| Opcional | WHERE <recurso> THE SYSTEM SHALL <resposta> | `REQ-005: WHERE o SSO estiver habilitado THE SYSTEM SHALL ocultar o login por senha.` |
## Não funcionais
Mesmo formato de ID, sempre com número e forma de medir:
```
REQ-010: THE SYSTEM SHALL responder GET /orders em p95 < 250 ms com 200 req/s (medido com k6).
REQ-011: THE SYSTEM SHALL manter 99,9% de disponibilidade mensal (SLO no monitoramento).
REQ-012: THE SYSTEM SHALL atender ASVS 5.0 nível L2 nos capítulos de autenticação e sessão.
REQ-013: THE SYSTEM SHALL carregar a página inicial com LCP <= 2,5 s e INP <= 200 ms (Lighthouse CI).
```
## Rastreabilidade
Cada teste cita o ID que prova, no nome ou num comentário:
```python
def test_req_003_token_expirado_retorna_401():
...
```
Com `[spec]` no `.dev-workflows.toml`, o gate nível 3 falha se algum `REQ-` da spec não aparecer
em nenhum arquivo de teste.
skills/wf-architecture/references/stride.md
+35
View File
@@ -0,0 +1,35 @@
# Threat model STRIDE com ASVS 5.0
Arquivo: `docs/security/threat-model.md`. Uma tabela por fronteira de confiança.
## Categorias e onde procurar o controle no ASVS 5.0
| STRIDE | Ameaça típica | Capítulos ASVS 5.0 para o controle |
|---|---|---|
| Spoofing (identidade falsa) | login forjado, token roubado, serviço se passando por outro | Autenticação, Gerenciamento de sessão, Tokens autocontidos |
| Tampering (adulteração) | parâmetro alterado, mensagem na fila modificada, upload malicioso | Validação e lógica de negócio, Manipulação de arquivos, Comunicação segura |
| Repudiation (negação) | ação sensível sem rastro | Log e tratamento de erro |
| Information disclosure (vazamento) | IDOR, stack trace na resposta, segredo em log | Autorização, Proteção de dados, Log e tratamento de erro |
| Denial of service | endpoint sem limite, query sem paginação, arquivo gigante | Validação e lógica de negócio (limites), Manipulação de arquivos |
| Elevation of privilege | usuário comum chega em rota de admin, injeção de comando | Autorização, Codificação e sanitização |
Os nomes dos capítulos seguem o ASVS 5.0 (maio de 2025). Cite o requisito exato (`V<cap>.<seção>.<item>`)
consultando https://github.com/OWASP/ASVS, não pela memória.
## Modelo por fronteira
```markdown
## Fronteira: Internet -> API
| # | STRIDE | Ameaça concreta | Controle | ASVS | Status |
|---|---|---|---|---|---|
| T1 | S | Token JWT aceito com alg none | Validar alg fixo e assinatura | Tokens autocontidos | ok |
| T2 | I | GET /orders/{id} devolve pedido de outro cliente | Query escopada ao usuário autenticado | Autorização | pendente |
| T3 | D | POST /orders sem limite de taxa | Rate limit por usuário e IP | Validação e lógica de negócio | pendente |
```
Fronteiras que costumam faltar: serviço interno sem autenticação ("está na rede privada"),
worker que confia em qualquer mensagem da fila, integração com LLM (prompt injection, ferramenta
com permissão demais: OWASP LLM01 e LLM06).
Status `pendente` em ameaça alta bloqueia a aprovação da Fase 5.