convez.ai
SkillAutomaçãoIntermediário
AndreRatzenberger

Loopify

AndreRatzenberger/loopify

Converte specs em loops verificáveis com rastreamento automático

Ver no GitHub
InicialPluginScore · de 0 a 100

Skill bundle que transforma especificações em loops de feedback executáveis para agentes Claude. Implementa padrão de "promptcraft com recibos": verifica realidade, aplica correções, registra o que aconteceu e define critérios de parada claros. Ideal para automações que precisam rastreabilidade e validação em tempo real.

Instalação

$npx convez-ai AndreRatzenberger/loopify

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 1 mês
Versão
v0.1
Issues abertas
0
Contribuidores
1

Casos de uso

  • Automação de features com validação e parada automática
  • Debugging iterativo com feedback loops e traces
  • Gestão de tarefas complexas com critérios de sucesso mensuráveis

Veredito

Loopify é uma abordagem prática para escapar de prompts heroicos e frágeis. Funciona melhor em fluxos bem especificados onde auditoria e parada determinística importam; menos útil para exploração aberta.

README

A tradução para o português deste README ainda está na fila.

Stop writing heroic prompts. Start writing contracts reality can check.

Loopify is a Claude plugin-format skill bundle for turning specs into executable feedback loops. A prompt asks for an answer. A loop gives the agent a workbench: check reality, patch the thing, write down what happened, stop for a reason.

Think of it as promptcraft with receipts. Tiny bureaucracy for ambitious agents. The kind where "done" has to show its work.

Or as Caveman Codex would say:

Spec alone: "Want fire."

Prompt alone: "Please make fire."

Loop: "Try make fire. Check smoke. If hand burns, stop. Write what happened."


⚡ Quick Loop

1. Install the loop machine

Codex CLI:

codex plugin marketplace add AndreRatzenberger/loopify
codex plugin add loopify-agent-skills@loopify

Or browse it interactively:

codex
/plugins

In the Codex app or desktop surface, open Plugins, search for Loopify, then choose Add to Codex / Install plugin. If Loopify is not visible yet, add the marketplace from the CLI command above, restart or refresh Codex, and check the marketplace list again. Shared workspace installs can also appear under Shared with you.

Claude Code/Github Copilot:

/plugin marketplace add AndreRatzenberger/loopify
/plugin install loopify-agent-skills@loopify

Other agent harnesses: Ask your bot.

Give it https://github.com/AndreRatzenberger/loopify and ask it to install or load the loopify-agent-skills bundle.

2. Turn a spec into a loop folder

Use loopify-spec on docs/goals/goal.md and bootstrap it into .loopify/loops/001-first-loop/.

For a read-only compile, omit and bootstrap it; loopify-spec will only write the contract. Add the bootstrap phrase when you want repo files.

3. Run until the loop earns a stop reason

Use loopify-run on .loopify/loops/001-first-loop/. Stop only with success, blocked, escalated, or budget-exhausted.

What just happened?

  • The spec said what should become true.
  • The Loop Contract named evidence, checks, authority, retries, and stop rules.
  • The run checked reality, patched from feedback, wrote a trace, and stopped with receipts.

You got a paper trail instead of a victory monologue. 🧾


🗂️ Loop Folders: One Feature, One Folder

Loopify saves runnable work as numbered folders:

.loopify/
  index.md
  loops/
    001-first-loop/
      source.md
      loop-contract.md
      quality-gate.sh
      acceptance-checklist.md
      trace.md
      final-report.md
      retro.md
      artifacts/
    002-next-feature/
      ...

Why folders? Because repos collect quests. First feature, weird bug, polish pass, release pass. One global contract turns into a junk drawer. Numbered loop folders keep each little adventure inspectable.

loopify-spec can hand off to loopify-bootstrap when the user explicitly asks for it: "spec and bootstrap it", "make this runnable", or "create the loop folder." Without that phrase, it stays pure and writes only the Loop Contract.


🔁 Prompt vs Spec vs Loop

  • Prompt: ask once and hope.
  • Spec: describe the desired end state.
  • Loop: check reality against the contract until the work earns a stop reason.

Prompts still matter. They are no longer the unit of done.

We don't do scary loops here. Just wholesome bounded loops.

The scary loop is unbounded: the model invents goals, judges itself, mutates its own harness, and ships when it feels done. Loopify is the boring loop: a contract, allowed actions, checks, budgets, trace, and stop reasons. It does not ask the model to become wise. It makes the model bump into reality more often.


📜 Loop Contract: The Deal Reality Can Check

A Loop Contract answers the questions a one-shot prompt usually hand-waves:

  • Goal: what output or state counts?
  • Evidence: what proves progress?
  • Authority: what may the loop read, write, call, spend, or publish?
  • Checks: which commands, tests, screenshots, or reviews count?
  • Budget: how many turns, retries, minutes, or dollars are allowed?
  • Stop: what ends in success, blocked, escalated, or budget-exhausted?
  • Trace: what receipt does the loop leave behind?

