@brunosps00/dev-workflow 0.9.0 → 0.11.0

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

@@ -50,6 +50,22 @@
     - Use `.dw/rules/` como contexto, caindo para grep
     - Sugira rodar `/dw-map-codebase` para enriquecer contexto downstream
 
+    ## Constitution Gate
+
+    <critical>ANTES das clarification questions, cheque `.dw/constitution.md`:
+
+    **Se AUSENTE**: copie `templates/constitution-template.md` (project-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled) literalmente para `.dw/constitution.md`. Setar frontmatter `mode: defaults` e `last_updated` para data ISO de hoje. Imprimir no chat:
+
+    > "Notei que `.dw/constitution.md` estava ausente. Instalei defaults em `.dw/constitution.md` (10 princípios canônicos, todos em `severity: info` — reportam mas não bloqueiam). Pode customizar a qualquer momento — ou re-rodar `/dw-analyze-project` para versão sob medida. Seguindo com o PRD."
+
+    Depois prossiga normalmente, tratando o arquivo recém-criado como a constitution.
+
+    **Se PRESENTE**: leia antes de redigir requisitos. Cada FR no PRD DEVE incluir linha "Constitution Alignment" mapeando para ≥1 princípio relevante (`Respects: P-001, P-009`) OU declarando explicitamente "no applicable principle" com motivo em uma linha. Sem alignment = FR está incompleto.
+
+    **Regras de severity** (aplicadas pelos comandos downstream, não enforçadas aqui):
+    - Violações `severity: info` → reportadas, nunca bloqueiam.
+    - Violações `severity: high` / `critical` → bloqueiam em `dw-create-techspec` e `dw-code-review` exceto se ADR justificar.</critical>
+
     ## Features Multi-Projeto
 
     Muitas funcionalidades podem envolver mais de um projeto no workspace.

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

@@ -149,5 +149,47 @@
     3. /dw-generate-pr [branch-alvo] quando todas tasks concluídas
     ```
 
+    ## Final Consistency Check (Auto-invocado antes da aprovação do usuário)
+
+    <critical>ANTES de apresentar tasks ao usuário, rode um check de consistência em 5 dimensões. Isto é mandatório; não pule mesmo se confiante de que as tasks estão limpas.</critical>
+
+    Rode estes 5 checks contra o conjunto PRD + TechSpec + tasks gerado:
+
+    1. **Cobertura de RF** — cada RF numerada no PRD mapeia para ≥1 task. RFs órfãs (PRD tem; nenhuma task cobre) são FAIL.
+    2. **Grounding das tasks** — cada task gerada referencia ≥1 RF em seu corpo (`Cobre: RF-N.M`). Tasks sem referência a RF sinalizam scope creep.
+    3. **Cobertura de teste** — cada RF com comportamento user-facing (UI, endpoint de API, mutação de dado) tem ≥1 task que adiciona teste (subtask contendo "test", "spec", "e2e" ou equivalente).
+    4. **Grafo de dependências** — dependências entre tasks (X.0 → Y.0 declarado como "Depende de") formam DAG. Sem ciclos. Ordem topológica válida.
+    5. **Alinhamento com constitution** (só se `.dw/constitution.md` existir) — cada task lista `Constitution: respects P-NNN, P-MMM` OU `Constitution: deviates P-NNN — ADR planejado: <slug>` OU `Constitution: n/a — motivo: <one-liner>`. Linha ausente = FAIL.
+
+    Escreva findings em `.dw/spec/prd-[nome-funcionalidade]/tasks-validation.md` com esta estrutura exata:
+
+    ```markdown
+    # Relatório de Validação de Tasks
+
+    Gerado por /dw-create-tasks em YYYY-MM-DD.
+
+    | Dimensão | Status | Findings |
+    |----------|--------|----------|
+    | 1. Cobertura de RF | PASS / FAIL | <lista de RFs órfãs ou "todas RFs cobertas"> |
+    | 2. Grounding de tasks | PASS / FAIL | <lista de tasks sem RF ou "todas tasks referenciam RFs"> |
+    | 3. Cobertura de teste | PASS / FAIL | <RFs sem testes ou "todas RFs user-facing cobertas"> |
+    | 4. Grafo de dependências | PASS / FAIL | <ciclos ou "DAG válido"> |
+    | 5. Alinhamento constitution | PASS / FAIL / N/A | <tasks não-alinhadas ou "todas alinhadas" ou "sem constitution"> |
+
+    ## Findings Detalhados
+
+    <uma seção por dimensão FAIL com fixes concretos; vazio se tudo PASS>
+    ```
+
+    **Comportamento do gate:**
+
+    - **Todas as 5 dimensões PASS (ou N/A)** → apresente tasks ao usuário normalmente e peça aprovação.
+    - **Qualquer dimensão FAIL** → PARE. Mostre a tabela no chat como markdown (NÃO esconda no arquivo de validação; o usuário precisa ver antes de aprovar). Depois pergunte ao usuário:
+      - "(a) Quer que eu conserte as tasks automaticamente?" → regenerar tasks afetadas, re-rodar o check.
+      - "(b) Vai editar tasks.md manualmente?" → aguardar usuário sinalizar conclusão, re-rodar o check.
+      - "(c) Override e seguir mesmo com FAIL?" → exigir mensagem de override explícita ("override: aceito o gap porque <motivo>"). Persistir o override em `tasks-validation.md` para auditabilidade.
+
+    O arquivo `tasks-validation.md` é commitado junto com `tasks.md`. Comandos downstream (`/dw-run-plan`, `/dw-code-review`, `/dw-review-implementation`) podem referenciá-lo.
+
     Após completar a análise e gerar todos os arquivos necessários, apresente os resultados ao usuário e aguarde confirmação para prosseguir com a implementação.
 </system_instructions>

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

@@ -23,6 +23,7 @@
     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**.
+    - `dw-source-grounding` (**SEMPRE**): cada decisão de framework/library segue Detect → Fetch → Implement → Cite. O techspec emite citações inline `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` ao lado de cada decisão arquitetural.
     - `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
