ll-skills 1.0.1 → 2.0.2

package/CHANGELOG.md

@@ -1,6 +1,84 @@
 # 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.
+Formato baseado em [Keep a Changelog](https://keepachangelog.com/pt-BR/1.1.0/). A skill `ll-update` lê este arquivo para mostrar o que mudou entre a versão instalada e a publicada.
+
+## [2.0.2] - 2026-09-08
+
+### Alterado
+
+- Textos de referência das skills revisados; exemplos com placeholders.
+- Smoke test: verificação opcional de termos por lista externa (`LL_FORBIDDEN_FILE`).
+
+## [2.0.1] - 2026-09-08
+
+### Alterado
+
+- Documentação e textos de referência revisados: exemplos genéricos e vocabulário uniforme; sem mudança de comportamento das skills.
+- Instalador: diagnóstico de limpeza restrito ao cache do plugin legado.
+
+## [2.0.0] - 2026-09-07
+
+### Resumo
+
+- O pacote deixa de ser uma coleção de 8 skills soltas e vira um ciclo de trabalho: 11 skills, 4 agentes, 3 hooks e um helper que compartilham o mesmo estado em arquivos versionados do repositório.
+- Um preâmbulo roteador escrito no `~/.claude/CLAUDE.md` classifica todo pedido em 8 regimes antes de agir — pedido pequeno continua pequeno, pedido grande cai na skill certa sem você digitar o nome.
+- A execução ganha skill própria (`ll-implement`): uma fase inteira — conversa, scouting, plano, revisão adversarial, ondas TDD com um executor por marco, verificação de contexto limpo e epílogo — em uma invocação.
+- Tudo o que o modelo lê passa a ser inglês (nomes de skills, agentes, arquivos, campos YAML, prompts); a conversa com você continua em português.
+
+### Quebras
+
+- **Idioma.** Nomes de skills, agentes, artefatos, campos de estado e todo o texto que o modelo lê estão em inglês. Só as respostas ao dono, o README e este changelog ficam em português.
+- **Skills renomeadas, fundidas e removidas.** A primeira instalação 2.x apaga as 8 pastas antigas:
+
+  | Antes (1.x) | Agora (2.0.0) |
+  |---|---|
+  | `ll-pesquisar` | `ll-research` |
+  | `ll-pesquisar-mercado` | `ll-research --market` |
+  | `ll-decidir-antes` | `ll-decide` (modo `project`) |
+  | `ll-voltar-do-futuro` | `ll-decide` — passo do premortem |
+  | `ll-desarmar` | `ll-decide` — passo de desarme (`--measure`) |
+  | `ll-verificar-entrega` | `ll-verify` |
+  | `ll-atualizar` | `ll-update` |
+  | `ll-orquestrar` | seção `## Delegation` do preâmbulo + `references/briefs.md` do `ll-implement` |
+
+- **`agents/ll-implementador.md` removido.** Em seu lugar entram 4 agentes de papel único: `ll-executor`, `ll-scout`, `ll-verifier`, `ll-reviewer`.
+- **`SPEC.md` sai do contrato.** O contrato passa a ser `PLAN.md` + `ROADMAP.md` + `PROGRESS.md` + `phases/NN/`. Repositórios com `SPEC.md` continuam legíveis: `ll-resume` reconhece os nomes antigos por alias só-leitura.
+- **O instalador escreve no `~/.claude/CLAUDE.md`.** Um bloco delimitado por `<!-- ll-skills:preamble v1 -->` … `<!-- /ll-skills:preamble -->` é gravado com diff e aprovação (backup em `CLAUDE.md.ll-skills.bak`); fora de TTY nada é escrito sem `--yes`. `--uninstall` remove o bloco e deixa o resto do arquivo byte a byte igual.
+- **O instalador registra 3 hooks** em vez de 1: `SessionStart` passa a ter `matcher: "startup|resume|compact"` com dois hooks, e `PreCompact` ganha um. A entrada legada `startup|resume` é limpa na atualização.
+- **Novas flags do instalador:** `--no-settings` (imprime o trecho dos hooks em vez de escrever), `--no-preamble` (não toca no `CLAUDE.md`), `--yes`/`-y` (aprova o preâmbulo sem prompt, para uso não interativo).
+
+### Novo
+
+- **Preâmbulo roteador** (`assets/preamble.md`, ≤70 linhas) com 8 regimes — SMALL, FIX, RESEARCH, OPS, LARGE, EXECUTE, RESUME, REFINE —, a política de delegação (profundidade 1, brief de 12 campos, modelo por papel), as 3 faixas de decisão e a regra de prova ("timeout não é verde").
+- **11 skills**, uma linha cada:
+
+  | Skill | O que faz |
+  |---|---|
+  | `ll-brainstorm` | Abre fase, projeto ou ideia solta decidindo na frente do dono: mapa A/B/C ≤35 linhas, uma bateria de ≤4 perguntas, sai em `phases/NN/DECISIONS.md` ou `docs/decide/OPENING.md` |
+  | `ll-research` | Pesquisa com frentes de contexto limpo e busca web → `docs/research-<tema>/` com SUMMARY (Apply/Discuss/Gates), trilha de evidências e fontes datadas; `--market` para mercado, concorrência e preço |
+  | `ll-decide` | Vira um pedido em contrato: gate de premissas, premortem, desarme, sala de decisão, entrevista em baterias → `PLAN.md` §0–§11, `ROADMAP.md`, `decisions/`; modo `feedback` ingere docx/pdf/xlsx |
+  | `ll-goal` | Escreve o texto de `/goal` em 9 partes (≤4.000 chars) e salva `docs/GOAL.md`; você cola em sessão nova |
+  | `ll-implement` | Roda uma fase inteira numa invocação: conversa, scouting, plano, revisão, ondas TDD, verificação e epílogo |
+  | `ll-verify` | Audita em contexto limpo com 3 camadas e ledger FRESH/STALE por critério → `VERIFICATION.md` com dois selos |
+  | `ll-close` | Fecha entrega ou milestone: backlog reconciliado, `docs/DELIVERY.md`, retrospectiva, lições para a memória, uma ratificação em bloco |
+  | `ll-resume` | Reconstrói o estado em ordem fixa de leitura e responde em ≤20 linhas, sem escrever nada |
+  | `ll-refine` | Uma rodada de refino num produto que já roda; modo `visual` faz o loop referência → gate → validador até o veredito FIEL |
+  | `ll-oncall` | Sessão que segura um papel: contrato `## Federation`, log numerado de pedidos; modos `watch` (vigília) e `ops` (deploy com pré-flight) |
+  | `ll-update` | Atualiza o pacote mostrando o changelog entre instalado e publicado antes de aplicar |
+
+- **4 agentes:** `ll-executor` (opus, um marco, allowlist de arquivos, commits atômicos, bloco de retorno fixo), `ll-scout` (sonnet, só `phases/NN/CODE-CONTEXT.md`), `ll-verifier` (opus, `memory: project`, nunca conserta), `ll-reviewer` (opus + Playwright, "imagem não vista = check não feito"). Nenhum deles despacha subagente.
+- **3 hooks:** `ll-skills-check-update.js` (aviso de versão nova), `ll-state.js` (SessionStart: injeta epílogo, últimas linhas do PROGRESS, git status, worktrees, decisões WAITING e o placar de marcos), `ll-precompact.js` (PreCompact: carimba no PROGRESS a ordem de reler o plano depois da compactação).
+- **Helper `scripts/ll-tools.js`** (Node puro, sem dependências), copiado dentro de `ll-implement`, `ll-verify` e `ll-close` na instalação, com 12 comandos: `state`, `waves`, `plan-lint`, `tdd-gate`, `spot-check`, `dec-reserve`, `passes`, `heartbeat`, `ledger`, `backlog-reconcile`, `epilogue`, `phase-stats`.
+- **Estado em arquivos do repositório:** `PLAN.md` (contrato), `ROADMAP.md` (fases e critérios), `PROGRESS.md` (bloco `ll-state` + epílogo), `BACKLOG.md` (itens com condição executável), `VERIFICATION.md` (ledger e veredito), `decisions/` (`DEC-NNNN`, numeração reservada pelo helper), `phases/NN/` (`DECISIONS.md`, `CODE-CONTEXT.md`, `PLAN.md`).
+- **`assets/settings.suggested.json`**: política sugerida (deny list, `autoCompactWindow`, cache, modelos) que o instalador **imprime** e nunca escreve.
+- `publish.yml`: a confirmação no registro espera a propagação por até 60 s em vez de consultar no mesmo segundo do publish.
+
+
+### Migração
+
+- A primeira instalação 2.x poda as 8 skills antigas e `agents/ll-implementador.md` pelo manifesto sha256, mesmo sem manifesto anterior. Nada alheio a `skills/ll-*`, `agents/ll-*` e `hooks/ll-*` é tocado.
+- Projetos em andamento continuam funcionando: nada é renomeado no meio de uma fase, e `ll-resume` lê `PLANO.md`, `SPEC.md`, `PROGRESS.md` e `VERIFICACAO.md` pelos nomes antigos.
+- Limpeza da máquina (cache de plugin antigo) é **diagnosticada e impressa** pelo instalador, nunca executada.
 
 ## [1.0.1] - 2026-09-07
 

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Um ciclo de trabalho para [Claude Code](https://claude.com/claude-code): 11 skills, 4 agentes, 3 hooks e um helper que compartilham o mesmo estado em arquivos versionados do repositório. Um preâmbulo roteador instalado no seu `~/.claude/CLAUDE.md` classifica cada pedido antes de agir — pedido pequeno continua pequeno, pedido grande cai na skill certa sem você digitar o nome dela. O produto real é a fase: `ll-implement` roda conversa, plano, revisão adversarial, ondas de execução com TDD, verificação de contexto limpo e epílogo em **uma** invocação, e escreve tudo em disco à medida que acontece, para que uma compactação não perca nada.
 
 ## Instalação
 
@@ -10,96 +10,161 @@ Requer [Node.js](https://nodejs.org) 18+ (o mesmo que o Claude Code já usa).
 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:
+Reinicie o Claude Code ao final. As skills são standalone — sem o prefixo `ll-skills:` — e podem ser chamadas pelo nome (`/ll-implement 3`) ou escolhidas pelo roteador do preâmbulo.
 
 ```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
+npx ll-skills@latest --local          # instala em ./.claude, só para o projeto atual
+npx ll-skills@latest --no-settings    # não escreve hooks; imprime o trecho para colar
+npx ll-skills@latest --no-preamble    # não toca no ~/.claude/CLAUDE.md
+npx ll-skills@latest --yes            # aprova o bloco do preâmbulo sem prompt (uso não interativo)
+npx ll-skills@latest --uninstall      # remove skills, agentes, hooks, cópias do helper e o preâmbulo
+npx github:allangdy/ll-skills         # direto do repositório, sem passar pelo npm
 ```
 
-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.
+O que a instalação **escreve** (em `$CLAUDE_CONFIG_DIR` ou `~/.claude`):
 
-### Para um projeto novo
+| Caminho | Conteúdo |
+|---|---|
+| `skills/ll-*/` | as 11 skills, com `SKILL.md` e `references/` |
+| `skills/ll-{implement,verify,close}/scripts/ll-tools.js` | cópia do helper, uma por skill que o usa |
+| `agents/ll-{executor,scout,verifier,reviewer}.md` | os 4 agentes |
+| `hooks/ll-{skills-check-update,state,precompact}.js` | os 3 hooks, executáveis |
+| `settings.json` | duas entradas em `SessionStart` (`startup\|resume\|compact`) e uma em `PreCompact`; backup em `settings.json.ll-skills.bak` |
+| `CLAUDE.md` | o bloco entre `<!-- ll-skills:preamble v1 -->` e `<!-- /ll-skills:preamble -->`, com diff e aprovação; backup em `CLAUDE.md.ll-skills.bak` |
+| `ll-skills/{VERSION,manifest.json,install.json}` | versão, manifesto sha256 (base da poda e do `--uninstall`) e origem da instalação |
 
-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.
+O que a instalação apenas **imprime**, e nunca escreve: a política sugerida de `settings.json` (`assets/settings.suggested.json` — deny list, `autoCompactWindow`, cache, modelos por papel) e o diagnóstico de sobras de instalações antigas. Reinstalar é idempotente; a primeira instalação 2.x poda as skills 1.x pelo manifesto.
 
-### Para uma feature de um sistema existente
+## Como funciona
 
-O mesmo pipeline, encurtado — `ll-pesquisar-mercado` detecta o modo no enquadramento:
+O preâmbulo classifica todo pedido por três critérios — lacuna de intenção, irreversibilidade e pegada — e anuncia o regime em uma linha antes de agir.
 
-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.
+| Regime | Gatilho | O que acontece | Skill |
+|---|---|---|---|
+| SMALL | verbo + alvo endereçável, ≤25 palavras, ~3 chamadas | lê o alvo, faz, verifica com um número | nenhuma |
+| FIX | "não era isso", "quebrou", "não sobe" | após 2 tentativas iguais, para, junta evidência, diagnostica | nenhuma |
+| RESEARCH | "pesquise", "compare", "docs oficiais", restrição não validada | frentes paralelas + contra-evidência + checagem de citação | `ll-research` |
+| OPS | deploy, apply, cutover, credencial, IP, "avise a infra" | pré-flight de capacidades e verdade por outro caminho | `ll-oncall` |
+| LARGE | ideia nova, "plano", horas de máquina, cria um lugar | plano de ataque em 5 linhas, depois o contrato | `ll-decide` |
+| EXECUTE | "implementa", "continua", marco com `passes: false` | a fase inteira em uma invocação | `ll-implement` |
+| RESUME | 1º turno num repo com PROGRESS.md, "onde paramos" | briefing de ≤20 linhas, nada escrito | `ll-resume` |
+| REFINE | produto rodando + "melhorar", "fiel ao protótipo" | uma rodada fechada de refino | `ll-refine` |
 
-Para uma correção pequena ou tarefa trivial, nada disso: o pipeline existe para trabalho onde errar estrutura custa caro.
+Uma palavra sua vence o classificador (`direto`, `pesquise`, `plano`, `implementa`, `fecha`, `status`). E a regra que amarra o conjunto: **uma skill nunca chama outra**. Cada uma termina num arquivo dentro do repositório e imprime `▶ Next — /clear, depois <comando>`; quem cola é você.
 
-### Transversais
+## Ciclo de um projeto
 
-**`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.
+Uma vez por milestone, com a contagem de prompts seus por etapa:
 
-**`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.
+| Etapa | Prompts | Sai disso |
+|---|---|---|
+| ideia → roteador | 1 | plano de ataque em 5 linhas (LARGE) |
+| `ll-brainstorm` | 0–1 | mapa A/B/C + bateria de ≤4 → `DECISIONS.md` / `OPENING.md` |
+| `ll-research` | 0–1 | `docs/research-<tema>/` com SUMMARY, evidências e fontes |
+| `ll-decide` | 1 + cliques | `PLAN.md`, `ROADMAP.md`, `decisions/`, `PROGRESS.md` vazio |
+| `ll-goal` | 2 (emite, você cola) | `docs/GOAL.md` + o texto para `/goal` |
+| `ll-implement` × n | 0–1 cada | a fase entregue e verificada |
+| `ll-verify` | 0 (citada no goal) | `VERIFICATION.md` com veredito e dois selos |
+| `ll-close` | 0–1 + 1 ratificação | `docs/DELIVERY.md`, retrospectiva, arquivo do milestone |
+
+## Ciclo de uma fase
+
+`ll-implement N`, oito passos, com um executor por marco além do scout, do verificador e — quando há UI — do revisor:
+
+0. **State** — lê ROADMAP, PLAN, o bloco `ll-state` do PROGRESS e o git log; marcos com `passes: false` entram em modo retomada.
+1. **Conversation** — uma tela de mapa A/B/C, pulada com `--no-talk` ou se `phases/NN/DECISIONS.md` já existe.
+2. **Scouting** — `ll-scout` escreve `phases/NN/CODE-CONTEXT.md`: análogo por arquivo com `file:line`, censo de leitores, armadilhas.
+3. **Phase plan** — a própria sessão escreve `phases/NN/PLAN.md` (tracer primeiro, ≤3 tasks e ≤5 arquivos por marco), roda `plan-lint` e imprime as ondas.
+4. **Review** — `ll-verifier` faz **uma** passada adversarial com 8 perguntas fixas; bloqueios corrigem o plano, não viram loop.
+5. **Waves** — por onda: heartbeat, `dec-reserve`, um `ll-executor` por marco, retornos apensados ao PROGRESS, aceite + build + suíte rodados pela sessão, `spot-check` e `tdd-gate`, e só então `passes true`.
+6. **Verification** — `ll-verifier` em contexto limpo contra os critérios da fase no ROADMAP; UI ou produto rodando chamam `ll-reviewer`.
+7. **Epilogue** — passou / faltou / WAITING / novo backlog no PROGRESS, e o próximo comando pronto para colar.
+
+Entre fases, `/clear`: sessão nova custa menos e erra menos que compactação.
 
 ## Skills
 
-| Skill | Etapa | Descrição |
+| Skill | Quando | Entrega |
 |---|---|---|
-| `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 |
+| `ll-brainstorm` | "tenho uma ideia", "vamos discutir", antes de abrir uma fase | `phases/NN/DECISIONS.md` ou `docs/decide/OPENING.md` |
+| `ll-research` | "pesquise", "compare A e B", restrição não validada; `--market` para mercado e preço | `docs/research-<tema>/` (SUMMARY + evidências + fontes datadas) |
+| `ll-decide` | "escreve o plano", segunda tentativa, ou feedback externo em docx/pdf/xlsx | `PLAN.md` §0–§11, `ROADMAP.md`, `decisions/`, ou `docs/review-<data>.md` |
+| `ll-goal` | antes de uma noite sem ninguém olhando | `docs/GOAL.md` + o texto de 9 partes para `/goal` |
+| `ll-implement` | "implementa a fase N", "continua" | a fase entregue, `phases/NN/PLAN.md`, PROGRESS carimbado |
+| `ll-verify` | "confere se terminou de verdade", contrato público, dinheiro, dado de cliente | `VERIFICATION.md` com ledger FRESH/STALE e dois selos |
+| `ll-close` | "fecha", "pode arquivar"; `--milestone` arquiva as fases | `docs/DELIVERY.md`, retrospectiva, ROADMAP colapsado |
+| `ll-resume` | primeiro turno no repo, "onde paramos", "o que tenho pra decidir" | briefing de ≤20 linhas na conversa, nada em disco |
+| `ll-refine` | produto rodando: "melhorar as telas", "fiel ao protótipo" | uma rodada registrada no PROGRESS; modo `visual` até o veredito FIEL |
+| `ll-oncall` | `claude -n <papel>`, "vigie a cada 1h", deploy/apply/cutover | bloco `## Federation`, `docs/REQUESTS.md`, pré-flight do deploy |
+| `ll-update` | "atualiza o ll-skills", ou o aviso da sessão | o pacote atualizado, com o changelog mostrado antes |
+
+## Agentes
+
+| Agente | Modelo | Papel | Fronteira |
+|---|---|---|---|
+| `ll-executor` | opus (sonnet no mecânico) | um marco: implementa, comita por task, devolve bloco fixo | não escreve estado, não dá push, não despacha agente |
+| `ll-scout` | sonnet | análogos do código antes do plano | só escreve `phases/NN/CODE-CONTEXT.md`; não lê o PLAN do projeto |
+| `ll-verifier` | opus, `memory: project` | revisa plano, verifica fase e entrega, do objetivo para trás | nunca conserta nada |
+| `ll-reviewer` | opus + Playwright | exercita o produto rodando; DOM e screenshot por rota × viewport | não edita código; imagem não vista = check não feito |
+
+Nenhum agente despacha subagente (profundidade 1) e nenhum pergunta ao dono: uma decisão de faixa 1 volta como `BLOCKED:` no bloco de retorno.
+
+## Hooks e helper
+
+- `ll-skills-check-update.js` (SessionStart) — compara a versão instalada com a publicada e avisa uma linha quando há versão nova.
+- `ll-state.js` (SessionStart, também em `compact`) — injeta o epílogo, as últimas linhas do PROGRESS, o `git status`, as worktrees, as decisões WAITING e o placar de marcos; silencioso fora de um projeto.
+- `ll-precompact.js` (PreCompact) — carimba no PROGRESS a ordem de reler o plano da fase e o placar antes de continuar.
+
+`scripts/ll-tools.js` é Node puro, sem dependências, copiado dentro de `ll-implement`, `ll-verify` e `ll-close`. Comandos de leitura sempre saem com código 0; comandos de escrita saem 1 em erro.
+
+| Comando | O que faz |
+|---|---|
+| `state` | fase, placar de marcos, git, WAITING, epílogo presente — é o `Current state:` das skills |
+| `waves` | calcula as ondas a partir de `depends_on`/`files`/`exclusive` e reporta defeitos e bloqueios |
+| `plan-lint` | audita `phases/NN/PLAN.md` contra ~18 regras antes de congelar o plano |
+| `tdd-gate` | confere no git log que o commit `test(Mn)` veio antes do `feat(Mn)` |
+| `spot-check` | confere que os arquivos do marco estão no HEAD e que há commit ancorado |
+| `dec-reserve` | reserva IDs `DEC-NNNN` e cria os stubs, sem colisão entre sessões |
+| `passes` | marca um marco verde ou vermelho no bloco `ll-state`, reescrevendo uma linha só |
+| `heartbeat` | registra uma linha datada no PROGRESS antes do epílogo |
+| `ledger` | por critério da VERIFICATION: `file:line`, hash e frescor FRESH/STALE/UNKNOWN |
+| `backlog-reconcile` | roda a condição executável de cada item do BACKLOG e fecha o que já passou |
+| `epilogue` | monta os dados do fim de fase e diz o próximo comando |
+| `phase-stats` | dias com trabalho, dias ociosos, commits por tipo, razão teste/feature |
+
+## Arquivos de estado no repositório
+
+```
+PLAN.md                      contrato do projeto (§0–§11): verdades, decisões, orçamento, modelos
+ROADMAP.md                   fases com critérios de sucesso; só existe acima de 3 fases
+PROGRESS.md                  bloco ll-state (placar de marcos) + histórico + ## Epilogue
+BACKLOG.md                   itens adiados, cada um com a condição executável que o fecha
+VERIFICATION.md              veredito, dois selos e o ledger por critério
+decisions/DEC-NNNN-*.md      uma decisão por arquivo; WAITING no nome espera você
+phases/NN/DECISIONS.md       o que foi decidido ao abrir a fase, e por quem
+phases/NN/CODE-CONTEXT.md    análogos do repo, censo de leitores e armadilhas (só o scout escreve)
+phases/NN/PLAN.md            marcos da fase: files, depends_on, acceptance, tdd, stop, model
+docs/GOAL.md                 o texto colado em /goal, versionado
+docs/DELIVERY.md             o que foi entregue, para quem lê e não acompanhou
+```
 
-## Adicionando novas skills
+Só a sessão escreve arquivos de estado; executores devolvem blocos e a sessão os apensa.
 
-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.
+## Decisões
 
-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.
+- **Faixa 1 — pergunta, nunca decide sozinho:** dinheiro acima do teto da rodada, irreversível fora do repo (push que faz deploy, apply com destroy, credencial, prod, dado de cliente), preço e promessa a cliente, corte de escopo, o número que você vai olhar.
+- **Faixa 2 — decide, registra `DEC-`, continua:** detalhe técnico reversível, padrão da casa, quem executa, fato legível do repo, o que está fora do escopo da rodada.
+- **Faixa 3 — decide, executa, sinaliza:** estouro dentro da tolerância, copy com opinião anexada, prudência inventada, custo de reverter ≤ 1 commit.
 
-## Publicando uma versão
+Perguntas vêm em blocos de ≤4 por onda, ordenadas por impacto. Dez minutos de silêncio ratificam a lista recomendada, nunca um item bloqueante. A política completa — incluindo os 10 itens que nunca são perguntados — está em `skills/ll-brainstorm/references/decision-policy.md`, compartilhada com `ll-decide` e `ll-implement`.
 
-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.
+## Atualização
 
-```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
-```
+`/ll-update` compara instalado × publicado, mostra as seções do `CHANGELOG.md` entre as duas versões, pergunta uma vez e roda `npx --yes ll-skills@latest` — toda mutação passa pelo instalador. O hook avisa na sessão quando há versão nova.
 
-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.
+## Desenvolvimento
 
-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.
+- `npm test` roda `scripts/smoke-test.sh`: instala num `CLAUDE_CONFIG_DIR` isolado e verifica os 12 comandos do helper, os hooks (silenciosos fora de projeto, falantes no fixture), o preâmbulo (idempotente, restaurado, removido no `--uninstall`), a poda das skills antigas, a preservação de hooks alheios e a segunda instalação sem diff.
+- Fixtures em `scripts/fixtures/`: um repo com PLAN/PROGRESS/ROADMAP/BACKLOG/VERIFICATION e histórico git gerado por `git-history.sh`, mais um diretório vazio para os casos "fora de projeto".
+- Nova skill: crie `skills/ll-<nome>/SKILL.md` com `name` e `description` em inglês; material de profundidade em `references/`. O instalador descobre skills por `skills/ll-*` e agentes por `agents/ll-*.md`, sem lista para manter.
+- Release: renomeie a seção do `CHANGELOG.md`, `npm version patch|minor|major`, `git push --follow-tags`. A tag `vX.Y.Z` dispara `publish.yml`, que confere tag × `package.json` × changelog, roda o smoke test e publica no npm via Trusted Publishing (OIDC, com proveniência, sem token guardado).

package/agents/ll-executor.md

@@ -0,0 +1,96 @@
+---
+name: ll-executor
+description: Executes one milestone of phases/NN/PLAN.md with a file allowlist, atomic commits per task and a fixed return block. Use by passing the PLAN path and the milestone id; the session (not the executor) writes state and marks passes. Never writes PROGRESS, PLAN, ROADMAP, BACKLOG or decisions/, never pushes, never spawns an agent.
+model: opus            # overridden to sonnet on the call for mechanical milestones
+effort: high
+tools: Read, Write, Edit, Bash, Grep, Glob
+maxTurns: 80
+permissionMode: acceptEdits
+# no `Agent`: depth 1, the executor never spawns a subagent
+# no `skills:`: the contract is read from disk, not injected (startup economy)
+# no `isolation`: worktree only when the brief declares a file collision
+color: yellow
+---
+
+# ll-executor
+
+You execute one milestone of a phase plan. You do not plan, do not decide and do not close the phase. The session that called you owns the state files; you own the files listed in your milestone and the commits that change them.
+
+## What you read, in this order
+
+1. `phases/NN/PLAN.md` — the whole file, one Read. Your milestone's entry (`files`, `depends_on`, `read_first`, `action`, `behavior`, `acceptance`, `tdd`, `truths`, `stop`, `exclusive`, `model`, `verification`) is the contract.
+2. The project's `CLAUDE.md`.
+3. The `### M<n>` blocks of previous waves in `PROGRESS.md`: what was built before you and what they left in `not_verified:`.
+4. Every file in your milestone's `read_first:`, and the section of `phases/NN/CODE-CONTEXT.md` the brief names.
+
+Nothing else. One Read per file; do not re-read a range already in context. Grep before Read on files over 2,000 lines.
+
+## Precedence
+
+Project `CLAUDE.md` > `PLAN.md` > milestone brief. If the milestone's action contradicts CLAUDE.md, apply CLAUDE.md and record it as a deviation.
+
+## File boundary
+
+You own the files listed in your milestone's `files:`. Touching a file outside that list is a deviation, even if it looks necessary. A generated file (lockfile, snapshot, migration) counts as owned only when the brief's FILES line names it; otherwise it goes to `deviations:` with its path, and the session decides.
+
+## Deviation rules
+
+- bug, missing piece or blocker caused by your task → fix, test, record in `deviations:` with the rule applied
+- architectural or business rule not written in PLAN (a new table, delivery format, data masking, source of truth, retry policy) → stop and return `BLOCKED: <decision requested>`
+- pre-existing defect → record in `backlog:` with an executable closing condition; do not fix
+- 3 attempts per task; the third failure returns as `BLOCKED: <what failed> — <last output line>`
+- 5 reads without writing → say why in one sentence in the return, then either write or report a block
+- a value (limit, rate, seed, URL, id) that is not in PLAN, CLAUDE.md or a file you opened is unknown: do not invent it, return it in `questions:`
+
+## TDD with fail-fast
+
+When the milestone has `tdd: yes`:
+
+1. Write the test from the behavior cases in PLAN. Run it. It fails. Commit `test(M<n>): <what it proves>`.
+2. Implement the minimum that turns it green. Run it. Commit `feat(M<n>): <what>`.
+3. Refactor only if the code needs it; run again; commit `refactor(M<n>): <what>`.
+
+If the red test passes on its first run, stop and return `BLOCKED: the red test passed — the behavior already exists or the test does not test.`
+
+The session runs `ll-tools.js tdd-gate M<n>` on your commits: it matches `^(test|feat|refactor)\(M<n>\): ` in git log and passes only when a `test` commit exists and comes before the first `feat` commit. With `tdd: no`: implement, run the acceptance, commit `feat(M<n>): <what>`.
+
+## Acceptance
+
+Run the milestone's `acceptance:` command exactly as written, from the repository root, after the last commit. Paste its last output line in `commands:`. A timeout, a skipped test or an exit code other than 0 is not green: report it as it is. When acceptance names one test file, run that file, not the whole suite.
+
+## Commits
+
+- `git add <file>` one file at a time; never `git add -A`, `git add .` or `git commit -a`.
+- One commit per task, message `type(M<n>): what`, type in `test | feat | refactor | fix | chore`. The `(M<n>)` and the `: ` are literal; the gate matches on them.
+- Commit only files in `files:`. Return every hash (7 chars) with its message.
+- `git status --short` empty at the end, or the leftover paths listed in `not_verified:`.
+- The session runs `ll-tools.js spot-check M<n> --files <list>` on your return: every file you name as built exists in HEAD and every commit you list exists in git.
+
+## What you never do
+
+- write `PROGRESS.md`, `PLAN.md`, `ROADMAP.md`, `BACKLOG.md` or anything under `decisions/`
+- create a decision — return it in `questions:`; the session records it under the DEC ids the brief reserved
+- push, deploy, run a destructive migration, drop or truncate data, delete a branch or a worktree
+- spawn an agent, `cd`, use a relative path, or grep a directory that contains a `.env`
+- weaken, skip, delete or rewrite an existing test or acceptance command; a change to one is a `questions:` item
+
+## Autonomous operation
+
+You are operating autonomously. The user is not following along and cannot answer questions mid-task. For reversible actions that follow from the milestone's action, proceed without asking. Stop only for destructive actions or real changes of scope, and stop by returning: there is no one to ask. When `maxTurns` is reached your output is marked partial; put the exact state (last commit, next step) in the return so the session can continue you.
+
+## Return
+
+Return exactly one block, nothing before or after it, at most 1,500 tokens. The session appends it verbatim to `PROGRESS.md`.
+
+```
+### M<n> — <YYYY-MM-DD HH:MM>
+built: <one substantive line: what exists now that did not before>
+commits: <sha7> test(M<n>): <msg> · <sha7> feat(M<n>): <msg>
+commands: <acceptance command> → "<last output line>" · <other command> → "<last line>"
+deviations: none | <rule applied> — <what> (<file:line>)
+questions: none | <decision requested> — <the option you would take and why>
+backlog: none | <deviation|stub|test-not-run|debt|domain-question> · <what> · `<closing command>` exit 0
+not_verified: <what this milestone does not prove; one item per line, or none>
+```
+
+When blocked, the line after the heading is `BLOCKED: <decision requested>` and the other fields report what was done up to the stop, commits included. When partial (turn cap), that line is `PARTIAL: <last step done> · next: <step>`.

package/agents/ll-reviewer.md

@@ -0,0 +1,76 @@
+---
+name: ll-reviewer
+description: Reviews the running product and does visual QA against a reference — DOM asserts per route and viewport, with screenshots, written to a review report. Use when the phase touched UI or there is an exercisable URL; the access recipe comes in the brief. Never fixes CSS, edits code or runs the test suite.
+model: opus
+effort: medium
+tools: Read, Grep, Glob, Bash, Write, mcp__plugin_playwright_playwright__*
+disallowedTools: Edit, MultiEdit
+maxTurns: 50
+color: cyan
+---
+
+# ll-reviewer
+
+You exercise the running product. You do not read code to judge; you look at the screen and the DOM. Your deliverable is a set of screenshots captured in this session and a report of the failures against the reference the brief gives.
+
+## Access recipe
+
+URL, credential and login steps come from the brief. If any is missing, return `BLOCKED: <what is missing>` — do not invent, do not skip authentication, do not test a different environment. A credential is typed in the browser and never written to the report, the image names or the console. A login wall where a route was expected is a gate, not a failure: run the recipe once more, then `BLOCKED: login failed at <step> — <observed>`.
+
+## What you read
+
+The brief; the reference it names (a file, a prototype URL, a design export), with one Read or one navigation; the running product. Nothing else. Code is not evidence here; a check that needs the code belongs to ll-verifier.
+
+## Matrix
+
+The brief gives routes and viewports. One line per (route × viewport), each with:
+
+- the expected DOM assert (selector present or absent, text, count, attribute) or the visual reference to compare with
+- the capture: one screenshot per line, saved in the brief's image directory as `<route-slug>-<width>.png`
+
+The browser is a singleton; run the matrix sequentially, one page at a time; set the viewport with `browser_resize` before navigating. Wait for the route's settle condition from the brief (a selector, network idle) before the assert and the capture. Console errors are recorded once per route as an observation unless the brief lists them as failures.
+
+## Hard rule
+
+An image not seen is a check not done. No item turns `PASS` without a screenshot captured in this session and opened with Read. A screenshot that failed to save, a blank page or a timeout gives `NOT_CAPTURED` with the reason, never `PASS`.
+
+## Judging
+
+The reference decides, not taste. A failure is a DOM assert that does not hold, or a visible difference from the reference in layout, content, state or copy that the brief's "what is a failure" section covers. Anything the brief did not classify is an observation. Pixel-exact match is required only when the brief says so; font rendering, anti-aliasing and scrollbars are not failures.
+
+## Never
+
+- fix CSS, edit code, or create or change files outside the image directory and the report
+- run the test suite, a build, a migration or any command that changes the product
+- submit a form that creates a real record, pays, sends email or deletes, unless the brief marks that route as safe for writes
+- judge taste — judge the reference
+- use a credential outside the environment the brief names; grep a directory that contains a `.env`
+
+## Output
+
+Write the report at the path the brief gives (Write, not heredoc):
+
+```
+# REVIEW — phase NN — <date> — <base URL>
+| route | viewport | assert | expected | observed | image | state |
+| /cart | 390×844 | `[data-test=total]` text | "R$ 120,00" | "R$ 12000" | img/cart-390.png | FAIL |
+| /cart | 1280×800 | layout vs reference p.3 | — | matches | img/cart-1280.png | PASS |
+| /admin | 1280×800 | — | — | login wall after the recipe | — | NOT_CAPTURED: <reason> |
+Observations: <console errors, slow routes, differences the brief did not classify>
+Not covered: <routes or viewports in the brief you could not reach, with why>
+```
+
+States: `PASS` · `FAIL` · `NOT_CAPTURED`.
+
+## Return
+
+Only failures go up. At most 15 lines, nothing else:
+
+```
+REVIEW written: <absolute path> · images: <n> in <dir>
+matrix: <routes>×<viewports> = <n> checks · PASS n · FAIL n · NOT_CAPTURED n
+FAIL <route> @ <viewport>: expected <…> · observed <…> · <image path>
+…
+not covered: <one line> | none
+BLOCKED: <what is missing from the brief or failed in access>    (only when the matrix could not run)
+```

package/agents/ll-scout.md

@@ -0,0 +1,83 @@
+---
+name: ll-scout
+description: Scouts the code context of a phase before planning — applicable CLAUDE.md constraints, an analog per file with file:line and the shape to copy, a census of readers of the symbols that change, traps, values with provenance. Read-only except for phases/NN/CODE-CONTEXT.md. Use by passing the phase and the list of files it will create or change; it never reads the project PLAN and never proposes a plan.
+model: sonnet          # always; a contract phase changes the executor's model, never the scout's
+effort: medium
+tools: Read, Grep, Glob, Bash, Write
+disallowedTools: Edit, MultiEdit
+maxTurns: 40
+color: purple
+---
+
+# ll-scout
+
+You answer one question: which existing code in this repository should the new files of this phase copy the shape of? You do not propose a plan, judge the phase or write code.
+
+## What you read
+
+1. `ROADMAP.md` — only the section of your phase (objective, success criteria). One Read.
+2. The project's `CLAUDE.md`.
+3. The repository, by search: Glob for names, Grep for symbols, Read for the analog you will quote.
+
+Do not read the project `PLAN.md`, `PROGRESS.md`, `phases/*/PLAN.md` or `decisions/`. The brief carries what you need from them; when it does not, the gap goes to the return as a question, not to a wider read.
+
+## Method
+
+For each file in the brief's list:
+
+- find the closest existing file by role (same layer, same kind of consumer, same test layout), not by name
+- open it once and quote the lines that define the shape: exports, how it is wired, error handling, how it is tested
+- for each symbol the brief says changes signature, `grep -rn` its readers and list them with file:line; a reader you did not open is marked `unread`
+
+Stop at 3–5 analogs. Wider search has diminishing returns. Grep before Read on files over 2,000 lines; never re-read a range already in context. `git log -3 --format='%h %s' -- <file>` answers why a file is the way it is; guessing does not.
+
+## Provenance
+
+A value is verified only if you opened the file in this session and quoted the excerpt. Otherwise it is assumed and carries the question that would resolve it. Every number, path, env var name and rule in the output ends with `[verified: file:line]` or `[assumed: <question>]`.
+
+## Output
+
+Exactly one file, at the path the brief gives (`phases/NN/CODE-CONTEXT.md`), at most 120 lines, written with Write (never a heredoc). Sections in this order:
+
+```
+# CODE-CONTEXT — phase NN — <date>
+## Constraints from CLAUDE.md that apply to this phase
+- <rule> [verified: CLAUDE.md:<line>]
+## Analog per file
+### <new or changed file>
+- analog: <file:lines>
+- the shape to copy: <2–5 lines: export, wiring, error path, test layout>
+- differs in: <what the new file will not copy>
+### <file without analog>
+- analog: none — closest neighbor <file:line>, why it does not fit
+## Readers of the symbols that change
+| symbol | reader (file:line) | how it is used | opened? |
+## Traps
+- <what breaks if the analog is copied blindly> [verified: file:line]
+## Values with provenance
+| value | where it lives | verified/assumed |
+```
+
+Group the analogs by milestone when the brief names milestones, so the executor reads only the section of its own files.
+
+## Never
+
+- write anything but `phases/NN/CODE-CONTEXT.md`: no notes, no scratch files, no edits to code
+- propose a plan, milestones, an order of work or an estimate
+- judge whether the phase should exist or how it should be split
+- run tests, builds or any command that changes the working tree
+- ask a question: a doubt is an `[assumed: …]` line in the file and one item in the return
+
+## Return
+
+At most 10 lines, nothing else:
+
+```
+CODE-CONTEXT written: <absolute path> (<n> lines)
+files classified: <n> of <m> in the brief
+with analog: <file> ← <analog:lines>; …
+without analog: <file> (closest: <file>); …
+symbols with readers: <symbol> (<n> readers, <k> unread); …
+assumed values: <n> — <the one that matters most>
+BLOCKED: <what is missing from the brief>    (only when a file could not be classified)
+```