ll-skills 1.0.1 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,105 @@
 # 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.
+
+## [3.0.0] - 2026-09-10
+
+### Adicionado
+
+- **`ll-auto`**: skill que roda o ciclo inteiro a partir do estado em disco — research, brainstorm, decide, fases, verificações, close — seguindo o `SKILL.md` de cada etapa em vigor, com as flags `"<objetivo>"`, `--research`, `--brainstorm`, `--interactive`, `--auto-decision`, `--pause-at <stage|N>`, `--from N`, `--to N`, `--only N`, `--verify all`, `--redo <stage>`, `--dry-run` e `--resume`; escreve `docs/AUTO.md` (objetivo, flags, roteiro, status por etapa) e lista no final toda decisão tomada sozinha, marcada `[decided by absence — revisable]`.
+- Helper `skills/ll-auto/scripts/ll-auto.js` (Node puro, sem dependências, próprio da skill): `detect`, `roteiro`, `next-cmd`, `report`, `auto-md`.
+- `--no-talk` em `ll-decide` e `ll-close`: nenhum bloco de pergunta é enviado; itens de faixa 2/3 tomam a recomendação como `ASM-n [decided by absence — revisable]`, itens de faixa 1 viram decisão `WAITING`.
+- **`ll-goal --autonomous`**: modo que aponta o texto do `/goal` para `ll-auto --auto-decision` até a entrega inteira fechar, em vez de uma fase; sem a parte BUDGET, frontmatter com `mode: autonomous` em vez de `ceiling_usd`.
+- Casos de eval `auto-dry-run` e `auto-empty-repo` (`scripts/evals/cases/`), a seção offline `evals-auto` do `scripts/smoke-test.sh` e uma repetição real de ambos via `scripts/evals/run.sh`.
+
+### Quebras
+
+- As skills não são mais invocadas pelo modelo — todas com `disable-model-invocation: true`.
+- Preâmbulo sem roteador de pedidos.
+- Descrições das skills reescritas em uma linha.
+
+### Alterado
+
+- Lint rule 1 e 3 do `lint-prompts.sh`.
+- Casos de eval `router-*` e `preamble-no-ritual` passam a exigir o comando nomeado e nenhuma chamada da ferramenta Skill; helper `no_tool_use` em `scripts/evals/lib/assert.sh`.
+
+## [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): 12 skills, 4 agentes, 3 hooks e dois helpers que compartilham o mesmo estado em arquivos versionados do repositório. Um preâmbulo instalado no seu `~/.claude/CLAUDE.md` carrega o bloco de regras da casa — delegação, decisões, prova — que vale para qualquer skill que você chamar. 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,183 @@ 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 são chamadas pelo nome (`/ll-implement 3`).
 
 ```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.
-
-### Para um projeto novo
+O que a instalação **escreve** (em `$CLAUDE_CONFIG_DIR` ou `~/.claude`):
 
-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.
+| Caminho | Conteúdo |
+|---|---|
+| `skills/ll-*/` | as 12 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 |
+| `skills/ll-auto/scripts/ll-auto.js` | o helper da própria skill, executável |
+| `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 |
 
-### Para uma feature de um sistema existente
+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.
 
-O mesmo pipeline, encurtado — `ll-pesquisar-mercado` detecta o modo no enquadramento:
+## Como as skills são chamadas
 
-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.
+Uma skill roda só quando você digita `/ll-<nome>`. A sessão nunca inicia uma skill sozinha: quando o pedido parece o trabalho de uma delas, ela responde com o comando exato para você colar e para aí. Uma skill por turno — nenhuma chama outra. Cada uma termina num arquivo dentro do repositório e imprime `▶ Next — /clear, depois <comando>`; quem cola é você. `ll-auto` é a única exceção: o único lugar que segue as instruções de outra skill, e só quando você digita `/ll-auto`.
 
-Para uma correção pequena ou tarefa trivial, nada disso: o pipeline existe para trabalho onde errar estrutura custa caro.
+## Ciclo de um projeto
 
-### Transversais
+Uma vez por milestone, com a contagem de prompts seus por etapa:
 
