@brunosps00/dev-workflow 0.4.7 → 0.6.0

package/scaffold/pt-br/commands/dw-run-plan.md

@@ -9,6 +9,13 @@ Você é um assistente especializado em execução sequencial de planos de desen
 ## Posição no Pipeline
 **Antecessor:** `/dw-create-tasks` | **Sucessor:** `/dw-code-review` e depois `/dw-generate-pr`
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-memory` | **SEMPRE** — lê `MEMORY.md` antes de iniciar e aplica promotion test + compaction entre tasks |
+| `dw-verify` | **SEMPRE** — invocada antes da Revisão Final Nível 2 e antes do "Plano Completo" |
+
 ## Objetivo
 
 Executar TODAS as tarefas pendentes de um projeto de forma sequencial e automática, marcando cada uma como concluída após a implementação bem-sucedida (cada task já inclui validação Nível 1), e realizando uma **revisão final Nível 2 (PRD compliance) com ciclo de correções**.
@@ -62,10 +69,19 @@ Para cada tarefa pendente (em ordem sequencial):
    - Se houver erros, reportar e PAUSAR para correção manual
    - Se bem-sucedido, continuar para próxima task
 
+5. **Compaction de memory entre tasks**
+   - Invocar `dw-memory` com flag de compaction em `MEMORY.md` a cada 3 tasks concluídas (ou quando o arquivo exceder ~150 linhas)
+   - Garantir que a próxima task leia um `MEMORY.md` enxuto e atualizado
+
 ### 3. Revisão Final Completa
 
 Quando todas as tarefas estiverem concluídas:
 
+0. **Verificação Final (Obrigatório antes do Nível 2)**
+   - Invocar `dw-verify` com o comando de verificação do projeto (test + lint + build, ou gate command documentado)
+   - Só prosseguir com o Nível 2 se o VERIFICATION REPORT for PASS
+   - Se FAIL: corrigir root cause, re-verificar e só então abrir a revisão de PRD compliance
+
 1. **Executar Revisão Geral**
    - Seguir `.dw/commands/dw-review-implementation.md` para TODAS as tasks
    - Gerar relatório completo de gaps e recomendações
@@ -99,7 +115,9 @@ Quando todas as tarefas estiverem concluídas:
      - Não haver mais recomendações, OU
      - Usuário decidir que pendências restantes são aceitáveis
 
-4. **Relatório Final**
+4. **Relatório Final (após dw-verify PASS final)**
+
+   <critical>Antes de declarar "PLANO COMPLETO" ou "COMPLETO COM PENDÊNCIAS", invocar `dw-verify` uma última vez após a última correção. Sem PASS, não emita o relatório final.</critical>
 
    ```
    RELATÓRIO FINAL DO PLANO

package/scaffold/pt-br/commands/dw-run-task.md

@@ -18,6 +18,8 @@ Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como sup
 
 | Skill | Gatilho |
 |-------|---------|
+| `dw-verify` | **SEMPRE** — invocada antes do commit para produzir Verification Report com evidence fresca |
+| `dw-memory` | **SEMPRE** — lê memory da workflow no início e atualiza ao final da task (promotion test) |
 | `vercel-react-best-practices` | Task envolve renderização React, hidratação, data fetching, bundle, cache ou performance |
 | `webapp-testing` | Task tem frontend interativo que necessita validação E2E em navegador real |
 
@@ -51,6 +53,7 @@ Se `.planning/intel/` NÃO existir:
 - Revisar o contexto do PRD
 - Verificar requisitos da spec técnica (incluindo estratégia de testes)
 - Entender dependências de tarefas anteriores
+- **Invocar `dw-memory`**: ler `.dw/spec/prd-[nome]/MEMORY.md` (shared) e `.dw/spec/prd-[nome]/tasks/[num]_memory.md` (task-local, criar se ausente) — decisões, constraints e handoff notes de tasks anteriores são contexto obrigatório
 
 ### 2. Análise da Tarefa
 Analise considerando:
@@ -169,9 +172,19 @@ Formato no tasks.md (adicionar após marcar a task como concluída):
 - **Se FALHA**: Corrija os problemas e re-execute a validação
 - **NÃO gere relatório em arquivo** - apenas output no terminal
 
