@brunosps00/dev-workflow 0.4.7 → 0.5.0

package/scaffold/en/commands/dw-review-implementation.md

@@ -23,6 +23,12 @@ This is **Review Level 2**:
 
 This command is called automatically by `/dw-run-plan` at the end of all tasks, but can also be executed manually.
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-review-rigor` | **ALWAYS** — when listing gaps between PRD/TechSpec and code, apply de-duplication (same gap in N modules = 1 entry), severity ordering, and verify-intent-before-flag |
+
 ## Input Variables
 
 | Variable | Description | Example |

package/scaffold/en/commands/dw-run-plan.md

@@ -9,6 +9,13 @@ You are an assistant specialized in sequential execution of development plans. Y
 ## Pipeline Position
 **Predecessor:** `/dw-create-tasks` | **Successor:** `/dw-code-review` then `/dw-generate-pr`
 
+## Complementary Skills
+
+| Skill | Trigger |
+|-------|---------|
+| `dw-memory` | **ALWAYS** — reads `MEMORY.md` before starting and applies promotion test + compaction between tasks |
+| `dw-verify` | **ALWAYS** — invoked before the Level 2 Final Review and before declaring "Plan Complete" |
+
 ## Objective
 
 Execute ALL pending tasks in a project sequentially and automatically, marking each as completed after successful implementation (each task already includes Level 1 validation), and performing a **final Level 2 review (PRD compliance) with a corrections cycle**.
@@ -62,10 +69,19 @@ For each pending task (in sequential order):
    - If there are errors, report and PAUSE for manual correction
    - If successful, continue to next task
 
+5. **Memory compaction between tasks**
+   - Invoke `dw-memory` with compaction flag on `MEMORY.md` every 3 completed tasks (or when the file exceeds ~150 lines)
+   - Ensure the next task reads a lean, up-to-date `MEMORY.md`
+
 ### 3. Final Comprehensive Review
 
 When all tasks are completed:
 
+0. **Final Verification (Required before Level 2)**
+   - Invoke `dw-verify` with the project's verify command (test + lint + build, or the documented gate command)
+   - Only proceed with Level 2 if the VERIFICATION REPORT is PASS
+   - If FAIL: fix the root cause, re-verify, and only then open the PRD-compliance review
+
 1. **Execute General Review**
    - Follow `.dw/commands/dw-review-implementation.md` for ALL tasks
    - Generate a complete gap report and recommendations
@@ -102,7 +118,9 @@ When all tasks are completed:
      - No more recommendations, OR
      - User decides that remaining items are acceptable
 
-4. **Final Report**
+4. **Final Report (after final dw-verify PASS)**
+
+   <critical>Before declaring "PLAN COMPLETE" or "COMPLETE WITH PENDING ITEMS", invoke `dw-verify` one last time after the last correction. Without PASS, do not emit the final report.</critical>
 
    ```
    ===================================================

package/scaffold/en/commands/dw-run-task.md

@@ -18,6 +18,8 @@ When available in the project at `./.agents/skills/`, use these skills as specia
 
 | Skill | Trigger |
 |-------|---------|
+| `dw-verify` | **ALWAYS** — invoked before the commit to produce a Verification Report with fresh evidence |
+| `dw-memory` | **ALWAYS** — reads workflow memory at task start and updates it at task end (promotion test) |
 | `vercel-react-best-practices` | Task touches React rendering, hydration, data fetching, bundle, cache, or performance |
 | `webapp-testing` | Task has interactive frontend needing E2E validation in a real browser |
 
@@ -51,6 +53,7 @@ If `.planning/intel/` does NOT exist:
 - Review the PRD context
 - Verify tech spec requirements (including testing strategy)
 - Understand dependencies from previous tasks
+- **Invoke `dw-memory`**: read `.dw/spec/prd-[name]/MEMORY.md` (shared) and `.dw/spec/prd-[name]/tasks/[num]_memory.md` (task-local, create if missing) — decisions, constraints and handoff notes from earlier tasks are mandatory context
 
 ### 2. Task Analysis
 Analyze considering:
@@ -170,9 +173,19 @@ Format in tasks.md (add after marking the task as completed):
 - **If FAILURE**: Fix the issues and re-execute the validation
 - **DO NOT generate a report file** - only output in the terminal
 
