ll-skills 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/). A skill `ll-atualizar` lê este arquivo para mostrar o que mudou entre a versão instalada e a publicada.
+
+## [1.0.0] - 2026-09-06
+
+### Alterado
+
+- Distribuição passa de plugin/marketplace para pacote npm: `npx ll-skills@latest` instala skills standalone em `~/.claude/skills/`, sem o prefixo `ll-skills:`.
+- Skills renomeadas para `ll-<nome>` (`ll-pesquisar-mercado`, `ll-voltar-do-futuro`, `ll-desarmar`, `ll-decidir-antes`, `ll-verificar-entrega`, `ll-pesquisar`, `ll-orquestrar`, `ll-atualizar`); agente renomeado para `ll-implementador`.
+- Instalador limpa a instalação anterior: desinstala o plugin legado `ll-skills@ll-skills`, poda arquivos órfãos de instalações standalone anteriores e apaga o cache antigo.
+- Hook de aviso de atualização reescrito em Node; compara a versão instalada com a publicada no npm.
+- `ll-atualizar` passa a rodar `npx --yes ll-skills@latest` e mostra o changelog a partir deste arquivo.
+- Publicação no npm pela CI com Trusted Publishing: tag `vX.Y.Z` dispara verificação (tag × package.json × CHANGELOG), smoke test e `npm publish` com proveniência.
+
+### Removido
+
+- Manifesto de plugin (`.claude-plugin/`) e `hooks/hooks.json`.

package/README.md

