@brunosps00/dev-workflow 0.10.0 → 0.13.0

package/README.md

@@ -13,7 +13,7 @@ This will:
 2. Create `.dw/commands/` with 31 workflow commands
 3. Create `.dw/templates/` with document templates (PRD, TechSpec, Tasks, ADR, etc.)
 4. Create `.dw/rules/` (populated by `/dw-analyze-project`)
-5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `ui-ux-pro-max`, `security-review`, etc.) to `.agents/skills/`
+5. Install bundled skills (`dw-verify`, `dw-memory`, `dw-review-rigor`, `dw-ui-discipline`, `dw-testing-discipline`, `security-review`, etc.) to `.agents/skills/`
 6. Generate skill wrappers for Claude Code, Codex, Copilot, and OpenCode
 7. Configure MCP servers (Context7 + Playwright)
 
@@ -55,7 +55,7 @@ Executes all pending tasks via the `dw-execute-phase` bundled skill — gated by
 Analyzes and fixes bugs with automatic triage that distinguishes between bugs, feature requests, and excessive scope. Asks exactly 3 clarification questions before proposing a solution. Supports Direct mode (executes fix immediately) and Analysis mode (`--analysis`) that generates a document for the techspec/tasks pipeline.
 
 #### `/dw-redesign-ui`
-Audits existing frontend pages or components, proposes 2-3 design directions using `ui-ux-pro-max` (colors, typography, layout), waits for user approval, then implements the redesign following the project's CSS methodology. Framework-agnostic (React, Angular, Vue). Generates a design contract persisted for consistency across tasks.
+Audits existing frontend pages or components, then runs the `dw-ui-discipline` hard-gate (brand authorities or curated defaults, surface job sentence, complete state matrix, scene sentence) before proposing 2-3 design directions. Each direction self-checks against the 14 anti-slop patterns. WCAG 2.2 AA floor is non-negotiable at validation. Framework-agnostic (React, Angular, Vue). Generates a design contract persisted for consistency across tasks.
 
 ### Quality
 
@@ -158,6 +158,59 @@ Shortcuts:
   /dw-redesign-ui "target"     Visual redesign of a page or component
 ```
 
+## Constitution
+
+A **constitution** is a declarative list of principles your team commits to (e.g., "every state-changing endpoint requires server-side authorization", "every bug fix ships with a regression test"). It lives at `.dw/constitution.md` and complements `.dw/rules/`:
+
+| File | Type | Authored by |
+|------|------|-------------|
+| `.dw/rules/` | Analytical — describes what the code IS (observed patterns) | `/dw-analyze-project` |
+| `.dw/constitution.md` | Declarative — describes what the code SHOULD BE (committed principles) | `/dw-analyze-project` (Step 8) or auto-installed defaults |
+
+**How it works:**
+
+- `/dw-analyze-project` offers three paths: synthesize from observed patterns (with your approval), install canonical defaults, or skip.
+- If `/dw-create-prd`, `/dw-create-techspec`, or `/dw-code-review` run **without** a constitution, they auto-install the defaults template (10 canonical principles at `severity: info`), notify in chat, and continue. Ausência nunca bloqueia.
+- Once principles exist:
+  - `severity: info` → reported, never blocks.
+  - `severity: high` → blocks PR/techspec when violated, unless an ADR justifies the deviation.
+  - `severity: critical` → blocks plus requires reviewer sign-off in the ADR.
+- Defaults start at `info`; you promote severities as your team trusts enforcement.
+
+**Tasks consistency check.** At the end of `/dw-create-tasks`, a 5-dimension consistency check validates PRD ↔ TechSpec ↔ Tasks alignment (FR coverage, task grounding, test coverage, dependency DAG, constitution alignment) and writes `.dw/spec/prd-<feature>/tasks-validation.md`. Any FAIL blocks user approval until resolved or explicitly overridden.
+
+## Template Overrides
+
+Customize templates locally without losing dev-workflow updates. Drop a file at `.dw/templates/overrides/<name>.md`; the override is used in place of the bundled core template on every `update`. Subdirectories work too (e.g., `.dw/templates/overrides/functional-doc/e2e-runbook.md`). See `.dw/templates/overrides/README.md` (created on init) for the workflow and `diff` cadence guidance.
+
+## Auto-Trigger (CLAUDE.md / AGENTS.md)
+
+`dev-workflow init` seeds two files at the project root with the same content: `CLAUDE.md` (read by Claude Code) and `AGENTS.md` (read by Codex CLI, Copilot CLI, and OpenCode). Together they tell the agent **when to invoke each `dw-*` command without being explicitly asked**.
+
+**What's inside:**
+
+- **Trigger Map** — 15 mappings from user intent ("Implement X", "Bug in Y", "Review my PR", ...) to the `dw-*` command the agent should run. `/dw-autopilot` is the safest default for non-trivial feature requests.
+- **Hard Gates** — reminders that constitution violations (high/critical), missing `dw-verify` PASS, and security failures block downstream commands.
+- **Escape Hatches** — explicit cases where the agent should NOT auto-trigger (typos, exploration, aesthetic edits, user opt-out).
+
+**Why two files:** Claude Code, Codex, Copilot, and OpenCode all support agent-instruction conventions but use different filenames. Shipping both means every supported platform picks up the same trigger logic out of the box.
+
+**Why descriptions, too:** every `dw-*` command's description leads with `Trigger when <user signal>...` so the agent can pick the right one even without consulting the trigger map. Both mechanisms reinforce each other.
+
+**Merge-aware update.** The content lives between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->` markers. Anything you add **outside** the markers (your own house rules, project-specific guidelines) is preserved on every `dev-workflow update` — only the block inside is refreshed.
+
+```bash
+# After init, both files exist at project root
+ls CLAUDE.md AGENTS.md
+
+# Edit OUTSIDE the markers freely — survives updates
+echo "## My team's house rules" >> CLAUDE.md
+echo "..." >> CLAUDE.md
+
+# Run update — block is refreshed, your additions stay
+npx @brunosps00/dev-workflow update
+```
+
 ## Platform Support
 
 | Platform | Wrapper Location | Status |
