loopify

Compilador de Looping Engineering para Claude Code e Codex CLI.

Transforma um prompt bruto ("implementa X, com testes, e roda até terminar") em um pacote de loop autônomo com imposição por código — não por obediência do modelo. Destilado da técnica "Ralph Wiggum" (Geoffrey Huntley) e de "Loop Engineering" (Addy Osmani), endurecido após uso real em produção (2026-07-02).

A ideia em 30 segundos

Prompt engineering: você escreve, lê, escreve de novo. Looping engineering: você projeta um SISTEMA — um prompt fixo relido a cada volta, uma checklist externa como memória, testes como contrapressão — e deixa o agente iterar sozinho até a lista acabar. O loopify gera esse sistema a partir de um pedido em linguagem natural, e adiciona o que prompt nenhum garante: camadas determinísticas que validam e desfazem desobediência.

Uso

/loopify <prompt bruto> # gera o pacote de loop
/loopify <prompt> --runner claude # codex | claude | ambos
/loopify <prompt> --dir loops/minha-tarefa # pasta destino
/loopify help # guia rápido

Ou em linguagem natural: "transforma isso em loop", "roda overnight".

O que é gerado

Arquivo	Papel
PROMPT.md	Ritual fixo relido a cada volta: 1 tarefa por volta, buscar antes de assumir, proibido placeholder, commit seletivo, parada em LOOP_DONE
LOOP_PLAN.md	Memória externa: fatos verificados + tarefas checkbox, cada uma com critério de aceite MECÂNICO (comando → resultado) + itens GATE-HUMANO
RODAR.md	Disparo vigiado e manual, como acompanhar, como parar
loop_spec.json	A spec que gerou tudo (auditoria/regeração)

Ciclo de vida

/loopify <pedido>
└─ reconhece o repo (testes, regras, baseline) e decompõe em tarefas
└─ você APROVA o loadout
└─ gerador em código grava os artefatos (bytes idênticos sempre)
└─ você dispara o vigia: python .../loop_guard.py --dir loops/x --runner claude --test-cmd "..."
volta 1 → tarefa 1 → testes → commit
volta 2 → tarefa 2 → ... (volta desobediente = DESFEITA)
volta N → LOOP_DONE.md → fim
└─ você revisa os commits da branch (a verificação final é humana)

As 4 camadas determinísticas (e seus limites honestos)

O modelo pensa; o código impõe. Cada camada cobre uma superfície diferente — e nenhuma delas promete mais do que entrega:

1. Gerador (scripts/loopify_gen.py) — o modelo preenche só a loop_spec.json; os bytes do ritual e das proibições nascem de código. Tarefa sem critério de aceite = spec recusada.
2. Validador (scripts/loopify_validate.py) — confere o pacote: arquivos, marcadores do ritual, Aceite: em toda tarefa, e recusa o disparo se o texto contiver qualquer flag da denylist loopify_common.FORBIDDEN (a lista autoritativa; ex.: --dangerously-skip-permissions).
3. Stop hook (scripts/loopify_stop_hook.py) — roda FORA do modelo ao fim de cada resposta. Pacote com o marcador de validação pendente (loopify_common.MARKER) — ou editado à mão depois de gerado, que o hook re-detecta quando o sha256 dos arquivos diverge do manifesto e re-arma o marcador — deixa a resposta BLOQUEADA até revalidar. Dois limites reais: essa detecção só alcança pacotes DENTRO da descoberta confinada e o estado do hash é LOCAL à pasta do loop; e o hook é FAIL-OPEN — qualquer erro interno dele termina em exit 0 e NUNCA derruba a sessão.
4. Vigia (scripts/loop_guard.py) — a única camada que IMPÕE em tempo de execução. Dispara as voltas e, após cada uma, exige: exatamente +1 caixinha (ou +1 BLOQUEADO), testes sem falha nova, working tree limpo. Violação → git reset --hard à volta anterior + relatório + parada.

Limites honestos. O manifesto .loopify_hashes.json guarda só o sha256 de cada arquivo, SEM chave secreta: é defesa-em-profundidade contra edição DESAVISADA (pega quem mexeu sem querer), NÃO é à prova de adulteração — quem souber do esquema recalcula o sha256 e reescreve o manifesto. E há uma tensão método-vs-vigia intencional: promover uma tarefa - [ ] aberta para GATE-HUMANO no meio do loop é recusado (fail-closed), porque a regra por volta do vigia conta exatamente +1 [x] OU +1 BLOQUEADO — o caminho sancionado para adiar um item é marcá-lo BLOQUEADO.

Instalação

Requisitos: Python 3.10+, git; Claude Code e/ou Codex CLI.

# Windows
git clone https://github.com/fernandoxavier02/loopify.git
cd loopify; .\install.ps1

O instalador copia a skill para ~/.claude/skills/loopify (disponível em TODOS os projetos da máquina) e registra o Stop hook em ~/.claude/settings.json (idempotente; faz backup do settings antes). Sessões novas do Claude Code carregam hook e skill automaticamente.

Como plugin (ex.: sessões cloud / outra máquina, sem clonar):

claude --plugin-url https://github.com/fernandoxavier02/loopify/archive/refs/heads/main.zip

Segurança

• A skill só GERA artefatos; nunca executa o loop nem toca código do projeto.
• O disparo gerado usa sempre a permissão mínima (acceptEdits + allowlist estreita no Claude; --sandbox workspace-write no Codex). Flags que pulam todas as permissões são rejeitadas pelo validador.
• Ações destrutivas/custo/produção viram itens GATE-HUMANO: o loop prepara o runbook e para — executar é decisão do operador.
• Avisos herdados dos autores do método: loop rodando sozinho também erra sozinho ('concluído' é afirmação, não prova); revisar os commits faz parte; cada volta custa tokens — planos enxutos economizam de verdade.

Estrutura do repositório

.claude-plugin/plugin.json manifest (instalável como plugin)
skills/loopify/SKILL.md a skill (fluxo de 6 passos + /loopify help)
skills/loopify/references/ método, templates documentados, runners
skills/loopify/scripts/ gen | validate | stop_hook | guard (SSOT dos bytes)
install.ps1 instalador local (skill + hook)

Licença

MIT.