@@ -0,0 +1,105 @@
+# LL Skills
+
+Coleção de skills para [Claude Code](https://claude.com/claude-code) que forma um **pipeline de desenvolvimento orientado a evidência**: da ideia à entrega verificada, com o mínimo de retrabalho e o máximo de decisões tomadas com lastro — antes de custar caro.
+
+## Instalação
+
+Requer [Node.js](https://nodejs.org) 18+ (o mesmo que o Claude Code já usa).
+
+```bash
+npx ll-skills@latest
+```
+
+O instalador copia as skills para `~/.claude/skills/ll-*`, o agente para `~/.claude/agents/` e registra um hook de aviso de atualização em `~/.claude/settings.json`. Se houver uma instalação anterior (inclusive o antigo formato de plugin por marketplace), ela é removida na mesma passada. Reinicie o Claude Code ao final.
+
+As skills são invocadas automaticamente pelo Claude quando o pedido bate com a description delas, ou manualmente pelo nome (ex.: `/ll-decidir-antes`). Por serem skills standalone, e não de plugin, não carregam o prefixo `ll-skills:`.
+
+Outras formas:
+
+```bash
+npx github:allangdy/ll-skills          # direto do repositório, sem passar pelo registro npm
+npx ll-skills@latest --local           # instala em ./.claude, só para o projeto atual
+npx ll-skills@latest --uninstall       # remove tudo que o instalador colocou
+CLAUDE_CONFIG_DIR=/outro/dir npx ll-skills@latest   # honra o diretório de configuração alternativo
+```
+
+### Atualizações
+
+Cada versão publicada no npm é uma nova versão. O ll-skills **avisa no início da sessão** quando a versão instalada ficou para trás, e `/ll-atualizar` atualiza por dentro do Claude, mostrando o changelog antes de aplicar. Manualmente: `npx ll-skills@latest` de novo.
+
+## O fluxo completo
+
+```mermaid
+flowchart LR
+    A[ll-pesquisar-mercado] --> B[ll-voltar-do-futuro]
+    B --> C[ll-desarmar]
+    C -->|placar realimenta o dossiê| A
+    C --> D[ll-decidir-antes]
+    D --> E[implementação longa autônoma via SPEC.md]
+    E --> F[ll-verificar-entrega]
+    F -->|falhas viram novas decisões| D
+    O[ll-orquestrar]:::trans -.regras transversais.-> A & B & C & D & E & F
+    classDef trans stroke-dasharray: 5 5
+```
+
+Cada etapa produz o insumo da seguinte, mas **toda skill funciona sozinha** — os handoffs são detectados pelos artefatos no repositório (`docs/`, placar, `SPEC.md`), nunca por acoplamento rígido.
+
+### Para um projeto novo
+
+1. **`ll-pesquisar-mercado`** — antes de qualquer código: dossiê indexado em `docs/` (mercado, dores, concorrentes, preços sem âncora, viabilidade, economia unitária), com força de evidência por linha. Termina com as **decisões em aberto** e as **premissas ordenadas por letalidade**.
+2. **`ll-voltar-do-futuro`** — o premortem: um agente narra do futuro por que o projeto morreu, atacando o que nunca foi medido. Cada falha traz o aviso que já existia, o viés que cegou e o **teste barato com critério de aceite** que a desarma. As premissas do dossiê são metade do insumo.
+3. **`ll-desarmar`** — executa os testes desarmadores e as POCs com aceite pré-registrado ("reprova primeiro") e preenche o **placar**: DESARMADA, CONFIRMADA COM ROTA DE SAÍDA, EM CURSO… Os números medidos realimentam o dossiê.
+4. **`ll-decidir-antes`** — com os riscos desarmados, a entrevista de decisões: perguntas via AskUserQuestion priorizadas por irreversibilidade × impacto (recomendações sempre com lastro — dos mapas do código ou de pesquisa web), consolidadas em **`SPEC.md` + `PROGRESS.md`** com protocolo anti-drift embutido. Decisões já tomadas nas etapas anteriores não são re-perguntadas.
+5. **Implementação longa** — um agente autônomo (horas ou dias) parte do `SPEC.md`, que é autossuficiente: contrato de decisões, critérios verificáveis por comando, marcos, protocolo de escalada. O ll-skills inclui o agente **`ll-implementador`**, que já parte com a `ll-orquestrar` pré-carregada — mas qualquer sessão/agente com a instrução de partida serve.
+6. **`ll-verificar-entrega`** — auditoria de contexto limpo: um verificador que nunca viu o raciocínio da implementação roda os comandos de aceite da SPEC um a um e confere o placar de marcos contra o código real. O auto-relato de agentes degrada em execuções longas; esta etapa é o que transforma "pronto" em pronto.
+
+### Para uma feature de um sistema existente
+
+O mesmo pipeline, encurtado — `ll-pesquisar-mercado` detecta o modo no enquadramento:
+
+1. **`ll-pesquisar-mercado` (modo feature)** — os dados internos entram como fonte de primeira classe (uso real, tickets, churn, pedidos de clientes = preferência revelada), mais gap competitivo da capacidade e impacto em preço/empacotamento. Desfecho: **construir / construir diferente / não construir**.
+2. **`ll-voltar-do-futuro`** — opcional; vale quando a feature é cara, irreversível ou toca contrato de dados.
+3. **`ll-desarmar`** → **`ll-decidir-antes`** → implementação → **`ll-verificar-entrega`**, como no fluxo novo.
+
+Para uma correção pequena ou tarefa trivial, nada disso: o pipeline existe para trabalho onde errar estrutura custa caro.
+
+### Transversais
+
+**`ll-pesquisar`** — pesquisa profunda de qualquer tema (técnica, comparativo de ferramenta, prática nova — ex.: GEO), em qualquer ponto do fluxo. Pesquisadores de contexto limpo com busca web entregam duas camadas: `SINTESE.md` acionável (fatos → backlog APPLY → decisões DISCUSS → gates de medição) e a trilha de evidências por frente com fontes e trechos salvos, para um agente futuro se aprofundar sem refazer a busca. A síntese é a base natural para a entrevista do `ll-decidir-antes` — a invocação da próxima skill é sempre sua.
+
+**`ll-orquestrar`** vale em qualquer etapa que use subagentes — mas é na **implementação longa** que ele mais trabalha: é o manual de como o implementador decompõe por fronteiras de contexto, delega, roteia modelos e verifica com contexto limpo durante horas ou dias. Nas demais etapas, rege os pesquisadores, narradores e verificadores que as skills despacham.
+
+## Skills
+
+| Skill | Etapa | Descrição |
+|---|---|---|
+| `ll-pesquisar-mercado` | 1 | Dossiê de mercado orientado a decisão — projeto novo ou feature de sistema existente |
+| `ll-voltar-do-futuro` | 2 | Premortem narrado do futuro: falhas com aviso, viés e teste desarmador |
+| `ll-desarmar` | 3 | Executa testes desarmadores e POCs com aceite pré-registrado e preenche o placar |
+| `ll-decidir-antes` | 4 | Entrevista de decisões → SPEC.md + PROGRESS.md para implementação autônoma longa |
+| `ll-verificar-entrega` | 6 | Auditoria de contexto limpo da entrega contra os critérios da SPEC |
+| `ll-pesquisar` | — | Pesquisa profunda de qualquer tema em duas camadas: síntese acionável + trilha de evidências reutilizável |
+| `ll-orquestrar` | — | Regras de orquestração multi-agente: delegação, briefs, roteamento, verificação |
+| `ll-atualizar` | — | Atualiza o ll-skills para a última versão publicada, com o changelog do que mudou antes de aplicar |
+
+## Adicionando novas skills
+
+1. Crie `skills/ll-<nome>/SKILL.md` com frontmatter `name: ll-<nome>` (kebab-case, igual ao nome da pasta) e `description` (diz ao Claude **quando** invocar)
+2. Material de profundidade vai em `skills/ll-<nome>/referencias/`, lido no momento certo
+3. Atualize a tabela acima e registre a mudança em `CHANGELOG.md`, numa seção `## [x.y.z] - data` com a versão que vai sair
+4. Publique uma versão (abaixo). O hook avisa quem está atrasado na próxima sessão.
+
+O instalador (`bin/install.js`) descobre as skills pela pasta `skills/ll-*` e os agentes por `agents/ll-*.md`; não há lista para manter. `npm test` roda o smoke test do instalador num diretório isolado.
+
+## Publicando uma versão
+
+A publicação no npm é feita pela CI via [Trusted Publishing](https://docs.npmjs.com/trusted-publishers) (OIDC entre GitHub Actions e npm, sem token guardado em lugar nenhum). Cada tag `vX.Y.Z` dispara `.github/workflows/publish.yml`, que confere tag × `package.json` × `CHANGELOG.md`, roda o smoke test e publica com proveniência.
+
+```bash
+npm version patch|minor|major    # sobe package.json, commita e cria a tag vX.Y.Z
+git push --follow-tags           # o push da tag dispara a publicação
+```
+
+Regra de bump: `patch` para ajuste em skill existente, `minor` para skill nova ou mudança de comportamento, `major` para renomear ou remover skill. O workflow falha se o `CHANGELOG.md` não tiver a seção da versão.
+
+Configuração feita uma vez no npmjs.com, em *Package settings → Trusted Publisher*: GitHub Actions, user `allangdy`, repository `ll-skills`, workflow `publish.yml`. Em *Publishing access*, "Require two-factor authentication and disallow tokens", para que só a CI publique.

package/agents/ll-implementador.md

@@ -0,0 +1,23 @@
+---
+name: ll-implementador
+description: Implementador autônomo de longa duração que executa um SPEC.md gerado pela skill decidir-antes até todos os marcos estarem verdes. Use para disparar a implementação de uma spec pronta (horas ou dias de execução), passando o caminho do SPEC.md na instrução.
+skills: ["ll-orquestrar"]
+---
+
+Você é o implementador de uma especificação de longa duração produzida pela skill
+`ll-decidir-antes`. Sua missão recebe o caminho de um `SPEC.md`; implemente-o até o fim.
+
+Leia a spec inteira antes de qualquer código. Ela é autossuficiente: as decisões da seção 3
+são contrato e nada é re-decidido; a seção 7 é o seu protocolo de operação e prevalece sobre
+qualquer hábito ou instrução genérica de sessão. Estado vive em `PROGRESS.md` e no git, não
+na conversa. Trabalhe um marco por vez até todos estarem `passes: true` com os comandos de
+verificação passando nesta sessão.
+
+Ao delegar trabalho a subagentes, siga a skill `ll-orquestrar` (pré-carregada neste agente):
+delegue apenas subtarefas grandes e genuinamente independentes, com brief autossuficiente e
+roteamento de modelo por etapa, e verifique resultados de subagentes com evidência barata.
+
+Antes de registrar qualquer progresso, audite cada afirmação contra um resultado de
+ferramenta desta sessão — comando rodado, teste executado, arquivo lido. Ao terminar,
+declare o estado real de cada marco; a auditoria final é da skill `ll-verificar-entrega`, e o
+`VERIFICACAO.md` dela, não o seu relato, é o que fecha o trabalho.

package/bin/install.js

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+'use strict';
+
+// Instalador do ll-skills.
+//
+//   npx ll-skills@latest            instala/atualiza em ~/.claude (ou $CLAUDE_CONFIG_DIR)
+//   npx ll-skills@latest --local    instala em ./.claude do diretório atual
+//   npx ll-skills@latest --uninstall
+//
+// Copia skills/ll-*, agents/ll-* e o hook de aviso de atualização para o diretório
+// de configuração do Claude Code, registra o hook em settings.json, grava
+// VERSION + manifesto com sha256 por arquivo e limpa o que ficou de instalações
+// anteriores (plugin legado por marketplace, arquivos órfãos, cache antigo).
+//
+// Sem dependências, sem prompts. Tudo relativo ao próprio pacote (__dirname),
+// nunca ao cwd.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+const { spawnSync } = require('child_process');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const PKG = require(path.join(PKG_ROOT, 'package.json'));
+const PKG_NAME = PKG.name;
+const REPO_URL = 'https://github.com/allangdy/ll-skills.git';
+const LEGACY_PLUGIN_ID = 'll-skills@ll-skills';
+const LEGACY_MARKETPLACE = 'll-skills';
+const HOOK_FILE = 'll-skills-check-update.js';
+const HOOK_MATCHER = 'startup|resume';
+const PREFIXOS_PROPRIOS = ['skills/ll-', 'agents/ll-', 'hooks/ll-skills-', 'll-skills/'];
+
+const CACHE_DIR = path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'll-skills');
+
+// ---------------------------------------------------------------------------
+// utilitários
+// ---------------------------------------------------------------------------
+
+function log(msg) {
+  process.stdout.write(msg + '\n');
+}
+
+function fail(msg, code = 1) {
+  process.stderr.write('ll-skills: ' + msg + '\n');
+  process.exit(code);
+}
+
+function parseArgs(argv) {
+  const args = { uninstall: false, local: false, help: false };
+  for (const a of argv) {
+    if (a === '--uninstall') args.uninstall = true;
+    else if (a === '--local') args.local = true;
+    else if (a === '--help' || a === '-h') args.help = true;
+    else fail(`argumento desconhecido: ${a} (use --help)`);
+  }
+  return args;
+}
+
+function usage() {
+  log(`ll-skills ${PKG.version}
+
+Uso:
+  npx ll-skills@latest              instala ou atualiza em $CLAUDE_CONFIG_DIR ou ~/.claude
+  npx ll-skills@latest --local      instala em ./.claude (só este projeto)
+  npx ll-skills@latest --uninstall  remove tudo que este pacote instalou
+  npx ll-skills@latest --help`);
+}
+
+function resolveConfigDir(args) {
+  if (args.local) return path.resolve(process.cwd(), '.claude');
+  if (process.env.CLAUDE_CONFIG_DIR) return path.resolve(process.env.CLAUDE_CONFIG_DIR);
+  return path.join(os.homedir(), '.claude');
+}
+
+function sha256(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// Retorna `fallback` se o arquivo não existe; `null` se existe mas não é JSON válido.
+function readJson(file, fallback) {
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (e) {
+    if (e.code === 'ENOENT') return fallback;
+    throw e;
+  }
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function writeJsonAtomic(file, obj) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.tmp.${process.pid}`;
+  fs.writeFileSync(tmp, JSON.stringify(obj, null, 2) + '\n');
+  fs.renameSync(tmp, file);
+}
+
+function insideDir(base, target) {
+  const rel = path.relative(base, target);
+  return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function isOwnRel(rel) {
+  return PREFIXOS_PROPRIOS.some((p) => rel.startsWith(p));
+}
+
+function walk(dir, base = dir, out = []) {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) walk(full, base, out);
+    else if (entry.isFile()) out.push(path.relative(base, full));
+  }
+  return out;
+}
+
+// Lista de arquivos do pacote a instalar: [{ src, rel }], rel relativo ao configDir.
+function planFiles(pkgRoot) {
+  const plan = [];
+  const skillsDir = path.join(pkgRoot, 'skills');
+  for (const name of fs.readdirSync(skillsDir)) {
+    if (!name.startsWith('ll-')) continue;
+    const dir = path.join(skillsDir, name);
+    if (!fs.statSync(dir).isDirectory()) continue;
+    for (const rel of walk(dir)) {
+      plan.push({ src: path.join(dir, rel), rel: path.posix.join('skills', name, rel.split(path.sep).join('/')) });
+    }
+  }
+  const agentsDir = path.join(pkgRoot, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const name of fs.readdirSync(agentsDir)) {
+      if (name.startsWith('ll-') && name.endsWith('.md')) {
+        plan.push({ src: path.join(agentsDir, name), rel: `agents/${name}` });
+      }
+    }
+  }
+  const hooksDir = path.join(pkgRoot, 'hooks');
+  if (fs.existsSync(hooksDir)) {
+    for (const name of fs.readdirSync(hooksDir)) {
+      if (name.startsWith('ll-skills-') && name.endsWith('.js')) {
+        plan.push({ src: path.join(hooksDir, name), rel: `hooks/${name}`, mode: 0o755 });
+      }
+    }
+  }
+  return plan;
+}
+
+// ---------------------------------------------------------------------------
+// origem da instalação (registry npm, github: ou clone local)
+// ---------------------------------------------------------------------------
+
+function detectInstallSource(pkgRoot) {
+  const npxRoot = path.resolve(pkgRoot, '..', '..');
+  const key = `node_modules/${PKG_NAME}`;
+  const lock =
+    readJson(path.join(npxRoot, 'node_modules', '.package-lock.json'), null) ||
+    readJson(path.join(npxRoot, 'package-lock.json'), null);
+  const resolved = (lock && lock.packages && lock.packages[key] && lock.packages[key].resolved) || '';
+  if (/^git\+/.test(resolved)) {
+    return { source: 'github', resolved, sha: resolved.split('#')[1] || null };
+  }
+  if (/registry\.npmjs\.org/.test(resolved)) {
+    return { source: 'registry', resolved, sha: null };
+  }
+  const outer = readJson(path.join(npxRoot, 'package.json'), null);
+  const pkgs = (outer && outer._npx && outer._npx.packages) || [];
+  const gh = pkgs.find((p) => /^(github:|git\+|git:)/.test(p));
+  if (gh) return { source: 'github', resolved: gh, sha: null };
+  if (fs.existsSync(path.join(pkgRoot, '.git'))) {
+    const r = spawnSync('git', ['-C', pkgRoot, 'rev-parse', 'HEAD'], { encoding: 'utf8' });
+    const sha = r.status === 0 ? r.stdout.trim() : null;
+    return { source: 'local', resolved: pkgRoot, sha };
+  }
+  return { source: 'local', resolved: pkgRoot, sha: null };
+}
+
+// ---------------------------------------------------------------------------
+// plugin legado (marketplace)
+// ---------------------------------------------------------------------------
+
+function removeLegacyPlugin(configDir) {
+  const registry = readJson(path.join(configDir, 'plugins', 'installed_plugins.json'), {});
+  const entries = registry && registry.plugins && registry.plugins[LEGACY_PLUGIN_ID];
+  if (!Array.isArray(entries) || entries.length === 0) return { found: false, removed: false, manual: [] };
+
+  const cmds = [];
+  for (const e of entries) {
+    const scope = e.scope || 'user';
+    const cwd = scope === 'project' && e.projectPath ? e.projectPath : process.cwd();
+    cmds.push({ args: ['plugin', 'uninstall', LEGACY_PLUGIN_ID, '-s', scope], cwd });
+  }
+  cmds.push({ args: ['plugin', 'marketplace', 'remove', LEGACY_MARKETPLACE], cwd: process.cwd() });
+
+  const manual = [];
+  let cliMissing = false;
+  for (const c of cmds) {
+    if (cliMissing) {
+      manual.push(`claude ${c.args.join(' ')}`);
+      continue;
+    }
+    const r = spawnSync('claude', c.args, { cwd: c.cwd, stdio: 'pipe', encoding: 'utf8', timeout: 60000 });
+    if (r.error && r.error.code === 'ENOENT') {
+      cliMissing = true;
+      manual.push(`claude ${c.args.join(' ')}`);
+      continue;
+    }
+    // Falhas de "já removido" são esperadas e ignoradas.
+  }
+  return { found: true, removed: !cliMissing, manual };
+}
+
+// ---------------------------------------------------------------------------
+// cópia, poda e estado
+// ---------------------------------------------------------------------------
+
+function copyFiles(configDir, plan) {
+  const files = {};
+  for (const item of plan) {
+    const dest = path.join(configDir, item.rel);
+    try {
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      const buf = fs.readFileSync(item.src);
+      fs.writeFileSync(dest, buf);
+      if (item.mode) fs.chmodSync(dest, item.mode);
+      files[item.rel] = sha256(buf);
+    } catch (e) {
+      fail(`não consegui gravar ${dest}: ${e.message}`);
+    }
+  }
+  return files;
+}
+
+function removeEmptyDirsUpTo(dir, stopAt) {
+  let cur = dir;
+  while (insideDir(stopAt, cur)) {
+    try {
+      if (fs.readdirSync(cur).length > 0) return;
+      fs.rmdirSync(cur);
+    } catch {
+      return;
+    }
+    cur = path.dirname(cur);
+  }
+}
+
+function removeManagedFile(configDir, rel) {
+  if (!isOwnRel(rel)) return false;
+  const full = path.resolve(configDir, rel);
+  if (!insideDir(configDir, full)) return false;
+  try {
+    fs.unlinkSync(full);
+  } catch (e) {
+    if (e.code !== 'ENOENT') return false;
+  }
+  removeEmptyDirsUpTo(path.dirname(full), configDir);
+  return true;
+}
+
+function pruneStale(configDir, oldManifest, newFiles) {
+  const removed = [];
+  const old = (oldManifest && oldManifest.files) || {};
+  for (const rel of Object.keys(old)) {
+    if (rel in newFiles) continue;
+    if (removeManagedFile(configDir, rel)) removed.push(rel);
+  }
+  return removed;
+}
+
+function stateDir(configDir) {
+  return path.join(configDir, 'll-skills');
+}
+
+function writeState(configDir, files, sourceInfo) {
+  const dir = stateDir(configDir);
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, 'VERSION'), PKG.version + '\n');
+  writeJsonAtomic(path.join(dir, 'manifest.json'), {
+    version: PKG.version,
+    timestamp: new Date().toISOString(),
+    files,
+  });
+  writeJsonAtomic(path.join(dir, 'install.json'), {
+    version: PKG.version,
+    installedAt: new Date().toISOString(),
+    repo: REPO_URL,
+    ...sourceInfo,
+  });
+}
+
+function clearOldCache() {
+  try {
+    fs.rmSync(CACHE_DIR, { recursive: true, force: true });
+  } catch {
+    /* melhor esforço */
+  }
+}
+
+// ---------------------------------------------------------------------------
+// settings.json
+// ---------------------------------------------------------------------------
+
+function hookCommand(configDir) {
+  const hookPath = path.join(configDir, 'hooks', HOOK_FILE);
+  // `node` bare: com nvm, um caminho absoluto para o binário quebra no próximo `nvm install`.
+  return `command -v node >/dev/null 2>&1 && node "${hookPath}" || true`;
+}
+
+function buildHookEntry(configDir) {
+  return {
+    matcher: HOOK_MATCHER,
+    hooks: [{ type: 'command', command: hookCommand(configDir), timeout: 5 }],
+  };
+}
+
+function isOwnHook(h) {
+  return Boolean(h && typeof h.command === 'string' && h.command.includes(HOOK_FILE));
+}
+
+function stripOwnHooks(settings) {
+  const ss = settings.hooks && settings.hooks.SessionStart;
+  if (!Array.isArray(ss)) return;
+  settings.hooks.SessionStart = ss
+    .map((e) => (e && Array.isArray(e.hooks) ? { ...e, hooks: e.hooks.filter((h) => !isOwnHook(h)) } : e))
+    .filter((e) => !(e && Array.isArray(e.hooks) && e.hooks.length === 0));
+}
+
+function stripLegacyPluginKeys(settings) {
+  if (settings.enabledPlugins && Object.prototype.hasOwnProperty.call(settings.enabledPlugins, LEGACY_PLUGIN_ID)) {
+    delete settings.enabledPlugins[LEGACY_PLUGIN_ID];
+    if (Object.keys(settings.enabledPlugins).length === 0) delete settings.enabledPlugins;
+  }
+  if (settings.extraKnownMarketplaces && Object.prototype.hasOwnProperty.call(settings.extraKnownMarketplaces, LEGACY_MARKETPLACE)) {
+    delete settings.extraKnownMarketplaces[LEGACY_MARKETPLACE];
+    if (Object.keys(settings.extraKnownMarketplaces).length === 0) delete settings.extraKnownMarketplaces;
+  }
+}
+
+function pruneEmptyHooks(settings) {
+  if (settings.hooks && Array.isArray(settings.hooks.SessionStart) && settings.hooks.SessionStart.length === 0) {
+    delete settings.hooks.SessionStart;
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) delete settings.hooks;
+}
+
+// Lê, aplica `mutate(settings)`, grava só se mudou. Retorna 'unchanged' | 'written' | 'invalid'.
+function updateSettings(configDir, mutate) {
+  const file = path.join(configDir, 'settings.json');
+  const settings = readJson(file, {});
+  if (settings === null || typeof settings !== 'object' || Array.isArray(settings)) return 'invalid';
+  const before = JSON.stringify(settings);
+  mutate(settings);
+  if (JSON.stringify(settings) === before) return 'unchanged';
+  if (fs.existsSync(file)) fs.copyFileSync(file, `${file}.ll-skills.bak`);
+  writeJsonAtomic(file, settings);
+  return 'written';
+}
+
+function registerHook(configDir) {
+  return updateSettings(configDir, (s) => {
+    if (!s.hooks || typeof s.hooks !== 'object') s.hooks = {};
+    if (!Array.isArray(s.hooks.SessionStart)) s.hooks.SessionStart = [];
+    stripOwnHooks(s);
+    s.hooks.SessionStart.push(buildHookEntry(configDir));
+    stripLegacyPluginKeys(s);
+  });
+}
+
+function unregisterHook(configDir) {
+  return updateSettings(configDir, (s) => {
+    stripOwnHooks(s);
+    pruneEmptyHooks(s);
+  });
+}
+
+function printManualHookSnippet(configDir) {
+  log('');
+  log(`AVISO: ${path.join(configDir, 'settings.json')} não é um JSON válido; não foi alterado.`);
+  log('Corrija o arquivo e adicione manualmente em "hooks" > "SessionStart":');
+  log('');
+  log(JSON.stringify(buildHookEntry(configDir), null, 2));
+  log('');
+}
+
+// ---------------------------------------------------------------------------
+// fluxos
+// ---------------------------------------------------------------------------
+
+function install(args) {
+  const configDir = resolveConfigDir(args);
+  log(`ll-skills ${PKG.version} → ${configDir}`);
+
+  // 1. plugin legado, ANTES de tocar em settings.json (o CLI `claude` reescreve o arquivo).
+  const legacy = removeLegacyPlugin(configDir);
+  if (legacy.found) {
+    if (legacy.removed) log('• plugin legado ll-skills@ll-skills desinstalado (marketplace removido)');
+    else log('• plugin legado detectado, mas o CLI `claude` não está no PATH');
+  }
+
+  // 2. instalação standalone anterior
+  const oldManifest = readJson(path.join(stateDir(configDir), 'manifest.json'), null);
+
+  // 3. cópia
+  const plan = planFiles(PKG_ROOT);
+  const files = copyFiles(configDir, plan);
+  const skillNames = [...new Set(Object.keys(files).filter((r) => r.startsWith('skills/')).map((r) => r.split('/')[1]))].sort();
+  const agentNames = Object.keys(files).filter((r) => r.startsWith('agents/')).map((r) => path.basename(r, '.md'));
+  log(`• ${skillNames.length} skills: ${skillNames.join(', ')}`);
+  if (agentNames.length) log(`• ${agentNames.length} agente: ${agentNames.join(', ')}`);
+
+  // 4. poda
+  const pruned = pruneStale(configDir, oldManifest, files);
+  if (pruned.length) log(`• ${pruned.length} arquivo(s) órfão(s) removido(s) da instalação anterior`);
+
+  // 5. estado
+  writeState(configDir, files, detectInstallSource(PKG_ROOT));
+
+  // 6. hook
+  const hookResult = registerHook(configDir);
+  if (hookResult === 'written') log('• hook de aviso de atualização registrado em settings.json');
+  else if (hookResult === 'unchanged') log('• hook de aviso de atualização já registrado');
+
+  // 7. cache antigo
+  clearOldCache();
+
+  log('');
+  if (legacy.manual.length) {
+    log('Para concluir a remoção do plugin legado, rode dentro do Claude Code ou no terminal:');
+    for (const c of legacy.manual) log(`  ${c}`);
+    log('');
+  }
+  if (hookResult === 'invalid') {
+    printManualHookSnippet(configDir);
+    log('Reinicie o Claude Code para que as skills ll-* apareçam.');
+    process.exit(1);
+  }
+  log('Pronto. Reinicie o Claude Code para que as skills ll-* apareçam (ex.: /ll-decidir-antes).');
+}
+
+function uninstall(args) {
+  const configDir = resolveConfigDir(args);
+  log(`ll-skills --uninstall → ${configDir}`);
+
+  const manifest = readJson(path.join(stateDir(configDir), 'manifest.json'), null);
+  const rels = manifest && manifest.files ? Object.keys(manifest.files) : planFiles(PKG_ROOT).map((p) => p.rel);
+  let n = 0;
+  for (const rel of rels) if (removeManagedFile(configDir, rel)) n++;
+  log(`• ${n} arquivo(s) removido(s)`);
+
+  try {
+    fs.rmSync(stateDir(configDir), { recursive: true, force: true });
+  } catch {
+    /* melhor esforço */
+  }
+
+  const hookResult = unregisterHook(configDir);
+  if (hookResult === 'written') log('• hook removido de settings.json');
+  else if (hookResult === 'invalid') log(`• AVISO: settings.json inválido; remova o hook "${HOOK_FILE}" manualmente`);
+
+  clearOldCache();
+  log('');
+  log('ll-skills removido. Reinicie o Claude Code.');
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) return usage();
+  if (args.uninstall) return uninstall(args);
+  return install(args);
+}
+
+main();