@@ -176,10 +229,14 @@ your-project/
 ├── .dw/
 │   ├── commands/          # 30 workflow command files
 │   ├── templates/         # Document templates (PRD, TechSpec, etc.)
+│   │   └── overrides/     # Project-local template customizations (override > core)
 │   ├── rules/             # Project-specific rules (run /dw-analyze-project)
+│   ├── constitution.md    # Declarative principles (auto-installed when missing)
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
-│   └── spec/              # PRD directories created by commands
+│   └── spec/              # PRD directories — each contains tasks-validation.md
+├── CLAUDE.md              # Auto-trigger decision tree for Claude Code (merge-aware)
+├── AGENTS.md              # Same content for Codex / Copilot / OpenCode
 ├── .claude/
 │   ├── skills/            # Claude Code wrappers
 │   └── settings.json      # MCP servers (Context7, Playwright)
@@ -212,12 +269,12 @@ These are not slash commands — they are primitives other commands call to enfo
 
 | Skill | Description | Source | License |
 |-------|-------------|--------|---------|
-| **ui-ux-pro-max** | Design intelligence: 50+ styles, 161 color palettes, 57 font pairings, 99 UX guidelines across 10 stacks | [Next Level Builder](https://github.com/skills-sh) | MIT |
+| **dw-ui-discipline** | UI doctrine: 4-checkpoint hard-gate (brand authorities or curated defaults, surface job sentence, state matrix, scene sentence), 14 anti-slop patterns + 17 anti-defaults, WCAG 2.2 AA floor with verification recipes, 10 curated palette/font defaults for bootstrap | [pedronauck/skills](https://github.com/pedronauck/skills) `ui-craft` | MIT |
+| **dw-testing-discipline** | Testing doctrine: Six Iron Laws, 12 positive patterns, 25 anti-patterns across 5 families (Brittleness/Flakiness/Mock-misuse/Process/AI-specific), 7 mandatory AI agent gates, flaky discipline + SLOs, Playwright recipes, browser security-boundary patterns | [pedronauck/skills](https://github.com/pedronauck/skills) `testing-boss` + [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) | MIT |
 | **vercel-react-best-practices** | 67 React/Next.js performance optimization rules across 8 priority categories. Wraps the rules with `references/perf-discipline.md` (measure → identify → fix → verify → guard) so perf work is data-driven, not vibes-based | [Vercel Labs](https://github.com/vercel-labs/agent-skills) + [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) | MIT |
 | **security-review** | Systematic vulnerability review based on OWASP with confidence-based reporting | [OWASP Cheat Sheet Series](https://cheatsheetseries.owasp.org/) | CC BY-SA 4.0 |
 | **humanizer** | Detects and removes 24 AI writing patterns based on Wikipedia's "Signs of AI Writing" guide | [Wikipedia AI Writing Guide](https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing) | -- |
 | **remotion-best-practices** | 25+ rules for video creation in React with Remotion | [Remotion](https://www.remotion.dev/) | -- |
-| **webapp-testing** | Playwright-based browser testing toolkit for E2E validation and screenshots. Cross-cutting references: `security-boundary` (every byte from a browser is potentially attacker-controlled) and `three-workflow-patterns` (UI bugs vs network issues vs perf — distinct workflows, don't conflate) | [Playwright](https://playwright.dev/) + [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) | -- |
 
 ## Dependencies
 
@@ -257,7 +314,22 @@ After running `npx @brunosps00/dev-workflow init`:
 
 Codebase intelligence (`/dw-intel`, `/dw-map-codebase`, the `dw-codebase-intel` bundled skill) and phase execution patterns (the `dw-execute-phase` bundled skill, with its `plan-checker` and `executor` agents) were adapted from [`get-shit-done-cc`](https://github.com/gsd-build/get-shit-done) by gsd-build (MIT). Schemas (`stack.json`, `files.json`, `apis.json`, `deps.json`, `arch.md`), the goal-backward verification protocol, and the wave-based parallel execution pattern come from there. dev-workflow specifics: `.dw/` namespace instead of `.planning/`, agent-driven runtime instead of `gsd-sdk` CLI, integration with the rest of the `dw-*` command surface.
 
-Source-driven development, code simplification, debugging discipline, and git workflow patterns adapted from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT) into the bundled `dw-source-grounding`, `dw-simplification`, `dw-debug-protocol`, and `dw-git-discipline` skills. Performance-optimization workflow (`vercel-react-best-practices/references/perf-discipline.md`), API-design discipline (`dw-codebase-intel/references/api-design-discipline.md`), and browser-DevTools patterns (`webapp-testing/references/{security-boundary, three-workflow-patterns}`) also incorporated as enhancements to existing bundled skills.
+Source-driven development, code simplification, debugging discipline, and git workflow patterns adapted from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) by Addy Osmani (MIT) into the bundled `dw-source-grounding`, `dw-simplification`, `dw-debug-protocol`, and `dw-git-discipline` skills. Performance-optimization workflow (`vercel-react-best-practices/references/perf-discipline.md`) and API-design discipline (`dw-codebase-intel/references/api-design-discipline.md`) also incorporated as enhancements to existing bundled skills. Browser security-boundary and three-workflow-patterns (originally from `addyosmani/agent-skills/browser-devtools`) now live inside `dw-testing-discipline/references/`.
+
+Spec-Driven Development patterns — declarative constitution (`.dw/constitution.md`), cross-artifact consistency check (PRD ↔ TechSpec ↔ Tasks), and template override layer (`.dw/templates/overrides/`) — adapted from [`github/spec-kit`](https://github.com/github/spec-kit) by GitHub (MIT). dev-workflow specifics: embedded into existing commands instead of new slash commands, severity-graded enforcement (`info`/`high`/`critical`) with ADR-justified deviation as the escape hatch, ausência-of-constitution never blocks (auto-installs defaults and continues), and integration with the analytical `.dw/rules/` already produced by `/dw-analyze-project`.
+
+UI discipline (hard-gate, 14 anti-slop patterns, 17 anti-defaults, WCAG 2.2 AA floor) and testing doctrine (Six Iron Laws, 25 anti-patterns across 5 families, 7 AI agent gates, flaky discipline) adapted from [`pedronauck/skills`](https://github.com/pedronauck/skills) `ui-craft` and `testing-boss` (MIT) into the bundled `dw-ui-discipline` and `dw-testing-discipline` skills. dev-workflow specifics: 10 curated palette/font defaults bootstrap discipline when no design authority exists; Playwright recipes from earlier `webapp-testing` migrate into `dw-testing-discipline/references/playwright-recipes.md`; both skills wire into 11 commands across the pipeline.
+
+## Migration from v0.12.x
+
+The `dev-workflow update` command automatically removes the two replaced skills and installs the new ones — no manual action required:
+
+- `ui-ux-pro-max` → replaced by `dw-ui-discipline` (auto-removed on update)
+- `webapp-testing` → replaced by `dw-testing-discipline` (auto-removed on update)
+
+The cleanup also detects and removes any **orphan `dw-*` wrappers** in `.claude/skills/`, `.agents/skills/`, and `.opencode/commands/` whose names no longer exist in the current scaffold (e.g., commands removed in v0.10 like `dw-execute-phase`, `dw-quick` that may still have wrappers from older installs).
+
+If you had **custom edits** inside `.agents/skills/ui-ux-pro-max/` or `.agents/skills/webapp-testing/`, back them up before running update — the migrator removes the entire directory. If you customized templates instead, those live in `.dw/templates/overrides/` (introduced in v0.11) and are preserved.
 
 ## License
 

package/lib/constants.js

@@ -2,21 +2,21 @@ const COMMANDS = {
   en: [
     { name: 'dw-adr', description: 'Records an architectural decision and the trade-offs accepted, before they get lost.' },
     { 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: 'Takes a wish and runs the full PRD-to-PR pipeline, stopping only at three approval gates.' },
+    { name: 'dw-autopilot', description: 'Trigger when user asks to implement, build, create, or add a feature non-trivially. Runs full PRD-to-PR pipeline with three gates.' },
     { name: 'dw-brainstorm', description: 'Refines an idea using the product\'s existing features as ground truth, before any PRD.' },
-    { name: 'dw-bugfix', description: 'Triages a bug report, asks three sharp questions, then fixes it or routes it to a PRD.' },
-    { name: 'dw-code-review', description: 'Level-3 review against PRD, rules, tests, and security; saves a verdict you can act on.' },
-    { name: 'dw-commit', description: 'Groups changes by intent and writes Conventional Commits messages that read clean.' },
-    { name: 'dw-create-prd', description: 'Writes a PRD after asking the questions that would otherwise haunt the techspec later.' },
-    { name: 'dw-create-tasks', description: 'Breaks the PRD and techspec into tasks small enough to ship one at a time.' },
-    { name: 'dw-create-techspec', description: 'Translates a finished PRD into a techspec the team can actually build from.' },
+    { 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-code-review', description: 'Trigger when user asks to review code, check quality, or verify PR readiness. Level-3 review with APPROVED/REJECTED verdict.' },
+    { name: 'dw-commit', description: 'Trigger when implementation is complete and pending changes need to be committed. Atomic commits with Conventional Commits messages.' },
+    { name: 'dw-create-prd', description: 'Trigger when user has a feature idea and needs a written spec before implementation. Asks the questions a techspec would otherwise inherit.' },
+    { name: 'dw-create-tasks', description: 'Trigger after PRD + techspec exist and the team is ready to break work into shippable units. Includes a 5-dimension consistency check.' },
+    { name: 'dw-create-techspec', description: 'Trigger when a PRD is approved and architecture must be defined before tasks. Adds framework choices, test strategy, and constitution alignment.' },
     { name: 'dw-deep-research', description: 'Researches a topic across sources, tracks citations, and flags claims that don\'t check out.' },
     { name: 'dw-deps-audit', description: 'Finds outdated and supply-chain-compromised packages, drafts a per-package update plan, and runs scoped QA after each upgrade.' },
     { 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-fix-qa', description: 'Fixes bugs found in QA and retests them with screenshot evidence until they stay fixed.' },
     { name: 'dw-functional-doc', description: 'Maps screens and user flows into a functional doc, validated end-to-end with Playwright.' },
-    { name: 'dw-generate-pr', description: 'Pushes the branch and opens a PR with a body that explains what changed and how to test it.' },
+    { name: 'dw-generate-pr', description: 'Trigger when commits are ready and the branch needs a PR. Pushes branch and opens PR with summary + test plan + hard verify gate.' },
     { name: 'dw-help', description: 'Lists every command and the flows that connect them. Pass a keyword for a contextual shortcut.' },
     { name: 'dw-intel', description: 'Answers questions about the codebase by querying .dw/intel/ (built by /dw-map-codebase) with .dw/rules/ and grep as fallbacks.' },
     { name: 'dw-map-codebase', description: 'Builds a queryable index in .dw/intel/ (stack, files, apis, deps, arch) so other commands stop re-exploring the codebase.' },
@@ -25,30 +25,30 @@ const COMMANDS = {
     { name: 'dw-refactoring-analysis', description: 'Catalogs code smells in Fowler\'s vocabulary and ranks them by impact, P0 to P3.' },
     { name: 'dw-review-implementation', description: 'Maps every PRD requirement to the code that delivers it, then runs /dw-code-review for the Level 3 quality layer.' },
     { name: 'dw-revert-task', description: 'Reverts the commits of one task, but only after checking nothing downstream depends on it.' },
-    { name: 'dw-run-plan', description: 'Runs every pending task in order, with PRD-compliance review at the end.' },
+    { name: 'dw-run-plan', description: 'Trigger when user wants to execute all pending tasks. Goal-backward plan check, then wave-based parallel execution with atomic commits.' },
     { name: 'dw-run-qa', description: 'Drives the browser to test happy paths, edge cases, and accessibility, with screenshot proof.' },
-    { name: 'dw-run-task', description: 'Implements one task, runs the validation that comes with it, and commits when it passes.' },
+    { name: 'dw-run-task', description: 'Trigger when user wants to execute one specific task by ID. Implements, validates with mandatory tests, commits when passing.' },
     { name: 'dw-security-check', description: 'OWASP review plus Trivy CVE/secret/IaC scan for TS, Python, C#, or Rust. CRITICAL or HIGH blocks the PR.' },
     { 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.' },
     { 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: 'Pega um desejo e roda do PRD ao PR, parando so em tres gates de aprovacao.' },
+    { name: 'dw-autopilot', description: 'Trigger quando usuario pede pra implementar, criar ou adicionar uma feature nao-trivial. Roda pipeline completo PRD-ao-PR com tres gates.' },
     { name: 'dw-brainstorm', description: 'Refina uma ideia usando as features existentes do produto como base, antes de qualquer PRD.' },
-    { name: 'dw-bugfix', description: 'Tria um bug, faz tres perguntas certas, e entao corrige ou redireciona para PRD.' },
-    { name: 'dw-code-review', description: 'Review Nivel 3 contra PRD, rules, testes e seguranca; gera um veredicto acionavel.' },
-    { name: 'dw-commit', description: 'Agrupa as mudancas por intencao e escreve mensagens Conventional Commits limpas.' },
-    { name: 'dw-create-prd', description: 'Escreve um PRD depois de fazer as perguntas que assombrariam o techspec depois.' },
-    { name: 'dw-create-tasks', description: 'Quebra PRD e techspec em tasks pequenas o suficiente para entregar uma de cada vez.' },
-    { name: 'dw-create-techspec', description: 'Traduz um PRD pronto em um techspec que o time consegue construir de fato.' },
+    { 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-code-review', description: 'Trigger quando usuario pede pra revisar codigo, checar qualidade ou validar prontidao pra PR. Review Nivel 3 com veredicto APROVADO/REPROVADO.' },
+    { name: 'dw-commit', description: 'Trigger quando implementacao esta completa e ha mudancas pendentes pra commit. Commits atomicos com mensagens Conventional Commits.' },
+    { name: 'dw-create-prd', description: 'Trigger quando usuario tem ideia de feature e precisa de spec escrito antes de implementar. Faz as perguntas que o techspec herdaria.' },
+    { name: 'dw-create-tasks', description: 'Trigger depois que PRD + techspec existem e o time vai quebrar em unidades entregaveis. Inclui consistency check em 5 dimensoes.' },
+    { name: 'dw-create-techspec', description: 'Trigger quando PRD esta aprovado e arquitetura precisa ser definida antes das tasks. Adiciona escolhas de framework, testes e alinhamento de constitution.' },
     { name: 'dw-deep-research', description: 'Pesquisa um topico em varias fontes, rastreia citacoes e marca o que nao confere.' },
     { name: 'dw-deps-audit', description: 'Encontra pacotes desatualizados e comprometidos por supply-chain, monta plano de update por pacote e roda QA do que foi afetado.' },
     { 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-fix-qa', description: 'Corrige bugs do QA e retesta com evidencia em screenshot ate ficarem estaveis.' },
     { name: 'dw-functional-doc', description: 'Mapeia telas e fluxos em um dossie funcional, validado E2E com Playwright.' },
-    { name: 'dw-generate-pr', description: 'Faz push da branch e abre um PR com corpo explicando o que mudou e como testar.' },
+    { name: 'dw-generate-pr', description: 'Trigger quando commits estao prontos e branch precisa de PR. Push da branch e abre PR com summary + test plan + hard verify gate.' },
     { name: 'dw-help', description: 'Lista todos os commands e os fluxos que os conectam. Passe uma keyword para atalho contextual.' },
     { name: 'dw-intel', description: 'Responde perguntas sobre o codebase consultando .dw/intel/ (do /dw-map-codebase) com .dw/rules/ e grep como fallback.' },
     { name: 'dw-map-codebase', description: 'Constroi um indice queryable em .dw/intel/ (stack, files, apis, deps, arch) para outros comandos pararem de re-explorar o codebase.' },
@@ -57,9 +57,9 @@ const COMMANDS = {
     { name: 'dw-refactoring-analysis', description: 'Cataloga code smells no vocabulario de Fowler e ranqueia por impacto, P0 a P3.' },
     { name: 'dw-review-implementation', description: 'Mapeia cada requisito do PRD ao codigo que o entrega, e roda /dw-code-review para a camada de qualidade Nivel 3.' },
     { name: 'dw-revert-task', description: 'Reverte os commits de uma task, mas so depois de checar que nada a frente depende dela.' },
-    { name: 'dw-run-plan', description: 'Roda todas as tasks pendentes em ordem, com review de PRD compliance no final.' },
+    { name: 'dw-run-plan', description: 'Trigger quando usuario quer executar todas as tasks pendentes. Plan check goal-backward, depois execucao paralela em ondas com commits atomicos.' },
     { name: 'dw-run-qa', description: 'Pilota o browser para testar fluxo feliz, edge cases e acessibilidade, com screenshot.' },
-    { name: 'dw-run-task', description: 'Implementa uma task, roda a validacao que vem com ela, e commita quando passa.' },
+    { name: 'dw-run-task', description: 'Trigger quando usuario quer executar uma task especifica por ID. Implementa, valida com testes obrigatorios, commita quando passa.' },
     { name: 'dw-security-check', description: 'Review OWASP + scan Trivy CVE/secret/IaC para TS, Python, C# ou Rust. CRITICAL ou HIGH bloqueia PR.' },
     { name: 'dw-update', description: 'Atualiza o dev-workflow para o release mais recente no npm, com snapshot para rollback.' },
   ],

package/lib/init.js

@@ -1,10 +1,11 @@
 const path = require('path');
 const { COMMANDS } = require('./constants');
-const { ensureDir, copyDir, writeFile, log } = require('./utils');
+const { ensureDir, copyDir, writeFile, upsertDelimitedBlock, log } = require('./utils');
 const { selectLanguage } = require('./prompts');
 const { generateWrappers } = require('./wrappers');
 const { installMCPs } = require('./mcp');
 const { migrate: migrateGsd } = require('./migrate-gsd');
+const { migrate: migrateSkills } = require('./migrate-skills');
 
 const SCAFFOLD_DIR = path.join(__dirname, '..', 'scaffold');
 
@@ -20,8 +21,10 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   console.log(`  ${'='.repeat(40)}\n`);
 
   // 0. GSD migration (idempotent; only runs if legacy GSD artifacts are detected)
+  // 0.1. Skill migration: removed bundled skills + orphan dw-* wrappers (idempotent)
   if (isUpdate) {
     migrateGsd(projectRoot);
+    migrateSkills(projectRoot);
   }
 
   // 1. Select language
@@ -48,18 +51,35 @@ async function run({ force = false, lang = null, mode = 'init' }) {
   totalOverwritten += cmdResults.overwritten;
   console.log(`    ${cmdResults.created} created, ${cmdResults.skipped} skipped, ${cmdResults.overwritten} overwritten\n`);
 
-  // 3. Copy templates
+  // 3. Copy templates (override-aware: .dw/templates/overrides/<name> wins over scaffold core)
   console.log('  Templates:');
+  const templatesDir = path.join(projectRoot, '.dw', 'templates');
+  const overridesDir = path.join(templatesDir, 'overrides');
   const tplResults = copyDir(
     path.join(langDir, 'templates'),
-    path.join(projectRoot, '.dw', 'templates'),
-    managedForce
+    templatesDir,
+    managedForce,
+    overridesDir
   );
   totalCreated += tplResults.created;
   totalSkipped += tplResults.skipped;
   totalOverwritten += tplResults.overwritten;
   console.log(`    ${tplResults.created} created, ${tplResults.skipped} skipped, ${tplResults.overwritten} overwritten\n`);
 
+  // 3.1. Seed .dw/templates/overrides/ with README on first init (never overwritten)
+  ensureDir(overridesDir);
+  const overridesReadmeSrc = path.join(SCAFFOLD_DIR, 'templates-overrides-readme.md');
+  const overridesReadmeDest = path.join(overridesDir, 'README.md');
+  if (require('fs').existsSync(overridesReadmeSrc)) {
+    const ovrStatus = writeFile(
+      overridesReadmeDest,
+      require('fs').readFileSync(overridesReadmeSrc, 'utf-8'),
+      false
+    );
+    if (ovrStatus === 'created') totalCreated++;
+    else totalSkipped++;
+  }
+
   // 3.5. Copy references (language-specific)
   const refsSrcDir = path.join(langDir, 'references');
   if (require('fs').existsSync(refsSrcDir)) {
@@ -127,6 +147,26 @@ async function run({ force = false, lang = null, mode = 'init' }) {
     console.log(`    ${skillsResults.created} created, ${skillsResults.skipped} skipped, ${skillsResults.overwritten} overwritten\n`);
   }
 
+  // 5.7. Install CLAUDE.md + AGENTS.md with auto-trigger decision tree
+  // Both files receive the same content (Claude Code reads CLAUDE.md; Codex/Copilot/OpenCode
+  // converge on AGENTS.md). Merge-aware: user edits outside the dev-workflow markers are preserved.
+  const agentInstructionsSrc = path.join(langDir, 'agent-instructions.md');
+  if (require('fs').existsSync(agentInstructionsSrc)) {
+    console.log('  Agent instructions:');
+    const blockContent = require('fs').readFileSync(agentInstructionsSrc, 'utf-8');
+    const startMarker = '<!-- dev-workflow:start -->';
+    const endMarker = '<!-- dev-workflow:end -->';
+    for (const fileName of ['CLAUDE.md', 'AGENTS.md']) {
+      const target = path.join(projectRoot, fileName);
+      const status = upsertDelimitedBlock(target, blockContent, startMarker, endMarker);
+      log(status === 'unchanged' ? 'skipped' : (status === 'created' ? 'created' : 'overwritten'), target);
+      if (status === 'created') totalCreated++;
+      else if (status === 'updated') totalOverwritten++;
+      else totalSkipped++;
+    }
+    console.log();
+  }
+
   // 6. Create .opencode/package.json
   const opencodePackageJson = path.join(projectRoot, '.opencode', 'package.json');
   const opencodeContent = JSON.stringify({ dependencies: { '@opencode-ai/plugin': '1.2.17' } }, null, 2) + '\n';

package/lib/migrate-skills.js

@@ -0,0 +1,129 @@
+const fs = require('fs');
+const path = require('path');
+const { COMMANDS } = require('./constants');
+const removedSkills = require('./removed-bundled-skills');
+
+/**
+ * Cleanup-on-update for dev-workflow.
+ *
+ * Two complementary scans:
+ *
+ * 1. Removed bundled skills (data-driven from `removed-bundled-skills.js`):
+ *    Detects `.agents/skills/<name>/` directories that match the manifest of
+ *    skills removed in past releases. Removes them and notes the replacement.
+ *
+ * 2. Orphan command wrappers (state-comparison vs `constants.js`):
+ *    Lists `.claude/skills/dw-*`, `.agents/skills/dw-*`, and
+ *    `.opencode/commands/dw-*.md` wrappers on disk. Any `dw-*` wrapper whose
+ *    base name is NOT present in the current `COMMANDS[lang]` is removed.
+ *
+ * Only touches names with prefix `dw-` (or names explicitly listed in the
+ * manifest). Never touches third-party skills/commands.
+ *
+ * Idempotent: silent when nothing to clean.
+ *
+ * Run automatically from lib/init.js when mode === 'update'.
+ */
+function migrate(projectRoot) {
+  const removed = scanRemovedBundledSkills(projectRoot);
+  const orphans = scanOrphanCommandWrappers(projectRoot);
+
+  if (removed.length === 0 && orphans.length === 0) {
+    return null; // silent — nothing to clean
+  }
+
+  console.log('\n  Skill migration:');
+
+  for (const entry of removed) {
+    console.log(
+      `    \x1b[33m-\x1b[0m [v${entry.removedIn}] Removing legacy skill ${entry.name} (replaced by ${entry.replacedBy})`
+    );
+    rmRecursive(entry.path);
+  }
+
+  for (const entry of orphans) {
+    const rel = path.relative(projectRoot, entry.path);
+    console.log(
+      `    \x1b[33m-\x1b[0m [orphan] Removing wrapper ${rel} — command no longer exists`
+    );
+    rmRecursive(entry.path);
+  }
+
+  console.log();
+  return { removed: removed.length, orphans: orphans.length };
+}
+
+function scanRemovedBundledSkills(projectRoot) {
+  const matches = [];
+  const agentsSkillsDir = path.join(projectRoot, '.agents', 'skills');
+
+  if (!fs.existsSync(agentsSkillsDir)) return matches;
+
+  for (const entry of removedSkills) {
+    const target = path.join(agentsSkillsDir, entry.name);
+    if (fs.existsSync(target)) {
+      matches.push({ ...entry, path: target });
+    }
+  }
+  return matches;
+}
+
+function scanOrphanCommandWrappers(projectRoot) {
+  const orphans = [];
+
+  // Build the canonical "known names" set:
+  //  - Commands from constants.js (en + pt-br union) — these become wrappers.
+  //  - Bundled skills from scaffold/skills/ — these are copied verbatim into
+  //    .agents/skills/ and .claude/skills/ alongside wrappers. They're NOT
+  //    orphans even though they share the .agents/skills/ directory with
+  //    command wrappers.
+  const canonical = new Set();
+  for (const lang of Object.keys(COMMANDS)) {
+    for (const cmd of COMMANDS[lang]) {
+      canonical.add(cmd.name);
+    }
+  }
+  const scaffoldSkillsDir = path.join(__dirname, '..', 'scaffold', 'skills');
+  if (fs.existsSync(scaffoldSkillsDir)) {
+    for (const entry of fs.readdirSync(scaffoldSkillsDir, { withFileTypes: true })) {
+      if (entry.isDirectory()) canonical.add(entry.name);
+    }
+  }
+
+  // Scan locations
+  const locations = [
+    { dir: path.join(projectRoot, '.claude', 'skills'), type: 'directory' },
+    { dir: path.join(projectRoot, '.agents', 'skills'), type: 'directory' },
+    { dir: path.join(projectRoot, '.opencode', 'commands'), type: 'file', suffix: '.md' },
+  ];
+
+  for (const loc of locations) {
+    if (!fs.existsSync(loc.dir)) continue;
+    const entries = fs.readdirSync(loc.dir, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const name = loc.suffix ? entry.name.replace(loc.suffix, '') : entry.name;
+
+      // Only scan dw-* prefix
+      if (!name.startsWith('dw-')) continue;
+
+      // Skip if it matches a canonical command OR a bundled skill
+      if (canonical.has(name)) continue;
+
+      // Match the expected entry type (directory or file)
+      const isExpected = loc.type === 'directory' ? entry.isDirectory() : entry.isFile();
+      if (!isExpected) continue;
+
+      orphans.push({ path: path.join(loc.dir, entry.name) });
+    }
+  }
+
+  return orphans;
+}
+
+function rmRecursive(target) {
+  if (!fs.existsSync(target)) return;
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+module.exports = { migrate };

package/lib/removed-bundled-skills.js

@@ -0,0 +1,16 @@
+/**
+ * Manifest of bundled skills removed in past releases.
+ *
+ * APPEND-ONLY: never modify or remove entries. A removed skill stays in
+ * this manifest forever so old installs still get cleaned up when the
+ * user runs `dev-workflow update`.
+ *
+ * Each entry triggers `.agents/skills/<name>/` removal during update
+ * (see lib/migrate-skills.js).
+ */
+module.exports = [
+  // v0.13.0 — replaced TASTE catalog (161 palettes) with discipline (hard-gate + anti-slop + WCAG floor)
+  { name: 'ui-ux-pro-max', removedIn: '0.13.0', replacedBy: 'dw-ui-discipline' },
+  // v0.13.0 — replaced Playwright recipes wrapper with full testing doctrine (Iron Laws + 25 anti-patterns + 7 AI gates)
+  { name: 'webapp-testing', removedIn: '0.13.0', replacedBy: 'dw-testing-discipline' },
+];

package/lib/uninstall.js

@@ -56,13 +56,17 @@ function run() {
 
   // 3. Remove bundled skills from .agents/skills/
   console.log('  Bundled skills:');
+  // Currently-active bundled skills. If a skill is removed in a future release,
+  // add it to lib/removed-bundled-skills.js (append-only manifest used by
+  // migrate-skills.js during `dev-workflow update`); this list is just for
+  // wholesale uninstall.
   const bundledSkills = [
+    'dw-ui-discipline',
+    'dw-testing-discipline',
     'humanizer',
     'remotion-best-practices',
     'security-review',
-    'ui-ux-pro-max',
     'vercel-react-best-practices',
-    'webapp-testing',
   ];
   for (const skill of bundledSkills) {
     removeDir(path.join(projectRoot, '.agents', 'skills', skill));

package/lib/utils.js

@@ -29,7 +29,7 @@ function writeFile(filePath, content, force = false) {
   return exists ? 'overwritten' : 'created';
 }
 
-function copyDir(srcDir, destDir, force = false) {
+function copyDir(srcDir, destDir, force = false, overridesDir = null) {
   const results = { created: 0, skipped: 0, overwritten: 0 };
 
   if (!fs.existsSync(srcDir)) {
@@ -40,14 +40,19 @@ function copyDir(srcDir, destDir, force = false) {
   for (const entry of entries) {
     const srcPath = path.join(srcDir, entry.name);
     const destPath = path.join(destDir, entry.name);
+    const overridePath = overridesDir ? path.join(overridesDir, entry.name) : null;
 
     if (entry.isDirectory()) {
-      const sub = copyDir(srcPath, destPath, force);
+      const subOverrides = overridePath && fs.existsSync(overridePath) ? overridePath : null;
+      const sub = copyDir(srcPath, destPath, force, subOverrides);
       results.created += sub.created;
       results.skipped += sub.skipped;
       results.overwritten += sub.overwritten;
     } else {
-      const status = copyFile(srcPath, destPath, force);
+      // Override wins: copy from override path so dest reflects user customization.
+      // Always force-copy overrides so a manual edit to overrides/X.md propagates to templates/X.md on next update.
+      const effectiveSrc = overridePath && fs.existsSync(overridePath) ? overridePath : srcPath;
+      const status = copyFile(effectiveSrc, destPath, effectiveSrc === overridePath ? true : force);
       results[status]++;
     }
   }
@@ -55,6 +60,48 @@ function copyDir(srcDir, destDir, force = false) {
   return results;
 }
 
+/**
+ * Upsert a delimited block inside an existing file.
+ *
+ * - If the file does not exist, creates it with the new block content.
+ * - If the file exists with markers, replaces only the content between markers.
+ * - If the file exists WITHOUT markers, appends the block (preserves existing content).
+ *
+ * Returns 'created' | 'updated' | 'unchanged'.
+ */
+function upsertDelimitedBlock(filePath, blockContent, startMarker, endMarker) {
+  const exists = fileExists(filePath);
+  ensureDir(path.dirname(filePath));
+
+  // The block content already includes its own start/end markers (so the scaffold
+  // file can be read verbatim). Validate that.
+  if (!blockContent.includes(startMarker) || !blockContent.includes(endMarker)) {
+    throw new Error(`Block content for ${filePath} is missing its markers`);
+  }
+
+  if (!exists) {
+    fs.writeFileSync(filePath, blockContent.endsWith('\n') ? blockContent : blockContent + '\n', 'utf-8');
+    return 'created';
+  }
+
+  const current = fs.readFileSync(filePath, 'utf-8');
+  const hasMarkers = current.includes(startMarker) && current.includes(endMarker);
+
+  if (!hasMarkers) {
+    const separator = current.endsWith('\n') ? '\n' : '\n\n';
+    const next = current + separator + (blockContent.endsWith('\n') ? blockContent : blockContent + '\n');
+    fs.writeFileSync(filePath, next, 'utf-8');
+    return 'updated';
+  }
+
+  const before = current.slice(0, current.indexOf(startMarker));
+  const after = current.slice(current.indexOf(endMarker) + endMarker.length);
+  const next = before + blockContent.trim() + after;
+  if (next === current) return 'unchanged';
+  fs.writeFileSync(filePath, next, 'utf-8');
+  return 'updated';
+}
+
 function log(status, filePath) {
   const icons = {
     created: '\x1b[32m+\x1b[0m',
@@ -66,4 +113,4 @@ function log(status, filePath) {
   console.log(`  ${icon} ${relative} [${status}]`);
 }
 
-module.exports = { ensureDir, fileExists, copyFile, writeFile, copyDir, log };
+module.exports = { ensureDir, fileExists, copyFile, writeFile, copyDir, upsertDelimitedBlock, log };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunosps00/dev-workflow",
-  "version": "0.10.0",
+  "version": "0.13.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"