Without those, "looping" burns tokens while the model chases its own reflection. Cyberpunk, sure. Useful, no.

The contract is boring on purpose. Boring is how the agent remembers where the sharp objects are.


🧰 The Skill Chest

Loopify ships 11 skills. The spine is small:

loopify-spec -> loopify-bootstrap -> loopify-run -> loopify-trace

The loopify-spec -> loopify-bootstrap edge is explicit. Say "bootstrap it" or "create the loop folder" when you want that mutation.

SkillWhat it does
loopify-specConverts prose specs into Loop Contracts, optionally handing off to bootstrap when asked.
loopify-bootstrapSeeds .loopify/loops/NNN-slug/ with source, contract, quality gate, trace, checklist, and index entry.
loopify-runExecutes a loop folder by checking, patching, rerunning, and tracing.
loopify-checksTurns vague requirements into honest evidence.
loopify-traceKeeps receipts across attempts.
loopify-reviewAudits contracts, traces, done claims, and residual risk.
loopify-debugRescues stuck loops before they become doom spirals.
loopify-demoBuilds public-safe demo material packs.
loopify-codex-sdkTreats Codex SDK calls as actuators inside a larger loop.
loopify-retroTurns one loop's failures into better future loops.
loopify-governanceAdds budgets, approvals, rollback, and authority boundaries.

Each skill keeps its SKILL.md lean. Deeper guidance lives in references/; copyable output shapes live in templates/; deterministic helpers live in scripts/. The agent sees the short path first and can reach for the heavy tools when the loop bites back.


🧪 Try the PaperTrail Stress Fixture

The repo includes a deliberately chunky app request:

docs/goals/prompt.md

It asks for a research-paper catalog with arXiv ingestion, GraphRAG, fallbacks, logging, four views, and mandatory Playwright testing. It is lumpy in all the right ways. A one-shot prompt would smile, nod, and quietly lose half the requirements.

Try:

Use loopify-spec on docs/goals/prompt.md and bootstrap it into .loopify/loops/001-papertrail/.

Then inspect:

.loopify/loops/001-papertrail/loop-contract.md

If the contract maps requirements to evidence, names manual review, and refuses to pretend taste is a unit test, the loop is doing its job.


🛡️ Stop Rules: Loopify Isn't That Reckless

Every loop stops with one of four reasons:

  • success: the checks pass and manual/visual gates are satisfied or queued.
  • blocked: the same blocker repeats or a required dependency is unavailable.
  • escalated: a human decision is required.
  • budget-exhausted: the contract's turn, time, retry, or cost budget is done.

A loop without stop rules is not autonomy. It is an expensive while true wearing a cape.


🧬 Codex SDK: The Actuator, Not the Whole Creature

loopify-codex-sdk can help scaffold repair, review, evaluator, context-builder, or trace-summarizer actuators.

But the SDK call is not the loop. The loop still owns:

  • state
  • checks
  • authority
  • budgets
  • stop rules
  • trace
  • review

Concrete SDK calls are intentionally template-based until current official SDK docs are checked in the consuming project. No fake APIs. No confidence cosplay.


💻 Development: Working With This Repo

Run the quality gate:

npm run quality
git diff --check

What it checks:

  • marketplace and plugin manifests parse
  • all 11 skills exist
  • every skill has the required sections
  • required references/templates/scripts are present
  • example Loop Contracts contain the required headings
  • the stuck-loop debug fixture has enough trace data to diagnose

Project shape:

loopify/
├── .claude-plugin/marketplace.json
├── docs/
│   ├── assets/
│   ├── concepts/
│   ├── examples/
│   └── goals/
├── plugins/
│   └── loopify-agent-skills/
│       ├── .claude-plugin/plugin.json
│       ├── README.md
│       └── skills/
└── scripts/

🤔 FAQ

Q: Is Loopify anti-prompt? A: Nope. Prompts are ingredients. Loops are the recipe notes, oven timer, smoke alarm, taste test, and cleanup checklist.

Q: Is a Loop Contract just a spec? A: No. A spec says what should be true. A Loop Contract says how reality is allowed to prove it became true.

Q: Can this run unattended? A: Sometimes. The safer answer is: it can run until its authority, budget, or stop rules say otherwise.

Q: Why all the trace fuss? A: Because "the model said it is done" is not evidence. A trace lets a human see what happened, what failed, what changed, and what remains unproven.

Q: Is this production-ready? A: It's a first release of a skill bundle, not a compliance vending machine. Use loopify-governance when loops touch production, money, data, dependencies, or public content.


📜 License

MIT.

Go forth and stop for boring, well-documented reasons. 🔁

Your prompts will never be the same.

Ver o original no GitHub

Bom para

Relacionados