+## Final Verification (Required before commit)
+
+<critical>Invoke the `dw-verify` skill before any "task complete" claim. Produce a VERIFICATION REPORT with the project's real verify command (test + lint + build) and exit code 0. Without a PASS report, DO NOT proceed to the commit.</critical>
+
+## Memory Update (Required before commit)
+
+Invoke `dw-memory` to:
+- Update `tasks/[num]_memory.md` with files touched, non-obvious decisions, and handoff notes
+- Apply the **promotion test** (next task needs it? durable? not obvious from repo?) and only promote what passes to `MEMORY.md`
+
 ## Automatic Commit (Required)
 
-At the end of the task (after Level 1 validation passes), **always** commit (no push):
+At the end of the task (after Level 1 validation + dw-verify PASS + dw-memory update), **always** commit (no push):
 
 ```bash
 git status

package/scaffold/en/commands/dw-update.md

@@ -10,8 +10,27 @@ You are an update utility. When invoked, update dev-workflow to the latest versi
 ## Pipeline Position
 **Predecessor:** (any) | **Successor:** (any)
 
+## Modes
+
+- **Update (default)**: `/dw-update` — updates to the latest version on npm
+- **Rollback**: `/dw-update --rollback` — restores the most recent snapshot in `.dw/.backup/` (created before each update)
+
 ## Behavior
 
+### 0. Snapshot Before Update (Required in default mode)
+
+Before overwriting managed files, create a 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
+[ -d .agents/skills ] && cp -r .agents/skills "$SNAPSHOT_DIR/agents-skills" 2>/dev/null
+echo "Snapshot saved to $SNAPSHOT_DIR"
+```
+
+Keep only the 3 most recent snapshots (remove older ones) to avoid buildup.
+
 ### 1. Record Current Version (Required)
 
 Before updating, capture the installed version so you can report the delta:
@@ -84,6 +103,26 @@ If commands/skills were updated, remind the user:
 - Run `/dw-help` after the reload to see the updated command set
 - If the release changed system dependencies (Playwright, MCPs), run `npx dev-workflow install-deps` separately
 
+## Rollback Mode
+
+If invoked with `--rollback`:
+
+1. List snapshots in `.dw/.backup/`
+2. If none exist: STOP and report "No snapshot available"
+3. If more than one exists: ask the user which to restore (default: most recent)
+4. Confirm with the user: "Restore snapshot `<path>`? This OVERWRITES `.dw/commands/`, `.dw/templates/`, `.dw/references/`, `.dw/scripts/`, and `.agents/skills/`. Proceed? [y/N]"
+5. Only after `y`: copy back
+
+```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. Report: snapshot restored, version likely recovered (read from `.dw/commands/dw-help.md` or metadata if present)
+
 ## Advanced Options
 
 If the user asks for a specific version (not `@latest`):

package/scaffold/en/templates/adr-template.md

@@ -0,0 +1,56 @@
+---
+id: NNN
+status: Proposed
+title: [Short imperative title of the decision]
+date: YYYY-MM-DD
+prd: [PRD slug, e.g. prd-user-auth]
+schema_version: "1.0"
+supersedes: null
+superseded_by: null
+---
+
+# ADR-NNN: [Title]
+
+## Status
+
+Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+
+## Context
+
+[Problem context. What motivating forces led to this decision?
+1-3 short paragraphs. Focus on "why are we deciding now" — do not retell the whole project history.]
+
+## Decision
+
+[The decision made. Start with a verb ("Adopt", "Use", "Migrate to", "Reject").
+1 actionable sentence, followed by 1-3 detail sentences if needed.]
+
+## Alternatives Considered
+
+1. **[Alternative 1]** — [what it was, why not chosen. 1-2 sentences.]
+2. **[Alternative 2]** — [what it was, why not chosen. 1-2 sentences.]
+3. **[Add more if relevant.]**
+
+## Consequences
+
+### Positive
+- [Positive consequence 1]
+- [Positive consequence 2]
+
+### Negative
+- [Accepted cost 1 — do not omit]
+- [Accepted cost 2]
+
+### Neutral / Mitigations
+- [Unbiased tradeoff, or mitigation plan]
+
+## Related
+
+- PRD: `.dw/spec/[prd-slug]/prd.md`
+- TechSpec: `.dw/spec/[prd-slug]/techspec.md` (if applicable)
+- Affected tasks: [task list, if applicable]
+- Related ADRs: [list, if applicable]
+
+## References
+
+- [Links to external docs, RFCs, posts, issues]

package/scaffold/en/templates/prd-template.md

@@ -1,3 +1,9 @@
+---
+type: prd
+schema_version: "1.0"
+status: draft
+---
+
 # Product Requirements Document (PRD) Template
 
 ## Overview
@@ -68,3 +74,9 @@ Implementation details will be addressed in the Technical Specification.]
 - Questions about user needs or business goals
 - Dependencies on external business factors
 - Areas requiring design or user research]
+
+## Related ADRs
+
+[List ADRs that constrain or inform this feature. Leave empty if none. Use `/dw-adr` to record a decision that emerges during execution.
+
+- `adrs/adr-NNN.md` — [short title]]

package/scaffold/en/templates/task-template.md

@@ -1,3 +1,9 @@
+---
+type: task
+schema_version: "1.0"
+status: pending
+---
+
 # Task X.0: [Main Task Title]
 
 <critical>Read the prd.md and techspec.md files in this folder. If you don't read these files your task will be invalidated.</critical>
@@ -60,3 +66,9 @@ git commit -m "feat([module]): [description]
 - [item 2]
 - Add unit tests"
 ```
