@brunosps00/dev-workflow 0.4.5 → 0.4.7

package/lib/constants.js

@@ -23,6 +23,7 @@ const COMMANDS = {
     { name: 'dw-run-plan', description: 'Execute ALL tasks sequentially until the plan is complete' },
     { name: 'dw-run-qa', description: 'Run visual QA with browser automation, E2E tests, and accessibility' },
     { name: 'dw-run-task', description: 'Execute a single task with built-in validation and testing' },
+    { name: 'dw-update', description: 'Update dev-workflow to the latest version published on npm without leaving the agent session' },
   ],
   'pt-br': [
     { name: 'dw-analyze-project', description: 'Analisa stack, patterns e convencoes do repositorio para gerar regras do projeto' },
@@ -48,6 +49,7 @@ const COMMANDS = {
     { name: 'dw-run-plan', description: 'Executar TODAS as tasks sequencialmente ate completar o plano' },
     { name: 'dw-run-qa', description: 'Executar QA visual com automacao de browser, testes E2E e acessibilidade' },
     { name: 'dw-run-task', description: 'Executar uma task com validacao e testes integrados' },
+    { name: 'dw-update', description: 'Atualizar o dev-workflow para a versao mais recente publicada no npm sem sair da sessao do agente' },
   ],
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "AI-driven development workflow commands for any project. Scaffolds a complete PRD-to-PR pipeline with multi-platform AI assistant support.",
   "bin": {
     "dev-workflow": "./bin/dev-workflow.js"

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

@@ -5,6 +5,24 @@ You are a full pipeline orchestrator. This command receives a user's wish and au
 <critical>The ONLY pause moments are the 3 gates defined below. Between gates, execute everything automatically without asking for confirmation.</critical>
 <critical>Each step MUST follow the complete instructions from the corresponding command in `.dw/commands/`. Read and execute the full command, not a summarized version.</critical>
 
+<critical>FORMAL EXECUTION IS MANDATORY — READ BEFORE STARTING:
+A step that invokes a `/dw-xxx` command is ONLY considered complete when the artifacts produced by that command exist on disk. Manual validations (running tests, opening Playwright ad-hoc, eyeballing the code, writing a short qa-report by hand) DO NOT replace formal execution of the command.
+- BEFORE each step: announce to the user `→ Invoking /dw-[name] — executing full instructions`.
+- DURING: follow the instructions in `.dw/commands/[name].md` in full, without summarizing or substituting.
+- AFTER: run `ls` on the artifact paths listed in that step and confirm they exist before updating `autopilot-state.json`. If any artifact is missing, the step did NOT run — re-execute the command formally.</critical>
+
+<critical>FORBIDDEN RATIONALIZATIONS — if you think any of these, STOP and execute the command formally:
+| Thought | Reality |
+|---------|---------|
+| "I already ran the tests manually" | The command produces structured artifacts. Run the command. |
+| "I validated via ad-hoc Playwright" | `/dw-run-qa` requires RF matrix, bugs.md, screenshots, scripts, logs, checklist. Run the command. |
+| "The implementation is obviously correct" | `/dw-review-implementation` requires a compliance matrix per RF/endpoint/task. Run the command. |
+| "A strong manual validation is enough" | NO. Technical equivalence DOES NOT replace formal execution. |
+| "I already checked build and lint, that's enough" | Build/lint DO NOT replace review nor QA. Run the commands. |
+| "I wrote a summarized qa-report.md by hand" | A loose file IS NOT execution of `/dw-run-qa`. The full `QA/` tree is mandatory. |
+| "The autopilot already advanced, I don't need to go back" | If the artifact doesn't exist, the step didn't run. Go back and execute. |
+| "I fixed bugs along the way, so QA is already ok" | Fixing bugs does not replace running formal QA. Run `/dw-run-qa`. |</critical>
+
 ## When to Use
 - Use when you want to go from an idea to a PR with minimal manual intervention
 - Use for complete features that go through the entire pipeline (research, planning, execution, quality)
@@ -143,12 +161,27 @@ Run `/dw-review-implementation` to verify PRD compliance (Level 2).
 - Maximum 3 correction cycles
 - Do NOT advance to QA until the review passes
 
+<critical>Required artifacts for this step (verify BEFORE marking complete):
+- Formatted output with compliance matrix shown to the user in the session
+- Explicit verdict (PASS / GAP / FAIL) for EACH RF in the PRD, EACH endpoint in the TechSpec, and EACH task
+- If gaps: correction commits before re-running the review
+A short text review, a "looks good", or a conclusion "implementation is correct" WITHOUT the structured RF-by-RF matrix DOES NOT count. A mental or eyeball review DOES NOT count. If the matrix didn't appear in the output, the command didn't run — re-execute.</critical>
+
 ### Step 10: Visual QA
 
 Run `/dw-run-qa` with Playwright MCP.
 - Test happy paths, edge cases, negative flows, accessibility
 - Document bugs with screenshots
 
+<critical>Required artifacts for this step (run `ls` on EACH path BEFORE marking complete):
+- `{{PRD_PATH}}/QA/qa-report.md` — exists and contains a per-RF section with PASS/FAIL
+- `{{PRD_PATH}}/QA/bugs.md` — exists (may be empty if no bugs, but the file must exist)
+- `{{PRD_PATH}}/QA/checklist.md` — exists and fully covered
+- `{{PRD_PATH}}/QA/screenshots/` — directory exists and contains at least 1 PNG per RF tested (format `RF-XX-[slug]-PASS.png` or `-FAIL.png`)
+- `{{PRD_PATH}}/QA/scripts/` — directory exists and contains Playwright `.spec.ts`/`.spec.js` scripts per RF
+- `{{PRD_PATH}}/QA/logs/` — directory exists with captured console/network logs
+Running Playwright ad-hoc, taking a few loose screenshots, or writing a short qa-report.md by hand DOES NOT replace this structure. If any artifact is missing or incomplete, the command did NOT run — invoke `/dw-run-qa` formally and follow its flow to completion.</critical>
+
 ### Step 11: Fix QA (Conditional)
 
 If QA found bugs:
@@ -168,6 +201,8 @@ Run `/dw-review-implementation` again to confirm QA fixes did not break PRD comp
 - If gaps found: fix and re-run
 - Maximum 3 cycles
 
+<critical>Required artifacts (same rules as Step 9): explicit RF-by-RF matrix in the output. No matrix = command didn't run = re-execute.</critical>
+
 ### Step 13: Code Review
 
 Run `/dw-code-review` (Level 3) for formal review.
@@ -175,6 +210,25 @@ Run `/dw-code-review` (Level 3) for formal review.
 
 ### Step 14: Commit
 
+<critical>MANDATORY PRE-COMMIT AUDIT — execute BEFORE invoking `/dw-commit`:
+
+Run `ls` on each path below and confirm existence. If ANY is missing, DO NOT commit:
+- `{{PRD_PATH}}/QA/qa-report.md`
+- `{{PRD_PATH}}/QA/bugs.md`
+- `{{PRD_PATH}}/QA/checklist.md`
+- `{{PRD_PATH}}/QA/screenshots/` (non-empty)
+- `{{PRD_PATH}}/QA/scripts/` (non-empty with `.spec.*` files)
+- `{{PRD_PATH}}/QA/logs/`
+- Evidence of the last `/dw-review-implementation` run with RF-by-RF matrix (session output or reference in `autopilot-state.json`)
+
+Also verify `autopilot-state.json`:
+- Every step 1 through 13 that is NOT in `skipped_steps` must be in `completed_steps`
+- Each completed step must have its artifacts listed in `step_artifacts`
+
+If any artifact or step is missing: STOP immediately. Report to the user: `Step N did not produce artifact X — re-running /dw-[command]`. Re-execute the command. Verify again. Only then proceed to `/dw-commit`.
+
+DO NOT make a partial commit. DO NOT justify the absence with manual validation. DO NOT mark a step as complete without the formal artifact.</critical>
+
 Run `/dw-commit` automatically.
 - Semantic commits following Conventional Commits
 - Do NOT wait for approval
@@ -213,13 +267,26 @@ Save the file `.dw/spec/prd-[name]/autopilot-state.json` with the following form
   "completed_steps": [1, 2, 3, 4, 5, 6, 7],
   "skipped_steps": [2],
   "gates_passed": ["prd", "tasks"],
+  "step_artifacts": {
+    "9": ["review-matrix-shown-in-session"],
+    "10": [
+      ".dw/spec/prd-[name]/QA/qa-report.md",
+      ".dw/spec/prd-[name]/QA/bugs.md",
+      ".dw/spec/prd-[name]/QA/checklist.md",
+      ".dw/spec/prd-[name]/QA/screenshots/",
+      ".dw/spec/prd-[name]/QA/scripts/",
+      ".dw/spec/prd-[name]/QA/logs/"
+    ],
+    "12": ["review-matrix-post-qa-shown-in-session"]
+  },
   "started_at": "2026-04-10T14:30:00Z",
   "last_updated": "2026-04-10T15:45:00Z"
 }
 ```
 
-- Update `current_step` and `completed_steps` BEFORE starting each step
-- If the session drops, `/dw-resume` will read this file and continue from the correct step
+- Update `current_step`, `completed_steps`, and `step_artifacts` BEFORE moving to the next step
+- A step ONLY moves to `completed_steps` after verifying its artifacts exist on disk
+- If the session drops, `/dw-resume` will read this file and continue from the correct step — and revalidate artifacts before trusting `completed_steps`
 - When the pipeline finishes (after commit or PR), remove the file or mark `"status": "completed"`
 
 <critical>After EACH completed step, display the updated progress block to the user. This is MANDATORY — the user MUST see what was done and what comes next. If a step was skipped, the reason MUST appear in the progress block.</critical>

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

@@ -146,6 +146,7 @@ This workspace uses an AI command system that automates the full development cyc
 | `/dw-task-summary` | Shows details of a task without executing | Number + path | Task summary |
 | `/dw-archive-prd` | Moves completed PRD to `.dw/archived/prd/` | PRD path | Archived PRD |
 | `/dw-help` | This command guide | (optional) command | This document |
+| `/dw-update` | Updates dev-workflow to the latest version on npm without leaving the agent | (none) | Updated managed files |
 
 ## Review Architecture (3 Levels)
 

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

@@ -0,0 +1,104 @@
+<system_instructions>
+You are an update utility. When invoked, update dev-workflow to the latest version published on npm without requiring the user to leave the agent.
+
+## When to Use
+- Use when the user wants to update `/dw-*` commands, templates, references, scripts, skills, wrappers, and MCPs to the latest version
+- Use when a new release is out and the user wants to apply it without exiting the session
+- Do NOT use to install from scratch in a new project (use `npx dev-workflow init`)
+- Do NOT use to install system dependencies/Playwright/MCPs (use `npx dev-workflow install-deps`)
+
+## Pipeline Position
+**Predecessor:** (any) | **Successor:** (any)
+
+## Behavior
+
+### 1. Record Current Version (Required)
+
+Before updating, capture the installed version so you can report the delta:
+
+```bash
+node -e "try { console.log(require('@brunosps00/dev-workflow/package.json').version) } catch(e) { console.log('not-cached-locally') }" 2>/dev/null
+```
+
+### 2. Detect Language of Installed Commands (Required)
+
+<critical>Do NOT assume the language from this command file. Detect by inspecting the actual files in `.dw/commands/` so a user with a mixed or switched install does not receive an update in the wrong language.</critical>
+
+Run at the project root:
+
+```bash
+if [ -d .dw/commands ]; then
+  PT_COUNT=$(grep -l "## Quando Usar" .dw/commands/*.md 2>/dev/null | wc -l)
+  EN_COUNT=$(grep -l "## When to Use" .dw/commands/*.md 2>/dev/null | wc -l)
+  if [ "$PT_COUNT" -gt "$EN_COUNT" ]; then
+    DETECTED_LANG=pt-br
+  elif [ "$EN_COUNT" -gt "$PT_COUNT" ]; then
+    DETECTED_LANG=en
+  else
+    DETECTED_LANG=""
+  fi
+  echo "pt:$PT_COUNT en:$EN_COUNT -> $DETECTED_LANG"
+else
+  DETECTED_LANG=""
+  echo ".dw/commands does not exist"
+fi
+```
+
+Rules:
+- If `DETECTED_LANG` is `pt-br` or `en`: use it in the next step
+- If empty (tie, missing folder, new install): ask the user `I detected [describe context]. Proceed with pt-br or en?` and wait for the response before continuing
+
+### 3. Run the Update (Required)
+
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` to FORCE fetching the latest version from npm (bypass local cache). Pass `--lang=<DETECTED_LANG>` to skip the interactive prompt.</critical>
+
+```bash
+npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
+```
+
+The `update` command overwrites managed files and PRESERVES:
+- `.dw/rules/` (user rules)
+- `.dw/spec/` (in-progress PRDs and tasks)
+- `.planning/` (user data)
+
+If the update fails (network error, permission, package unavailable): report the error to the user and STOP. Do NOT attempt manual workarounds like copying files by hand.
+
+### 4. Capture New Version
+
+```bash
+node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+```
+
+### 5. Report Result
+
+Present to the user:
+- Detected language (`DETECTED_LANG`)
+- Previous version → new version
+- Summary of what the `update` output showed (files copied, wrappers generated, MCPs configured)
+- Any warnings or errors
+
+### 6. Suggest Next Step
+
+If commands/skills were updated, remind the user:
+- Restart the agent session (or reload skills) so the new instructions take effect — skills are usually loaded at session start
+- 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
+
+## Advanced Options
+
+If the user asks for a specific version (not `@latest`):
+
+```bash
+npx -y @brunosps00/dev-workflow@<version> update --lang=$DETECTED_LANG
+```
+
+E.g.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=en`
+
+## Notes
+
+- `npx -y` skips the "OK to install" prompt when the package is not cached
+- `@latest` bypasses the npx cache and pulls the `latest` tag from the registry
+- `--lang=...` skips the interactive language prompt; the value comes from the auto-detection in step 2
+- This command does NOT update the user project's Node dependencies — only the dev-workflow scaffold
+
+</system_instructions>

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

@@ -5,6 +5,24 @@ Voce e um orquestrador de pipeline completo. Este comando recebe um desejo do us
 <critical>Os UNICOS momentos de pausa sao os 3 gates definidos abaixo. Entre os gates, execute tudo automaticamente sem pedir confirmacao.</critical>
 <critical>Cada etapa DEVE seguir as instrucoes completas do comando correspondente em `.dw/commands/`. Leia e execute o comando inteiro, nao uma versao resumida.</critical>
 
+<critical>EXECUCAO FORMAL OBRIGATORIA — LEIA ANTES DE COMECAR:
+Uma etapa que invoca um comando `/dw-xxx` SO e considerada completa quando os artefatos produzidos pelo comando existem no disco. Validacoes manuais (rodar testes, abrir o Playwright, revisar o codigo a olho, gerar um qa-report curto a mao) NAO substituem a execucao formal do comando.
+- ANTES de cada etapa: anuncie ao usuario `→ Invocando /dw-[nome] — executando instrucoes completas`.
+- DURANTE: siga as instrucoes do arquivo `.dw/commands/[nome].md` integralmente, sem resumir nem substituir.
+- DEPOIS: rode `ls` nos caminhos de artefato listados na propria etapa e confirme existencia antes de atualizar `autopilot-state.json`. Se faltar qualquer artefato, a etapa NAO rodou — re-execute o comando formalmente.</critical>
+
+<critical>RACIOCINIOS PROIBIDOS — se voce pensar qualquer uma destas frases, PARE e execute o comando formalmente:
+| Pensamento | Realidade |
+|------------|-----------|
+| "Ja rodei os testes manualmente" | O comando produz artefatos estruturados. Rode o comando. |
+| "Validei via Playwright ad-hoc" | `/dw-run-qa` exige matriz por RF, bugs.md, screenshots, scripts, logs, checklist. Rode o comando. |
+| "A implementacao esta obviamente correta" | `/dw-review-implementation` exige matriz de compliance por RF/endpoint/task. Rode o comando. |
+| "Validacao manual forte ja basta" | NAO. Equivalencia tecnica NAO substitui a execucao formal. |
+| "Ja conferi build e lint, e suficiente" | Build/lint NAO substituem review nem QA. Rode os comandos. |
+| "Gerei um qa-report.md resumido a mao" | Um arquivo solto NAO e execucao de `/dw-run-qa`. A arvore `QA/` completa e obrigatoria. |
+| "O autopilot ja avancou, nao preciso voltar" | Se o artefato nao existe, a etapa nao rodou. Volte e execute. |
+| "Corrigi bugs no caminho, entao o QA ja esta ok" | Corrigir bugs nao substitui rodar o QA formal. Rode `/dw-run-qa`. |</critical>
+
 ## Quando Usar
 - Use quando quiser ir de uma ideia ate um PR com minima intervencao manual
 - Use para features completas que passam por todo o pipeline (pesquisa, planejamento, execucao, qualidade)
@@ -143,12 +161,27 @@ Execute `/dw-review-implementation` para verificar PRD compliance (Level 2).
 - Maximo 3 ciclos de correcao
 - NAO avance para QA ate que o review passe
 
+<critical>Artefatos obrigatorios desta etapa (verifique ANTES de marcar como completa):
+- Output formatado com matriz de compliance exibido ao usuario na propria sessao
+- Veredicto explicito (PASS / GAP / FAIL) para CADA RF do PRD, CADA endpoint da TechSpec e CADA task
+- Se houver gaps: commits de correcao antes de re-executar o review
+Um review textual curto, um "parece ok" ou conclusao "implementacao correta" SEM a matriz estruturada RF-by-RF NAO conta. Uma revisao mental ou a olho NAO conta. Se a matriz nao apareceu no output, o comando nao rodou — re-execute.</critical>
+
 ### Etapa 10: QA Visual
 
 Execute `/dw-run-qa` com Playwright MCP.
 - Teste happy paths, edge cases, fluxos negativos, acessibilidade
 - Documente bugs com screenshots
 
+<critical>Artefatos obrigatorios desta etapa (rode `ls` em CADA caminho ANTES de marcar como completa):
+- `{{PRD_PATH}}/QA/qa-report.md` — existe e contem secao por RF com PASS/FAIL
+- `{{PRD_PATH}}/QA/bugs.md` — existe (pode ser vazio se sem bugs, mas o arquivo deve existir)
+- `{{PRD_PATH}}/QA/checklist.md` — existe e esta coberto integralmente
+- `{{PRD_PATH}}/QA/screenshots/` — diretorio existe e contem pelo menos 1 PNG por RF testado (formato `RF-XX-[slug]-PASS.png` ou `-FAIL.png`)
+- `{{PRD_PATH}}/QA/scripts/` — diretorio existe e contem scripts Playwright `.spec.ts`/`.spec.js` por RF
+- `{{PRD_PATH}}/QA/logs/` — diretorio existe com logs de console/rede capturados
+Rodar Playwright ad-hoc, tirar algumas screenshots soltas ou escrever um qa-report.md curto a mao NAO substitui esta estrutura. Se qualquer artefato estiver ausente ou incompleto, o comando NAO rodou — invoque `/dw-run-qa` formalmente e siga o fluxo dele ate o fim.</critical>
+
 ### Etapa 11: Fix QA (Condicional)
 
 Se o QA encontrou bugs:
@@ -168,6 +201,8 @@ Execute `/dw-review-implementation` novamente para confirmar que as correcoes do
 - Se encontrar gaps: corrija e re-execute
 - Maximo 3 ciclos
 
+<critical>Artefatos obrigatorios (mesmas regras da Etapa 9): matriz RF-by-RF explicita no output. Sem matriz = comando nao rodou = re-execute.</critical>
+
 ### Etapa 13: Code Review
 
 Execute `/dw-code-review` (Level 3) para review formal.
@@ -175,6 +210,25 @@ Execute `/dw-code-review` (Level 3) para review formal.
 
 ### Etapa 14: Commit
 
+<critical>AUDITORIA PRE-COMMIT OBRIGATORIA — execute ANTES de invocar `/dw-commit`:
+
+Rode `ls` em cada caminho abaixo e confirme existencia. Se QUALQUER um faltar, NAO faca commit:
+- `{{PRD_PATH}}/QA/qa-report.md`
+- `{{PRD_PATH}}/QA/bugs.md`
+- `{{PRD_PATH}}/QA/checklist.md`
+- `{{PRD_PATH}}/QA/screenshots/` (nao vazio)
+- `{{PRD_PATH}}/QA/scripts/` (nao vazio com arquivos `.spec.*`)
+- `{{PRD_PATH}}/QA/logs/`
+- Evidencia do ultimo `/dw-review-implementation` com matriz RF-by-RF (output da sessao ou referencia em `autopilot-state.json`)
+
+Verifique tambem `autopilot-state.json`:
+- Toda etapa de 1 a 13 que NAO esta em `skipped_steps` deve estar em `completed_steps`
+- Cada etapa completada deve ter seus artefatos listados em `step_artifacts`
+
+Se faltar qualquer artefato ou etapa: PARE imediatamente. Reporte ao usuario: `Etapa N nao produziu artefato X — re-executando /dw-[comando]`. Re-execute o comando. Verifique novamente. Soh entao prossiga para `/dw-commit`.
+
+NAO faca commit parcial. NAO justifique a falta com validacao manual. NAO marque etapa como completa sem o artefato formal.</critical>
+
 Execute `/dw-commit` automaticamente.
 - Commits semanticos seguindo Conventional Commits
 - NAO aguarde aprovacao
@@ -213,13 +267,26 @@ Salve o arquivo `.dw/spec/prd-[nome]/autopilot-state.json` com o seguinte format
   "completed_steps": [1, 2, 3, 4, 5, 6, 7],
   "skipped_steps": [2],
   "gates_passed": ["prd", "tasks"],
+  "step_artifacts": {
+    "9": ["review-matrix-shown-in-session"],
+    "10": [
+      ".dw/spec/prd-[nome]/QA/qa-report.md",
+      ".dw/spec/prd-[nome]/QA/bugs.md",
+      ".dw/spec/prd-[nome]/QA/checklist.md",
+      ".dw/spec/prd-[nome]/QA/screenshots/",
+      ".dw/spec/prd-[nome]/QA/scripts/",
+      ".dw/spec/prd-[nome]/QA/logs/"
+    ],
+    "12": ["review-matrix-post-qa-shown-in-session"]
+  },
   "started_at": "2026-04-10T14:30:00Z",
   "last_updated": "2026-04-10T15:45:00Z"
 }
 ```
 
-- Atualize `current_step` e `completed_steps` ANTES de iniciar cada etapa
-- Se a sessao cair, o `/dw-resume` lera este arquivo e continuara da etapa correta
+- Atualize `current_step`, `completed_steps` e `step_artifacts` ANTES de iniciar a proxima etapa
+- Uma etapa SO vai para `completed_steps` apos verificar que seus artefatos existem no disco
+- Se a sessao cair, o `/dw-resume` lera este arquivo e continuara da etapa correta — e revalidara os artefatos antes de confiar em `completed_steps`
 - Ao finalizar o pipeline (apos commit ou PR), remova o arquivo ou marque `"status": "completed"`
 
 <critical>Apos CADA etapa completada, exiba o bloco de progresso atualizado ao usuario. Isso e OBRIGATORIO — o usuario DEVE ver o que foi feito e o que vem a seguir. Se uma etapa foi pulada, o motivo DEVE aparecer no bloco de progresso.</critical>

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

@@ -129,6 +129,7 @@ Este workspace utiliza um sistema de comandos AI que automatiza o ciclo completo
 | 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 |
 
 ## Fluxos Comuns
 

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

@@ -0,0 +1,104 @@
+<system_instructions>
+Você é um utilitário de atualização. Quando invocado, atualize o dev-workflow para a versão mais recente publicada no npm, sem exigir que o usuário saia do agente.
+
+## Quando Usar
+- Use quando o usuário quiser atualizar comandos `/dw-*`, templates, references, scripts, skills, wrappers e MCPs para a versão mais recente
+- Use quando uma nova versão foi lançada e o usuário quer aplicar sem sair da sessão
+- NÃO use para instalar do zero em um projeto novo (use `npx dev-workflow init`)
+- NÃO use para instalar dependências de sistema/Playwright/MCPs (use `npx dev-workflow install-deps`)
+
+## Posição no Pipeline
+**Antecessor:** (qualquer) | **Sucessor:** (qualquer)
+
+## Comportamento
+
+### 1. Registrar Versão Atual (Obrigatório)
+
+Antes de atualizar, capture a versão instalada para poder reportar o delta:
+
+```bash
+node -e "try { console.log(require('@brunosps00/dev-workflow/package.json').version) } catch(e) { console.log('not-cached-locally') }" 2>/dev/null
+```
+
+### 2. Detectar Idioma dos Comandos Instalados (Obrigatório)
+
+<critical>Não assuma o idioma a partir do arquivo deste comando. Detecte analisando os arquivos reais em `.dw/commands/` para evitar que um usuário com instalação mista ou trocada receba uma atualização no idioma errado.</critical>
+
+Rode no diretório raiz do projeto:
+
+```bash
+if [ -d .dw/commands ]; then
+  PT_COUNT=$(grep -l "## Quando Usar" .dw/commands/*.md 2>/dev/null | wc -l)
+  EN_COUNT=$(grep -l "## When to Use" .dw/commands/*.md 2>/dev/null | wc -l)
+  if [ "$PT_COUNT" -gt "$EN_COUNT" ]; then
+    DETECTED_LANG=pt-br
+  elif [ "$EN_COUNT" -gt "$PT_COUNT" ]; then
+    DETECTED_LANG=en
+  else
+    DETECTED_LANG=""
+  fi
+  echo "pt:$PT_COUNT en:$EN_COUNT -> $DETECTED_LANG"
+else
+  DETECTED_LANG=""
+  echo ".dw/commands não existe"
+fi
+```
+
+Regras:
+- Se `DETECTED_LANG` vier `pt-br` ou `en`: use-o na próxima etapa
+- Se vier vazio (empate, pasta ausente, instalação nova): pergunte ao usuário `Detectei [descrever contexto]. Prosseguir com pt-br ou en?` e aguarde resposta antes de continuar
+
+### 3. Executar o Update (Obrigatório)
+
+<critical>Use `npx -y @brunosps00/dev-workflow@latest` para FORÇAR a busca da versão mais recente no npm (ignora cache local). Passe `--lang=<DETECTED_LANG>` para evitar prompt interativo.</critical>
+
+```bash
+npx -y @brunosps00/dev-workflow@latest update --lang=$DETECTED_LANG
+```
+
+O comando `update` sobrescreve arquivos gerenciados e PRESERVA:
+- `.dw/rules/` (rules do usuário)
+- `.dw/spec/` (PRDs e tasks em andamento)
+- `.planning/` (dados do usuário)
+
+Se o update falhar (erro de rede, permissão, pacote indisponível): reporte o erro ao usuário e PARE. NÃO tente workarounds manuais como copiar arquivos.
+
+### 4. Capturar Nova Versão
+
+```bash
+node -e "console.log(require('@brunosps00/dev-workflow/package.json').version)" 2>/dev/null
+```
+
+### 5. Reportar Resultado
+
+Apresente ao usuário:
+- Idioma detectado (`DETECTED_LANG`)
+- Versão anterior → nova versão
+- Resumo do que o output do `update` mostrou (arquivos copiados, wrappers gerados, MCPs configurados)
+- Quaisquer avisos ou erros
+
+### 6. Sugerir Próximo Passo
+
+Se comandos/skills foram atualizados, lembre o usuário:
+- Reinicie a sessão do agente (ou recarregue skills) para que as instruções novas tenham efeito — skills costumam ser carregadas no início da sessão
+- 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
+
+## Opções Avançadas
+
+Se o usuário pedir uma versão específica (não `@latest`):
+
+```bash
+npx -y @brunosps00/dev-workflow@<versao> update --lang=$DETECTED_LANG
+```
+
+Ex.: `npx -y @brunosps00/dev-workflow@0.4.5 update --lang=pt-br`
+
+## Observações
+
+- `npx -y` evita o prompt "OK to install" quando o pacote não está em cache
+- `@latest` ignora o cache do npx e busca a tag `latest` do registry
+- `--lang=...` evita o prompt interativo de idioma; o valor vem da detecção automática na etapa 2
+- Este comando NÃO atualiza dependências Node do projeto do usuário, apenas o scaffold do dev-workflow
+
+</system_instructions>