@brunosps00/dev-workflow 0.11.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
 
@@ -183,6 +183,34 @@ A **constitution** is a declarative list of principles your team commits to (e.g
 
 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 |
@@ -207,6 +235,8 @@ your-project/
 │   ├── references/        # Reference documentation
 │   ├── scripts/           # Utility scripts
 │   └── 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)
@@ -239,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
 
@@ -284,10 +314,23 @@ 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
 
 MIT

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
@@ -144,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

@@ -60,6 +60,48 @@ function copyDir(srcDir, destDir, force = false, overridesDir = null) {
   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',
@@ -71,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.11.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"

package/scaffold/en/agent-instructions.md

@@ -0,0 +1,68 @@
+<!-- dev-workflow:start -->
+# dev-workflow — AI Agent Instructions
+
+This project uses [`@brunosps00/dev-workflow`](https://www.npmjs.com/package/@brunosps00/dev-workflow) (`dw-*` commands) for structured AI-driven development. The commands compose into a PRD → TechSpec → Tasks → Implement → Review → Commit → PR pipeline with hard gates for security, constitution compliance, and verification.
+
+**The whole point of this file:** when the user states an intent that matches the Trigger Map below, run the matching `dw-*` command **without asking permission first** — unless the change is genuinely trivial (see Escape Hatches).
+
+## Trigger Map
+
+| User intent (literal or paraphrased) | Auto-trigger |
+|--------------------------------------|--------------|
+| "Implement X" / "Build Y" / "Add feature Z" / "I need ..." / "Create ..." | `/dw-autopilot "X"` |
+| Pasted error / "X is broken" / "Bug in Y" / failing test screenshot | `/dw-bugfix "X"` |
+| "Run this task" (with task ID) | `/dw-run-task <ID>` |
+| "Run all pending tasks" / "Execute the plan" | `/dw-run-plan` |
+| "Review my PR" / "Check code quality" / "Is this ready to ship?" | `/dw-code-review` |
+| "Time to commit" / changes are validated and ready | `/dw-commit` |
+| "Open a PR" / "Ship this" | `/dw-generate-pr` |
+| "Write a PRD for X" / "Spec out Y" | `/dw-create-prd` |
+| "Design the architecture" / "Make the techspec" | `/dw-create-techspec` |
+| "Break this into tasks" | `/dw-create-tasks` |
+| "Where is X?" / "What uses Y?" / "How is Z structured?" | `/dw-intel "<question>"` |
+| "Audit our dependencies" / "Are we behind on packages?" | `/dw-deps-audit` |
+| "Scan for vulnerabilities" / "Security check" | `/dw-security-check` |
+| "QA this feature" / "Run the test plan" | `/dw-run-qa` |
+| "Fix the QA bugs" | `/dw-fix-qa` |
+
+**Priority:** when in doubt between two commands, `/dw-autopilot` is the safest default for any non-trivial feature request — it composes the rest.
+
+## Hard Gates (the commands enforce these — don't bypass)
+
+- **`.dw/constitution.md`**: principles with `severity: high` or `critical` block PRs / techspecs without an ADR justifying the deviation. Missing constitution? Commands auto-install defaults at `severity: info` (non-blocking) and continue — never blocks on absence.
+- **`.dw/spec/<prd>/tasks-validation.md`**: auto-generated at the end of `/dw-create-tasks`. Any FAIL dimension blocks user approval until resolved or explicitly overridden.
+- **Verification**: `/dw-generate-pr` requires a fresh `dw-verify` PASS (tests + lint + build) after the last edit.
+- **Security**: TS / Python / C# / Rust projects must pass `/dw-security-check` (Trivy + OWASP + lockfile audit) before the PR opens.
+
+## Escape Hatches — do NOT auto-trigger
+
+When any of these apply, answer directly and do **not** invoke a `dw-*` command:
+
+- One-line typo, rename, import sort, comment fix.
+- Pure exploration: "how does this work?", "show me X", "explain Y".
+- Aesthetic preference: "I prefer this style" — apply, don't run a pipeline.
+- User explicitly says "do this directly" / "skip autopilot" / "no need for a PRD" — honor it.
+- The conversation is already inside a `dw-*` flow (you're already executing tasks; don't start a new pipeline).
+
+## Workflow Reference
+
+```
+/dw-autopilot "wish"  ────►  Runs entire pipeline automatically
+                              (3 gates: PRD approval, Tasks approval, PR confirmation)
+
+  --- OR step-by-step ---
+
+/dw-brainstorm ─► /dw-create-prd ─► /dw-create-techspec ─► /dw-create-tasks
+                                                              │
+                                                              ▼
+/dw-commit + /dw-generate-pr ◄──── /dw-code-review ◄──── /dw-run-plan
+```
+
+Full command list and contextual help: `/dw-help`.
+
+## Editing this section
+
+This block lives between `<!-- dev-workflow:start -->` and `<!-- dev-workflow:end -->` markers. Anything you write **outside** these markers in `CLAUDE.md` / `AGENTS.md` is preserved on every `dev-workflow update`. Anything **inside** is refreshed from the package — your edits inside the block will be overwritten.
+
+To customize the trigger map permanently, copy the block content to outside the markers (or to a separate file like `.dw/agent-instructions-custom.md`) and edit there.
+<!-- dev-workflow:end -->

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

@@ -141,7 +141,7 @@ Present to the user:
 ### Step 7: Design Contract (Conditional)
 
 Evaluate whether tasks involve frontend:
-- **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `ui-ux-pro-max` skill is available
+- **YES** (run `/dw-redesign-ui`): if there are tasks with visual components AND the `dw-ui-discipline` skill is available
   - Generate the design contract in `.dw/spec/prd-[name]/design-contract.md`
   - Present a summary of the design contract to the user (palette, typography, mobile/desktop layout) as a visual checkpoint before proceeding
 - **NO** (skip to step 8): purely backend/infra tasks

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

@@ -41,7 +41,7 @@ digraph brainstorm_decision {
 When available in the project under `./.agents/skills/`, use these skills to enrich ideation:
 
 - `dw-council` (opt-in via `--council`): multi-advisor stress-test of the most promising options with mandatory steel-manning and concession tracking. **DO NOT invoke by default** — only when the flag is present or when consensus forms too quickly (false-consensus signal).
-- `ui-ux-pro-max`: use when brainstorming involves frontend, UI style direction, design system choices, or visual identity exploration
+- `dw-ui-discipline`: use when brainstorming involves frontend or UI direction — its hard-gate (scene sentence, surface job) is a generative forcing function during ideation, not just a review check
 - `vercel-react-best-practices`: use when brainstorming React/Next.js architecture or performance trade-offs
 - `security-review`: use when brainstorming touches auth, data handling, or security-sensitive features
 

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

@@ -18,7 +18,7 @@
     - `dw-debug-protocol`: **ALWAYS** — runs the bug through the six-step triage (Reproduce → Localize → Reduce → Fix Root Cause → Guard → Verify End-to-End). Stop-the-line discipline; root-cause over symptom; regression test committed in the same atomic commit. Non-reproducible bugs follow the instrument-first sub-protocol — no guess fixes without explicit acknowledgement.
     - `dw-verify`: **ALWAYS** — in Direct mode, invoked before committing the fix. The VERIFICATION REPORT must show the original bug symptom no longer reproduces (not just that tests pass).
     - `vercel-react-best-practices`: use when the bug affects React/Next.js and there is suspicion of render, hydration, fetching, waterfall, bundle, or re-render issues
-    - `webapp-testing`: use when the fix requires a reproducible E2E/retest flow in a web app
+    - `dw-testing-discipline`: use when the fix requires a reproducible E2E/retest flow in a web app — `references/playwright-recipes.md` for recipes, Iron Laws + 7 AI Gates for any test the fix adds, flaky-discipline if the bug surfaces intermittently.
     - `security-review`: use when the root cause touches auth, authorization, external input, upload, secrets, SQL, XSS, SSRF, or other sensitive surfaces
 
     ## Input Variables
@@ -159,7 +159,7 @@
     - Related error messages
     - Stack traces
     - Recently modified files
-    - If the bug is UI-related or depends on browser flow, supplement collection with `webapp-testing`
+    - If the bug is UI-related or depends on browser flow, supplement collection with `dw-testing-discipline` (playwright-recipes + three-workflow-patterns to pick the right verification mode)
 
     ### 3. Clarification Questions (MANDATORY - EXACTLY 3)
 
@@ -197,7 +197,7 @@
     - **Probable Cause**: Based on the evidence
     - **Affected Files**: List of files to modify
     - **Impact**: Other components that may be affected
-    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `webapp-testing`, or `security-review`
+    - **Skills used**: explicitly record if the analysis used `vercel-react-best-practices`, `dw-testing-discipline`, or `security-review`
 
     ### 4.1 Scope Checkpoint (MANDATORY)
 

package/scaffold/en/commands/dw-create-techspec.md

@@ -25,7 +25,7 @@
     - `dw-council` (opt-in via `--council`): multi-advisor debate on the primary architectural decision with steel-manning. **DO NOT invoke by default**.
     - `dw-source-grounding` (**ALWAYS**): every framework/library decision must follow Detect → Fetch → Implement → Cite. The techspec emits inline citations `[source: <url>, version: X.Y, retrieved: YYYY-MM-DD]` next to each architectural decision.
     - `vercel-react-best-practices`: use when defining frontend architecture for React/Next.js projects
-    - `ui-ux-pro-max`: use when defining design system decisions, color palettes, typography, and UI style for the TechSpec
+    - `dw-ui-discipline`: use when the TechSpec includes UI sections — enforces the 4-checkpoint hard-gate (brand authorities / surface job / state matrix / scene sentence), the 14 anti-slop patterns, and the WCAG 2.2 AA floor BEFORE design decisions land.
     - `security-review`: use when the feature touches auth, authorization, or sensitive data handling
 
     ## Codebase Intelligence