wizz-method 2.13.0 → 2.15.0

package/src/skills-lib/wizz-ui-component-curator/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wizz-ui-component-curator
-description: analyze an existing frontend project, infer its visual style and product tone, then research and recommend compatible UI components and effects from public component catalogs, registries and source repositories. use when the user wants help choosing components, effects, sections, or visual patterns that fit an existing project — especially hero effects, cards, buttons, testimonials, pricing sections, navigation, or any interactive pattern. trigger whenever the user wants to add a UI element and wants Claude to study the project first before suggesting options. always inspect the codebase and exact component sources, provide evidence and plan before editing.
+description: analyze an existing frontend project, infer its visual style and product tone, then research and recommend compatible UI components and effects from public component catalogs, registries and source repositories. use when the user wants help choosing components, effects, sections, or visual patterns that fit an existing project or dashboard — especially hero effects, cards, buttons, hovers, loading animations, testimonials, pricing sections, navigation, or any interactive pattern. trigger whenever the user wants to add a UI element and wants Claude to study the project first before suggesting options. always inspect the codebase and exact component sources, provide evidence and plan before editing.
 ---
 
 # Overview
@@ -19,6 +19,8 @@ Act as a UI curator with taste and restraint — not a gallery explorer. Optimiz
 
 If `{output_folder}/design-state.yaml` exists, the need being worked is already written there: take its `query`, `budget.fontes` and `floor` instead of improvising them, honour the `proibidos` block, and write the result back under `discoveries` with the `need` id. If the request does not match any open need, say so before researching: an unplanned need is either a gap in the map (go back to `wizz-design-needs`) or scope creep.
 
+Not there? Look before deciding it does not exist: `find . -name design-state.yaml -not -path '*/node_modules/*'`. A map found anywhere else is still the map: use it, and tell the user it is off-place (it belongs in `{output_folder}`).
+
 With no state file, continue normally.
 
 ## 1. Read and infer the style DNA
@@ -38,7 +40,9 @@ Do not ask the user to describe the style unless the project has no inspectable
 
 ## 2. Search and inspect public sources
 
