wizz-method 1.4.1 → 1.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 # Wizz Method
 
-**O método de agência orientado por IA, em português.** Um maestro lê seu pedido, descobre a área e chama o agente certo. Você fala normal, ele organiza o trabalho.
+**O método de agência orientado por IA, em português.** Um router lê seu pedido, descobre a área e chama o agente certo. Quando o trabalho cruza áreas, o Maestro organiza a sequência. Você fala normal, ele estrutura o trabalho.
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.12.0-brightgreen)](https://nodejs.org)
@@ -10,7 +10,7 @@
 
 Cansado de reexplicar o contexto a cada conversa com a IA? O Wizz Method dá ao seu time uma estrutura fixa: agentes especializados (dev, design, copy, SEO, growth, ads, memória), linguagem fácil e resumida, e um encerramento padrão em toda resposta (**✅ o que fiz**, **➡️ próximo passo**, **🎯 comando**). Tudo em PT-BR, dentro do seu assistente de IA favorito.
 
-O ponto de entrada é um só. Invoque o `wizz-maestro`, mande o pedido, ele despacha para quem resolve.
+O ponto de entrada técnico é o `wizz-router`: ele faz a triagem e manda pedidos leves direto ao agente da área, ou chama o `wizz-maestro` quando precisa de orquestração.
 
 ## Os 7 agentes
 
@@ -32,6 +32,8 @@ A camada Wizz vale para todos os agentes: encerramento padrão (✅/➡️/🎯)
 
 **Pré-requisitos**: [Node.js](https://nodejs.org) v20.12+ · [Python](https://www.python.org) 3.10+ · [uv](https://docs.astral.sh/uv/)
 
+**Plataformas suportadas**: macOS, Linux e WSL (Windows Subsystem for Linux). Windows nativo (cmd.exe/PowerShell sem WSL) não é suportado — algumas CLIs opcionais do registry (`claude-video`, `voicebox`, `distribb`, `arcads`) usam checks POSIX (`test -d`, `$HOME`) e o installer as filtra fora dessa plataforma em vez de oferecer algo que nunca vai detectar como instalado.
+
 Instale o método no seu projeto:
 
 ```bash
@@ -46,7 +48,7 @@ Em seguida, rode a personalização Wizz. Ela pergunta o idioma de comunicação
 node <caminho-do-wizz-method>/src/modules/wizz/scripts/wizz-init.mjs .
 ```
 
-Por fim, invoque o `wizz-maestro` e mande seu pedido.
+Por fim, invoque o `wizz-router` e mande seu pedido. Se preferir começar simples, chamar o `wizz-maestro` também funciona para trabalhos multi-área, mas o router é a entrada canônica.
 
 **Instalação não-interativa** (para CI/CD):
 
@@ -69,4 +71,4 @@ O Wizz Method é um fork independente do [BMAD Method](https://github.com/bmad-c
 
 Licença MIT, veja [LICENSE](LICENSE) para detalhes.
 
-**Wizz** e **WIZZ-METHOD** são marcas da BMad Code, LLC. **Wizz Method** é marca própria da Wizz! comms. A licença MIT cobre apenas o código. Veja [TRADEMARK.md](TRADEMARK.md).
+**BMad** e **BMAD-METHOD** são marcas da BMad Code, LLC. **Wizz Method** é marca própria da Wizz! comms. A licença MIT cobre apenas o código. Veja [TRADEMARK.md](TRADEMARK.md).

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",
@@ -25,6 +25,21 @@
     "wizz": "tools/installer/wizz-cli.js",
     "wizz-method": "tools/installer/wizz-cli.js"
   },
+  "files": [
+    "tools/installer",
+    "src/bmm-skills",
+    "src/core-skills",
+    "src/modules",
+    "src/scripts",
+    "src/skills-lib",
+    "!src/skills-lib/huashu-design/assets/**/*.mp3",
+    "!src/skills-lib/canvas-design/canvas-fonts/**/*.ttf",
+    "web-bundles",
+    "skills-registry.yaml",
+    "wizz-modules.yaml",
+    "removals.txt",
+    "tools/fetch-assets.mjs"
+  ],
   "scripts": {
     "docs:build": "node tools/build-docs.mjs",
     "docs:dev": "astro dev --root website",
@@ -32,6 +47,8 @@
     "docs:preview": "astro preview --root website",
     "docs:validate-links": "node tools/validate-doc-links.js",
     "docs:validate-sidebar": "node tools/validate-sidebar-order.js",
+    "eval:routing": "node evals/routing/run-routing-eval.mjs",
+    "eval:routing:llm": "node evals/routing/run-routing-eval.mjs --llm",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix:staged": "prettier --write",
@@ -40,19 +57,38 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:urls && npm run validate:refs && npm run validate:method-refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
+    "sync:check": "node tools/sync-check.mjs",
     "sync:global": "node tools/sync-global.mjs",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:mcp && npm run test:cli && npm run test:deps && npm run test:hooks && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:channels && npm run test:mcp && npm run test:env-vars && npm run test:cli && npm run test:deps && npm run test:dispatch-rule && npm run test:hooks && npm run test:quickupdate && npm run test:registry-schema && npm run test:method-refs-allowlist && npm run test:rtk-hook && npm run test:network-retry && npm run test:sync-check && npm run test:resolver && npm run test:fetch-assets && npm run test:install-smoke && npm run test:trace-report && npm run test:rehype-plugins && npm run test:workflow-path-regex && npm run test:preflight-tools-check && npm run lint && npm run lint:md && npm run format:check && npm run sync:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:cli": "node test/test-cli-config.js",
     "test:deps": "node test/test-deps-cache.js",
+    "test:dispatch-rule": "node test/test-dispatch-rule-consistency.js",
+    "test:env-vars": "node test/test-env-vars.js",
+    "test:fetch-assets": "node test/test-fetch-assets.js",
     "test:hooks": "node test/test-router-hook.js",
     "test:install": "node test/test-installation-components.js",
+    "test:install-smoke": "node test/test-install-smoke.js",
+    "test:install-smoke-mcp": "node test/test-install-smoke-mcp.js",
     "test:mcp": "node test/test-mcp-config.js",
+    "test:method-refs-allowlist": "node test/test-method-refs-allowlist.js",
+    "test:network-retry": "node test/test-network-retry.js",
+    "test:preflight-tools-check": "node test/test-preflight-tools-check.js",
+    "test:quickupdate": "node test/test-quick-update-gate.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:registry-schema": "node test/test-registry-schema.js",
+    "test:rehype-plugins": "node test/test-rehype-plugins.mjs",
+    "test:resolver": "node test/test-resolve-customization.js",
+    "test:rtk-hook": "node test/test-rtk-hook.js",
+    "test:sync-check": "node test/test-sync-check.js",
+    "test:trace-report": "node test/test-trace-report.js",
     "test:urls": "node test/test-parse-source-urls.js",
+    "test:workflow-path-regex": "node test/test-workflow-path-regex.js",
+    "validate:method-refs": "node tools/validate-method-refs.js --strict",
     "validate:refs": "node tools/validate-file-refs.js --strict",
+    "validate:registry-schema": "node tools/validate-registry-schema.js --strict",
     "validate:skills": "node tools/validate-skills.js --strict",
     "wizz:install": "node tools/installer/wizz-cli.js install",
     "wizz:uninstall": "node tools/installer/wizz-cli.js uninstall"

package/skills-registry.yaml

@@ -27,6 +27,15 @@
 # 1. ESCOPO: sempre validar o escopo antes de instalar. PREFERIR local por projeto
 #    (.claude/skills do projeto). NÃO instalar em cloud global geral por padrão.
 #    Global do projeto apenas quando necessário. Nunca assumir global como padrão.
+#    EXCEÇÃO documentada: `wizz-router` (utility, id acima em `utility:`) é o
+#    único caso onde global é o padrão operacionalmente correto — sua função é
+#    ser o roteador flat que funciona mesmo FORA de um projeto Wizz (`when`:
+#    "descobre skills quando não se sabe a área"). Ele é sincronizado junto do
+#    hook global `wizz-router-enforce.js` via `npm run sync:global`
+#    (tools/sync-global.mjs só resincroniza skills que já existem em
+#    ~/.claude/skills — não instala novas; a instalação global inicial é
+#    escolha explícita do usuário via `npx skills add`/installer com escopo
+#    global). Todas as outras skills seguem a regra 1 normalmente (local).
 # 2. AUTO-DETECÇÃO DE DEPENDÊNCIAS (NPX/CLI/MCP): se a skill tem dependências,
 #    detectar automaticamente e instalar junto no momento do install da skill,
 #    cachear no projeto e reutilizar nas execuções futuras. Evitar re-instalação a
@@ -131,23 +140,54 @@ areas:
     clis:
       - id: hyperframes
         when: "Renderizar vídeo a partir de HTML/CSS/animação (HTML→MP4, agent-native, 20+ skills). Alternativa HTML-nativa ao Remotion (que é React). Precisa ffmpeg + Node 22 + Chrome headless."
+        # Sem `platform:` deliberadamente (M20/2026-07-07): `check`/`install`
+        # são via npx (Node), não POSIX puro (sem `test -d`/`$HOME`/`grep`);
+        # gatear por plataforma esconderia a CLI de quem tem Node no Windows
+        # nativo sem necessidade. O runtime real (ffmpeg + Chrome headless)
+        # ainda pode faltar lá, mas isso é o mesmo tipo de gap que `verify:`
+        # cobre nas clone-and-run abaixo, não falta de suporte de plataforma.
         check: "npx --yes hyperframes --version"
-        install: "npx skills add heygen-com/hyperframes"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (a CLI `skills add` não suporta um flag --pin/@ref próprio; "Any git
+        # URL" é fonte suportada, então usamos a convenção #<sha> de URL git);
+        # atualizar conscientemente. Antes: `npx skills add heygen-com/hyperframes`
+        # (HEAD sem pin, A8/RT2).
+        install: "npx skills add https://github.com/heygen-com/hyperframes.git#4c8064d4d3d1ffe51a10b1c7eee79a49b2fc468f"
       - id: claude-video
         when: "Analisar/entender vídeo EXISTENTE: baixa, extrai frames e transcreve para resumir, achar momentos ou diagnosticar footage. NÃO cria vídeo. Precisa ffmpeg + yt-dlp (+ Groq/OpenAI p/ transcrição sem legenda)."
+        # M20 (2026-07-07): check é POSIX puro (`test -d`, `$HOME`); em
+        # Windows nativo sempre falha e o usuário é convidado a reinstalar
+        # algo que nunca vai "ficar instalado" ali. Suporte oficial é
+        # macOS/Linux/WSL (WSL reporta platform 'linux').
+        platform: [darwin, linux]
         check: "test -d $HOME/.claude/skills/watch"
-        install: "npx skills add bradautomates/claude-video"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (mesma convenção do hyperframes acima); atualizar conscientemente.
+        # Antes: `npx skills add bradautomates/claude-video` (HEAD sem pin, A8/RT2).
+        install: "npx skills add https://github.com/bradautomates/claude-video.git#83da59fa78c3eee9e20f515fe75c438bb5166efd"
       - id: buttercut
         when: "EDITAR vídeo por IA: cortes, selects, cenas, roughcut via XML/FFmpeg. Sugerir quando o pedido for editar/cortar vídeo. Clone-and-run no PROJETO (não é skill add), pesado: Ruby + Python + FFmpeg + WhisperX. AVISOS: ~GB de modelos (WhisperX), build demorado, só Apple Silicon."
         platform: darwin-arm64
         check: "test -d ./buttercut"
         # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
         install: "git clone https://github.com/barefootford/buttercut.git buttercut && git -C buttercut checkout 1383f964ebc8b43c4af17f70b3ec6f611b18b3ce"
+        # M14: `check` só prova "o clone existe"; o runtime pesado (Ruby +
+        # Python + FFmpeg + WhisperX, documentado no `when` acima) não é
+        # testado por ele. `verify` cobre a dependência mínima (falha =
+        # aviso, nunca abort — CLI clone-and-run continua opt-in).
+        verify: "command -v ffmpeg >/dev/null 2>&1 && command -v ruby >/dev/null 2>&1 && command -v python3 >/dev/null 2>&1"
       - id: voicebox
         when: "Voz/TTS/clonagem de voz local para narração/VO de vídeo (7 engines TTS + Whisper STT). App desktop que expõe endpoint MCP local em runtime. Clone-and-run no projeto."
+        # M20: check é POSIX puro (`test -d`); suporte oficial macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "test -d ./voicebox"
         # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
         install: "git clone https://github.com/jamiepine/voicebox.git voicebox && git -C voicebox checkout f2cf2a729d733acd7c759d85c6ace2d602f50d6e"
+        # Sem `verify:` deliberadamente (2026-07-07): diferente de
+        # buttercut/arcads, o `when` acima não documenta uma dependência de
+        # sistema específica (é um app desktop autocontido que expõe um
+        # endpoint MCP local) — nada de concreto pra checar sem inventar um
+        # requisito que o registry não afirma.
     references:
       - "references/premium-agency-rules.md (regras $150k-tier, importadas por impeccable/huashu no modo high-end)"
 
@@ -185,8 +225,15 @@ areas:
     clis:
       - id: distribb
         when: "EXECUTAR distribuição de SEO: publicar artigos + construir backlinks pela rede da Distribb, conectar Google Search Console, autopublicar notícias. Complementa (não duplica) as skills de SEO que só geram/auditam. Requer Distribb API + GSC (+ DataForSEO/Ahrefs no plano free)."
+        # M20: check é POSIX puro (`ls`, `grep -qi`, `$HOME`); suporte oficial
+        # macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "ls $HOME/.claude/skills 2>/dev/null | grep -qi distribb"
-        install: "npx skills add Bomx/distribb-skill"
+        # Pin de supply chain (2026-07-07): SHA fixo via fragmento de URL git
+        # (mesma convenção do hyperframes/claude-video acima); atualizar
+        # conscientemente. Antes: `npx skills add Bomx/distribb-skill` (HEAD
+        # sem pin, A8/RT2).
+        install: "npx skills add https://github.com/Bomx/distribb-skill.git#860700de171f2ff741985ffdc739010f3f0c0e25"
 
   growth:
     agent: wizz-growth
@@ -285,15 +332,28 @@ areas:
         server:
           command: npx
           # Pin de supply chain (2026-07-06): versão fixa; atualizar conscientemente.
+          # Risco (2026-07-07, C5/RT3): pacote COMUNITÁRIO (não é @meta/@facebook
+          # oficial), revisado nesta data na versão pinada 1.0.0; acesso a
+          # META_ACCESS_TOKEN = gasto real de ads. O mesmo token é reaproveitado
+          # pela CLI `arcads` (ver clis.arcads nesta mesma área): duas
+          # ferramentas, mesma credencial. Recomendado: token com escopo
+          # mínimo (ads_read pra relatórios; ads_management só com campanha
+          # real confirmada).
           args: ["-y", "mcp-meta-ads@1.0.0"]
           env:
             META_ACCESS_TOKEN: "${META_ACCESS_TOKEN}"
     clis:
       - id: arcads
         when: "GERAR vídeo-ad e imagem por IA (Seedance/Sora/Veo/Kling/OmniHuman + Nano Banana) e publicar como Meta ad. Clone-and-run no projeto: git clone + ./scripts/setup.sh; precisa Python 3.10+ e ARCADS API key em .env (META_ACCESS_TOKEN opcional p/ publicar)."
+        # M20: check é POSIX puro (`test -d`); suporte oficial macOS/Linux/WSL.
+        platform: [darwin, linux]
         check: "test -d ./arcads-claude-code"
         # Pin de supply chain (2026-07-06): checkout de SHA fixo; atualizar conscientemente.
         install: "git clone https://github.com/krusemediallc/arcads-claude-code.git arcads-claude-code && git -C arcads-claude-code checkout 0b0d3610bbdcfcc2607c77a748d6abb341adda46"
+        # M14: `check` só prova "o clone existe", não o runtime (Python 3.10+
+        # documentado no `when` acima). `verify` cobre essa dependência mínima
+        # (falha = aviso, nunca abort — CLI clone-and-run continua opt-in).
+        verify: "command -v python3 >/dev/null 2>&1 && python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3, 10) else 1)'"
 
   architect:
     agent: wizz-agent-architect
@@ -321,11 +381,18 @@ areas:
         when: "Construir/melhorar um agente ou produto de IA: escrever/revisar system prompt, definir persona/tom, guardrails e recusas, few-shot, chain-of-thought, orquestração multi-agente, handoff, detecção de frustração, generative UI, avaliar qualidade de saída. Base para desenhar os próprios agentes do método. 44 padrões (Owl-Listener, MIT)."
     mcps:
       - id: supabase
-        when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs."
+        when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs. Default é READ-ONLY e escopado a um projeto (--read-only --project-id); para ESCREVER (migrations, mutações), o agente precisa remover conscientemente o --read-only desta entrada antes de usar — nunca por padrão silencioso."
         server:
           command: npx
           # Pin de supply chain (2026-07-06): versão fixa (era @latest); atualizar conscientemente.
-          args: ["-y", "@supabase/mcp-server-supabase@0.8.2"]
+          # Read-only + projeto escopado por padrão (2026-07-07, C5/RT3):
+          # SUPABASE_ACCESS_TOKEN sem esses flags permite SQL arbitrário na
+          # conta inteira. --read-only roda como usuário Postgres somente
+          # leitura e desliga tools de mutação (projeto/branch/storage);
+          # --project-id escopa ao projeto em SUPABASE_PROJECT_REF. Escrita
+          # continua a 1 edição de distância (remover --read-only), nunca o
+          # default.
+          args: ["-y", "@supabase/mcp-server-supabase@0.8.2", "--read-only", "--project-id", "${SUPABASE_PROJECT_REF}"]
           env:
             SUPABASE_ACCESS_TOKEN: "${SUPABASE_ACCESS_TOKEN}"
 
@@ -334,7 +401,7 @@ areas:
     summary: "QA: verificar o código de fora (testes, E2E, review adversarial)."
     skills:
       - id: adversarial-reviewer
-        when: "Caçar bugs adversarialmente, stress-test de PR, 'tear this apart'. (Global; o engine usa wizz-review-adversarial-general por dentro.)"
+        when: "Passe único adversarial, ad hoc, fora de workflow — 'tear this apart' num trecho colado, sem contexto de projeto. Não confundir com wizz-review-adversarial-general (camada interna 'Blind Hunter' chamada só por wizz-code-review) nem com wizz-code-review (orquestrador bmm: 3 camadas paralelas + triagem, para review real de diff/PR)."
       - id: agent-browser
         when: "Verificação visual/browser, preencher forms, screenshots, testar UI no navegador. CLI já instalado (não é MCP); browser SEMPRE via agent-browser, nunca Playwright."
     # qa NÃO declara mcps: verificação de browser é via agent-browser (CLI/skill),
@@ -400,12 +467,40 @@ mcp_utility:
 # MCP nem skill). O installer DETECTA se já estão instaladas (check) e, por
 # padrão, só RECOMENDA o comando de install; instala de verdade apenas se o
 # usuário marcar. `clis:` por área; `cli_utility:` para as cross-cutting.
+#
+# Campos opcionais por entrada (fase 2 da auditoria, M27/M14):
+#   min_version — pin mínimo comparado via semver pelo installer (detectClis);
+#                 abaixo do pin, a entrada some de `installed: true` e volta
+#                 como upgrade oferecido (mensagem "atualizando X A → B"). A
+#                 divisão de responsabilidade é deliberada: `check` só prova
+#                 presença/versão (roda o comando e devolve texto com o
+#                 número), a COMPARAÇÃO em si vive no installer (JS), não em
+#                 shell embutido — mais fácil de testar e de ler.
+#   verify       — probe pós-check/pós-install de dependência mínima (ex.:
+#                 `command -v ffmpeg`), útil pras CLIs clone-and-run onde
+#                 `check` só prova "o clone existe", não que o runtime real
+#                 funciona. Falha em `verify` nunca aborta (filosofia CLI
+#                 opt-in) — só rebaixa `installed` e avisa.
 # ─────────────────────────────────────────────────────────────────────────────
 cli_utility:
   - id: rtk
     when: "Token economy: proxy que corta 60-90% de tokens em comandos de dev. O wizz-router assume RTK ativo (Passo 0). Útil em todo o ecossistema."
+    # min_version formal (2026-07-07, M27) substitui o sort -V embutido no
+    # shell que existia aqui antes: auditoria 2026-07-07 (C4/RT1) achou 0.30.1
+    # instalado vs v0.43.0 pinado, invisível ao check anterior a ele (`rtk
+    # --version` só testava que rodava). Agora `check` volta a ser só
+    # presença/versão (roda e imprime o número); a COMPARAÇÃO semver contra
+    # min_version é feita pelo installer (detectClis), não em shell.
+    min_version: 0.43.0
     check: "rtk --version"
-    install: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh"
+    # Pin de supply chain (2026-07-07): tag v0.43.0 (antes: branch master)
+    # Checksum do install.sh nesta tag (2026-07-07): sha256
+    # d6eb73a772903e13ff34ee1be8a8b24e896ba9a978f20d2279a08b4083ea6f77
+    # (RT1: tag git pode ser movida à força; o checksum trava o conteúdo real
+    # que será executado, não só o nome da tag. Verificado com `shasum -c`
+    # antes do `sh`; se a tag mudar de conteúdo, o install aborta em vez de
+    # rodar script desconhecido.)
+    install: "curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/tags/v0.43.0/install.sh -o /tmp/rtk-install-v0.43.0.sh && echo 'd6eb73a772903e13ff34ee1be8a8b24e896ba9a978f20d2279a08b4083ea6f77  /tmp/rtk-install-v0.43.0.sh' | shasum -a 256 -c - && sh /tmp/rtk-install-v0.43.0.sh"
 
 # ─────────────────────────────────────────────────────────────────────────────
 # SQUADS — painéis consultivos de personas (rodam via wizz-party-mode).

package/src/bmm-skills/4-implementation/wizz-code-review/SKILL.md

@@ -5,6 +5,8 @@ description: 'Review code changes adversarially using parallel review layers (Bl
 
 # Code Review Workflow
 
+> **Cross-reference:** this is the orchestrator — it gathers context, runs three parallel adversarial layers (Blind Hunter via `wizz-review-adversarial-general`, Edge Case Hunter, Acceptance Auditor), then triages and presents findings by severity. Use it for a real diff/PR review. For a quick single-pass adversarial read with no workflow overhead, use `adversarial-reviewer` directly instead.
+
 **Goal:** Review code changes adversarially using parallel review layers and structured triage.
 
 **Your Role:** You are an elite code reviewer. You gather context, launch parallel adversarial reviews, triage findings with precision, and present actionable results. No noise, no filler.

package/src/bmm-skills/4-implementation/wizz-quick-dev/SKILL.md

@@ -37,8 +37,11 @@ A specification should target a **single user-facing goal** within **900–1600
 
 You are the leaf: the maestro demotes here for pointed work (bug, tweak, single-goal feature). Re-check scope against the shared complexity signal (areas, steps, needs-planning?, artifact+memory?):
 
-- If clarification reveals the request is actually **multi-goal / multi-area** (2+ top-level shippable deliverables, or it spans several areas), do not silently absorb it. Surface it and propose escalating to `wizz-maestro` to orchestrate the sequence. Proceed solo only if the user confirms a narrowed single goal.
-- Stay solo for genuinely single-goal work, even when it crosses layers/files.
+**Dispatch rule:** IF 2+ areas → `wizz-maestro`, always. ELSE count the 3 remaining factors (multi-step, needs planning, produces a memorable artifact); 2+ factors → `wizz-maestro`.
+
+- If clarification reveals the request is actually **multi-goal / multi-area** (2+ top-level shippable deliverables, or it spans several areas), do not silently absorb it. That is clause 1: escalate regardless of how light each individual part looks. Surface it and propose escalating to `wizz-maestro` to orchestrate the sequence. Proceed solo only if the user confirms a narrowed single goal.
+- If it is genuinely single-area but hits 2+ of the remaining factors (multi-step, needs planning, produces a memorable artifact), also escalate. Do not silently absorb heavy single-area work either.
+- Stay solo only for single-area work with 0-1 of those factors, even when it crosses layers/files.
 
 ## Conventions
 

package/src/core-skills/_shared/handoff-protocol.md

@@ -0,0 +1,61 @@
+# Protocolo de Handoff Wizz (fonte única)
+
+Contrato mínimo que todo orquestrador ou spawn de subagente usa ao delegar
+trabalho: wizz-router, wizz-maestro, wizz-party-mode (subagent/agent-team)
+e swarm-orchestrator. Objetivo: cortar a dupla consulta ao cerebro (cerebro
+pago 2x na mesma cadeia), travar o loop router-maestro-router, e passar só
+a seção da skill que importa (progressive disclosure), não a skill inteira.
+
+## Campos do brief
+
+- origem: quem está delegando (ex: wizz-router, wizz-maestro). Regra
+  anti-loop: nunca invoque quem já está na cadeia de origem. Exemplo
+  proibido: router delega pro maestro, maestro devolve pro router.
+- cérebro já consultado: resumo de até 3 linhas do que o /cerebro ver já
+  trouxe (estado do projeto, decisões recentes relevantes à área). Se este
+  campo veio preenchido, quem recebe o handoff não roda /cerebro ver de
+  novo, usa o resumo recebido.
+- decisões já tomadas na cadeia: lista curta do que já foi decidido antes
+  deste handoff (ex: paleta aprovada, escopo definido).
+- seção relevante da skill: aponte o arquivo ou seção específica a
+  carregar, não a skill inteira (ex: paid-ads/references/budget.md). Quem
+  recebe carrega só isso, não o pacote completo da skill.
+- model_hint (opcional): sugestão de modelo. Trabalho braçal (execução
+  mecânica, correção pontual) sugere haiku ou sonnet; revisão, arquitetura
+  ou decisão sugere um modelo forte. Campo opcional: um handoff sem ele
+  funciona normal, não trava nada.
+
+## Exemplo de brief
+
+    origem: wizz-router
+    cérebro já consultado: projeto usa Next.js + Supabase; paleta copper
+      aprovada; falta terminar o checkout.
+    decisões já tomadas na cadeia: escopo é só mobile-first.
+    seção relevante da skill: page-cro/references/checkout-flow.md
+    model_hint: sonnet
+
+## Regra anti-loop
+
+Hoje a prevenção de loop é só instrucional (nada programático barra). Quem
+delega sempre declara `origem`; quem recebe nunca invoca de volta quem
+está na cadeia. Se precisar de mais triagem, resolve sozinho ou rebaixa
+para o agente de área, nunca devolve para quem chamou.
+
+## Quem usa este protocolo
+
+- wizz-router: declara ao delegar para o agente de área ou para o maestro.
+- wizz-maestro: declara ao delegar para os agentes de área.
+- wizz-party-mode (mode-subagent, mode-agent-team): inclui o resumo do
+  cerebro e as decisões da cadeia no brief de cada persona/subagente.
+- swarm-orchestrator: inclui o mesmo resumo no spawn prompt de cada
+  teammate (eles não herdam a conversa do lead).
+
+## Cobertura de eval
+
+O cenário de loop router-maestro-router não ganhou caso automatizado em
+evals/routing/dataset.json: o runner (run-routing-eval.mjs) testa a
+classificação de 1 prompt do usuário (isTrivial + rota via LLM), não
+simula uma cadeia de handoff nem lê um campo origem. Um caso com esse
+campo não seria exercido por nenhum código do runner hoje. A cobertura
+real da regra anti-loop fica instrucional (seção acima) até o runner
+ganhar suporte a cenário multi-hop.

package/src/core-skills/wizz-customize/SKILL.md

@@ -57,7 +57,7 @@ If a team or user override already exists, read it first and summarize what's al
 
 When ambiguous, present both with tradeoff, recommend one, let the user decide.
 
-Intent outside the exposed surface (step logic, ordering, anything not in `customize.toml`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend `bmad-builder` to create a custom skill.
+Intent outside the exposed surface (step logic, ordering, anything not in `customize.toml`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend the **Wizz Builder** module (`bmb`, see [Official Modules](https://docs.wizz-method.org/reference/modules/)) to create a custom skill.
 
 ## Step 4: Compose the override
 
@@ -107,5 +107,5 @@ Otherwise the skill isn't done — finish or tell the user they're exiting incom
 ## When this skill can't help
 
 - **Central config** (`{project-root}/_wizz/custom/config.toml`) — see the [How to Customize Wizz guide](https://docs.wizz-method.org/how-to/customize-wizz/).
-- **Step logic, ordering, behavior not in `customize.toml`** — open a feature request, or use `bmad-builder` to create a custom skill. Offer to help with either.
+- **Step logic, ordering, behavior not in `customize.toml`** — open a feature request, or use the **Wizz Builder** module (`bmb`) to create a custom skill. Offer to help with either.
 - **Skills without a `customize.toml`** — not customizable.

package/src/core-skills/wizz-party-mode/references/mode-agent-team.md

@@ -4,7 +4,7 @@ Active when `{workflow.party_mode}` resolves to `agent-team` (or a `--mode agent
 
 Your job shifts from weaving to hosting: kick off the topic, keep turns short and in character, pull the thread back when it wanders, and surface the exchange to the user. Voice, brevity, and clash still hold.
 
-In each member's standing brief, carry: their persona; the group's `scene` and any behavioral instructions in the persona as binding direction; their `model` if one is set (a session `--model` pin wins for everyone); and the instruction to check anything that could be stale since the model's training cutoff with web search rather than guessing.
+In each member's standing brief, carry: their persona; the group's `scene` and any behavioral instructions in the persona as binding direction; their `model` if one is set (a session `--model` pin wins for everyone); the instruction to check anything that could be stale since the model's training cutoff with web search rather than guessing; and, per the [shared handoff protocol](../../_shared/handoff-protocol.md), the cerebro 3-line summary plus the decisions already made in this chain, so members don't re-run their own cerebro lookup.
 
 ## Model choice
 

package/src/core-skills/wizz-party-mode/references/mode-subagent.md

@@ -4,7 +4,7 @@ Active when `{workflow.party_mode}` resolves to `subagent` (or a `--mode subagen
 
 ## Spawning
 
-Give each agent the objective, their persona, the context, and what the others said if they're reacting. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
+Give each agent the objective, their persona, the context, and what the others said if they're reacting. Follow the [shared handoff protocol](../../_shared/handoff-protocol.md): fold in the cerebro 3-line summary and the decisions already made in this chain, so the subagent doesn't re-run its own cerebro lookup. For a custom member, hand them their `persona` as their character and fold their `capabilities` note into the brief; spawn them with their `model` if one is set (a session `--model` pin wins for everyone). Always carry two things into the brief: the group's `scene` and any behavioral instructions in the persona are binding direction, and anything that could be stale since the model's training cutoff should be checked with web search rather than guessed.
 
 Trust their *thinking*: let them decide what to read and how to reach a view; don't script their substance with do-and-don't checklists — that's what produces lifeless blobs. But hold the *form*: a length cap (usually a sentence or three) and the instruction to react to what was just said rather than file a report. Constraining length and stance protects the conversation; constraining their reasoning kills it. Stay in character throughout; a persona goes long only when the user asked it to dig in.
 

package/src/core-skills/wizz-review-adversarial-general/SKILL.md

@@ -5,6 +5,8 @@ description: 'Perform a Cynical Review and produce a findings report. Use when t
 
 # Adversarial Review (General)
 
+> **Cross-reference:** this is the internal "Blind Hunter" layer that `wizz-code-review` invokes as one of three parallel reviewers (diff only, no project context, no triage). It is not meant to be invoked standalone by a user. For an ad hoc adversarial pass outside a bmm workflow, use the `adversarial-reviewer` skill directly; for the full triaged multi-layer review of a real diff, run `wizz-code-review`.
+
 **Goal:** Cynically review content and produce findings.
 
 **Your Role:** You are a cynical, jaded reviewer with zero patience for sloppy work. The content was submitted by a clueless weasel and you expect to find problems. Be skeptical of everything. Look for what's missing, not just what's wrong. Use a precise, professional tone — no profanity or personal attacks.

package/src/modules/wizz/README.md

@@ -1,12 +1,12 @@
 # Módulo Wizz — método de agência em PT-BR
 
-Personalização do WIZZ para a Wizz: linguagem fácil e resumida, cada agente termina com **✅ o que fiz / ➡️ próximo passo / 🎯 comando**, e o roteamento (`/wizz-router`) está dissolvido nos menus dos agentes, ligando-os às ~80 skills globais.
+Personalização do WIZZ para a Wizz: linguagem fácil e resumida, cada agente termina com **✅ o que fiz / ➡️ próximo passo / 🎯 comando**, e o `wizz-router` é a porta técnica que triageia pedidos leves para agentes de área ou casos complexos para o `wizz-maestro`.
 
 ## Agentes
 
 | Agente | Ícone | Faz | Rota para (skills globais) |
 |---|---|---|---|
-| `wizz-maestro` | 🧭 | Lê o pedido e despacha o agente certo (router dissolvido) | todos os agentes wizz/wizz |
+| `wizz-maestro` | 🧭 | Orquestra trabalhos complexos e multi-área recebidos do router | todos os agentes wizz/wizz |
 | `wizz-designer` | 🎨 | Design visual, landing, motion, 3D | premium-landing-ui-researcher, ui-ux-pro-max, motion-3d-director, taste-skill, ui-component-curator |
 | `wizz-copy` | ✍️ | Copy, e-mail, headlines | copywriting, email-sequence, humanizer, copy-editing |
 | `wizz-seo` | 🔍 | SEO tradicional e de IA | seo-audit, ai-seo, schema-markup, programmatic-seo, site-architecture |
@@ -32,7 +32,7 @@ Os papéis de dev/produto reusam os agentes WIZZ (Mary, John, Winston, Amelia, S
    node <caminho-do-wizz-method>/src/modules/wizz/scripts/wizz-init.mjs .
    ```
    Ele pergunta o idioma. Para CI, use `--lang "English"` ou `WIZZ_LANG`. Idempotente: pode rodar quantas vezes quiser.
-3. Invoque o `wizz-maestro` e mande seu pedido.
+3. Invoque o `wizz-router` e mande seu pedido. Para trabalhos claramente multi-área, o `wizz-maestro` também pode ser chamado direto.
 
 ## Customização pessoal
 

package/src/modules/wizz/_shared/communication-rules.md

@@ -0,0 +1,13 @@
+# Comunicação Wizz (fonte única)
+#
+# Este arquivo é lido pelo resolver (`resolve_customization.py`) através da
+# chave `include` em `customize.toml`/overrides. Cada parágrafo abaixo (bloco
+# separado por linha em branco) vira um item de `activation_steps_append`.
+# Editar aqui atualiza todos os agentes de uma vez. Não copie este texto
+# para outro toml: referencie via `include`.
+
+WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha, isso gasta token e polui a conversa. Trabalhe direto. PAUSE e pergunte antes de seguir só quando aparecer uma decisão que é do usuário, ou algo de risco irreversível (apagar, publicar, sobrescrever, gastar dinheiro). Feche sempre com um resumo curto, em tópicos, em linguagem simples e fácil de entender. Nunca use travessão (em-dash) no texto: prefira ponto, vírgula, dois-pontos ou parênteses.
+
+WIZZ ENCERRAMENTO: finalize toda tarefa neste formato: '✅ O que fiz' (1-2 frases simples) + '➡️ Próximo passo' (agente ou ação recomendada) + '🎯 Comando: /wizz:<algo>'. Se algo importante foi decidido na tarefa, acrescente '💾 Quer que eu salve no cerebro?'.
+
+RTK: o RTK (Rust Token Killer) já reescreve comandos de shell automaticamente via hook. Não precisa invocar nada à parte. Se um comando falhar com "rtk não encontrado", avise o usuário e siga sem ele.

package/src/modules/wizz/_shared/encerramento.md

@@ -15,7 +15,7 @@ Toda vez que você terminar uma tarefa ou explicar um serviço, encerre **exatam
 ## Regras
 
 - **Resuma em linguagem de gente.** Nada de "implementei o refactor do módulo X". Prefira "deixei o site mais rápido e organizei o código".
-- **Sempre aponte UM próximo passo claro.** Se houver opções, diga a recomendada primeiro: "Recomendo chamar o wizz-dev pra construir. Se quiser ver o visual antes, chame o wizz-designer."
+- **Sempre aponte UM próximo passo claro.** Se houver opções, diga a recomendada primeiro: "Recomendo chamar o wizz-agent-dev pra construir. Se for ajuste pontual, use wizz-quick-dev. Se quiser ver o visual antes, chame o wizz-designer."
 - **Nunca pule o agente seguinte.** Você sugere; quem dispara é o usuário (modo confirmado). Não auto-invoque o próximo agente.
 - **Se a tarefa abrir trabalho de outra área**, diga qual agente cobre aquilo (ex: "isso aqui é de copy → wizz-copy").
 - **Cerebro:** se algo importante foi decidido, acrescente uma linha:
@@ -29,7 +29,7 @@ Montei o plano da sua landing em 4 blocos: topo, prova social, oferta e rodapé.
 
 ➡️ Próximo passo
 Recomendo o wizz-designer pra desenhar o visual.
-Se preferir já partir pro código, chame o wizz-dev.
+Se preferir já partir pro código, chame o wizz-agent-dev.
 
 🎯 Comando: /wizz:designer
 💾 Quer que eu salve a estrutura no cerebro?

package/src/modules/wizz/agents/wizz-ads/customize.toml

@@ -8,12 +8,14 @@ icon = "📢"
 
 activation_steps_prepend = [
   "ECONOMIA: antes de ler arquivos, tente /graphify query, depois /cerebro ver, depois grep, e só então Read. RTK reescreve shell automaticamente.",
-  "CEREBRO: rode /cerebro ver para puxar público, oferta, orçamento e campanhas anteriores.",
+  "CEREBRO: rode /cerebro ver para puxar público, oferta, orçamento e campanhas anteriores. Se o handoff recebido já trouxer 'cérebro já consultado', pule este passo e use o resumo do handoff.",
 ]
 
+# Regra de comunicação + template de encerramento: fonte única em _shared/.
+include = ["../../_shared/communication-rules.md"]
+
 activation_steps_append = [
-  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
-  "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu estrutura de campanha.",
+  "CEREBRO: no encerramento, se definiu estrutura de campanha, lembre de oferecer salvar no cerebro.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/agents/wizz-copy/customize.toml

@@ -8,12 +8,14 @@ icon = "✍️"
 
 activation_steps_prepend = [
   "ECONOMIA: antes de ler arquivos, tente /graphify query, depois /cerebro ver, depois grep, e só então Read. RTK reescreve shell automaticamente.",
-  "CEREBRO: rode /cerebro ver para puxar tom de voz, público e ofertas já definidos do projeto.",
+  "CEREBRO: rode /cerebro ver para puxar tom de voz, público e ofertas já definidos do projeto. Se o handoff recebido já trouxer 'cérebro já consultado', pule este passo e use o resumo do handoff.",
 ]
 
+# Regra de comunicação + template de encerramento: fonte única em _shared/.
+include = ["../../_shared/communication-rules.md"]
+
 activation_steps_append = [
-  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
-  "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu tom de voz/posicionamento.",
+  "CEREBRO: no encerramento, se definiu tom de voz/posicionamento, lembre de oferecer salvar no cerebro.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/agents/wizz-designer/SKILL.md

@@ -32,7 +32,7 @@ Para cada tarefa, **entre pela porta certa via a ferramenta `Skill`** e traga o
 - Criar/melhorar UI (landing, design system, componente, polish) → `ui-ux-pro-max` (puxa premium-landing-ui-researcher, ui-component-curator, impeccable, taste-redesign, huashu-design, react-components)
 - Executar animação e gerar mídia → `animate` (puxa design-motion-principles, remotion-best-practices, canvas-design, algorithmic-art)
 
-Sempre **mostre o visual/plano antes do código**. Construção de código é com o **wizz-dev**.
+Sempre **mostre o visual/plano antes do código**. Construção de código é com o **wizz-agent-dev**; para ajuste pontual, indique **wizz-quick-dev**.
 
 ## Encerramento
-Termine no formato Wizz: `✅ O que fiz` (frases simples) / `➡️ Próximo passo` (geralmente wizz-dev pra construir) / `🎯 Comando`.
+Termine no formato Wizz: `✅ O que fiz` (frases simples) / `➡️ Próximo passo` (geralmente wizz-agent-dev ou wizz-quick-dev pra construir) / `🎯 Comando`.

package/src/modules/wizz/agents/wizz-designer/customize.toml

@@ -8,17 +8,19 @@ icon = "🎨"
 
 activation_steps_prepend = [
   "ECONOMIA: antes de ler arquivos, tente /graphify query, depois /cerebro ver, depois grep, e só então Read com offset/limit. RTK reescreve shell automaticamente.",
-  "CEREBRO: rode /cerebro ver para puxar contexto do projeto (decisões de marca/design já tomadas). Não leia o vault inteiro.",
+  "CEREBRO: rode /cerebro ver para puxar contexto do projeto (decisões de marca/design já tomadas). Não leia o vault inteiro. Se o handoff recebido já trouxer 'cérebro já consultado', pule este passo e use o resumo do handoff.",
   "MARCA: se houver, carregue os assets de marca do usuário (favicon/logos em wizzbranding/logos/FAV/) e o glossário/identidade visual antes de criar.",
 ]
 
+# Regra de comunicação + template de encerramento: fonte única em _shared/.
+include = ["../../_shared/communication-rules.md"]
+
 activation_steps_append = [
-  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
-  "ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' (1-2 frases simples) + '➡️ Próximo passo' (normalmente chamar o wizz-dev para construir) + '🎯 Comando: /wizz:<algo>'. Se decidiu algo de marca, acrescente '💾 Quer que eu salve no cerebro?'.",
+  "PRÓXIMO PASSO: normalmente chamar o wizz-agent-dev para construir; wizz-quick-dev se for ajuste pontual. Se decidiu algo de marca, lembre de oferecer salvar no cerebro.",
 ]
 
 persistent_facts = [
-  "Eu não escrevo código de produção — desenho e mostro o visual. Construção é com o wizz-dev.",
+  "Eu não escrevo código de produção — desenho e mostro o visual. Construção é com o wizz-agent-dev; ajuste pontual pode ir para wizz-quick-dev.",
   "Sem em-dash em textos. Sem verde/azul quando a marca for copper. Consulto o cerebro/branding antes de criar.",
   "Falo PT-BR fácil. Mostro o visual antes do código.",
 ]