@@ -32,11 +33,29 @@
     <critical>Se `.dw/intel/` existir, a consulta via `/dw-intel` é OBRIGATÓRIA antes de redigir o techspec. NÃO pule este passo.</critical>
     - Execute internamente: `/dw-intel "padrões arquiteturais e decisões técnicas do projeto"`
     - Alinhe propostas com padrões existentes; sinalize desvios explicitamente
+    - Quando o techspec define endpoints de API, consulte TAMBÉM `dw-codebase-intel/references/api-design-discipline.md` (Hyrum's Law, contract-first, error semantics, boundary validation, versionamento) — o novo endpoint deve seguir convenções já presentes em `apis.json`, e não impor "best practices" externas que conflitem com os padrões existentes.
 
     Se `.dw/intel/` NÃO existir:
     - Use `.dw/rules/` como contexto, caindo para grep
     - Sugira rodar `/dw-map-codebase` para enriquecer contexto downstream
 
+    ## Constitution Gate
+
+    <critical>ANTES de redigir decisões arquiteturais, cheque `.dw/constitution.md`:
+
+    **Se AUSENTE**: copie `templates/constitution-template.md` (project-local em `.dw/templates/constitution-template.md`, com fallback para scaffold bundled) literalmente para `.dw/constitution.md`. Setar frontmatter `mode: defaults`. Imprimir no chat: "Constituição defaults instalada em `.dw/constitution.md` (severity: info — não bloqueia este techspec). Seguindo." Depois prossiga.
+
+    **Se PRESENTE**: leia. Toda escolha de framework / library / arquitetura no techspec DEVE carregar uma de:
+    - `Respects: P-NNN` — a decisão honra ativamente o(s) princípio(s) nomeado(s).
+    - `Deviates: P-NNN — justification: <slug do ADR ou racional em uma linha>` — a decisão se afasta intencionalmente do princípio.
+
+    **Gate graduado por severity:**
+    - Desvio de princípio `severity: info` → apenas registra, nunca bloqueia.
+    - Desvio de princípio `severity: high` sem ADR linkado (`.dw/spec/<prd>/adrs/adr-NNN.md`) → BLOQUEIA o techspec. Instrua o usuário a revisar a decisão OU criar ADR via `/dw-adr` documentando o trade-off.
+    - Desvio de princípio `severity: critical` → BLOQUEIA o techspec com mesma exigência de ADR, adicionalmente exigindo acknowledgment de reviewer no campo `Approved by` do ADR.
+
+    Sem exceções para `high`/`critical` sem ADR. Se o usuário resistir, aponte para `/dw-adr` — esse é o escape hatch por design.</critical>
+
     ## Fluxograma de Decisão Multi-Projeto
 
     ```dot

package/scaffold/pt-br/commands/dw-deep-research.md

@@ -5,6 +5,12 @@ Você é um assistente de pesquisa avançada capaz de conduzir investigações p
 <critical>NUNCA fabrique citações - se não encontrar fonte, diga explicitamente</critical>
 <critical>A bibliografia DEVE conter TODAS as citações usadas no corpo do relatório, sem abreviações ou ranges</critical>
 
+## Skills Complementares
+
+| Skill | Gatilho |
+|-------|---------|
+| `dw-source-grounding` | **SEMPRE** — aplica o protocolo Detect → Fetch → Implement → Cite com hierarquia estrita de fontes (docs oficiais versionadas > changelogs > web standards > compat tables; Stack Overflow / blogs / training data são só descoberta). Cada finding termina com `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`; a bibliografia e construida a partir dessas citacoes. |
+
 ## Quando Usar
 - Use para análise abrangente multi-fonte, comparações de tecnologia ou revisões do estado da arte que exigem evidências citadas
 - NÃO use para buscas simples, debugging ou perguntas que podem ser respondidas com 1-2 buscas

package/scaffold/pt-br/commands/dw-deps-audit.md

@@ -29,6 +29,7 @@ Este comando e **distinto** do `/dw-security-check`:
 | `dw-verify` | **SEMPRE** — toda fase emite VERIFICATION REPORT (comandos rodados, exit codes, artefatos) antes da proxima fase comecar |
 | `dw-review-rigor` | **SEMPRE** — aplica deduplicacao (mesmo advisory em N pacotes = 1 finding com lista afetada), severity ordering, e signal-over-volume na lista OUTDATED-MINOR |
 | `security-review` (`references/supply-chain.md`) | **SEMPRE** ao classificar findings — da o framing OWASP A06 (Vulnerable & Outdated Components) para os trade-offs do brainstorm |
+| `dw-source-grounding` | **SEMPRE** na fase de brainstorm — cada opcao de update por pacote (Conservadora/Balanceada/Ousada) cita o changelog/release notes oficial da versao alvo: `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]`. Previne "agent recomenda v5 porque parece moderno, mas v5 dropou Node 18". |
 | `dw-council` | Opt-in automatico quando >=3 pacotes caem em tier COMPROMISED — stress-test multi-conselheiro sobre ordem e escopo de remediacao |
 | `webapp-testing` | Opcional — quando o projeto e frontend e a fase de testes escopados precisa de selecao Playwright-aware |
 

package/scaffold/pt-br/commands/dw-find-skills.md

@@ -15,7 +15,7 @@ Voce e um assistente de descoberta de skills neste workspace. Sua funcao e ajuda
 
 ## Posicao no Pipeline
 
-**Predecessor:** qualquer pergunta exploratoria | **Sucessor:** nenhum (fluxo independente). Se nao achar skill, caia para `/dw-brainstorm` (explorar ideias) ou `/dw-quick` (mudanca pequena one-off) quando aplicavel.
+**Predecessor:** qualquer pergunta exploratoria | **Sucessor:** nenhum (fluxo independente). Se nao achar skill, caia para `/dw-brainstorm` (explorar ideias) ou `/dw-run-task` (mudanca pequena one-off) quando aplicavel.
 
 ## Skills Complementares
 
@@ -81,7 +81,7 @@ Catalogo: https://skills.sh/
    - Reconheca que nao houve match, sem inventar
    - Ofereca ajudar direto com capacidades gerais
    - Sugira `/dw-brainstorm` se o usuario quer explorar antes de construir
-   - Sugira `/dw-quick` se cabe em uma mudanca pequena (<= 3 arquivos, sem PRD)
+   - Sugira `/dw-run-task` se cabe em uma mudanca pequena (<= 3 arquivos, sem PRD)
    - Mencione `npx skills init <nome>` como caminho para criar a skill que falta
 
 ## Categorias Comuns
@@ -128,7 +128,7 @@ Pesquisei skills sobre "<query>" e nao achei match forte
 
 Posso ajudar direto. Ou:
   /dw-brainstorm "<sua ideia>"     — explorar abordagens antes
-  /dw-quick "<mudanca pequena>"    — se cabe em uma task curta
+  /dw-run-task "<mudanca pequena>" — se cabe em uma task curta (escreva PRD curto antes)
   npx skills init <nome>           — criar voce mesmo se vale a pena reutilizar
 ```
 