-Start with existing project components. Then search appropriate public sources: [React Bits](https://reactbits.dev/), [Cult UI](https://www.cult-ui.com/docs), [Componentry](https://componentry.dev/), or [shadcn/ui](https://ui.shadcn.com/docs). Compare at least two suitable sources when available.
+Start with existing project components. Then search the public sources. The full authorized list (React Bits, Cult UI, Ali Imam, Watermelon, StyleUI, Skiper UI, Bklit UI, Componentry, shadcn/ui, plus the reference galleries) lives in one place: [component-sources](../wizz-premium-landing-ui-researcher/references/component-sources.md). Read it instead of relying on memory. Compare at least two suitable sources per need.
+
+Use whatever search tools the session has: web search (Exa when configured, WebSearch otherwise), WebFetch, scrapling, and `agent-browser` to watch hover and motion live. A tool that errors or hangs is not the end of the research: record the failure, move to the next tool, and never stop without reporting what was and was not checked.
 
 Open the exact demo and source file/registry item. Check the actual imports, license, dependencies, stack variant and revision; use current official documentation (Context7 when available) for API compatibility. Inspect animation/interaction in the available browser; label static-only inspection honestly. If a source fails, record the failure and continue elsewhere.
 
@@ -68,6 +72,22 @@ Send the exact candidate links and recommendation. If the user authorized implem
 
 ---
 
+## Dashboard and app panels
+
+A panel is used every day, so the bar is different from a landing page: motion that delights once tires on the tenth visit. When the project is a dashboard, admin or operational panel, cover these categories (only the ones the request or the map opens):
+
+- loading: skeleton, spinner, route progress, branded loader
+- action feedback: toast, confirmation, undo, a discreet success state
+- numbers: animated counter, sparkline, gauge, KPI card
+- lists and queues: enter/exit animation, swipe actions on mobile
+- navigation: sidebar, command menu, tooltip, dock
+- surfaces: hover states, border glow, spotlight, subtle background
+- empty states, charts and form controls
+
+For each candidate, judge "does it tire with daily use", reduced-motion support and weight. Reject landing-page effects that do not serve a task.
+
+---
+
 # Consistency rules
 
 If there is tension between the most impressive option and the best-fitting option: **choose the one that fits.**

package/tools/installer/core/doctor.js

@@ -25,7 +25,7 @@ const { HOOK_DEFS, isOurHookCommand } = require('./hooks-settings');
 const { classifyPython, PYTHON_ONLY_SKILLS } = require('./python-check');
 
 // Piso de versão do rtk que o hook rtk-rewrite.sh exige para `rtk rewrite`
-// (o registry pin do CLI é mais alto, 0.45.0, e é aplicado pelo detectClis
+// (o registry pin do CLI é mais alto, 0.50.0, e é aplicado pelo detectClis
 // no install; aqui reportamos o piso que quebra o hook hoje).
 const RTK_HOOK_FLOOR = '0.23.0';
 
@@ -464,6 +464,28 @@ async function currentInputHash({ projectDir, relPath, skill, sources, fileExist
  * @param {object} [options.deps] - checkers injetáveis (ver chamadas abaixo)
  * @returns {Promise<{results: Array<{check, status, detail}>, exitCode: number, hasError: boolean}>}
  */
+/**
+ * CLAUDE.md/AGENTS.md: bloco Wizz presente e sem regra legada fora dele.
+ * Sem o bloco, um CLAUDE.md antigo vence as regras do Wizz (2026-09-30).
+ * @returns {Promise<{check: 'instructions', status: 'ok'|'warn', detail: string}>}
+ */
+async function checkProjectInstructions({ projectDir, fileExists, readFile }) {
+  const { INSTRUCTION_FILES, BLOCK_BEGIN, scanLegacy } = require('./project-instructions');
+  const problems = [];
+  let seen = 0;
+  for (const name of INSTRUCTION_FILES) {
+    const file = path.join(projectDir, name);
+    if (!(await fileExists(file))) continue;
+    seen += 1;
+    const text = await readFile(file);
+    if (!text.includes(BLOCK_BEGIN)) problems.push(`${name} sem o bloco Wizz no topo (rode wizz install)`);
+    for (const f of scanLegacy(text)) problems.push(`${name}:${f.line} ${f.why}: ${f.snippet}`);
+  }
+  if (seen === 0) return { check: 'instructions', status: 'ok', detail: 'Sem CLAUDE.md/AGENTS.md no projeto.' };
+  if (problems.length === 0) return { check: 'instructions', status: 'ok', detail: 'Bloco Wizz presente, nenhuma regra legada.' };
+  return { check: 'instructions', status: 'warn', detail: problems.join('\n') };
+}
+
 async function runDoctor(options = {}) {
   const deps = options.deps || {};
   const {
@@ -578,6 +600,13 @@ async function runDoctor(options = {}) {
     });
   }
 
+  // 7) instructions — CLAUDE.md/AGENTS.md com bloco Wizz e sem regra legada.
+  if (skip.includes('instructions')) {
+    results.push({ check: 'instructions', status: 'ok', detail: 'pulado.' });
+  } else if (wizzDir) {
+    results.push(await checkProjectInstructions({ projectDir, fileExists, readFile }));
+  }
+
   const hasError = results.some((r) => r.status === 'error');
   return { results, exitCode: hasError ? 1 : 0, hasError };
 }
@@ -631,6 +660,7 @@ function safeReadJson(file) {
 }
 
 module.exports = {
+  checkProjectInstructions,
   CHECKS,
   RTK_HOOK_FLOOR,
   extractVersion,

package/tools/installer/core/installer.js

@@ -20,6 +20,7 @@ const { buildHookEntries, filterHooksRegisteredGlobally, mergeHooksIntoSettings
 
 const { ExistingInstall } = require('./existing-install');
 const { warnPreNativeSkillsLegacy } = require('./legacy-warnings');
+const { applyProjectInstructions, removeProjectInstructions } = require('./project-instructions');
 const userFilePreservation = require('./user-file-preservation');
 const moduleConfigWriter = require('./module-config-writer');
 const helpCatalog = require('./help-catalog');
@@ -808,6 +809,11 @@ class Installer {
           addResult('Hooks settings', 'ok', `${pendingHooksSettingsWrite.count} hook(s) → .claude/settings.json${skippedDetail}`);
         }
 
+        // Bloco gerenciado no CLAUDE.md/AGENTS.md (2026-09-30): sem ele, um
+        // CLAUDE.md antigo vence as regras do Wizz, que chegam só por hook.
+        // Depois do swap pelo mesmo motivo do settings.json: vive fora de _wizz/.
+        await this._applyProjectInstructions(paths, config, addResult);
+
         await this._appendPreservedSkillManifestRows(paths.wizzDir, previousSkillManifestRows, preservedModules);
 
         // Apply post-install --set TOML patches. Runs after writeCentralConfig
@@ -1223,6 +1229,31 @@ class Installer {
    * @param {string} file
    * @returns {Promise<{settings: object, invalidJson: boolean}>}
    */
+  async _applyProjectInstructions(paths, config, addResult) {
+    if (!(await fs.pathExists(path.join(paths.wizzDir, 'wizz')))) return;
+    try {
+      const results = await applyProjectInstructions({
+        projectRoot: paths.projectRoot,
+        fs,
+        createIfMissing: (config.ides || []).includes('claude-code'),
+      });
+      for (const r of results) {
+        const name = path.basename(r.file);
+        const legacy = r.findings.length > 0 ? `, ${r.findings.length} trecho(s) legado(s) marcados` : '';
+        addResult('Project instructions', r.findings.length > 0 ? 'warn' : 'ok', `bloco Wizz no topo de ${name}${legacy}`);
+      }
+      const totalLegacy = results.reduce((n, r) => n + r.findings.length, 0);
+      if (totalLegacy > 0) {
+        await prompts.log.warn(
+          `${totalLegacy} regra(s) antiga(s) no CLAUDE.md/AGENTS.md (GSD, superpowers, BMAD puro ou modelo aposentado). O bloco Wizz no topo tem prioridade, mas vale limpar: rode wizz doctor para ver as linhas.`,
+        );
+      }
+    } catch (error) {
+      await prompts.log.warn(`Falha ao gravar o bloco Wizz no CLAUDE.md/AGENTS.md: ${error.message}`);
+      addResult('Project instructions', 'warn', error.message);
+    }
+  }
+
   async _readSettingsJson(file) {
     if (!(await fs.pathExists(file))) return { settings: {}, invalidJson: false };
     try {
@@ -1600,6 +1631,7 @@ class Installer {
     // 2. IDE CLEANUP (before _wizz/ deletion so configs are accessible)
     if (options.removeIdeConfigs !== false) {
       await this.uninstallIdeConfigs(projectDir, existingInstall, { silent: options.silent });
+      await removeProjectInstructions({ projectRoot: projectDir, fs });
       removed.ideConfigs = true;
     }
 

package/tools/installer/core/project-instructions.js

@@ -0,0 +1,199 @@
+// project-instructions.js — bloco gerenciado no CLAUDE.md/AGENTS.md do projeto.
+//
+// Motivo (2026-09-30): o Claude Code carrega o CLAUDE.md do projeto como
+// instrução de projeto (prioridade alta), enquanto as regras do Wizz chegam
+// por hook e skill (contexto extra, prioridade menor). Num projeto que já
+// tinha CLAUDE.md antigo (GSD, superpowers, BMAD puro, modelos aposentados),
+// a regra velha vencia a nova. O installer agora grava um bloco no TOPO do
+// arquivo dizendo que o Wizz vence em conflito e listando os trechos legados
+// detectados. Nada fora do bloco é apagado ou reescrito.
+//
+// Lógica pura (texto → texto) + um aplicador fino com fs injetável, para os
+// testes não dependerem de disco real.
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+
+const BLOCK_BEGIN = '<!-- wizz:begin -->';
+const BLOCK_END = '<!-- wizz:end -->';
+const INSTRUCTION_FILES = ['CLAUDE.md', 'AGENTS.md'];
+
+// IDs de modelo aposentados. Compartilhado com tools/validate-model-ids.mjs.
+// claude-haiku-4-5 continua atual (não há Haiku mais novo em 2026-09-30).
+// `claude-(opus|sonnet)-5` sem sufixo foi trocado por 5-5; o lookahead evita
+// casar o próprio `-5-5`.
+const RETIRED_MODEL_RE =
+  /\bclaude-(?:instant|2|3|3-5|3-7)(?:-[a-z0-9]+)*\b|\bclaude-(?:opus|sonnet)-4(?:-\d+)?\b|\bclaude-(?:opus|sonnet)-5\b(?!-)/gi;
+
+const LEGACY_RULES = [
+  { id: 'gsd', re: /\bGSD\b|get-shit-done|\/gsd[:-]/, why: 'GSD foi substituído pelas fases e checkpoints do Wizz Method' },
+  { id: 'superpowers', re: /\bsuperpowers\b/i, why: 'superpowers foi substituído pelo Wizz Method' },
+  {
+    id: 'bmad',
+    re: /_bmad\/|\/bmad[-:]|\bbmad-(?:master|agent|method|help)\b/i,
+    why: 'comandos e pastas do BMAD puro viraram wizz-* e _wizz/',
+  },
+  { id: 'modelo-aposentado', re: RETIRED_MODEL_RE, why: 'ID de modelo aposentado; a escada do Wizz usa os apelidos atuais' },
+];
+
+const MAX_SNIPPET = 120;
+
+// project-context.md (2026-09-30, porte do BMAD 6.12 #2750): em vez de cada
+// skill procurar o arquivo em toda ativação (persistent_facts), o bloco
+// importa uma vez por sessão. Busca rasa, pulando pastas de dependência/build.
+const CONTEXT_FILE = 'project-context.md';
+const CONTEXT_MAX_DEPTH = 4;
+const CONTEXT_SKIP_DIRS = new Set(['node_modules', '.git', '_wizz', '.claude', 'build', 'dist', '.next', 'vendor', '.venv']);
+
+/** Caminho relativo (posix) do project-context.md mais raso, ou null. */
+async function findProjectContext(projectRoot) {
+  let level = [projectRoot];
+  for (let depth = 0; depth <= CONTEXT_MAX_DEPTH && level.length > 0; depth++) {
+    const next = [];
+    for (const dir of level.sort()) {
+      let entries;
+      try {
+        entries = await fsp.readdir(dir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      if (entries.some((e) => e.isFile() && e.name === CONTEXT_FILE)) {
+        return path.relative(projectRoot, path.join(dir, CONTEXT_FILE)).split(path.sep).join('/');
+      }
+      for (const e of entries) if (e.isDirectory() && !CONTEXT_SKIP_DIRS.has(e.name)) next.push(path.join(dir, e.name));
+    }
+    level = next;
+  }
+  return null;
+}
+
+/** Linha de contexto por arquivo: CLAUDE.md importa com @; AGENTS.md só aponta. */
+function contextLine(fileName, contextPath) {
+  if (!contextPath) return null;
+  return fileName === 'CLAUDE.md'
+    ? `Contexto do projeto (regras de stack e padrões, importado uma vez por sessão):\n@${contextPath}`
+    : `- Contexto do projeto: leia \`${contextPath}\` antes de implementar (regras de stack e padrões).`;
+}
+
+/** Separa o bloco gerenciado do resto do arquivo. */
+function splitManagedBlock(text) {
+  const start = text.indexOf(BLOCK_BEGIN);
+  const end = text.indexOf(BLOCK_END);
+  if (start === -1 || end === -1 || end < start) return { block: null, rest: text };
+  const after = text.slice(end + BLOCK_END.length).replace(/^\r?\n+/, '');
+  return { block: text.slice(start, end + BLOCK_END.length), rest: text.slice(0, start) + after };
+}
+
+/**
+ * Procura regras legadas no texto, pulando as linhas do bloco gerenciado.
+ * `line` é a linha real no arquivo (1-based), para o doctor apontar.
+ * @returns {{id: string, line: number, snippet: string, why: string}[]}
+ */
+function scanLegacy(text) {
+  const findings = [];
+  let inBlock = false;
+  for (const [i, line] of text.split(/\r?\n/).entries()) {
+    if (line.includes(BLOCK_BEGIN)) inBlock = true;
+    if (inBlock) {
+      if (line.includes(BLOCK_END)) inBlock = false;
+      continue;
+    }
+    const rule = LEGACY_RULES.find((r) => new RegExp(r.re.source, r.re.flags.replace('g', '')).test(line));
+    if (rule) findings.push({ id: rule.id, line: i + 1, snippet: line.trim().slice(0, MAX_SNIPPET), why: rule.why });
+  }
+  return findings;
+}
+
+/** Monta o bloco. Sem número de linha: o próprio bloco desloca as linhas. */
+function renderManagedBlock(findings = [], context = null) {
+  const lines = [
+    BLOCK_BEGIN,
+    '<!-- Gerenciado pelo Wizz Method: o install reescreve este bloco. Edite fora dele. -->',
+    '## Wizz Method: estas regras têm prioridade',
+    '',
+    'Este projeto usa o Wizz Method (`_wizz/`). Se alguma instrução deste arquivo, fora deste bloco, contradizer o Wizz Method, vale o Wizz Method.',
+    '',
+    '- Pedido não trivial: uma área vai para o agente da área; duas ou mais áreas vão para o `wizz-maestro`. Edição trivial de 1 linha e conversa executam direto.',
+    '- Planejamento, TDD, checkpoints e review seguem o Wizz Method. Não usar GSD, superpowers nem os comandos antigos do BMAD (`/bmad-*`, `_bmad/`).',
+    '- Modelos seguem a escada do Wizz (`wizz-exec-mechanical`, `-standard`, `-strong`, `-ultra`, `-review`), que usa os apelidos atuais. Ignore IDs de modelo fixos deste arquivo.',
+  ];
+  if (context) lines.push('', ...context.split('\n'));
+  if (findings.length > 0) {
+    lines.push('', 'Trechos legados detectados abaixo (não valem mais; `wizz doctor` lista de novo):');
+    for (const f of findings) lines.push(`- \`${f.snippet.replaceAll('`', "'")}\` (${f.why})`);
+  }
+  lines.push(BLOCK_END);
+  return lines.join('\n');
+}
+
+/** Insere ou substitui o bloco no topo. Idempotente. */
+function upsertManagedBlock(text, context = null) {
+  const { rest } = splitManagedBlock(text);
+  const findings = scanLegacy(rest);
+  const block = renderManagedBlock(findings, context);
+  const body = rest.replace(/^\s+/, '');
+  return { text: body ? `${block}\n\n${body}` : `${block}\n`, findings };
+}
+
+/** Remove o bloco (uninstall). Devolve o texto intacto se não houver bloco. */
+function removeManagedBlock(text) {
+  return splitManagedBlock(text).rest;
+}
+
+/**
+ * Aplica o bloco nos arquivos de instrução que existem na raiz do projeto.
+ * Sem nenhum dos dois, cria CLAUDE.md só se `createIfMissing`.
+ * Com project-context.md no projeto, o bloco importa (CLAUDE.md) ou aponta (AGENTS.md) para ele.
+ * @returns {Promise<{file: string, changed: boolean, findings: object[]}[]>}
+ */
+async function applyProjectInstructions({ projectRoot, fs, createIfMissing = false }) {
+  const results = [];
+  const targets = [];
+  for (const name of INSTRUCTION_FILES) {
+    const file = path.join(projectRoot, name);
+    if (await fs.pathExists(file)) targets.push(file);
+  }
+  if (targets.length === 0 && createIfMissing) targets.push(path.join(projectRoot, 'CLAUDE.md'));
+
+  const contextPath = await findProjectContext(projectRoot);
+  for (const file of targets) {
+    const before = (await fs.pathExists(file)) ? await fs.readFile(file, 'utf8') : '';
+    const { text, findings } = upsertManagedBlock(before, contextLine(path.basename(file), contextPath));
+    const changed = text !== before;
+    if (changed) await fs.writeFile(file, text, 'utf8');
+    results.push({ file, changed, findings });
+  }
+  return results;
+}
+
+/** Tira o bloco dos arquivos de instrução (uninstall). */
+async function removeProjectInstructions({ projectRoot, fs }) {
+  const removed = [];
+  for (const name of INSTRUCTION_FILES) {
+    const file = path.join(projectRoot, name);
+    if (!(await fs.pathExists(file))) continue;
+    const before = await fs.readFile(file, 'utf8');
+    const after = removeManagedBlock(before);
+    if (after !== before) {
+      await fs.writeFile(file, after, 'utf8');
+      removed.push(file);
+    }
+  }
+  return removed;
+}
+
+module.exports = {
+  BLOCK_BEGIN,
+  BLOCK_END,
+  INSTRUCTION_FILES,
+  findProjectContext,
+  contextLine,
+  RETIRED_MODEL_RE,
+  splitManagedBlock,
+  scanLegacy,
+  renderManagedBlock,
+  upsertManagedBlock,
+  removeManagedBlock,
+  applyProjectInstructions,
+  removeProjectInstructions,
+};