+
+## Related ADRs
+
+[ADRs that constrain this task's decisions. Leave empty if none.
+
+- `adrs/adr-NNN.md` — [short title, how the decision affects this task]]

package/scaffold/en/templates/tasks-template.md

@@ -1,3 +1,9 @@
+---
+type: tasks-index
+schema_version: "1.0"
+status: draft
+---
+
 # Implementation Tasks Summary for [Feature]
 
 ## Branch

package/scaffold/en/templates/techspec-template.md

@@ -1,3 +1,9 @@
+---
+type: techspec
+schema_version: "1.0"
+status: draft
+---
+
 # Technical Specification Template
 
 ## Executive Summary
@@ -121,3 +127,9 @@ type ServiceName interface {
 ### Relevant Files
 
 [List relevant project files here]
+
+## Related ADRs
+
+[List architectural ADRs that constrain or inform this techspec. Leave empty if none. Use `/dw-adr` during execution to record new decisions.
+
+- `adrs/adr-NNN.md` — [short title]]

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

@@ -0,0 +1,117 @@
+<system_instructions>
+Você é um registrador de decisões arquiteturais. Sua função é criar um **Architecture Decision Record (ADR)** que documente uma decisão técnica importante feita durante a fase atual do PRD.
+
+## Quando Usar
+- Use quando uma decisão arquitetural ou de design foi tomada e precisa ser registrada para referência futura (escolha de biblioteca, padrão de comunicação, tradeoff de performance, restrição imposta por compliance, etc.)
+- Use durante `/dw-create-techspec` ou `/dw-run-task` quando a justificativa da decisão não cabe no techspec nem no task file
+- NÃO use para decisões triviais ou reversíveis sem custo (escolha de nome de variável, ordem de import)
+- NÃO use para registrar bugs ou incidents (use `/dw-bugfix` ou notas operacionais)
+
+## Posição no Pipeline
+**Antecessor:** qualquer ponto do pipeline após `/dw-create-prd` | **Sucessor:** continua o fluxo anterior (techspec, task, review)
+
+O ADR é **aditivo**: ele não substitui nenhuma etapa do pipeline. Qualquer command existente pode invocar `/dw-adr` quando uma decisão não-trivial precisar de registro permanente.
+
+## Variáveis de Entrada
+
+| Variável | Descrição | Exemplo |
+|----------|-----------|---------|
+| `{{PRD_PATH}}` | Caminho da pasta do PRD ativo | `.dw/spec/prd-minha-feature` |
+| `{{TITLE}}` | Título curto da decisão (imperativo) | "Usar PostgreSQL ao invés de MongoDB" |
+
+Se `{{PRD_PATH}}` não for fornecido, pergunte ao usuário qual PRD está ativo (leia `.dw/spec/` e liste). Se `{{TITLE}}` não for fornecido, pergunte.
+
+## Localização dos Arquivos
+
+- Diretório de ADRs: `{{PRD_PATH}}/adrs/`
+- Arquivo novo: `{{PRD_PATH}}/adrs/adr-NNN.md` (NNN zero-padded para 3 dígitos)
+- Template: `.dw/templates/adr-template.md`
+
+## Fluxo de Trabalho
+
+### 1. Descobrir o próximo número
+- Liste os arquivos em `{{PRD_PATH}}/adrs/` (crie o diretório se não existir)
+- O próximo número é `max(existentes) + 1`, ou `1` se vazio
+
+### 2. Coletar contexto (perguntas mínimas)
+
+Pergunte ao usuário **4 perguntas objetivas**, uma por vez:
+
+1. **Contexto**: qual problema ou força motivadora levou a esta decisão? (1-3 frases)
+2. **Decisão**: qual é a decisão tomada? (1 frase acionável, começa com verbo)
+3. **Alternativas consideradas**: quais outras opções foram avaliadas e por que não foram escolhidas? (mínimo 2)
+4. **Consequências**: quais são os tradeoffs positivos e negativos desta decisão? (explicite os negativos — sem painting rosy)
+
+### 3. Escrever o arquivo ADR
+
+Use `.dw/templates/adr-template.md` como base. Campos obrigatórios:
+
+```yaml
+---
+id: NNN
+status: Proposed | Accepted | Deprecated | Superseded
+title: [título do ADR]
+date: YYYY-MM-DD
+prd: [slug do PRD]
+schema_version: "1.0"
+---
+
+# ADR-NNN: [Título]
+
+## Status
+[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]
+
+## Context
+[Contexto e forças motivadoras]
+
+## Decision
+[A decisão tomada]
+
+## Alternatives Considered
+1. **[Alternativa 1]** — [por que não foi escolhida]
+2. **[Alternativa 2]** — [por que não foi escolhida]
+
+## Consequences
+### Positivas
+- [consequência positiva 1]
+
+### Negativas
+- [consequência negativa / tradeoff aceito]
+
+## Related
+- PRD: `.dw/spec/prd-[nome]/prd.md`
+- TechSpec: `.dw/spec/prd-[nome]/techspec.md` (se aplicável)
+- Tasks afetadas: [lista, se aplicável]
+```
+
+### 4. Atualizar referências cruzadas
+
+Se o ADR for criado **durante** a execução de um PRD, adicionar uma linha na seção "Related ADRs" dos artefatos relacionados:
+- `prd.md`, `techspec.md`, ou `[N]_task.md`, conforme o escopo da decisão
+
+Se a seção "Related ADRs" não existir no arquivo, adicioná-la ao final.
+
+### 5. Reportar
+
+Apresente ao usuário:
+- Caminho do ADR criado
+- Artefatos atualizados com referência cruzada
+- Status inicial (geralmente `Accepted` para decisões já tomadas, `Proposed` para decisões ainda abertas)
+
+## Comportamento Obrigatório
+
+<critical>NUNCA sobrescreva um ADR existente. Cada ADR é imutável — se a decisão muda, crie um novo ADR com status `Supersedes ADR-NNN` e marque o antigo como `Superseded by ADR-XXX`.</critical>
+
+<critical>NUNCA pinte o tradeoff como "só positivo". A seção Consequências Negativas é obrigatória — se não houver nenhum custo, a decisão não precisa de ADR.</critical>
+
+## Inspired by
+
+Este command é inspirado no padrão de ADRs de `/tmp/compozy/.agents/skills/cy-create-adr/` do projeto [Compozy](https://github.com/compozy/compozy). Adaptações para dev-workflow:
+
+- Paths são `.dw/spec/<prd>/adrs/` ao invés de `.compozy/tasks/<name>/adrs/`
+- 4 perguntas mínimas em vez do fluxo interativo mais longo (alinhado com o estilo conciso de outros commands dw-*)
+- Integração explícita com `schema_version` dos templates v1.0
+
+Credit: Compozy project.
+
+</system_instructions>

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

@@ -33,6 +33,13 @@ Uma etapa que invoca um comando `/dw-xxx` SO e considerada completa quando os ar
 ## Posicao no Pipeline
 **Antecessor:** (desejo do usuario) | **Sucessor:** (merge do PR)
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-memory` | **SEMPRE** — thread de memory atravessa todas as fases (brainstorm -> PRD -> techspec -> tasks -> execucao -> QA -> review -> PR). Decisoes de um gate alimentam o contexto do proximo. |
+| `dw-verify` | **SEMPRE** — invocada em cada gate (PRD, Tasks, PR) antes de pedir aprovacao do usuario; e antes do commit final + push. |
+
 ## Variaveis de Entrada
 
 | Variavel | Descricao | Exemplo |

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

@@ -11,6 +11,11 @@ Você é um facilitador de brainstorming para o workspace atual. Este comando ex
 ## Posição no Pipeline
 **Antecessor:** (ideia do usuário) | **Sucessor:** `/dw-create-prd`
 
+## Flags
+
+- **(padrão)**: brainstorm normal com 3-7 opções (conservadora, equilibrada, ousada) e trade-offs
+- **`--council`**: após o brainstorm normal, invoca a skill `dw-council` para stress-test das top 2-3 opções através de 3-5 archetypes (pragmatic-engineer, architect-advisor, security-advocate, product-mind, devils-advocate). Útil quando a escolha é de alto impacto e há genuine dissent entre caminhos.
+
 ## Fluxograma de Decisão: Brainstorm vs PRD Direto
 
 ```dot
@@ -33,6 +38,7 @@ digraph brainstorm_decision {
 
 Quando disponíveis no projeto em `./.agents/skills/`, use para enriquecer a ideação:
 
+- `dw-council` (opt-in via `--council`): stress-test multi-advisor das opções mais promissoras com steel-manning obrigatório e concession tracking. **NÃO invocar por padrão** — só quando a flag está presente ou quando surge consenso rápido demais (sinal de false consensus).
 - `ui-ux-pro-max`: use quando o brainstorm envolver frontend, direção de estilo UI, escolhas de design system ou exploração de identidade visual
 - `vercel-react-best-practices`: use quando explorar arquitetura React/Next.js ou trade-offs de performance
 - `security-review`: use quando o brainstorm tocar auth, manipulação de dados ou features sensíveis à segurança

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

@@ -15,6 +15,7 @@
 
     Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte contextual sem substituir este comando:
 
+    - `dw-verify`: **SEMPRE** — em modo Direto, invocada antes do commit da correção. O VERIFICATION REPORT deve mostrar que o sintoma original do bug não se reproduz mais (não apenas que os testes passam).
     - `vercel-react-best-practices`: use quando o bug afeta React/Next.js e há suspeita de problemas de render, hidratação, fetching, waterfall, bundle ou re-render
     - `webapp-testing`: use quando a correção requer fluxo E2E/reteste reproduzível em uma web app
     - `security-review`: use quando a causa raiz toca auth, autorização, input externo, upload, secrets, SQL, XSS, SSRF ou outras superfícies sensíveis
@@ -219,6 +220,14 @@
     - `ajustar` - me diga o que modificar no plano
     ```
 
+    ### 5.5. Verificação Final (Modo Direto — obrigatório antes do commit)
+
+    <critical>Após aplicar as tarefas aprovadas em modo Direto, invocar `dw-verify` antes do commit. O VERIFICATION REPORT deve mostrar:
+    1. O comando de verificação do projeto (test + lint + build) com exit 0.
+    2. Reprodução do sintoma original: o cenário que disparava o bug já NÃO dispara mais.
+    
+    Sem PASS nos dois, NÃO commit. Reportar o que falhou e retomar da etapa 4 (análise de causa raiz).</critical>
+
     ### 6. Gerar Documento Bugfix (Modo Análise)
 
     <critical>

package/scaffold/pt-br/commands/dw-code-review.md

@@ -21,6 +21,8 @@ Normalmente invocado antes de criar PR via `/dw-generate-pr`
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apoio analítico sem substituir este comando:
 
+- `dw-review-rigor`: **SEMPRE** — aplica de-duplication (mesmo pattern em N arquivos = 1 finding), severity ordering (critical → high → medium → low), verify-before-flag, skip-what-linter-catches, e signal-over-volume. A tabela "Problemas Encontrados" do relatório segue essa disciplina.
+- `dw-verify`: **SEMPRE** — invocada antes de emitir verdict `APROVADO` ou `APROVADO COM RESSALVAS`. Sem VERIFICATION REPORT PASS (test + lint + build), o verdict não pode sair como APROVADO.
 - `security-review`: use quando auth, autorização, input externo, upload, SQL, integração externa, secrets, SSRF, XSS ou superfícies sensíveis estiverem presentes
 - `vercel-react-best-practices`: use quando o diff tocar React/Next.js para revisar padrões de renderização, fetching, bundle, hidratação e performance
 
@@ -180,6 +182,22 @@ Verificar:
 
 <critical>O REVIEW NÃO PODE SER APROVADO SE ALGUM TESTE FALHAR</critical>
 
+### 6.5. Aplicar `dw-review-rigor` (Obrigatório)
+
+Antes de escrever a tabela "Problemas Encontrados" do relatório, invocar a skill `dw-review-rigor` e aplicar as cinco regras:
+
+1. **De-duplicação**: se o mesmo padrão aparece em N arquivos, emitir 1 finding com a lista de arquivos afetados — nunca N findings idênticos.
+2. **Severity ordering**: apresentar sempre na ordem critical → high → medium → low (não por arquivo).
+3. **Verify intent before flagging**: checar comentários adjacentes, ADRs em `.dw/spec/*/adrs/`, cobertura de testes, regras em `.dw/rules/`. Não flaggar o que tem justificativa documentada.
+4. **Skip what linter catches**: rodar o linter do projeto primeiro; nada que ele já reporta vira finding.
+5. **Signal over volume**: máximo ~8 findings precisos são mais úteis que 30 marginais. Manter todos os critical/high; podar medium/low para os mais impactantes.
+
+Se houver reviews anteriores em `{{PRD_PATH}}/reviews/` ou `{{PRD_PATH}}/dw-code-review.md` (round anterior), ler e emitir **apenas findings NOVOS** — não re-flaggar itens já tratados.
+
+### 6.6. Verificação Final (Obrigatório antes do verdict)
+
+<critical>Invocar `dw-verify` e incluir o VERIFICATION REPORT no início do relatório. Sem PASS, o verdict só pode ser `REPROVADO` — nunca `APROVADO` ou `APROVADO COM RESSALVAS`.</critical>
+
 ### 7. Gerar Relatório de Code Review (Obrigatório)
 
 Salvar em `{{PRD_PATH}}/dw-code-review.md`:

package/scaffold/pt-br/commands/dw-create-tasks.md

@@ -42,10 +42,22 @@
     - Organizar sequenciamento
     - Incluir testes unitários como subtarefas de cada task
 
+    3.5. **Verificação de Dependências Circulares (Pré-flight)**
+    - Antes de escrever qualquer arquivo, monte o grafo de dependências (campo `blockedBy` ou "Depende de" entre tasks)
+    - Detecte ciclos: se a task A depende de B e B depende (direta ou transitivamente) de A, há ciclo
+    - Se houver ciclo: **NÃO escreva os arquivos**. Apresente o ciclo ao usuário e peça reestruturação (ex: extrair responsabilidade comum, inverter dependência, mesclar tasks)
+    - Se não houver ciclo: prossiga
+
     4. **Gerar Arquivos de Tarefas Individuais**
     - Criar arquivo para cada tarefa principal
     - Detalhar subtarefas e critérios de sucesso
     - Incluir testes unitários obrigatórios
+    - **Enriquecimento codebase-aware (Opcional mas recomendado)**: para tasks que tocam áreas conhecidas do codebase, dispatche um Agent Explore em paralelo (um por task ou um por área) para preencher:
+      - "Arquivos Relevantes": paths e razão pela qual são relevantes para a task
+      - "Arquivos Dependentes": paths que podem precisar mudar em cascata
+      - "Regras Aplicáveis": links para `.dw/rules/*.md` que restringem a task
+      - "ADRs Relacionados": arquivos em `.dw/spec/<prd>/adrs/` que constrangem decisões
+      Esse enriquecimento é aditivo: não bloqueia a geração das tasks, apenas aumenta a qualidade do contexto que a `dw-run-task` recebe depois.
 
     ## Diretrizes de Criação de Tarefas
 

package/scaffold/pt-br/commands/dw-create-techspec.md

@@ -13,10 +13,16 @@
     ## Posição no Pipeline
     **Antecessor:** `/dw-create-prd` | **Sucessor:** `/dw-create-tasks`
 
+    ## Flags
+
+    - **(padrão)**: gera techspec normal a partir do PRD
+    - **`--council`**: antes de finalizar o techspec, invoca a skill `dw-council` sobre a decisão arquitetural principal (ex: monólito vs microserviços, SQL vs NoSQL, lib X vs Y). O output do council vira uma seção "Debate Arquitetural" no techspec, e decisões firmes viram ADR via `/dw-adr`. Útil quando o techspec introduz uma escolha estrutural de alto impacto.
+
     ## Skills Complementares
 
     Quando disponíveis no projeto em `./.agents/skills/`, use como apoio:
 
+    - `dw-council` (opt-in via `--council`): debate multi-advisor da decisão arquitetural principal com steel-manning. **NÃO invocar por padrão**.
     - `vercel-react-best-practices`: use quando definir arquitetura frontend para projetos React/Next.js
     - `ui-ux-pro-max`: use quando definir decisões de design system, paletas de cores, tipografia e estilo UI no TechSpec
     - `security-review`: use quando a feature tocar auth, autorização ou manipulação de dados sensíveis
@@ -94,6 +100,8 @@
     - Revisar padrões do projeto em `{{RULES_PATH}}`
     - Confirmar que o PRD existe em `{{PRD_PATH}}` ou `.dw/spec/prd-[nome-funcionalidade]/prd.md`
 
+    <critical>Hard gate: se o PRD tiver seção "Questões em Aberto" / "Open Questions" com itens não resolvidos, PARAR. Apresentar as questões ao usuário e pedir que sejam resolvidas antes de escrever o techspec. Um techspec construído sobre requisitos indefinidos gera retrabalho garantido.</critical>
+
     ## Fluxo de Trabalho
 
     ### 1. Analisar PRD (Obrigatório)

package/scaffold/pt-br/commands/dw-fix-qa.md

@@ -17,6 +17,7 @@ Você é um assistente IA especializado em correção de bugs pós-QA com retest
 
 Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte operacional sem substituir este comando:
 
+- `dw-verify`: **SEMPRE** — invocada antes de marcar qualquer bug como `Corrigido` ou `Fechado` no `QA/bugs.md`. Sem VERIFICATION REPORT PASS (test + lint + build) + evidência de reteste, o status permanece `Reaberto` ou `Em análise`.
 - `webapp-testing`: suporte para estruturar retestes, capturas e scripts quando complementar ao Playwright MCP
 - `vercel-react-best-practices`: use apenas se a correção afetar frontend React/Next.js e houver risco de regressão de renderização, hidratação, fetching ou performance
 
@@ -88,6 +89,10 @@ Para cada bug corrigido:
 7. Registrar no relatório de QA qual usuário/perfil foi usado no reteste
 8. Se o reteste exigir auth persistente, inspeção além do MCP, ou reprodução mais fiel em navegador real, registrar no relatório
 
+### 3.5. Verificação Final Antes de Atualizar Status
+
+<critical>Invocar a skill `dw-verify` antes de mudar o status de qualquer bug para `Corrigido` ou `Fechado`. O VERIFICATION REPORT (test + lint + build) deve ser PASS **e** a evidência de reteste do Playwright deve estar salva. Sem os dois, o status não muda.</critical>
+
 ### 4. Atualização de Artefatos
 
 Atualizar `QA/bugs.md` para cada bug:

package/scaffold/pt-br/commands/dw-generate-pr.md

@@ -9,6 +9,14 @@
     ## Posição no Pipeline
     **Antecessor:** `/dw-code-review` ou `/dw-commit` | **Sucessor:** (merge)
 
+    ## Skills Complementares
+
+    | Skill | Gatilho |
+    |-------|---------|
+    | `dw-verify` | **SEMPRE** — invocada antes do `git push`. Sem VERIFICATION REPORT PASS na sessão após a última edição de código, o PR **NÃO** pode ser criado. |
+
+    <critical>Hard gate: se a sessão atual não tem um VERIFICATION REPORT PASS de `dw-verify` produzido APÓS a última edição/commit, PARAR e invocar `dw-verify` antes de prosseguir. PR é um artefato permanente — exige o maior rigor de verificação.</critical>
+
     ## Uso
 
     ```

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

@@ -11,7 +11,26 @@ Você é um assistente de ajuda do workspace. Quando invocado, apresente ao usu
 ## Comportamento
 
 - Se invocado sem argumentos (`/dw-help`): mostre o guia completo abaixo
-- Se invocado com argumento (`/dw-help dw-create-prd`): mostre apenas a seção detalhada daquele comando
+- Se invocado com argumento correspondente a um comando (`/dw-help dw-create-prd`): mostre apenas a seção detalhada daquele comando
+- Se invocado com **keyword que não é nome de comando** (`/dw-help bug`, `/dw-help review`, `/dw-help design`): faça lookup contextual — identifique o(s) comando(s) mais relevante(s) pela keyword e apresente cada um com 1-2 linhas de justificativa ("para bug, use `/dw-bugfix` porque..."). Use a tabela de mapeamento abaixo.
+
+### Mapeamento contextual (keyword → comando sugerido)
+
+| Keyword(s) | Comando sugerido | Justificativa |
+|------------|------------------|---------------|
+| bug, erro, falha, problema | `/dw-bugfix` | Triagem automática bug vs feature + correção |
+| review, revisão, qualidade | `/dw-code-review` | Review formal Nível 3 com relatório |
+| qa, teste visual, playwright | `/dw-run-qa` | QA E2E com browser automation |
+| refactor, smell, fowler | `/dw-refactoring-analysis` | Auditoria de code smells priorizada |
+| design, ui, redesign | `/dw-redesign-ui` | Auditoria + propostas + implementação visual |
+| decisão, adr, arquitetura | `/dw-adr` | Registrar Architecture Decision Record |
+| debate, council, stress-test, opiniões | `/dw-brainstorm --council` ou `/dw-create-techspec --council` | Invoca `dw-council` para debate multi-advisor |
+| reverter, rollback de task | `/dw-revert-task` | Revert seguro com check de dependências |
+| hotfix, mudança rápida | `/dw-quick` | Task pontual com garantias sem PRD |
+| retomar, onde parei | `/dw-resume` | Restaura contexto da sessão anterior |
+| pesquisa, research | `/dw-deep-research` | Pesquisa multi-fonte com citações |
+| ideia, brainstorm | `/dw-brainstorm` | Ideação estruturada com trade-offs |
+| atualizar dev-workflow | `/dw-update` | Atualiza para versão npm mais recente |
 
 ---
 
@@ -123,13 +142,33 @@ Este workspace utiliza um sistema de comandos AI que automatiza o ciclo completo
 |---------|-----------|-------|--------|
 | `/dw-commit` | Commit semântico (Conventional Commits) | - | Commit |
 | `/dw-generate-pr` | Push + cria PR + copia body + abre URL | Branch alvo | PR no GitHub |
+| `/dw-revert-task` | Reverte com segurança os commits de uma task específica (check de dependências + confirmação) | Path do PRD + número da task | Commits revertidos + `tasks.md` atualizado |
+
+### Decisões Arquiteturais
+
+| Comando | O que faz | Input | Output |
+|---------|-----------|-------|--------|
+| `/dw-adr` | Registra um Architecture Decision Record (ADR) para decisão não-trivial durante o PRD | Path do PRD + título | `.dw/spec/<prd>/adrs/adr-NNN.md` + cross-refs atualizadas |
 
 ### Utilitários
 
 | Comando | O que faz | Input | Output |
 |---------|-----------|-------|--------|
-| `/dw-help` | Este guia de comandos | (opcional) comando | Este documento |
-| `/dw-update` | Atualiza o dev-workflow para a versão mais recente no npm sem sair do agente | (nenhum) | Arquivos gerenciados atualizados |
+| `/dw-help` | Este guia de comandos (suporta lookup por keyword: `/dw-help bug`) | (opcional) comando ou keyword | Este documento ou seção filtrada |
+| `/dw-update` | Atualiza o dev-workflow para a versão mais recente no npm sem sair do agente (suporta `--rollback`) | (nenhum) ou `--rollback` | Arquivos gerenciados atualizados ou restaurados |
+
+### Bundled Skills (invocadas internamente — não são commands)
+
+Skills em `.agents/skills/` que os commands acima invocam transparentemente. Você não as chama diretamente.
+
+| Skill | Invocada por | Papel |
+|-------|--------------|-------|
+| `dw-verify` | run-task, run-plan, fix-qa, bugfix, code-review, generate-pr, quick | Iron Law: nenhuma claim de sucesso sem VERIFICATION REPORT PASS |
+| `dw-memory` | run-task, run-plan, autopilot, resume, revert-task | Memory de workflow em dois níveis (shared + task-local) com promotion test |
+| `dw-review-rigor` | code-review, review-implementation, refactoring-analysis | De-duplication, severity ordering, verify-intent-before-flag, signal-over-volume |
+| `dw-council` | brainstorm `--council`, create-techspec `--council` | Debate multi-advisor (3-5 archetypes) com steel-manning, concession tracking e synthesis que preserva dissent. Opt-in. |
+
+Inspiradas em skills do projeto [Compozy](https://github.com/compozy/compozy) (`cy-final-verify`, `cy-workflow-memory`, `cy-review-round`).
 
 ## Fluxos Comuns