@brunosps00/dev-workflow 2.2.0 → 2.3.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "dev-workflow",
   "description": "Standalone, à-la-carte skills from the dev-workflow pipeline: minimalism, search-first, simplification, verification, security review, and more.",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "author": {
     "name": "Bruno Santos"
   },

package/CHANGELOG.md

@@ -10,6 +10,52 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 > those versions were released, so they are summaries of what shipped, not
 > contemporaneous release notes. `git log` remains the authoritative record.
 
+## [2.3.0] — 2026-09-09
+
+### Added
+
+- Task execution contracts with per-task tool, model, effort, agent and fallback
+  choices, dependency validation and persistent execution state. Schema 1.0 plans
+  remain supported with local execution defaults.
+- Instruction size and routed-reference validation in `npm run validate`, with
+  regression tests for missing resources and byte/discovery budget violations.
+- Frontend engineering guidance and EN/PT-BR quality baseline templates integrated
+  into project analysis, planning, review and QA. Controls cover API contracts,
+  types, import boundaries, code reachability, duplication and gradual CI adoption.
+- Scoped mutation-testing guidance that investigates behavioral gaps and cache
+  validity without introducing a universal score threshold.
+- Managed `routing-defaults.json` for comparing current model candidates while
+  preserving owner routing. Upgrade checks cover legacy plans and template overrides.
+
+### Changed
+
+- Approved implementation plans continue through execution, correction and
+  validation without a mandatory second invocation. Publication remains subject
+  to the user's authorization.
+- Claude, Codex and Copilot runner instructions use approved task assignments,
+  explicit session identity and parent review. New-install model routing defaults
+  are updated; existing owner configuration is preserved.
+- Installed root instructions are approximately 62% smaller. Detailed command
+  routing and conditional skill procedures move into references loaded as needed.
+- Verification reuses inspectable passing evidence only while command, inputs,
+  environment and scope remain equivalent. Required project checks still apply.
+- Planning and testing guidance favors behavior and risk over fixed task/file
+  quotas, blanket parallelism, universal coverage targets and score-only approval.
+
+### Fixed
+
+- Resume guidance preserves partial work and avoids blind latest-session recovery
+  or destructive retries. Dependent tasks retain a coherent worktree history.
+- Removed contradictory mutation-testing guidance and aligned EN/PT-BR review,
+  goal and resume behavior with the continuous execution contract.
+- Humanizer's upstream version is preserved under supported skill metadata.
+- `/dw-update` reads installed versions from `.dw/install-state.json` instead of
+  resolving an npm package that may only exist in the `npx` execution environment.
+
+Validation: 129 tests pass; registry, instruction and plugin checks pass.
+Install/update and package checks include the new resources. External provider
+dispatches and frontend analysis tools were not exercised against live projects.
+
 ## [2.2.0] — 2026-08-24
 
 Release driven by two operational failures observed on a real project, both of the

package/README.md