-**`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.
+| Etapa | Prompts | Sai disso |
+|---|---|---|
+| ideia → `/ll-brainstorm` ou `/ll-research` | 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; `ll-goal --autonomous ["<objetivo>"]` cobre a entrega inteira | `docs/GOAL.md` + o texto de 9 partes para `/goal`; no modo autônomo, o texto mantém `ll-auto --auto-decision` rodando até a entrega fechar |
+| `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 |
+| `ll-auto` | `/ll-auto "<objetivo>" [flags]` | `docs/AUTO.md` e o ciclo inteiro |
+
+### Fluxo autônomo
+
+`ll-auto` lê o estado em disco (`detect`), corta a lista de etapas com as flags (`roteiro`) e segue cada etapa lendo o `SKILL.md` dela — a única skill que faz isso, e só porque você digitou o comando.
+
+| Flag | Efeito |
+|---|---|
+| `--research` | entra `research` no roteiro, se não estiver `done` |
+| `--brainstorm` | entra `brainstorm` no roteiro, se não estiver `done` |
+| `--interactive` | tira o `--no-talk` de `ll-brainstorm`/`ll-implement`: essas etapas falam com você |
+| `--auto-decision` | resolve toda decisão de dono para a opção recomendada e segue |
+| `--pause-at <stage\|N>` | para depois daquela etapa ou fase, com `▶ Next — /clear, then ll-auto --resume` |
+| `--from N` / `--to N` / `--only N` | corta as fases por número (`--only N` corta o `close`) |
+| `--verify all` | roda `ll-verify NN` depois de cada fase, mesmo sem o epílogo pedir |
+| `--redo <stage>` | força uma etapa `done` de volta para `todo` |
+| `--dry-run` | imprime a tabela do roteiro e para, antes de escrever `docs/AUTO.md` |
+| `--resume` | retoma as flags gravadas em `docs/AUTO.md`, a partir da primeira linha que não é `done` |
+
+Num repositório vazio (sem pesquisa, sem `OPENING.md`, sem `PLAN.md`) e sem objetivo, `ll-auto` não pergunta nada: imprime o comando que completa (`/ll-auto "<objetivo>" [--research] [--brainstorm]`) e para. Toda decisão de dono tomada sozinha ao longo do run (com `--auto-decision`) entra listada no fim, cada uma marcada `[decided by absence — revisable]`.
+
+#### Para rodar sem parar
+
+`ll-goal --autonomous` escreve o texto, você cola em `/goal <texto>`, e o loop do `/goal` reinicia `ll-auto --auto-decision` sempre que a sessão parar antes da entrega; decisões tomadas sozinhas ficam listadas no fim (`[decided by absence — revisable]`); só dinheiro, produção ou dados de cliente param a corrida.
+
+## 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 |
+
+`skills/ll-auto/scripts/ll-auto.js` é o helper próprio da skill `ll-auto` — Node puro, sem dependências, nunca uma cópia de `ll-tools.js`.
+
+| Comando | O que faz |
+|---|---|
+| `detect` | lê o estado em disco e devolve a tabela de etapas (`research` … `close`) com status `todo`/`half`/`done` |
+| `roteiro` | corta a tabela do `detect` pelas flags e devolve a lista ordenada de etapas a rodar |
+| `next-cmd` | lê o comando da última linha `▶ Next` de um arquivo |
+| `report` | lista os `decisions/*.md` marcados `[decided by absence — revisable]` |
+| `auto-md` | monta o corpo de `docs/AUTO.md` (objetivo, flags, roteiro, decisões, log) |
+
+## Arquivos de estado no repositório
 
-## Adicionando novas skills
+```
+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
+```
 
-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.
+Só a sessão escreve arquivos de estado; executores devolvem blocos e a sessão os apensa.
 
-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.
+## Decisões
 
-## Publicando uma versão
+- **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.
 
-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.
+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`.
 
-```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
-```
+## Atualizaçã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,97 @@
+---
+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.
+5. The brief itself, field by field: MILESTONE, PLAN, CONTEXT, FILES, WAVE (your wave and the milestones running in parallel — their files are not yours), TDD, ACCEPTANCE, MODEL, DEC RESERVED (the only ids you may cite in `questions:`), INPUTS (paths that already exist), DO NOT, RETURN.
+
+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)
+```