@@ -150,7 +150,7 @@ Posso ajudar direto. Ou:
 `dw-find-skills` porta a skill `find-skills` (do bundle superpowers do Claude, `~/.agents/skills/find-skills/SKILL.md`) para um comando do workflow `dw-*` — assim toda plataforma suportada (Claude Code, Codex, Copilot, OpenCode) ganha a mesma porta de descoberta. Adaptacoes para o dev-workflow:
 
 - Integracao com o pipeline: `/dw-help <keyword>` roteia para ca quando bate em `skill`/`find skill`/`install skill`/`extend agent`.
-- Fallback para `/dw-brainstorm` ou `/dw-quick` quando nao acha skill — mantem o usuario dentro do workflow ao inves de despeja-lo de maos vazias.
+- Fallback para `/dw-brainstorm` ou `/dw-run-task` quando nao acha skill — mantem o usuario dentro do workflow ao inves de despeja-lo de maos vazias.
 - Pergunta explicita de escopo (`-g` vs local) antes de instalar, em vez de assumir global.
 
 Credito: skill `find-skills` do ecossistema superpowers do Claude e o projeto `npx skills` / [skills.sh](https://skills.sh/).

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

@@ -18,6 +18,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-debug-protocol`: **SEMPRE** — todo finding bug-shaped (cenário falhando, não feature ausente) passa pelo six-step triage. A evidência de reteste é o artefato da etapa 6 (verify); o regression test da etapa 5 é o que sustenta o status `Corrigido`.
 - `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 (screenshot em modo UI OU linha JSONL em modo API), o status permanece `Reaberto` ou `Em análise`.
 - `webapp-testing`: (modo UI) suporte para estruturar retestes, capturas e scripts quando complementar ao Playwright MCP
 - `vercel-react-best-practices`: (modo UI) 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

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

@@ -14,6 +14,7 @@
     | 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. |
+    | `dw-git-discipline` | **SEMPRE** — valida naming de branch (`<tipo>/<escopo>` kebab-case), histórico atomic-commit (cada commit single-intent, mensagem conventional), tempo de vida da branch (flag se >7 dias) e escopo da PR (sugere split se diff > ~400 linhas). Descrição da PR segue summary + test plan, não dump de `git log`. |
     | `/dw-security-check` | **SEMPRE para projetos TS/Python/C#/Rust** — `security-check.md` com status ≠ REJECTED é obrigatório para projetos em linguagem suportada. |
 
     <critical>Hard gate 1 (verify): 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>

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

@@ -23,20 +23,14 @@ Você é um assistente de ajuda do workspace. Quando invocado, apresente ao usu
 | 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 |
 | security, segurança, vulnerabilidade, owasp, trivy, cve | `/dw-security-check` | Check multi-camada rígido (OWASP estático + Trivy SCA/IaC + audit nativo) para TS/Python/C#/Rust |
 | supply chain, outdated, comprometido, pacote malicioso, atualizar deps, npm audit, pip-audit | `/dw-deps-audit` | Detecta + classifica + plano de update por pacote com QA escopada. Vai além do `/dw-security-check` adicionando remediação. |
 | skill, achar skill, instalar skill, ecossistema, capacidade, estender agente | `/dw-find-skills` | Descobre skills no skills.sh / `npx skills` e instala global ou local |
 | projeto novo, scaffold, bootstrap, comecar, iniciar projeto, fullstack, monorepo | `/dw-new-project` | Entrevista de stack + tools create-* + docker-compose para dev. Roda apos `npx dev-workflow init`. |
 | dockerize, docker, dockerfile, compose, container, imagem prod, multi-stage | `/dw-dockerize` | Le projeto existente, brainstorm de base, gera Dockerfile + docker-compose para dev/prod/ambos, ou audita artefatos existentes. |
-| mapear codebase, indice intel, code map, knowledge graph, indice queryable | `/dw-map-codebase` | Constroi .dw/intel/ (stack/files/apis/deps/arch) para /dw-intel e outros comandos pararem de re-explorar o codebase. |
-| executar fase, tasks paralelas, wave, dispatch, commits atomicos | `/dw-execute-phase` | Roda uma fase de PRD em waves com commits atomicos por task, deviation handling e gate hard de plan-checker antes de tocar codigo. |
-| plan check, verificar plano, validacao de plano, goal backward | `/dw-plan-checker` | Verificacao goal-backward de tasks.md antes da execucao. PASS / REVISE / BLOCK em 6 dimensoes. |
 | refinamento, refine, idea, one-pager, ideia | `/dw-brainstorm --onepager` | Refinamento de ideia com Product Inventory + classification (IMPROVES/CONSOLIDATES/NEW) + one-pager durável |
 | 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 |
@@ -117,9 +111,6 @@ Este workspace utiliza um sistema de comandos AI que automatiza o ciclo completo
 | `/dw-bugfix` | Analisa e corrige bugs (triagem bug vs feature) | Target + descrição | Fix + commit OU PRD (se feature) |
 | `/dw-fix-qa` | Corrige bugs documentados no QA e retesta com evidências | Path do PRD | Código + `QA/bugs.md` + `QA/qa-report.md` atualizados |
 | `/dw-redesign-ui` | Audita, propõe e implementa redesign visual de páginas/componentes | Página/componente alvo | Brief de redesign + código |
-| `/dw-quick` | Executa task pontual com garantias do workflow sem PRD | Descrição da mudança | Código + commit |
-| `/dw-resume` | Restaura contexto da sessão e sugere próximo passo | (nenhum) | Resumo + sugestão |
-| `/dw-intel` | Consulta inteligência do codebase sobre padrões e arquitetura | Pergunta | Resposta com fontes |
 | `/dw-autopilot` | Orquestrador completo: de um desejo até o PR com mínima intervenção | Descrição do desejo | PRD + código + commits + PR |
 
 ### Análise e Pesquisa
@@ -154,11 +145,15 @@ Este workspace utiliza um sistema de comandos AI que automatiza o ciclo completo
 | `/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
+### Comandos internos (usados por outros dw-* commands; raramente invocados direto)
 
-| 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 |
+| Comando | O que faz | Tipicamente invocado por |
+|---------|-----------|--------------------------|
+| `/dw-adr` | Registra Architecture Decision Record durante execução do PRD | `/dw-create-techspec`, `/dw-run-task` quando surge decisão não-trivial |
+| `/dw-intel` | Consulta o índice do codebase em `.dw/intel/` | `/dw-create-prd`, `/dw-create-techspec`, `/dw-code-review` etc. |
+| `/dw-map-codebase` | Constroi/refresca o índice queryable em `.dw/intel/` | `/dw-analyze-project` (auto-roda após geração de rules) |
+
+Esses ficam expostos como slash commands para uso manual ocasional (ex.: registrar ADR rapidamente mid-sessão, consultas ad-hoc no codebase) mas a maioria dos usuários nunca invoca direto — eles são chamados pelos comandos high-level acima.
 
 ### Utilitários
 
@@ -245,16 +240,6 @@ Inspiradas em skills do projeto [Compozy](https://github.com/compozy/compozy) (`
 /dw-autopilot "descrição do que quer construir"    # Pesquisa → PRD → Tasks → Código → QA → PR
 ```
 
-### Task Rápida
-```bash
-/dw-quick "descrição da mudança"                   # Implementa + valida + commit
-```
-
-### Retomar Sessão
-```bash
-/dw-resume                                         # Restaura contexto + sugere próximo passo
-```
-
 ### Consultar Codebase
 ```bash
 /dw-intel "como funciona X neste projeto?"         # Resposta com fontes
@@ -287,9 +272,7 @@ workspace/
 │   │   ├── dw-review-implementation.md
 │   │   ├── dw-deep-research.md
 │   │   ├── dw-intel.md
-│   │   ├── dw-quick.md
 │   │   ├── dw-redesign-ui.md
-│   │   ├── dw-resume.md
 │   │   ├── dw-bugfix.md
 │   │   ├── dw-fix-qa.md
 │   │   ├── dw-commit.md
@@ -339,10 +322,7 @@ workspace/
 - Sim. O comando é framework-agnostic. Para React usa react-doctor e `vercel-react-best-practices`; para Angular usa `ng lint` e Angular DevTools. Design visual (`ui-ux-pro-max`) funciona com qualquer framework.
 
 **Q: Como obtenho inteligência do codebase e execução paralela?**
-- Os dois são nativos do dev-workflow desde a v0.9.0. Rode `/dw-map-codebase` para construir o índice queryable em `.dw/intel/`, depois `/dw-intel "<pergunta>"` para consultá-lo. Para execução paralela, `/dw-execute-phase` dispatcha tasks em waves com commits atômicos por task. Sem dependência externa.
-
-**Q: O `/dw-quick` substitui o `/dw-run-task`?**
-- Não. `/dw-quick` é para mudanças pontuais sem PRD. `/dw-run-task` executa tasks de um plano estruturado com PRD e TechSpec.
+- Os dois são nativos do dev-workflow. Rode `/dw-map-codebase` para construir o índice queryable em `.dw/intel/`, depois `/dw-intel "<pergunta>"` para consultá-lo. Para execução paralela, `/dw-run-plan` invoca os agentes bundled de execução de fase (executor + plan-checker) diretamente para dispatcha tasks em waves com commits atômicos por task. Sem dependência externa.
 
 **Q: O `/dw-autopilot` substitui todos os outros comandos?**
 - Não. Ele orquestra os comandos existentes em sequência. Você ainda pode usar cada comando individualmente para controle manual. O autopilot é para quando quer ir do desejo ao PR com mínima intervenção.

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

@@ -10,7 +10,7 @@ Voce e um assistente de inteligencia do codebase. Este comando responde pergunta
 - Use para entender como algo funciona no projeto (fluxo de auth, modelo de dados, superficie de rotas)
 - Use para encontrar padroes, convencoes ou decisoes arquiteturais
 - Use para verificar se algo ja existe antes de implementar
-- NAO use para implementar mudancas (use `/dw-quick` ou `/dw-run-task`)
+- NAO use para implementar mudancas (use `/dw-run-task`)
 
 ## Posicao no Pipeline
 

package/scaffold/pt-br/commands/dw-refactoring-analysis.md

@@ -21,8 +21,9 @@ Pré-requisito: Execute `/dw-analyze-project` primeiro para entender padrões e
 Quando disponíveis no projeto em `./.agents/skills/`, use como suporte analítico sem substituir este comando:
 
 - `dw-review-rigor`: **SEMPRE** — ao catalogar code smells, aplicar de-duplication (mesmo smell em N arquivos = 1 entrada com affected list), severity ordering nos P0-P3, signal-over-volume (máx ~20 findings; manter críticos, podar marginais). Smell com ADR justificatório baixa para `low` no máximo.
+- `dw-simplification`: **SEMPRE** — todo smell flagueado passa pelo filtro Chesterton's Fence (o que o construto FAZ, por que foi adicionado, o que quebra se removido). Smells sem resposta clara para "por que isso está aqui" caem para `info` com nota de investigação, em vez de virarem proposta de refactor. Métricas de complexidade fundamentam severidade (complexidade cognitiva ≥16 ou nesting depth ≥4 = candidato `high`; <10 = `low` no máximo).
 - `security-review`: delegue preocupações de segurança para este skill — não duplique
-- `vercel-react-best-practices`: delegue padrões de performance React/Next.js para este skill
+- `vercel-react-best-practices`: delegue padrões de performance React/Next.js para este skill — ao sinalizar smells de perf, siga `references/perf-discipline.md` (measure → identify → fix → verify → guard) e cite a métrica + ferramenta, não vibes
 
 ## Ferramentas de Análise
 

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

@@ -313,6 +313,25 @@
 
     <critical>NÃO APROVE requisitos sem evidência concreta no código</critical>
     <critical>ANALISE o código real, não confie apenas nos checkboxes do tasks.md</critical>
-    <critical>Se 100% dos requisitos foram implementados e NÃO há gaps: NÃO entre em plan mode, NÃO crie tasks. Apenas apresente o relatório e ENCERRE.</critical>
-    <critical>Se gaps forem encontrados, entre no loop de fix-review automaticamente. NÃO aguarde instruções do usuário para corrigir gaps. Máximo de 3 ciclos antes de marcar como BLOCKED.</critical>
+    <critical>Se 100% dos requisitos foram implementados e NÃO há gaps: NÃO entre em plan mode, NÃO crie tasks. Apresente o relatório Level 2 e siga para Level 3 (próxima seção).</critical>
+    <critical>Se gaps forem encontrados, entre no loop de fix-review automaticamente. NÃO aguarde instruções do usuário para corrigir gaps. Máximo de 3 ciclos antes de marcar como BLOCKED. Level 3 só roda após o loop chegar em APPROVED no Level 2.</critical>
+
+## Level 3 — Camada de Qualidade (auto-invocada no fim)
+
+Após Level 2 (cobertura do PRD) chegar em APPROVED, **invoque automaticamente `/dw-code-review`** para adicionar a camada formal de qualidade (best practices, SOLID, DRY, complexity, security, convenções). Resolve a expectativa do usuário de que um review único cubra tanto "entregamos tudo?" (Level 2) quanto "o que entregamos está bem feito?" (Level 3).
+
+Pipeline:
+
+1. Após Level 2 APPROVED, rode `/dw-code-review {{PRD_PATH}}` com o mesmo escopo de PRD.
+2. Aguarde `/dw-code-review` produzir veredito (APPROVED / APPROVED WITH CAVEATS / REJECTED).
+3. Escreva resumo consolidado em `{{PRD_PATH}}/QA/review-consolidated.md` referenciando ambos.
+4. Status final combina os dois vereditos:
+   - Level 2 APPROVED + Level 3 APPROVED → consolidado APPROVED
+   - Level 2 APPROVED + Level 3 APPROVED WITH CAVEATS → consolidado APPROVED WITH CAVEATS
+   - Level 2 APPROVED + Level 3 REJECTED → consolidado REJECTED (Level 3 vence)
+
+### Flag para pular Level 3
+
+`/dw-review-implementation --no-code-review` pula Level 3 e emite só Level 2.
+
 </system_instructions>

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

@@ -158,7 +158,7 @@ Se uma tarefa FALHAR durante a execução:
 
 ### Verificação de Plano (Pré-Execução)
 
-Antes de iniciar execução, delegue para `/dw-plan-checker {{PRD_PATH}}`:
+Antes de iniciar execução, spawne o **agente plan-checker** de `.agents/skills/dw-execute-phase/agents/plan-checker.md`:
 - O agente plan-checker verifica as 6 dimensões (cobertura de requisitos, completude da task, soundness de dependência, wiring de artefatos, budget de contexto, compliance de constraints)
 - Se REVISE: apresente os issues e sugira correções. Máximo 3 ciclos via `/dw-create-tasks --revise`
 - Se BLOCK: suba o conflito para o usuário, NÃO auto-replan
@@ -166,7 +166,7 @@ Antes de iniciar execução, delegue para `/dw-plan-checker {{PRD_PATH}}`:
 
 ### Execução Paralela (Wave-Based)
 
-Após PASS do plan-checker, delegue para `/dw-execute-phase {{PRD_PATH}}`:
+Após PASS do plan-checker, spawne o **agente executor** de `.agents/skills/dw-execute-phase/agents/executor.md`:
 - O agente executor analisa o campo `Depends on:` de cada task para montar o grafo de dependências
 - Agrupa tasks em waves:
   - Wave 1: tasks sem dependências (rodam em paralelo)

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

@@ -0,0 +1,111 @@
+---
+schema_version: "1.0"
+generated_by: dev-workflow
+last_updated: YYYY-MM-DD
+mode: defaults | custom
+---
+
+# Constituição do Projeto
+
+> Princípios declarativos que este time escolheu seguir. PRDs, TechSpecs e Code Reviews leem este arquivo como hard gate. Qualquer coisa que viole um princípio com `severity: critical` ou `high` é bloqueada — exceto quando justificada por um ADR explícito.
+
+## Como este arquivo funciona
+
+- **Cada princípio tem um ID (`P-NNN`), severity, regra, `Why` e `Enforcement`.**
+- **Escala de severity:** `info` (apenas reporta, nunca bloqueia) → `high` (bloqueia PR sem ADR) → `critical` (bloqueia PR sem ADR + exige aprovação de reviewer).
+- **Edite à vontade.** Este arquivo é seu para evoluir. Promova princípios de `info` para `high` quando confiar que o projeto cumpre.
+- **Escape via ADR.** Um PR que viola princípio `high`/`critical` é desbloqueado quando um ADR na mesma feature documenta o desvio e o trade-off.
+- **Versão analítica regenerável** a qualquer momento via `/dw-analyze-project` (oferece sintetizar princípios a partir dos padrões observados no código).
+
+---
+
+## Qualidade de Código
+
+**P-001 — Sem `any` / `unknown` em TypeScript sem justificativa** (severity: info)
+**Regra:** Código de produção não pode usar `as any`, `as unknown` ou `// @ts-ignore` sem comentário inline `// @ts-ignore — motivo: <X>` nomeando a restrição.
+**Why:** Escapes silenciosos do tipo vazam bugs de runtime que o type system existia para pegar. Cada escape é um contrato que o type system para de garantir.
+**Enforcement:** `dw-code-review` greppa o diff por `as any`/`@ts-ignore`/`@ts-expect-error` sem comentário-razão correspondente.
+
+**P-002 — Funções devem ser testáveis isoladamente** (severity: info)
+**Regra:** Função que toca rede, filesystem, banco de dados ou system clock deve receber a dependência como parâmetro (ou via factory) em vez de importar diretamente.
+**Why:** Código que constrói suas próprias dependências não pode ser testado sem setup de integração. Testes ficam lentos, são pulados, e bugs vão pra produção.
+**Enforcement:** `dw-code-review` flagueia funções importando `fs`, `axios`, `prisma`, `Date.now`, etc., diretamente em módulos de business logic.
+
+---
+
+## Padrões de Teste
+
+**P-003 — Todo bug fix carrega um regression test** (severity: info)
+**Regra:** Commit com tipo `fix:` deve adicionar ou modificar pelo menos um teste que teria pego o bug antes do fix.
+**Why:** Sem o teste, o bug volta na próxima vez que alguém refatora a área. O fix se deteriora.
+**Enforcement:** `dw-code-review` verifica se commits `fix:` incluem diff em paths `**/*test*` ou `**/*spec*`.
+
+**P-004 — Testes devem ser determinísticos** (severity: info)
+**Regra:** Sem `sleep`-based waits, sem comparações de relógio real, sem chamadas a serviços live em unit tests. Mockar em boundaries.
+**Why:** Testes flaky treinam o time a ignorar falhas. A próxima falha real passa despercebida.
+**Enforcement:** `dw-code-review` greppa testes por `setTimeout`, chamadas reais de fetch/axios, e `Date.now()` sem `vi.useFakeTimers()`/`jest.useFakeTimers()`.
+
+---
+
+## Consistência de UX
+
+**P-005 — Strings user-facing vivem em fonte única** (severity: info)
+**Regra:** Toda copy visível (labels, mensagens de erro, empty states) passa por um módulo centralizado de i18n / strings — não inline em componentes.
+**Why:** Strings inline driftam no tom, quebram esforços de i18n e causam duplicatas da mesma mensagem em variações sutis.
+**Enforcement:** `dw-code-review` flagueia text nodes JSX e mensagens de erro declarados dentro de componentes em vez de importados de `src/strings/`, `src/i18n/`, ou equivalente.
+
+**P-006 — Estados de loading + empty + error são obrigatórios em qualquer UI que busca dados** (severity: info)
+**Regra:** Componente ou página que faz fetch deve renderizar explicitamente loading, empty e error — não só o happy path.
+**Why:** Experiências "só com spinner" e estados de erro silencioso são a #1 fonte de bugs reportados por usuários.
+**Enforcement:** `dw-review-implementation` verifica componentes de data-fetching pelos três estados em JSX ou equivalente.
+
+---
+
+## Performance
+
+**P-007 — Mudanças de performance carregam medição** (severity: info)
+**Regra:** Qualquer commit que afirme melhorar performance deve incluir a métrica, a ferramenta e os números antes/depois no body do commit OU no techspec.
+**Why:** Sem medição, "otimização" de performance é palpite — e geralmente errado (ver `dw-simplification` + `perf-discipline.md`).
+**Enforcement:** `dw-code-review` verifica commits `perf:` por números antes/depois; flagueia se ausente.
+
+**P-008 — Queries N+1 são flagueadas em code review** (severity: info)
+**Regra:** Loops ou operações em lista que disparam chamadas DB/HTTP por item devem batchar (ex: `IN (...)`, `findMany`, DataLoader) ou ser explicitamente justificadas.
+**Why:** Padrões N+1 escalam linearmente com tamanho dos dados e silenciosamente degradam até que a carga de produção revele.
+**Enforcement:** `dw-code-review` e `dw-refactoring-analysis` detectam padrões await-em-loop contra módulos de repository / API client.
+
+---
+
+## Segurança
+
+**P-009 — Authorization server-side em todo endpoint que altera estado** (severity: info)
+**Regra:** Endpoint que cria, atualiza ou deleta dado deve verificar autorização do caller no servidor. Gating em UI (botões escondidos, formulários disabled) não é segurança.
+**Why:** Browsers são untrusted (ver `webapp-testing/security-boundary.md`). Gating em UI é conveniência; só checks server-side protegem dado.
+**Enforcement:** `dw-code-review` e `dw-security-check` exigem check de auth explícito (decorator, middleware ou assertion in-handler) em rotas POST/PUT/PATCH/DELETE.
+
+**P-010 — Secrets nunca entram no repositório** (severity: info)
+**Regra:** Nenhuma API key, password, signing key, token ou endpoint de produção commitado em source. `.env.example` documenta forma apenas.
+**Why:** Histórico de repositório é permanente. Um secret commitado uma vez está vazado mesmo que revertido no commit seguinte.
+**Enforcement:** `dw-security-check` roda Trivy + secret scanners no diff.
+
+---
+
+## Princípios Customizados
+
+> Adicione princípios específicos do seu time abaixo. Mesmo formato: `**P-NNN — <nome>** (severity: info|high|critical): <regra>. **Why:** <motivo>. **Enforcement:** <como>.`
+
+<!-- Exemplo:
+**P-100 — Todo cálculo financeiro usa Decimal, nunca Number** (severity: critical)
+**Regra:** Valores monetários devem usar tipos `Decimal` / `BigDecimal` end-to-end. Sem `parseFloat`, sem aritmética com `Number`.
+**Why:** Erros de arredondamento IEEE 754 acumulam centavos perdidos em milhões de transações; ambientes auditados exigem aritmética exata.
+**Enforcement:** `dw-code-review` greppa por `Number(`/`parseFloat(` em qualquer arquivo sob `src/billing/`, `src/payments/`, `src/finance/`.
+-->
+
+---
+
+## Como evoluir este arquivo
+
+1. **Viva em `info` por pelo menos um release-ciclo.** Observe quão frequentemente cada princípio é violado organicamente; o dado te diz se vale promover.
+2. **Promova para `high` quando violações forem raras e o time concordar.** PRs que violarem princípio `high` agora precisam de ADR.
+3. **Promova para `critical` os princípios que protegem usuários / dados / compliance.** Trate-os como load-bearing; o escape via ADR exige aprovação de reviewer, não só opt-out do autor.
+4. **Demote ou remova princípios que não ganharam seu peso.** Constitution é ferramenta, não museu.
+5. **Re-rode `/dw-analyze-project`** quando o codebase mudar substancialmente (nova stack, refactor grande); ele pode propor updates fundamentados em observação fresca.

package/scaffold/pt-br/templates/idea-onepager.md

@@ -86,5 +86,5 @@ Idealmente 2-4 stories. Se são mais de 5, provavelmente não é MVP.]
 Escolha UM:
 
 - **`/dw-create-prd`** com este one-pager como input — quando a direção está clara mas precisamos detalhar user stories, acceptance criteria e passar ao techspec