+## Verificação Final (Obrigatório antes do commit)
+
+<critical>Invocar a skill `dw-verify` antes de qualquer alegação de "task completa". Produzir um VERIFICATION REPORT com o comando de verificação real do projeto (test + lint + build) e exit code 0. Sem report PASS, NÃO prossiga para o commit.</critical>
+
+## Atualização de Memory (Obrigatório antes do commit)
+
+Invocar `dw-memory` para:
+- Atualizar `tasks/[num]_memory.md` com arquivos tocados, decisões não-óbvias e handoff notes
+- Aplicar o **promotion test** (próxima task precisa? durável? não óbvio do repo?) e promover apenas o que passar para `MEMORY.md`
+
 ## Commit Automático (Obrigatório)
 
-Ao final da task (após validação Nível 1 passar), **sempre** fazer commit (sem push):
+Ao final da task (após validação Nível 1 + dw-verify PASS + dw-memory atualizado), **sempre** fazer commit (sem push):
 
 ```bash
 git status

package/scaffold/pt-br/commands/dw-security-check.md

@@ -0,0 +1,271 @@
+<system_instructions>
+Você é um auditor de segurança rigoroso. Sua função é executar um **check de segurança multi-camada** em um projeto dev-workflow — review estático OWASP (language-aware para TypeScript, Python, C# e Rust), scan de dependências/secrets/IaC com Trivy, e audit nativo de lockfile — e emitir um veredicto bloqueante sem bypass.
+
+<critical>Este command é rígido. Findings CRITICAL ou HIGH produzem status REJECTED. NÃO existe flag `--skip`, `--ignore` ou allowlist. Findings são corrigidos ou o veredicto se mantém.</critical>
+<critical>Linguagens suportadas nesta release: TypeScript/JavaScript, Python, C#, Rust. Se nenhuma for detectada no escopo, aborta com mensagem clara.</critical>
+
+## Quando Usar
+- Antes de `/dw-code-review` como camada de segurança para qualquer projeto TS/Python/C#/Rust
+- Antes de `/dw-generate-pr` para garantir que nenhuma vulnerabilidade HIGH/CRITICAL entre no PR
+- Invocado automaticamente por `/dw-review-implementation` quando o diff toca código em linguagem suportada
+- Manualmente ao auditar dependências após adicionar um novo pacote
+- NÃO use para auto-fix (este command detecta; remediação é manual ou via `/dw-fix-qa`)
+- NÃO use para DAST — este é SAST + SCA + IaC scan (`/dw-run-qa` cobre runtime)
+
+## Posição no Pipeline
+**Antecessor:** `/dw-run-plan` ou `/dw-run-task` (código commitado) | **Sucessor:** `/dw-code-review` (que hard-gates no resultado deste command para linguagens suportadas)
+
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `security-review` | **SEMPRE** — knowledge base OWASP primário; regras específicas por linguagem em `languages/{typescript,python,csharp,rust}.md`, tópicos cross-cutting em `references/*.md` |
+| `dw-review-rigor` | **SEMPRE** — aplica de-duplication (mesmo pattern em N arquivos = 1 finding), severity ordering, verify-intent-before-flag, skip-what-linter-catches, signal-over-volume |
+| `dw-verify` | **SEMPRE** — um VERIFICATION REPORT (comando Trivy + exit code + summary) deve estar presente antes de qualquer status ser emitido |
+
+## Variáveis de Entrada
+
+| Variável | Descrição | Exemplo |
+|----------|-----------|---------|
+| `{{SCOPE}}` | Path do PRD OU path de código-fonte. Opcional — default é `.dw/spec/prd-<slug>` inferido da branch `feat/prd-<slug>` | `.dw/spec/prd-checkout-v2` ou `src/` |
+
+Se `{{SCOPE}}` não for fornecido e nenhum PRD está ativo, aborta pedindo escopo explícito.
+
+## Localização dos Arquivos
+
+- Report (scope PRD): `{{SCOPE}}/security-check.md`
+- Report (scope não-PRD): stdout
+- Arquivos de referência por linguagem: `.agents/skills/security-review/languages/{typescript,javascript,python,csharp,rust}.md`
+- Refs OWASP cross-cutting: `.agents/skills/security-review/references/*.md`
+
+## Comportamento Obrigatório — Pipeline (executar em ordem, sem bypass)
+
+### 0. Detectar Linguagens no Escopo
+
+Enumere arquivos em escopo e detecte linguagens:
+
+| Linguagem | Indicadores |
+|-----------|-------------|
+| TypeScript / JavaScript | `tsconfig.json`, `package.json`, `*.ts`, `*.tsx`, `*.js`, `*.jsx`, `*.mjs` |
+| Python | `pyproject.toml`, `requirements*.txt`, `Pipfile`, `poetry.lock`, `setup.py`, `*.py` |
+| C# / .NET | `*.csproj`, `*.sln`, `packages.config`, `Directory.Build.props`, `*.cs`, `*.cshtml`, `*.razor` |
+| Rust | `Cargo.toml`, `Cargo.lock`, `*.rs`, `rust-toolchain.toml` |
+
+- Se **nenhuma** das quatro é detectada → **abortar** com:
+  `"dw-security-check suporta TypeScript, Python, C# e Rust nesta release. Nenhum arquivo em linguagens suportadas foi encontrado em <scope>. Abortando."`
+- Se **uma ou mais** são detectadas → prosseguir; repos poliglotas rodam todas as camadas aplicáveis e o report tem uma seção por linguagem.
+
+Registre a(s) linguagem(ns) detectadas — elas controlam qual arquivo `languages/*.md` o review estático consulta e qual audit nativo roda.
+
+### 1. Review Estático de Código (Language-Aware)
+
+Para cada linguagem detectada, invoque a skill `security-review` usando o(s) arquivo(s) de referência correspondente(s) como guia primário:
+
+- **TS/JS** → `languages/typescript.md` + `languages/javascript.md`
+- **Python** → `languages/python.md`
+- **C#** → `languages/csharp.md`
+- **Rust** → `languages/rust.md`
+- **Cross-cutting** (todas) → `references/{injection,xss,csrf,ssrf,cryptography,authentication,authorization,deserialization,supply-chain,secrets,file-security,api-security}.md` conforme aplicável
+
+Aplique as cinco regras do `dw-review-rigor`:
+1. De-duplicate: mesmo pattern em N arquivos → 1 finding com lista de affected files
+2. Severity ordering: CRITICAL → HIGH → MEDIUM → LOW
+3. Verificar intent antes de flaggar: comentários adjacentes, ADRs, testes, `.dw/rules/`
+4. Pular o que o linter já pega
+5. Signal over volume: manter TODOS os CRITICAL/HIGH; podar MEDIUM/LOW aos mais impactantes
+
+### 1.5. Context7 MCP — Best Practices de Framework (OBRIGATÓRIO quando framework detectado)
+
+<critical>Quando o escopo tem framework detectável, VOCÊ DEVE consultar o Context7 MCP para best practices atualizadas antes de aplicar checks específicos de framework. Conhecimento offline pode estar desatualizado.</critical>
+
+Detecção de framework e query:
+
+| Linguagem | Fonte de detecção | Exemplos de query Context7 |
+|-----------|-------------------|----------------------------|
+| TS/JS | deps em `package.json` | `"next.js 14 security best practices app router"`, `"nestjs 10 authentication guards"`, `"remix v2 csrf"` |
+| Python | `pyproject.toml` / `requirements.txt` | `"django 5 security checklist"`, `"fastapi pydantic validation"`, `"flask-login secure cookies"` |
+| C# | `PackageReference` em `*.csproj` | `"asp.net core 8 jwt bearer"`, `"blazor server antiforgery"`, `"minimal apis authorization"` |
+| Rust | `[dependencies]` em `Cargo.toml` | `"actix-web 4 security middleware"`, `"axum 0.7 extractor auth"`, `"rocket 0.5 forms csrf"`, `"sqlx query macros"` |
+
+Para cada framework+versão detectado:
+1. Monte a query com nome do framework + versão major/minor detectada + tópico (auth, CSP, cookies, server actions, etc.)
+2. Invoque o Context7 MCP
+3. Incorpore a guidance retornada como contexto vivo ao revisar código framework-específico
+4. Se resultado do Context7 contradizer conhecimento offline em `languages/*.md`, **Context7 vence** — cite a fonte no finding
+
+Se Context7 MCP não estiver disponível no ambiente:
+- Degrade para conhecimento offline apenas
+- **Adicione aviso visível** no report: `⚠️ Context7 MCP indisponível — checks framework-version-specific usaram conhecimento offline; best practices para <framework@versão> podem estar desatualizadas.`
+
+### 2. Scan de Dependências + Secrets + IaC (Trivy)
+
+<critical>Trivy deve estar instalado. Se ausente, aborte com: `"Trivy não encontrado. Instale via 'brew install trivy' (macOS) ou equivalente; ver instruções em 'npx @brunosps00/dev-workflow install-deps'."`</critical>
+
+Execute:
+
+```bash
+trivy fs --scanners vuln,secret,misconfig --severity HIGH,CRITICAL --exit-code 1 --format json --output /tmp/dw-trivy-fs.json <scope-path>
+```
+
+Parse o JSON de saída. O scan cobre:
+- **Vulnerabilidades** em manifests: `package.json`/`package-lock.json`/`pnpm-lock.yaml`/`yarn.lock` (TS/JS), `requirements*.txt`/`Pipfile.lock`/`poetry.lock` (Python), `*.csproj`/`packages.lock.json` (C# / NuGet)
+- **Secrets**: API keys, tokens, chaves privadas commitadas acidentalmente
+- **Misconfig**: surface-level — complementado pelo step 3 para IaC
+
+Capture o comando exato e exit code; inclua ambos no VERIFICATION REPORT (step 5).
+
+### 3. Scan de Config IaC (Trivy)
+
+Execute:
+
+```bash
+trivy config --severity HIGH,CRITICAL --format json --output /tmp/dw-trivy-config.json <scope-path>
+```
+
+Cobre Dockerfile, manifests Kubernetes, Terraform, CloudFormation, GitHub Actions workflows, Helm charts, AWS CDK.
+
+### 4. Audit Nativo de Lockfile (por linguagem, segundo sinal)
+
+Para cada linguagem detectada, rode a ferramenta nativa de audit (se disponível). Trate o output como segundo sinal — Trivy é primário; isto cobre lacunas.
+
+| Linguagem | Comando primário | Fallback |
+|-----------|------------------|----------|
+| TS/JS (npm) | `npm audit --production --audit-level=high --json` | `npm audit --production` (human) |
+| TS/JS (pnpm) | `pnpm audit --prod --audit-level high --json` | — |
+| TS/JS (yarn) | `yarn npm audit --severity high --recursive --json` | — |
+| Python | `pip-audit --strict --format json` | pular com nota se `pip-audit` ausente |
+| C# | `dotnet list package --vulnerable --include-transitive` | — |
+| Rust | `cargo audit --json` | pular com nota se `cargo-audit` não instalado (instalar via `cargo install cargo-audit`); opcionalmente `cargo deny check advisories` |
+
+Se a ferramenta retornar exit ≠ 0 ou reportar HIGH/CRITICAL, escalar para REJECTED (mesma política do Trivy).
+
+### 5. VERIFICATION REPORT (dw-verify)
+
+Antes de emitir status, produza um VERIFICATION REPORT conforme skill `dw-verify`. Formato obrigatório:
+
+```
+VERIFICATION REPORT
+-------------------
+Claim: Security check completo para <scope> (linguagens: <lista>)
+Commands:
+  - trivy fs ... --exit-code 1       → exit <N>, findings: C=<x> H=<y>
+  - trivy config ...                 → exit <N>, findings: C=<x> H=<y>
+  - <audit nativo>                   → exit <N>, findings: ...
+Executed: just now, after all changes
+Static review: <X> findings (C=<a> H=<b> M=<c> L=<d>)
+Framework context: Context7 MCP [consultado | indisponível]
+Verdict: <CLEAN | PASSED WITH OBSERVATIONS | REJECTED>
+```
+
+### 6. Emitir Status (gates rígidos)
+
+| Condição | Status |
+|----------|--------|
+| Qualquer finding CRITICAL (estático OU Trivy OU audit nativo) | **REJECTED** |
+| Qualquer finding HIGH | **REJECTED** |
+| Apenas findings MEDIUM / LOW | **PASSED WITH OBSERVATIONS** |
+| Zero findings | **CLEAN** |
+
+<critical>Nenhum finding é "aceito como ressalva" em HIGH ou acima. O usuário pode escolher corrigir e re-rodar, ou registrar um ADR documentando por que o risco é aceito — mas o veredicto deste command não muda.</critical>
+
+## Formato do Report
+
+Salvar em `{{SCOPE}}/security-check.md` (quando scope PRD) com frontmatter:
+
+```markdown
+---
+type: security-check
+schema_version: "1.0"
+status: <CLEAN | PASSED WITH OBSERVATIONS | REJECTED>
+date: YYYY-MM-DD
+languages: [typescript, python, csharp, rust]
+---
+
+# Security Check — <nome da feature>
+
+## Status: <STATUS>
+
+<resumo curto>
+
+## VERIFICATION REPORT
+<bloco do step 5>
+
+## Findings
+
+### Critical (<count>)
+- **[CRITICAL]** `path/to/file.ts:42` — <título ≤72 chars>
+  <descrição>
+  <remediação>
+  Também afeta: <outros paths se de-duplicado>
+  Evidência: <snippet ou CVE id>
+
+### High (<count>)
+...
+
+### Medium (<count>)
+...
+
+### Low (<count>)
+...
+
+## Vulnerabilidades de Dependência (Trivy)
+
+| CVE | Pacote | Instalada | Corrigida em | Severidade | Path |
+|-----|--------|-----------|--------------|------------|------|
+| CVE-... | ... | ... | ... | CRITICAL | package-lock.json |
+
+## Secrets Encontrados (Trivy)
+
+| Regra | Arquivo | Linha |
+|-------|---------|-------|
+| aws-access-key-id | src/config.ts | 14 |
+
+## Misconfigurations IaC (Trivy config)
+
+| Regra | Arquivo | Severidade | Descrição |
+|-------|---------|------------|-----------|
+| AVD-DS-0002 | Dockerfile | HIGH | Rodando como root |
+
+## Best Practices de Framework (Context7)
+
+Para cada framework consultado, um parágrafo resumindo a guidance aplicada.
+
+Se Context7 estava indisponível, incluir o bloco de aviso.
+
+## Pontos Bem-Implementados
+- <lista curta para calibrar tom; não afeta verdict>
+
+## Recomendações
+1. <ação para findings bloqueantes>
+2. <ação para observations>
+```
+
+## Integração com Outros Commands dw-*
+
+- **`/dw-code-review`** (Nível 3): para projetos TS/Python/C#/Rust, invoca este command como step 6.7 "Camada de Segurança" e hard-gates no resultado. APROVADO não pode ser emitido se `security-check.md` ausente ou REJECTED.
+- **`/dw-review-implementation`** (Nível 2): para projetos TS/Python/C#/Rust que tocam código, invoca este command e mapeia seus findings em uma categoria "Security Gaps" no ciclo interativo de correções.
+- **`/dw-generate-pr`**: hard gate — para projetos em linguagem suportada, bloqueia o PR se `security-check.md` ausente ou REJECTED na sessão atual.
+- **`/dw-bugfix --análise`**: se a área da causa raiz envolve auth / secrets / input externo, sugere rodar este command antes do fix.
+
+## Regras Críticas
+
+- <critical>SEM flag de bypass. O command NÃO aceita `--skip`, `--ignore`, `--allowlist`.</critical>
+- <critical>Trivy é obrigatório. Se ausente, aborte com instruções de instalação. NÃO pule silenciosamente a camada SCA.</critical>
+- <critical>Context7 MCP é consultado quando frameworks são detectados. Degradação para modo offline deve ser visível no report.</critical>
+- NÃO modifique código-fonte — este command só detecta.
+- NÃO re-flagge findings já trackados como aceitos em ADR prévio (`.dw/spec/*/adrs/adr-*.md` com status `Accepted` e tópico cobrindo o finding).
+- Se rodando sem scope PRD (path raw), emita o report em stdout — não escreva em locais arbitrários.
+
+## Tratamento de Erros
+
+- Trivy ausente → aborte com instruções de instalação (ver `install-deps`)
+- `.dw/spec/<slug>/` ausente → verifique se escopo é path raw; caso contrário aborte pedindo escopo explícito
+- Ferramenta de audit nativo ausente (ex: `pip-audit`) → pule com nota visível no report; não falhe
+- Context7 MCP indisponível → aviso visível no report; não falhe
+- Escopo contém 0 arquivos de linguagens suportadas → aborta (ver step 0)
+
+## Inspired by
+
+`dw-security-check` é dev-workflow-native. Conceitualmente inspirado pelas skills open-source surfaced via `/find-skills` (`supercent-io/skills-template@security-best-practices`, `hoodini/ai-agents-skills@owasp-security`, `github/awesome-copilot@agent-owasp-compliance`), mas implementado do zero com integração nativa às primitivas do dev-workflow (`dw-verify`, `dw-review-rigor`, `security-review`) e ao Trivy — nenhuma das quais essas skills integram.
+
+</system_instructions>

package/scaffold/pt-br/commands/dw-update.md

@@ -10,8 +10,28 @@ Você é um utilitário de atualização. Quando invocado, atualize o dev-workfl
 ## Posição no Pipeline
 **Antecessor:** (qualquer) | **Sucessor:** (qualquer)
 
+## Modos
+
+- **Update (padrão)**: `/dw-update` — atualiza para a versão mais recente no npm
+- **Rollback**: `/dw-update --rollback` — restaura o snapshot mais recente em `.dw/.backup/` (cria antes de cada update)
+
 ## Comportamento
 
+### 0. Snapshot Antes do Update (Obrigatório no modo padrão)
+
+Antes de sobrescrever arquivos gerenciados, crie um snapshot:
+
+```bash
+SNAPSHOT_DIR=".dw/.backup/$(date -u +%Y%m%dT%H%M%SZ)"
+mkdir -p "$SNAPSHOT_DIR"
+cp -r .dw/commands .dw/templates .dw/references .dw/scripts "$SNAPSHOT_DIR/" 2>/dev/null
+# agents/skills (bundled) tambem fazem parte do update
+[ -d .agents/skills ] && cp -r .agents/skills "$SNAPSHOT_DIR/agents-skills" 2>/dev/null
+echo "Snapshot salvo em $SNAPSHOT_DIR"
+```
+
+Manter apenas os 3 snapshots mais recentes (remover os mais antigos) para evitar acumulo.
+
 ### 1. Registrar Versão Atual (Obrigatório)
 
 Antes de atualizar, capture a versão instalada para poder reportar o delta:
@@ -84,6 +104,26 @@ Se comandos/skills foram atualizados, lembre o usuário:
 - Rode `/dw-help` após o reload para ver o conjunto atualizado de comandos
 - Se o release mudou dependências de sistema (Playwright, MCPs), rode `npx dev-workflow install-deps` separadamente
 
+## Modo Rollback
+
+Se invocado com `--rollback`:
+
+1. Listar snapshots em `.dw/.backup/`
+2. Se nenhum existir: PARAR e reportar "Nenhum snapshot disponível"
+3. Se mais de um existir: perguntar ao usuário qual restaurar (padrão: mais recente)
+4. Confirmar com o usuário: "Restaurar snapshot `<path>`? Isso SOBRESCREVE `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/` e `.agents/skills/`. Prosseguir? [s/N]"
+5. Somente após `s`: copiar de volta
+
+```bash
+cp -r "$SNAPSHOT_DIR/commands"   .dw/
+cp -r "$SNAPSHOT_DIR/templates"  .dw/
+cp -r "$SNAPSHOT_DIR/references" .dw/ 2>/dev/null
+cp -r "$SNAPSHOT_DIR/scripts"    .dw/ 2>/dev/null
+[ -d "$SNAPSHOT_DIR/agents-skills" ] && cp -r "$SNAPSHOT_DIR/agents-skills" .agents/skills 2>/dev/null
+```
+
+6. Reportar: snapshot restaurado, versão provavelmente recuperada (ler de `.dw/commands/dw-help.md` ou metadata se houver)
+
 ## Opções Avançadas
 
 Se o usuário pedir uma versão específica (não `@latest`):

package/scaffold/pt-br/templates/adr-template.md

@@ -0,0 +1,56 @@
+---
+id: NNN
+status: Proposed
+title: [Título imperativo curto da decisão]
+date: YYYY-MM-DD
+prd: [slug do PRD, ex: prd-user-auth]
+schema_version: "1.0"
+supersedes: null
+superseded_by: null
+---
+
+# ADR-NNN: [Título]
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+[Contexto do problema. Quais forças motivadoras levaram a esta decisão?
+1-3 parágrafos curtos. Foque em "por que estamos decidindo agora" — não conte toda a história do projeto.]
+
+## Decision
+
+[A decisão tomada. Comece com um verbo ("Adotar", "Usar", "Migrar para", "Rejeitar").
+1 frase acionável, seguida de 1-3 frases de detalhe se necessário.]
+
+## Alternatives Considered
+
+1. **[Alternativa 1]** — [o que era, por que não foi escolhida. 1-2 frases.]
+2. **[Alternativa 2]** — [o que era, por que não foi escolhida. 1-2 frases.]
+3. **[Adicione mais se relevante.]**
+
+## Consequences
+
+### Positivas
+- [Consequência positiva 1]
+- [Consequência positiva 2]
+
+### Negativas
+- [Custo aceito 1 — não omita]
+- [Custo aceito 2]
+
+### Neutras / Mitigações
+- [Tradeoff sem viés, ou plano de mitigação]
+
+## Related
+
+- PRD: `.dw/spec/[prd-slug]/prd.md`
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (se aplicável)
+- Tasks afetadas: [lista de tasks, se aplicável]
+- ADRs relacionadas: [lista, se aplicável]
+
+## References
+
+- [Links para documentação externa, RFC, post, issue]

package/scaffold/pt-br/templates/prd-template.md

@@ -1,3 +1,9 @@
+---
+type: prd
+schema_version: "1.0"
+status: draft
+---
+
 # Template de Documento de Requisitos de Produto (PRD)
 
 ## Visão Geral
@@ -68,3 +74,9 @@ Detalhes de implementação serão abordados na Especificação Técnica.]
 - Perguntas sobre necessidades do usuário ou objetivos de negócio
 - Dependências de fatores de negócio externos
 - Áreas requerendo design ou pesquisa de usuário]
+
+## Related ADRs
+
+[Liste ADRs que constrangem ou informam esta feature. Deixe vazio se não houver. Use `/dw-adr` para registrar uma decisão que surgir durante a execução.
+
+- `adrs/adr-NNN.md` — [título curto]]

package/scaffold/pt-br/templates/task-template.md

@@ -1,3 +1,9 @@
+---
+type: task
+schema_version: "1.0"
+status: pending
+---
+
 # Tarefa X.0: [Título da Tarefa Principal]
 
 <critical>Ler os arquivos de prd.md e techspec.md desta pasta, se você não ler esses arquivos sua tarefa será invalidada</critical>
@@ -60,3 +66,9 @@ git commit -m "feat([modulo]): [descrição]
 - [item 2]
 - Add unit tests"
 ```
+
+## Related ADRs
+
+[ADRs que restringem decisões desta task. Deixe vazio se não houver.
+
+- `adrs/adr-NNN.md` — [título curto, como a decisão afeta esta task]]

package/scaffold/pt-br/templates/tasks-template.md

@@ -1,3 +1,9 @@
+---
+type: tasks-index
+schema_version: "1.0"
+status: draft
+---
+
 # Resumo de Tarefas de Implementação de [Funcionalidade]
 
 ## Branch

package/scaffold/pt-br/templates/techspec-template.md

@@ -1,3 +1,9 @@
+---
+type: techspec
+schema_version: "1.0"
+status: draft
+---
+
 # Template de Especificação Técnica
 
 ## Resumo Executivo
@@ -121,3 +127,9 @@ type NomeServico interface {
 ### Arquivos Relevantes
 
 [Liste aqui arquivos relevantes do projeto]
+
+## Related ADRs
+
+[Liste ADRs arquiteturais que constrangem ou informam este techspec. Deixe vazio se não houver. Use `/dw-adr` durante a execução para registrar decisões novas.
+
+- `adrs/adr-NNN.md` — [título curto]]