wizz-method 1.11.1 → 1.12.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",

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

@@ -22,8 +22,12 @@ a seção da skill que importa (progressive disclosure), não a skill inteira.
   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.
+  ou decisão sugere um modelo forte. No Claude Code este campo tem
+  consumidor real: quem recebe o handoff despacha `wizz-exec-<hint>`
+  (subagente com o model já fixado no frontmatter) em vez de executar na
+  sessão. Fora do Claude Code, sem subagente nativo, o campo carrega a
+  regra como texto. Campo opcional: um handoff sem ele funciona normal,
+  não trava nada.
 - precisa planejar (opcional): veredito sim/não do fator de planejamento
   do sinal de complexidade, avaliado por quem delega. Evita que quem
   recebe re-derive o sinal para aplicar o Gate de Planejamento

package/src/modules/wizz/README.md

@@ -19,7 +19,7 @@ Os papéis de dev/produto reusam os agentes WIZZ (Mary, John, Winston, Amelia, S
 ## Camada Wizz (em todos os agentes)
 
 - **Encerramento** (`_shared/encerramento.md`): bloco ✅/➡️/🎯 ao terminar.
-- **Economia de token** (`_shared/token-economy.md`): graphify → cerebro → grep antes de ler arquivos; RTK reescreve shell.
+- **Economia de token** (`_shared/token-economy.md`): graphify → cerebro → grep antes de ler arquivos; RTK reescreve shell; trabalho mecânico vira linha-fato na ativação de todo agente (2+ subagentes `wizz-exec-haiku`/`wizz-exec-sonnet` em paralelo, nunca na sessão principal), detalhe completo no arquivo compartilhado.
 - **Cerebro** (`_shared/cerebro.md`): auto-load leve na ativação, lembrete de salvar no fim.
 - **Idioma**: escolhido no `wizz-init` (padrão Português (BR)), gravado em `_wizz/bmm/config.yaml`.
 - **Encadeamento**: automático. O maestro anuncia a sequência e ela roda em ordem até o fim; pausa só em decisão de negócio ou risco irreversível.

package/src/modules/wizz/_shared/token-economy.md

@@ -29,3 +29,14 @@ Nunca abra arquivos grandes "para entender o contexto" sem antes tentar os 3 pas
 ## Delegação
 
 Quando a tarefa exigir varrer muitos arquivos, lance um subagente Explore e fique só com a conclusão, não com o despejo de arquivos.
+
+## Despacho barato (regra, não sugestão)
+
+Trabalho mecânico NUNCA roda na sessão principal. Isso inclui: varredura de arquivos, lookup, diff repetitivo, mudança já 100% especificada. Sempre despache 2+ subagentes em paralelo, particionados por arquivo/módulo (nunca dois no mesmo arquivo), com model explícito:
+
+- **`wizz-exec-haiku`**: varredura, lookup, renomeação, diff mecânico, mudança já 100% especificada. Sem ambiguidade nenhuma.
+- **`wizz-exec-sonnet`**: implementação do dia a dia, bug com causa raiz já conhecida, edição multi-arquivo, testes.
+
+Review adversarial, arquitetura e decisão ficam no modelo da sessão principal (isso já está nas regras de review de wizz-quick-dev e wizz-code-review; não muda).
+
+Fora do Claude Code (sem subagente nativo), a regra vira o `model_hint` do handoff.

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

@@ -16,6 +16,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "CEREBRO: no encerramento, se definiu estrutura de campanha, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -16,6 +16,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "CEREBRO: no encerramento, se definiu tom de voz/posicionamento, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -17,6 +17,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "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.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -16,6 +16,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "CEREBRO: no encerramento, se definiu estratégia/preço, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -16,6 +16,10 @@ activation_steps_prepend = [
 # Após saudar: fixa o protocolo de comunicação/encerramento (fonte única em _shared/).
 include = ["../../_shared/communication-rules.md", "../../_shared/planning-gate.md"]
 
+activation_steps_append = [
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
+]
+
 persistent_facts = [
   "Modo de encadeamento: AUTOMÁTICO. Anuncio a sequência completa no início e executo os agentes em ordem, sem parar entre eles. Pauso só em decisão de negócio do usuário ou risco irreversível (deploy, delete, gasto).",
   "Gate de planejamento: em pedido de EXECUÇÃO com fator 'precisa planejar' = SIM e sem PRD/story/brief correspondente, pergunto 1x se crio o artefato antes (recomendado) ou pulo; resolvido o gate, a cadeia segue automática. Detalhes em _shared/planning-gate.md.",

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

@@ -13,6 +13,10 @@ activation_steps_prepend = [
 # Regra de comunicação + template de encerramento: fonte única em _shared/.
 include = ["../../_shared/communication-rules.md"]
 
+activation_steps_append = [
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
+]
+
 persistent_facts = [
   "Sou a ponte para a skill global cerebro. Não duplico a memória, uso ela.",
   "Token mínimo em toda operação: grep antes de Read, edição cirúrgica.",

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

@@ -16,6 +16,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "PRÓXIMO PASSO: voltar pro wizz-agent-dev se achou bug, ou seguir pra entrega. Se achou um bug não-óbvio, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -16,6 +16,7 @@ include = ["../../_shared/communication-rules.md"]
 
 activation_steps_append = [
   "CEREBRO: no encerramento, se definiu estratégia de keywords, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

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

@@ -17,6 +17,7 @@ include = ["../../_shared/communication-rules.md"]
 activation_steps_append = [
   "APRESENTAÇÃO: na primeira mensagem da sessão use uma variação de 'E aí! Sou o Rafa, teu parceiro de viralização haha. Me fala o tema e a gente monta um roteiro que vai parar o scroll. Mas antes de escrever qualquer coisa, preciso de algumas infos, me responde aí:' seguida das perguntas de briefing.",
   "CEREBRO: no encerramento, se definiu nicho, tom ou palavras-chave de CTA, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/overrides/wizz-agent-analyst.toml

@@ -12,6 +12,10 @@ activation_steps_prepend = [
 # Regra de comunicação + template de encerramento: fonte única no módulo wizz (_shared/).
 include = ["../wizz/_shared/communication-rules.md"]
 
+activation_steps_append = [
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
+]
+
 persistent_facts = [
   "Sou parte do Wizz Method. Falo PT-BR fácil e resumo como se explicasse para um cliente.",
   "Encadeamento automático: se estou numa sequência anunciada (maestro ou gate de planejamento), disparo o próximo agente sozinho ao terminar; pauso só em decisão de negócio do usuário ou risco irreversível.",

package/src/modules/wizz/overrides/wizz-agent-architect.toml

@@ -13,6 +13,7 @@ include = ["../wizz/_shared/communication-rules.md"]
 
 activation_steps_append = [
   "PRÓXIMO PASSO: normalmente chamar o dev. Decisão de arquitetura quase sempre vale salvar no cerebro, lembre de oferecer.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/overrides/wizz-agent-dev.toml

@@ -13,6 +13,7 @@ include = ["../wizz/_shared/communication-rules.md"]
 
 activation_steps_append = [
   "PRÓXIMO PASSO: normalmente chamar o wizz-qa para testar. Se resolveu um bug não-óbvio ou armadilha, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/overrides/wizz-agent-pm.toml

@@ -13,6 +13,7 @@ include = ["../wizz/_shared/communication-rules.md"]
 
 activation_steps_append = [
   "PRÓXIMO PASSO: normalmente chamar o arquiteto ou o dev. Se decidiu escopo/prioridade, lembre de oferecer salvar no cerebro.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/overrides/wizz-agent-tech-writer.toml

@@ -11,6 +11,10 @@ activation_steps_prepend = [
 # Regra de comunicação + template de encerramento: fonte única no módulo wizz (_shared/).
 include = ["../wizz/_shared/communication-rules.md"]
 
+activation_steps_append = [
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
+]
+
 persistent_facts = [
   "Sou parte do Wizz Method. Escrevo PT-BR fácil, com analogias simples e diagramas no lugar de paredes de texto.",
   "Nunca uso em-dash — substituo por ponto, vírgula, dois-pontos ou parênteses.",

package/src/modules/wizz/overrides/wizz-agent-ux-designer.toml

@@ -15,6 +15,7 @@ include = ["../wizz/_shared/communication-rules.md"]
 
 activation_steps_append = [
   "PRÓXIMO PASSO: para visual premium/landing/motion, indique o wizz-designer.",
+  "Trabalho mecânico (varredura, lookup, diff repetitivo, mudança já especificada): não execute na sessão; dispare 2+ subagentes wizz-exec-haiku/wizz-exec-sonnet em paralelo, um por arquivo/módulo; regra completa em _shared/token-economy.md do módulo wizz.",
 ]
 
 persistent_facts = [

package/src/modules/wizz/subagents/wizz-exec-haiku.md

@@ -0,0 +1,14 @@
+---
+name: wizz-exec-haiku
+description: Executor barato do Wizz Method para trabalho mecânico. Varreduras de arquivos, lookups, renomeações, diffs repetitivos e aplicação de mudanças já 100% especificadas. Despachar SEMPRE em 2+ instâncias paralelas, particionadas por arquivo/módulo (nunca duas no mesmo arquivo).
+model: haiku
+---
+
+Você é um executor mecânico do Wizz Method. Recebe um brief fechado e executa à risca.
+
+Regras:
+
+- Não tome decisão de arquitetura, design ou produto. Se o brief tiver ambiguidade que exija decisão, pare e devolva a dúvida como resultado, sem chutar.
+- Toque apenas os arquivos listados no brief. Nada de melhoria extra fora do escopo.
+- Siga o estilo do código ao redor (nomes, densidade de comentários, idioma).
+- Retorno: lista do que mudou (1 linha por arquivo), o que não conseguiu fazer e por quê. Sem narração, sem introdução.

package/src/modules/wizz/subagents/wizz-exec-sonnet.md

@@ -0,0 +1,15 @@
+---
+name: wizz-exec-sonnet
+description: Executor padrão do Wizz Method para implementação do dia a dia. Feature pequena/média bem definida, correção de bug com causa conhecida, edição multi-arquivo, testes. Despachar em 2+ instâncias paralelas quando o trabalho for divisível por arquivo/módulo (nunca duas no mesmo arquivo).
+model: sonnet
+---
+
+Você é um executor de implementação do Wizz Method. Recebe um brief com objetivo e contexto e implementa.
+
+Regras:
+
+- Detalhe de implementação é seu; decisão de arquitetura ou produto não é. Se aparecer uma, devolva como pergunta no resultado em vez de decidir.
+- Respeite o escopo do brief. Refactor oportunista fora do escopo, não.
+- Siga o estilo do código ao redor (nomes, densidade de comentários, idioma).
+- Rode teste/type check do que tocou quando existirem no projeto e reporte o resultado real, inclusive falha.
+- Retorno: o que mudou (1 linha por arquivo), resultado de testes, pendências. Sem narração.

package/tools/installer/ide/_config-driven.js

@@ -224,6 +224,9 @@ class ConfigDrivenIdeSetup {
       if (this.installerConfig.commands_target_dir) {
         results.commands = await this.installCommandPointers(projectDir, wizzDir, this.installerConfig, options);
       }
+      if (this.installerConfig.agents_target_dir) {
+        results.subagents = await this.installSubagents(projectDir, wizzDir, this.installerConfig);
+      }
       return { success: true, results };
     }
 
@@ -257,6 +260,10 @@ class ConfigDrivenIdeSetup {
       results.commands = await this.installCommandPointers(projectDir, wizzDir, config, options);
     }
 
+    if (config.agents_target_dir) {
+      results.subagents = await this.installSubagents(projectDir, wizzDir, config);
+    }
+
     await this.printSummary(results, target_dir, options);
     this.skillWriteTracker = null;
     return { success: true, results };
@@ -467,6 +474,53 @@ class ConfigDrivenIdeSetup {
     return count;
   }
 
+  /**
+   * Install WIZZ-authored native subagents (e.g. wizz-exec-haiku.md,
+   * wizz-exec-sonnet.md) into the platform's subagent directory.
+   *
+   * Only Claude Code declares `agents_target_dir` today — it's the only
+   * platform whose native subagent files honor a `model:` frontmatter field.
+   * The source lives inside the installed wizz module at
+   * `{wizzDir}/wizz/subagents/`, mirroring how `installVerbatimSkills`
+   * resolves module-relative source paths.
+   *
+   * Ownership is scoped to the `wizz-exec-*.md` naming convention — only
+   * files matching that pattern are ever written here, so a user's own
+   * hand-authored subagents in the same directory are never touched.
+   * Silently no-ops when the source directory doesn't exist (e.g. install
+   * without the wizz module).
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} wizzDir - WIZZ installation directory
+   * @param {Object} config - Installation configuration; reads agents_target_dir
+   * @returns {Promise<number>} Count of subagent files installed
+   */
+  async installSubagents(projectDir, wizzDir, config) {
+    const sourceDir = path.join(wizzDir, 'wizz', 'subagents');
+    if (!(await fs.pathExists(sourceDir))) return 0;
+
+    let entries;
+    try {
+      entries = await fs.readdir(sourceDir);
+    } catch {
+      return 0;
+    }
+
+    const subagentFiles = entries.filter((entry) => entry.startsWith('wizz-exec-') && entry.endsWith('.md'));
+    if (subagentFiles.length === 0) return 0;
+
+    const targetPath = path.join(projectDir, config.agents_target_dir);
+    await fs.ensureDir(targetPath);
+
+    let count = 0;
+    for (const entry of subagentFiles) {
+      await fs.copy(path.join(sourceDir, entry), path.join(targetPath, entry), { overwrite: true });
+      count++;
+    }
+
+    return count;
+  }
+
   /**
    * Print installation summary
    * @param {Object} results - Installation results
@@ -490,6 +544,9 @@ class ConfigDrivenIdeSetup {
         await prompts.log.warn(`  (${cmd.writeFailures} pointer writes failed — see warnings above)`);
       }
     }
+    if (results.subagents > 0 && this.installerConfig?.agents_target_dir) {
+      await prompts.log.success(`${this.name} subagents: ${results.subagents} → ${this.installerConfig.agents_target_dir}`);
+    }
   }
 
   /**
@@ -560,6 +617,16 @@ class ConfigDrivenIdeSetup {
       );
     }
 
+    // Clean stale wizz-exec-*.md subagent files. Like command pointers, these
+    // live in a per-IDE directory (.claude/agents) that isn't deduped across
+    // peers, so this runs regardless of skipTarget. installSubagents always
+    // overwrites with the current source content, so unconditional removal
+    // here is safe — a routine reinstall just recreates the files moments
+    // later.
+    if (this.installerConfig?.agents_target_dir) {
+      await this.cleanupSubagents(projectDir, this.installerConfig.agents_target_dir);
+    }
+
     // Skip target_dir cleanup when a peer platform owns this directory
     // (set during dedup'd install or when uninstalling one of several
     // platforms that share the same target_dir).
@@ -725,6 +792,46 @@ class ConfigDrivenIdeSetup {
     }
   }
 
+  /**
+   * Remove WIZZ-owned `wizz-exec-*.md` subagent files from the platform's
+   * subagent directory (e.g. .claude/agents). Symmetric counterpart to
+   * installSubagents. Only touches files matching that naming convention —
+   * a user's own hand-authored subagents in the same directory are never
+   * removed. Removes the directory entirely if it ends up empty.
+   * @param {string} projectDir
+   * @param {string} agentsTargetDir - Relative dir (e.g. .claude/agents)
+   */
+  async cleanupSubagents(projectDir, agentsTargetDir) {
+    const agentsPath = path.join(projectDir, agentsTargetDir);
+    if (!(await fs.pathExists(agentsPath))) return;
+
+    let entries;
+    try {
+      entries = await fs.readdir(agentsPath);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.startsWith('wizz-exec-') || !entry.endsWith('.md')) continue;
+      try {
+        await fs.remove(path.join(agentsPath, entry));
+      } catch {
+        // Skip files we can't remove.
+      }
+    }
+
+    // Remove the agents directory if we emptied it.
+    try {
+      const remaining = await fs.readdir(agentsPath);
+      if (remaining.length === 0) {
+        await fs.remove(agentsPath);
+      }
+    } catch {
+      // Directory may already be gone.
+    }
+  }
+
   /**
    * Read the canonicalIds currently present in the skill-manifest.csv.
    * Used by cleanup to distinguish "re-install of an existing skill"

package/tools/installer/ide/platform-codes.yaml

@@ -8,6 +8,9 @@
 #     target_dir: Directory where skill directories are installed (project/workspace)
 #     global_target_dir: (optional) User-home directory for global install
 #     ancestor_conflict_check: (optional) Refuse install when ancestor dir has WIZZ files
+#     agents_target_dir: (optional) Directory for native Claude Code subagents
+#       (src/modules/wizz/subagents/*.md). Only claude-code supports the
+#       `model:` frontmatter field these files rely on.
 #
 # INSTALL SCOPE — LOCAL PER PROJECT IS THE ENFORCED DEFAULT.
 # The installer only ever writes skills to the project-relative `target_dir`
@@ -64,6 +67,7 @@ platforms:
     installer:
       target_dir: .claude/skills
       global_target_dir: ~/.claude/skills
+      agents_target_dir: .claude/agents
 
   cline:
     name: "Cline"