-- **`/dw-quick`** — quando é um IMPROVES tão pequeno que cabe em task única (até 3 arquivos, sem novo endpoint/tela)
+- **`/dw-run-task`** — quando é um IMPROVES tão pequeno que cabe em task única (até 3 arquivos, sem novo endpoint/tela) — escreva um PRD curto antes
 - **Parar aqui** — se alguma "Open Question" é bloqueante, parar e resolver com stakeholder antes de avançar

package/scaffold/skills/dw-codebase-intel/SKILL.md

@@ -95,6 +95,7 @@ If no `.dw/intel/` exists at all, `/dw-intel` falls back to `.dw/rules/` (seeded
 - `references/intel-format.md` — schema for each `.dw/intel/` file with examples.
 - `references/incremental-update.md` — how partial updates work (which files to re-read, how to merge with existing entries).
 - `references/query-patterns.md` — how `/dw-intel` answers different question shapes (where-is, what-uses, architecture-of, dependency-of).
+- `references/api-design-discipline.md` — Hyrum's Law, contract-first design, error semantics, boundary validation, versioning. Use when intel feeds techspec authoring (`/dw-create-techspec`) for endpoints — design must respect existing project conventions surfaced in `apis.json`. Adapted from [`addyosmani/agent-skills/api-design`](https://github.com/addyosmani/agent-skills/tree/main/api-design) (MIT).
 
 ## Inspired by
 

package/scaffold/skills/dw-codebase-intel/references/api-design-discipline.md

@@ -0,0 +1,138 @@
+# API design discipline — contract-first, convention-respecting
+
+> Adapted from [`addyosmani/agent-skills/api-design`](https://github.com/addyosmani/agent-skills/tree/main/api-design) (MIT). Patterns adapted to dev-workflow's context where intel feeds techspec authoring; emphasis is on respecting the project's existing conventions over imposing external standards.
+
+When designing or extending APIs, the goal is not "follow REST best practices" — it's "fit this project's contract and remain stable." This file frames the discipline.
+
+## Hyrum's Law
+
+> With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody.
+
+Practical consequence: any field returned, any header sent, any error format used, any timing characteristic — at least one consumer probably depends on it. Changing it breaks them. This is true even for behaviors you consider "implementation details."
+
+Implications:
+
+1. **Be deliberate about what you expose.** Returning `{ ok: true, data: ... }` instead of just `data` adds an observable that future consumers will couple to.
+2. **Default to the smallest contract that satisfies known consumers.** Adding more later is easy; removing later is breaking.
+3. **Treat the contract as load-bearing infrastructure.** Schema docs, type definitions, and OpenAPI/JSON Schema spec files are part of the contract, not metadata.
+
+## Read project intel before designing
+
+When intel is available (`.dw/intel/` populated), read it first:
+
+- `apis.json` — what shapes already exist? Naming patterns? Pagination style?
+- `arch.md` — how do existing endpoints group? Which layer owns what?
+- `stack.json` — what's the framework? Schema validator? Serializer?
+
+A new API should look LIKE existing APIs in the project. If the project uses snake_case in JSON, your new endpoint uses snake_case. If existing endpoints return `{ data, meta }`, yours does too. Imposing an external "best practice" that conflicts with existing patterns adds inconsistency for no payoff.
+
+## Contract-first design
+
+Before writing the handler, write the contract:
+
+```typescript
+// API contract (TypeScript-first; equivalent in OpenAPI/Zod/etc.)
+interface CreateOrderRequest {
+  customer_id: string;
+  items: { sku: string; qty: number }[];
+  shipping_address: Address;
+}
+
+interface CreateOrderResponse {
+  order_id: string;
+  status: 'pending' | 'confirmed';
+  estimated_ship_date: string;  // ISO-8601
+}
+
+interface CreateOrderError {
+  code: 'invalid_input' | 'inventory_unavailable' | 'payment_declined';
+  message: string;
+  details?: Record<string, unknown>;
+}
+```
+
+The contract is reviewed BEFORE implementation. Errors caught here cost minutes; errors caught after release cost hours of migration.
+
+## Error semantics
+
+Errors are part of the contract. Common pitfalls:
+
+- **Generic 500 with no body.** Caller can't differentiate transient from permanent → over-retries.
+- **Different error shapes per endpoint.** Caller can't write a unified error handler.
+- **Validation errors mixed with auth errors mixed with server errors.** Status codes alone aren't enough; codes must be discriminating.
+
+Discipline:
+
+- Pick one error shape (e.g., `{ code, message, details? }` or RFC 7807 ProblemDetails). Use it everywhere.
+- Distinguish: validation (`400`/`422`), auth (`401`/`403`), not-found (`404`), conflict (`409`), rate-limit (`429`), retryable server error (`503`), permanent server error (`500`).
+- Document error codes alongside the request/response shape. Callers code against codes, not English messages.
+
+## Boundary validation
+
+Validate at the API boundary, not deep inside.
+
+- Use a schema validator (Zod, Joi, Pydantic, etc.) that matches the project's stack.
+- Reject malformed input with a structured error before any business logic runs.
+- Trust internal callers; validate external input.
+
+The same principle applies on the response: type-check what you serialize. A handler returning `customer.email` when there's a possibility of `customer === null` produces a 500 in production — caught in development with strict typing.
+
+## Versioning
+
+When the contract changes incompatibly, version. Common strategies:
+
+| Strategy | Trade-off |
+|----------|-----------|
+| URL versioning (`/v1/orders`, `/v2/orders`) | Visible, simple; URL clutter |
+| Header versioning (`Accept: application/vnd.app.v2+json`) | Cleaner URLs; less discoverable |
+| Body versioning (`{ version: 2, ... }`) | Flexible per-request; more parsing complexity |
+
+Pick the project's existing strategy; don't introduce a second one. Changing strategy is itself a breaking change.
+
+When deprecating a version:
+
+1. Announce deprecation date in docs and response headers (`Deprecation: ...`, `Sunset: ...`).
+2. Continue to serve the old version for the announced period.
+3. Provide a migration guide for callers.
+4. Remove ONLY after the deprecation period and confirmation no callers remain.
+
+## Pagination
+
+| Style | When |
+|-------|------|
+| Offset/limit (`?offset=20&limit=10`) | Small datasets, simple UIs. Breaks under concurrent inserts (skip/dup rows). |
+| Cursor-based (`?cursor=abc&limit=10`) | Large datasets, infinite scroll. Stable under writes. |
+| Page-based (`?page=3&per_page=10`) | UI-driven, equivalent to offset under the hood. |
+
+Cursor is preferred for any list expected to grow large or change during browsing. Don't mix styles across the API.
+
+## Idempotency
+
+Operations that can be retried (POST creating something, PUT updating, DELETE removing) need idempotency guarantees:
+
+- **Idempotency keys:** caller sends a unique key with each request; server deduplicates.
+- **Conditional requests:** use ETags / `If-Match` headers for safe concurrent updates.
+- **Replay-safe semantics:** the operation produces the same outcome regardless of how many times it's retried.
+
+Without these, retries cause duplicates (orders, charges, emails) — common production bug.
+
+## When the project has its own conventions
+
+If `.dw/intel/apis.json` shows a strong existing pattern (e.g., all endpoints use `snake_case`, return `{ data, meta }`, use cursor pagination, error format `{ error: { code, message } }`):
+
+- Follow it. Don't propose a "better" alternative without explicit user buy-in.
+- Document the convention in the techspec so future contributors stay aligned.
+- Inconsistency hurts more than imperfection.
+
+## Anti-patterns
+
+- Designing the handler before the contract — handler implementation forces awkward shapes.
+- Returning different shapes for success and error (callers need bifurcating type guards everywhere).
+- Stuffing multiple operations into one endpoint (`POST /process`) — opaque, hard to test, hard to monitor.
+- Using HTTP status 200 with a body indicating failure — callers can't trust standard error handling.
+- Breaking changes shipped without a version bump.
+- Adding "nice to have" fields to the response that aren't documented — callers will couple to them anyway (Hyrum).
+
+## Integration with dev-workflow
+
+Use this discipline when authoring techspecs (`/dw-create-techspec`) or refactoring API surfaces. Cite `apis.json` evidence in the techspec — "existing endpoints use cursor pagination (apis.json:42); this endpoint follows the same pattern."