@@ -42,13 +42,13 @@ Exportable skills (no `.dw/` pipeline required): `dw-minimalism`, `dw-search-fir
 
 ## Commands
 
-dev-workflow v2.2.0 ships **41 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
+dev-workflow v2.3.0 ships **41 commands** organized into four tiers. Most users only invoke Tier 1 + Tier 2.
 
 ### Tier 1 — Gateway (4)
 
 | Command | When |
 |---------|------|
-| **`/dw-autopilot "wish"`** | Default entry point in two invocations. First run completes PRD → TechSpec → Tasks and stops. Second run resumes from state, executes `/dw-goal --from-autopilot <slug>` for Run → Review → QA/Fix → Review, then Security Gate → Commit → PR. |
+| **`/dw-autopilot "wish"`** | Plan and approve task execution assignments, then continue through implementation, review and validation. Cross-tool workers return to the parent; merge/push/publication follow existing authorization. |
 | **`/dw-bugfix "description"`** | A bug report or pasted error. Triages bug-vs-feature-vs-scope, surgical fix or routes to a PRD. |
 | **`/dw-triage [item]`** | An external bug report, feature request, or PR. Checks whether it already exists and whether it was rejected before, verifies the claim, then routes to `/dw-bugfix`, `/dw-plan prd`, or `/dw-brainstorm --mode=grill`. Local-first in `.dw/triage/`; works with no network and no `gh`. |
 | **`/dw-help [keyword]`** | Discover commands. Pass a keyword for shortcuts; `--advanced` reveals internal commands. |
@@ -112,8 +112,8 @@ These are auto-invoked by Tier 1-3 commands. Available standalone via `/dw-help
 ## Workflow
 
 ```
-/dw-autopilot "wish"  ------>  First invocation: PRD → TechSpec → Tasks → STOP
-/dw-autopilot          ------>  Second invocation: /dw-goal → Security Gate → Commit → PR
+/dw-autopilot "wish"  ------>  PRD → TechSpec → Tasks + execution assignments → approval
+                             → /dw-goal → Security Gate → validated delivery → authorized publication
     --- OR step-by-step ---
 
 /dw-opportunities --> /dw-brainstorm --> /dw-plan --> .dw/spec/prd-{name}/{prd,techspec,tasks}.md
@@ -315,6 +315,8 @@ These are not slash commands — they are primitives other commands call to enfo
 
 ## Dependencies
 
+Frontend engineering guidance is loaded when planning or reviewing frontend data flow, dependencies or quality tooling. `/dw-analyze-project` documents the module's existing controls and gaps; `/dw-plan` carries accepted changes into tasks; `/dw-review` and `/dw-qa` use applicable evidence. The localized `frontend-quality-template.md` distinguishes required checks, advisory diagnostics and deferred proposals. API contracts, architecture checks and scoped mutation analysis complement the visual UI skill. Tool installation and CI policy changes remain scoped to the consumer project's task.
+
 Installed via `npx @brunosps00/dev-workflow install-deps`:
 
 | Dependency | Purpose | Link |
@@ -442,3 +444,9 @@ Skill description format ("pushy" trigger phrases ≤200 chars, "Use when X. Tri
 ## License
 
 MIT
+
+### Task execution across tools
+
+During `/dw-plan tasks`, review the proposed complexity, local/cross-tool executor, model, effort and agents for each task. Claude can delegate to `/dw-codex-run`, and Codex to `/dw-claude-run`. Approval carries through implementation, review and corrections; the parent continues after each worker handoff. A planning-only request still ends with the plan.
+
+Existing task documents remain compatible and default to local execution. Updates preserve your `.dw/config/routing.json`; new model candidates are proposals to verify against your account, not silent upgrades. See [workflow modernization](docs/model-workflow-modernization.md) for the execution contract, evidence reuse and validation limits.

package/lib/constants.js

@@ -2,13 +2,13 @@ const COMMANDS = {
   en: [
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost. --scope=repo writes .dw/adrs/ (works before any PRD); --scope=prd writes under the active PRD. Gated on hard-to-reverse + surprising + genuine trade-off.' },
     { name: 'dw-analyze-project', description: 'Scans the repo to learn its stack and conventions, then writes the rules other commands rely on.' },
-    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. First invocation plans and stops; second invocation resumes via dw-goal, then commit and PR.' },
-    { name: 'dw-brainstorm', description: 'Refine a concrete idea against the product\'s existing features. Auto-dispatches internal modes via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill is a native stateful alignment session (a direct grill-me phrase or --mode=grill) that writes canonical vocabulary to .dw/domain/. Use dw-opportunities before you have an idea and dw-refactor for code-health audits.' },
+    { name: 'dw-autopilot', description: 'Plan a multi-component implementation, approve task execution assignments, then continue through implementation, review and validation.' },
+    { name: 'dw-brainstorm', description: 'Explore unresolved product or architecture choices for a concrete idea; use grill for stateful alignment, research for unknowns, or council for competing approaches.' },
     { name: 'dw-bugfix', description: 'Trigger when user reports a bug, pastes an error, or describes broken behavior. Triages with three questions, then fixes or routes to PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger when user asks to run/fire Claude (claude -p headless) in a dedicated worktree to implement a prepared prompt/spec. Claude adapter over the dw-cli-run protocol: durable audit log, resumable session via --session-id, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger when user asks to run/fire Codex (codex exec) in a dedicated worktree to implement a prepared prompt/spec. Codex adapter over the dw-cli-run protocol: durable audit log, resumable per-task session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Run an approved task through Claude CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Run an approved task through Codex CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger when user asks to run/fire GitHub Copilot CLI (copilot -p) in a dedicated worktree to implement a prepared prompt/spec. Copilot adapter over the dw-cli-run protocol: durable audit log, resumable session, 0-10 dual evaluation, STOP for the gate. Never the main checkout; never merges.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Run an approved task through Copilot CLI in a dedicated worktree; return a durable session and evidence to the parent.' },
     { name: 'dw-dockerize', description: 'Reads a project, detects the stack and runtime deps, then proposes Dockerfile and docker-compose for dev and prod with explicit trade-offs.' },
     { name: 'dw-find-skills', description: 'Searches the npx skills ecosystem for a skill matching what you need, vets it, and installs it where you choose.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
@@ -17,41 +17,41 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lists primary commands and the flows that connect them. Pass --advanced to see internal/hidden commands.' },
     { name: 'dw-context-budget', description: 'Audits context overhead from commands, skills, agents, instructions, and MCPs; recommends token savings.' },
     { name: 'dw-harness-audit', description: 'Runs a deterministic health scorecard for dev-workflow installation, agents, MCPs, gates, and context discipline.' },
-    { name: 'dw-install-aws-skills', description: 'Trigger when user asks to install AWS expertise, setup AWS MCP server, or add AWS agent skills. Opt-in: clones curated skills from aws/agent-toolkit-for-aws into .agents/skills/aws/ and registers the unified AWS MCP Server (stdio via mcp-proxy-for-aws). Requires uv, aws cli, and AWS credentials.' },
+    { name: 'dw-install-aws-skills', description: 'Install selected AWS expertise and configure the AWS MCP integration when requested.' },
     { name: 'dw-install-azure-skills', description: 'Trigger when user asks to install Azure expertise, setup Microsoft docs MCP, or add Azure agent skills. Opt-in: clones curated skills from MicrosoftDocs/Agent-Skills into .agents/skills/azure/ and registers the Microsoft Learn MCP server.' },
     { name: 'dw-intel', description: 'Codebase intelligence: query mode (default) answers questions citing .dw/intel/ + .dw/rules/; --build mode (re)builds the index.' },
     { name: 'dw-learn', description: 'Synthesizes durable decisions, bugfixes, deviations, and git history into atomic confidence-weighted instincts you approve; can propose constitution principles. On-demand and human-in-the-loop — no always-on observer.' },
     { name: 'dw-new-project', description: 'Interviews you about stack and infra, then scaffolds a working monorepo with docker-compose for dev, .env, scripts, CI, and seeded rules.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Trigger when user asks to generate, iterate, or refactor/redesign headless Open Design HTML prototypes via the od CLI. Imports a target folder with isolated OD_DATA_DIR, refines briefs before dispatch, supports --refactor screenshots via --url/--viewports or --screenshot, runs web-prototype briefs with explicit --agent codex|claude, verifies files, captures JSONL audit logs, and stops for a dual >=9 visual gate.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Generate or iterate Open Design HTML prototypes through the od CLI, including screenshot-based redesign and visual verification.' },
     { name: 'dw-opportunities', description: 'Scans the installed project for product, UX, automation, refactor, and security opportunities, then routes each idea to the right next dw-* command.' },
     { name: 'dw-pause', description: 'Trigger when user says "pause work", "end session", or "save where we are". Consolidates open loops, decisions, blockers, and todos into .dw/STATE.md so the next session can resume.' },
-    { name: 'dw-plan', description: 'Trigger when user has a feature idea and needs spec + architecture + tasks. Runs PRD → TechSpec → Tasks sequentially. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-plan', description: 'Produce PRD, architecture and tasks, with local/cross-tool executor, model, effort and agent proposals by task complexity.' },
     { name: 'dw-qa', description: 'Trigger when user wants to validate behavior beyond unit tests. Mode-aware (UI / API / --ai / --uat). --fix enters the iterative QA + fix-retest loop. --bugfix <slug> targets a .dw/bugfixes/ entry.' },
     { name: 'dw-redesign-ui', description: 'Audits a frontend page, proposes design directions you choose from, then ships the redesign.' },
     { name: 'dw-refactor', description: 'Audits a target for refactor opportunities using the refactor-audit protocol, Fowler smells, deep-modules analysis, and behavior-preserving test gates.' },
-    { name: 'dw-report', description: 'Trigger when user asks for periodic progress reports ("report every 10 minutes", "keep me posted while this runs"). Timestamped done / doing / remaining report at a fixed cadence (default 10m, --every <N>m), appended to .dw/reports/YYYY-MM-DD.md; silent while blocked, final report + auto-disarm when the work ends. Auto-armed by dw-run, dw-autopilot, and the dw-cli-run adapters.' },
+    { name: 'dw-report', description: 'Report progress periodically during authorized long-running work; persist updates and stop reporting when the work ends.' },
     { name: 'dw-resume', description: 'Trigger when user says "resume work", "where did we stop?", or starts a session in a project with an existing .dw/STATE.md. Reads STATE.md, presents a TLDR, and suggests the next dw-* command.' },
     { name: 'dw-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Default runs L2 (PRD coverage) + L3 (code quality). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger when user wants to execute tasks. Default runs all pending in dependency order; \'run <task-id>\' runs one; \'run --resume\' continues an interrupted plan.' },
-    { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH block. Auto-invoked by /dw-review and /dw-generate-pr, explicit phase in /dw-autopilot, and runnable standalone.' },
+    { name: 'dw-secure-audit', description: 'Audit relevant code and dependencies for security findings using available scanners; validate exploitability and enforce blocking findings.' },
     { name: 'dw-skill-health', description: 'Audits installed skills and agents for bloat, duplication, missing references, and stale or unused modules.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Creates a minimal input packet for a subagent without injecting the parent transcript.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Records a structured subagent handoff with result, files, decisions, risks, verification, and blockers.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consumes pending subagent handoffs, summarizes them for the parent, and archives the local packets.' },
     { name: 'dw-triage', description: 'Local-first intake for external bug reports, feature requests, and PRs. Persists .dw/triage/ state, checks redundancy and prior rejections, verifies claims, then routes to /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, or no work.' },
-    { name: 'dw-worktree', description: 'Worktree lifecycle for delegated work: create prepared (../<project>-<slug> + install/build prep), list with verdicts (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), clean only what is proven merged and clean (dry-run by default), merge in the safe ff-only order and remove in the same turn. Never --force. Backed by .dw/scripts/lib/worktree-gc.mjs; used by the dw-*-run adapters, /dw-pause, and /dw-harness-audit.' },
+    { name: 'dw-worktree', description: 'Create prepared worktrees, inspect their state, clean safely merged worktrees, or integrate an explicitly authorized branch.' },
     { name: 'dw-update', description: 'Updates dev-workflow to the latest npm release in-place, with a snapshot you can roll back to.' },
   ],
   'pt-br': [
     { name: 'dw-adr', description: 'Registra uma decisao arquitetural e os trade-offs aceitos, antes que se percam. --scope=repo escreve em .dw/adrs/ (funciona antes de qualquer PRD); --scope=prd escreve sob o PRD ativo. Gated em dificil-de-reverter + surpreendente + trade-off real.' },
     { name: 'dw-analyze-project', description: 'Escaneia o repo para aprender stack e convencoes, e escreve as regras que os outros commands usam.' },
-    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Primeira invocacao planeja e para; segunda retoma via dw-goal, depois commit e PR.' },
-    { name: 'dw-brainstorm', description: 'Refina uma ideia concreta contra features existentes do produto. Auto-dispatch de modos internos via --mode= (option-matrix / grill / prototype / council / research / refactor-audit / onepager). Grill e uma sessao nativa de alinhamento com estado (frase direta tipo me-questione ou --mode=grill) que escreve vocabulario canonico em .dw/domain/. Use dw-opportunities antes de ter uma ideia e dw-refactor para auditoria de code health.' },
+    { name: 'dw-autopilot', description: 'Planeja implementação multicomponente, aprova escolhas de execução por task e continua por implementação, review e validação.' },
+    { name: 'dw-brainstorm', description: 'Explora escolhas pendentes de produto ou arquitetura; grill para alinhamento com estado, pesquisa para lacunas e council para alternativas concorrentes.' },
     { name: 'dw-bugfix', description: 'Trigger quando usuario reporta bug, cola erro ou descreve comportamento quebrado. Tria com tres perguntas, depois corrige ou roteia pra PRD.' },
-    { name: 'dw-claude-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Claude (claude -p headless) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Claude sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel via --session-id, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
-    { name: 'dw-codex-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o Codex (codex exec) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Codex sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel por tarefa, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-claude-run', userInvoked: true, description: 'Executa task aprovada pela CLI Claude em worktree dedicado; retorna sessão durável e evidências ao parent.' },
+    { name: 'dw-codex-run', userInvoked: true, description: 'Executa task aprovada pela CLI Codex em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
-    { name: 'dw-copilot-run', userInvoked: true, description: 'Trigger quando usuario pede pra rodar/disparar o GitHub Copilot CLI (copilot -p) numa worktree dedicada pra implementar um prompt/spec preparado. Adapter Copilot sobre o protocolo dw-cli-run: log de auditoria duravel, sessao resumivel, dupla avaliacao 0-10, PARA pro gate. Nunca no checkout principal; nunca mergeia.' },
+    { name: 'dw-copilot-run', userInvoked: true, description: 'Executa task aprovada pela CLI Copilot em worktree dedicado; retorna sessão durável e evidências ao parent.' },
     { name: 'dw-dockerize', description: 'Le um projeto, detecta stack e deps de runtime, e propoe Dockerfile e docker-compose para dev e prod com trade-offs explicitos.' },
     { name: 'dw-find-skills', description: 'Busca no ecossistema npx skills uma skill que resolva o que voce precisa, valida e instala onde voce escolher.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
@@ -60,29 +60,29 @@ const COMMANDS = {
     { name: 'dw-help', description: 'Lista comandos primarios e fluxos que os conectam. Passe --advanced para ver comandos internos/escondidos.' },
     { name: 'dw-context-budget', description: 'Audita overhead de contexto em comandos, skills, agentes, instrucoes e MCPs; recomenda economia de tokens.' },
     { name: 'dw-harness-audit', description: 'Roda um scorecard deterministico da instalacao dev-workflow, agentes, MCPs, gates e disciplina de contexto.' },
-    { name: 'dw-install-aws-skills', description: 'Trigger quando usuario pede pra instalar expertise AWS, configurar MCP da AWS, ou adicionar agent skills AWS. Opt-in: clona skills curadas de aws/agent-toolkit-for-aws para .agents/skills/aws/ e registra o AWS MCP Server unificado (stdio via mcp-proxy-for-aws). Requer uv, aws cli e credenciais AWS.' },
-    { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure. Opt-in: clona skills curadas de MicrosoftDocs/Agent-Skills para .agents/skills/azure/ e registra o Microsoft Learn MCP server.' },
+    { name: 'dw-install-aws-skills', description: 'Instala expertise AWS selecionada e configura integração MCP AWS quando solicitado.' },
+    { name: 'dw-install-azure-skills', description: 'Trigger quando usuario pede pra instalar expertise Azure, configurar MCP do Microsoft docs, ou adicionar agent skills Azure.' },
     { name: 'dw-intel', description: 'Inteligencia do codebase: modo query (default) responde citando .dw/intel/ + .dw/rules/; modo --build (re)constroi indice.' },
     { name: 'dw-learn', description: 'Sintetiza decisoes duraveis, bugfixes, deviations e historico git em instincts atomicos ponderados por confianca que voce aprova; pode propor principios de constitution. On-demand e human-in-the-loop — sem observador sempre-ligado.' },
     { name: 'dw-new-project', description: 'Entrevista voce sobre stack e infra, depois faz scaffold de um monorepo com docker-compose para dev, .env, scripts, CI e rules seed.' },
-    { name: 'dw-open-design', userInvoked: true, description: 'Trigger quando usuario pede para gerar, iterar ou refatorar/redesenhar prototipos HTML headless do Open Design via od CLI. Importa pasta alvo com OD_DATA_DIR isolado, refina briefs antes de despachar, suporta prints --refactor via --url/--viewports ou --screenshot, roda briefs web-prototype com --agent codex|claude explicito, verifica arquivos, captura logs JSONL e para para gate visual dual >=9.' },
+    { name: 'dw-open-design', userInvoked: true, description: 'Gera ou itera protótipos HTML Open Design pela CLI od, incluindo redesign por screenshots e verificação visual.' },
     { name: 'dw-opportunities', description: 'Escaneia o projeto instalado por oportunidades de produto, UX, automacao, refactor e seguranca, e roteia cada ideia para o proximo comando dw-* correto.' },
     { name: 'dw-pause', description: 'Trigger quando usuario diz "pausa o trabalho", "encerra a sessao" ou "salva onde paramos". Consolida pontas soltas, decisoes, bloqueios e todos em .dw/STATE.md para a proxima sessao retomar.' },
-    { name: 'dw-plan', description: 'Trigger quando usuario tem ideia de feature e precisa spec + arquitetura + tasks. Roda PRD → TechSpec → Tasks sequencial. Stages: prd / techspec / tasks; --from techspec; --council.' },
+    { name: 'dw-plan', description: 'Produz PRD, arquitetura e tasks com propostas de executor local/cruzado, modelo, esforço e agentes por complexidade.' },
     { name: 'dw-qa', description: 'Trigger quando usuario quer validar comportamento alem de unit tests. Mode-aware (UI / API / --ai / --uat). --fix entra no loop iterativo QA + fix-retest. --bugfix <slug> aponta para uma entrada em .dw/bugfixes/.' },
     { name: 'dw-redesign-ui', description: 'Audita uma pagina frontend, propoe direcoes de design que voce escolhe, e entrega o redesign.' },
     { name: 'dw-refactor', description: 'Audita um target por oportunidades de refactor usando o protocolo refactor-audit, smells Fowler, deep-modules e gates de teste preservando comportamento.' },
-    { name: 'dw-report', description: 'Trigger quando usuário pede report periódico de progresso ("report de 10 em 10 minutos", "me mantém informado enquanto isso roda"). Report carimbado com data/hora de feito / fazendo / falta em cadência fixa (default 10m, --every <N>m), anexado em .dw/reports/YYYY-MM-DD.md; silencioso enquanto bloqueado, report final + auto-desarme quando o trabalho termina. Auto-armado por dw-run, dw-autopilot e pelos adapters dw-cli-run.' },
+    { name: 'dw-report', description: 'Reporta progresso periódico durante trabalho longo autorizado; persiste atualizações e encerra quando o trabalho termina.' },
     { name: 'dw-resume', description: 'Trigger quando usuario diz "retoma", "onde paramos?" ou comeca sessao num projeto com .dw/STATE.md existente. Le STATE.md, apresenta TLDR e sugere proximo comando dw-*.' },
     { name: 'dw-review', description: 'Trigger quando usuário pede pra revisar código, checar qualidade ou validar prontidão pra PR. Default roda L2 (cobertura PRD) + L3 (qualidade). Flags --coverage-only / --code-only / --bugfix <slug> / --since <ref>.' },
     { name: 'dw-run', description: 'Trigger quando usuario quer executar tasks. Default roda todas pendentes em ordem de dependencia; \'run <task-id>\' roda uma; \'run --resume\' continua plan interrompido.' },
-    { name: 'dw-secure-audit', description: 'Security Gate: OWASP + Semgrep SAST (diff) + gitleaks secrets + Trivy SCA/IaC + lockfile + supply-chain + outdated. Rigoroso: secrets/CRITICAL/HIGH bloqueiam. Auto-invocado por /dw-review e /dw-generate-pr, fase explicita no /dw-autopilot, e executavel standalone.' },
+    { name: 'dw-secure-audit', description: 'Audita código e dependências relevantes com scanners disponíveis; valida explorabilidade e aplica achados bloqueantes.' },
     { name: 'dw-skill-health', description: 'Audita skills e agentes instalados por bloat, duplicacao, referencias quebradas e modulos sem uso.' },
     { name: 'dw-subtask-start', userInvoked: true, description: 'Cria um input packet minimo para subagente sem injetar transcript bruto do parent.' },
     { name: 'dw-subtask-complete', userInvoked: true, description: 'Registra handoff estruturado do subagente com resultado, arquivos, decisoes, riscos, verificacao e bloqueios.' },
     { name: 'dw-subtask-resume', userInvoked: true, description: 'Consome handoffs pendentes de subagentes, resume para o parent e arquiva os pacotes locais.' },
-    { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos. Persiste estado em .dw/triage/, checa redundância e rejeições anteriores, verifica alegações, e então roteia para /dw-bugfix, /dw-plan prd, /dw-brainstorm --mode=grill, ou nenhum trabalho.' },
-    { name: 'dw-worktree', description: 'Ciclo de vida de worktrees de delegação: cria preparada (../<projeto>-<slug> + prep de install/build), lista com vereditos (REMOVABLE / KEEP:unmerged / KEEP:dirty / KEEP:in-use), limpa só o que está provadamente mergeado e limpo (dry-run por default), mergeia na ordem segura ff-only e remove no mesmo turno. Nunca --force. Apoiado em .dw/scripts/lib/worktree-gc.mjs; usado pelos adapters dw-*-run, /dw-pause e /dw-harness-audit.' },
+    { name: 'dw-triage', description: 'Intake local-first para bug reports, feature requests e PRs externos.' },
+    { name: 'dw-worktree', description: 'Cria worktrees preparados, inspeciona estado, limpa worktrees integrados com segurança ou integra branch explicitamente autorizada.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],
 };

package/lib/init.js

@@ -202,6 +202,13 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     const cfgDir = path.join(projectRoot, '.dw', 'config');
     ensureDir(cfgDir);
     const routingDest = path.join(cfgDir, 'routing.json');
+    // Refresh the candidate reference without replacing active owner choices.
+    const defaultsDest = path.join(cfgDir, 'routing-defaults.json');
+    const defaultsStatus = writeFile(defaultsDest, require('fs').readFileSync(routingSrc, 'utf-8'), managedForce);
+    if (defaultsStatus === 'created') totalCreated++;
+    else if (defaultsStatus === 'overwritten') totalOverwritten++;
+    else totalSkipped++;
+    touchedFiles.push(defaultsDest);
     const rtStatus = writeFile(routingDest, require('fs').readFileSync(routingSrc, 'utf-8'), false);
     if (rtStatus === 'created') totalCreated++;
     else totalSkipped++;
@@ -419,6 +426,7 @@ async function run({ force = false, lang = null, mode = 'init', profile = null,
     managedFiles: listManagedFiles(projectRoot, touchedFiles),
   });
   console.log(`  Install state: ${path.relative(projectRoot, path.join(projectRoot, '.dw', 'install-state.json'))} (${installState.managed_files.length} files tracked)\n`);
+  console.log(`  Installed version: ${priorState?.version || 'unknown'} -> ${installState.version}\n`);
 
   // 10. Summary
   console.log(`  ${'='.repeat(40)}`);

package/lib/instruction-health.js

@@ -0,0 +1,38 @@
+const fs = require('fs');
+const path = require('path');
+const { COMMANDS } = require('./constants');
+
+const LIMITS = { instructions: 6000, skill: 8000, description: 250 };
+
+function inspectInstructions(root = path.join(__dirname, '..')) {
+  const issues = [];
+  const metrics = { instructions: {}, descriptions: {}, skills: {} };
+  for (const locale of ['en', 'pt-br']) {
+    const file = path.join(root, 'scaffold', locale, 'agent-instructions.md');
+    metrics.instructions[locale] = fs.statSync(file).size;
+    if (metrics.instructions[locale] > LIMITS.instructions) issues.push(`${locale} installed instructions exceed ${LIMITS.instructions} bytes`);
+    metrics.descriptions[locale] = 0;
+    for (const command of COMMANDS[locale]) {
+      metrics.descriptions[locale] += [...command.description].length;
+      if ([...command.description].length > LIMITS.description) issues.push(`${locale} ${command.name} description exceeds ${LIMITS.description} characters`);
+    }
+  }
+  const skillsDir = path.join(root, 'scaffold', 'skills');
+  for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const file = path.join(skillsDir, entry.name, 'SKILL.md');
+    if (!fs.existsSync(file)) continue; // Registry validator reports missing entrypoints.
+    const content = fs.readFileSync(file, 'utf8');
+    metrics.skills[entry.name] = Buffer.byteLength(content);
+    if (metrics.skills[entry.name] > LIMITS.skill) issues.push(`${entry.name} entrypoint exceeds ${LIMITS.skill} bytes`);
+    const description = content.match(/^description:\s*(.+)$/m)?.[1]?.replace(/^"|"$/g, '');
+    if (!description || [...description].length > LIMITS.description) issues.push(`${entry.name} requires a description of at most ${LIMITS.description} characters`);
+    // Concrete skill-relative router links, not wildcard examples or installed paths.
+    for (const match of content.matchAll(/(?:`|\]\()((?:references|agents|rules|languages|infrastructure)\/[\w./-]+\.md)(?:`|\))/g)) {
+      if (!fs.existsSync(path.join(path.dirname(file), match[1]))) issues.push(`${entry.name} missing routed reference ${match[1]}`);
+    }
+  }
+  return { issues, metrics };
+}
+
+module.exports = { LIMITS, inspectInstructions };

package/lib/post-update.js

@@ -71,7 +71,7 @@ function listPostUpdateActions(projectRoot) {
   });
   actions.push({
     command: '/dw-skill-health',
-    reason: 'audit refreshed bundled skills and agents for bloat, duplication, and stale references',
+    reason: 'audit refreshed skills and compare .dw/config/routing.json with managed routing-defaults.json; preserve owner choices and approved plans',
   });
 
   return actions;
@@ -80,6 +80,7 @@ function listPostUpdateActions(projectRoot) {
 function printPostUpdateActions(projectRoot) {
   const actions = listPostUpdateActions(projectRoot);
   console.log('  Post-update agent actions:');
+  console.log('    Read the refreshed .dw/commands/dw-update.md before following the post-update instructions.');
   console.log('    The CLI refreshed managed files. Project-derived docs require the agent to run commands:');
   for (const action of actions) {
     console.log(`    - ${action.command} - ${action.reason}`);

package/lib/validate.js

@@ -3,6 +3,7 @@ const path = require('path');
 const { validateSkillRegistry } = require('./skill-registry');
 const { validateAgentRegistry, readAgentRegistry } = require('./agents');
 const { buildManifests } = require('./build-plugin');
+const { inspectInstructions } = require('./instruction-health');
 
 /**
  * Repo quality gate (npm run validate). Validates the skill + agent registries
@@ -20,6 +21,7 @@ function run() {
   const agent = validateAgentRegistry(readAgentRegistry());
   issues.push(...agent.issues);
   warnings.push(...agent.warnings);
+  issues.push(...inspectInstructions().issues);
 
   // Plugin manifest drift check.
   const { plugin, marketplace } = buildManifests();
@@ -41,7 +43,7 @@ function run() {
     console.log('FAIL');
     process.exit(1);
   }
-  console.log('PASS: skill + agent registries valid; plugin manifests in sync.');
+  console.log('PASS: skill + agent registries valid; instruction budgets valid; plugin manifests in sync.');
 }
 
 function checkManifestDrift(relPath, expected, issues) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "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/config/routing.json

@@ -1,32 +1,51 @@
 {
-  "_note": "Dispatch routing for the CLI runners (/dw-claude-run, /dw-codex-run) via the dw-cli-run skill. Maps a task's Conventional-Commit type to a tier, and a tier to a concrete model + effort per brand. Seeded once on init and NEVER overwritten on update — model availability differs per account, so this file is yours to edit. Verify the model ids against `claude --help` / `codex --help` before trusting them; the shipped values are conservative defaults, not a guarantee that your account has access.",
+  "_note": "Model candidates for planning task execution by complexity. Preserve approved task assignments. Seeded on init and never overwritten on update. Verify provider/account availability and CLI capabilities before approval; model documentation is not proof of account access.",
   "schema_version": "1.0",
-
   "brands": {
-    "claude": { "detect": "claude --version" },
-    "codex": { "detect": "codex --version" }
+    "claude": {
+      "detect": "claude --version"
+    },
+    "codex": {
+      "detect": "codex --version"
+    }
   },
-
   "tiers": {
     "light": {
       "_use": "mechanical, low-ambiguity work; the answer is obvious and the diff is small",
-      "claude": { "model": "haiku", "effort": "low" },
-      "codex": { "model": "gpt-5.4-mini", "effort": "low" }
+      "claude": {
+        "model": "haiku",
+        "effort": "low"
+      },
+      "codex": {
+        "model": "gpt-5.6-luna",
+        "effort": "low"
+      }
     },
     "standard": {
       "_use": "normal feature and fix work",
-      "claude": { "model": "sonnet", "effort": "medium" },
-      "codex": { "model": "gpt-5.3-codex", "effort": "medium" }
+      "claude": {
+        "model": "sonnet",
+        "effort": "medium"
+      },
+      "codex": {
+        "model": "gpt-5.6-sol",
+        "effort": "medium"
+      }
     },
     "heavy": {
       "_use": "architectural, security-sensitive, or wide-blast-radius work",
-      "claude": { "model": "opus", "effort": "high" },
-      "codex": { "model": "gpt-5.5", "effort": "high" }
+      "claude": {
+        "model": "opus",
+        "effort": "high"
+      },
+      "codex": {
+        "model": "gpt-6-astra",
+        "effort": "high"
+      }
     }
   },
-
   "by_commit_type": {
-    "_note": "The task's type is already declared in tasks.md and in the atomic commit subject — no new inference needed.",
+    "_note": "Legacy fallback hint only. Approved task complexity/assignment takes precedence.",
     "chore": "light",
     "docs": "light",
     "style": "light",
@@ -38,23 +57,42 @@
     "refactor": "standard",
     "perf": "heavy"
   },
-
   "escalate_on_surface": {
     "_note": "If the task's fence touches any of these, override the type-derived tier upward. Match against file paths and the task title.",
     "tier": "heavy",
-    "patterns": ["auth", "session", "token", "credential", "migration", "payment", "billing", "invoice", "tenant", "crypto", "permission"]
+    "patterns": [
+      "auth",
+      "session",
+      "token",
+      "credential",
+      "migration",
+      "payment",
+      "billing",
+      "invoice",
+      "tenant",
+      "crypto",
+      "permission"
+    ]
   },
-
   "validation": {
-    "_note": "The worker never signs off on its own exam. Cross-brand is the default because a second vendor fails differently.",
-    "cross_brand": "preferred",
-    "degrade": "When only one brand is installed, validate in a SEPARATE dispatch at a different tier — never reuse the executing session.",
-    "acceptance_score": 9
+    "cross_brand": "when-planned",
+    "degrade": "Use approved independent review assignments; do not switch providers or tiers silently.",
+    "acceptance": "Required checks and task acceptance criteria pass; no blocking findings. Scores are diagnostic only."
   },
-
   "defaults": {
-    "_note": "Applied to every dispatch unless the prompt names a capability that needs otherwise.",
-    "no_mcp": true,
+    "_note": "Preserve effective permissions and user configuration; enable only approved capabilities where selective configuration is supported.",
+    "no_mcp": false,
     "read_only_skips_worktree": true
+  },
+  "sources": {
+    "checked_at": "2026-09-09",
+    "codex": [
+      "https://developers.openai.com/api/docs/models/gpt-5.6-luna",
+      "https://developers.openai.com/api/docs/models/gpt-5.6-sol",
+      "https://developers.openai.com/api/docs/guides/latest-model"
+    ],
+    "claude": [
+      "https://code.claude.com/docs/en/model-config"
+    ]
   }
 }