loopcraft

Loopcraft

English | 한국어 | 日本語 | 中文

Loop engineering plugin for Claude Code — instead of steering the model with ever-longer prompts, design loops where it self-corrects from environment feedback and accumulates memory across sessions.

Inspired by Lance Martin's loop engineering work and Andrej Karpathy's LLM Wiki pattern: self-improvement is a property of the system, not the model. Loopcraft builds that system as an installable plugin.

Why Loopcraft?

Every Claude Code session starts from zero. The context you built up last time — why a test was flaky, the refactor you already tried and abandoned, the quirks of this codebase — is gone the moment the session ends or the window compacts. The usual response is to pour more into the prompt: longer CLAUDE.md files, more standing instructions. But steering a model with an ever-growing prompt doesn't scale, and it still won't stop it from forgetting yesterday's work — or from grading its own output too generously.

Loop engineering takes a different position: self-improvement is a property of the system, not the model. Instead of a bigger prompt, you build a loop — the model acts, the environment pushes back (tests, an independent grader), the model corrects, and whatever was learned is written to durable memory that the next session reads before doing anything. The model doesn't have to get smarter; the system around it has to remember and check.

Loopcraft is that system, packaged as an installable plugin. Reach for it when you:

• work a real project across many sessions and keep re-explaining the same context;
• want work verified against explicit criteria instead of trusting the model's own "looks good to me";
• run Claude unattended and need every result gated and auditable before it reaches main;
• are tired of the model repeating a mistake it already hit — and solved — last week.

And because the vault is plain markdown rather than a hidden database, that memory stays yours: point Obsidian at .loop/memory/ and watch the knowledge graph grow, grep it from the terminal, or just read it in a pull request. You can see — and edit — everything the system has learned.

How it works

The loop closes on two timescales:

• Within a task — loop-task hands your work to an independent verifier that grades it against a rubric, seeing only the output and the criteria — never the maker's reasoning, so it can't be argued into a pass. Fail, and the maker gets the verdict and retries, up to maxRetries. Pass, and the work clears your real gates (tests, typecheck) and lands as a commit stamped Loop-Verified: n/m.
• Across sessions — the .loop/memory vault travels with the repo. SessionStart injects it, so Claude begins already knowing what past sessions learned; when something fails, distill turns it into a verified, reusable rule; and the Stop gate and PreCompact hooks make sure progress is written down before a session ends or the context is summarized away. Nothing gets re-learned from scratch.

And it scales out to a whole backlog: loop-run applies that same task loop to each item — read from a pluggable source (file / GitHub / Jira) and written back as a comment or a draft PR — unattended, while merging to your default branch stays your call.

Concepts

Loop engineering is the idea underneath everything here: you improve outcomes by shaping the loop the model runs in — act, get feedback from the environment, correct, and write down what was learned — rather than by hand-tuning an ever-larger prompt. The leverage moves from the model's weights to the system around it: memory, verification, and gates. A weaker model in a good loop beats a stronger model with no memory and no checks. (The framing draws on Lance Martin's work on loop/context engineering and Andrej Karpathy's LLM Wiki pattern.)

The rest of the vocabulary this README uses:

• Maker — whoever produces the work in a loop-task: Claude, acting on your request. The maker never grades itself.
• Verifier — an independent subagent that scores the maker's output against a rubric. It sees only the output and the criteria — never the maker's reasoning — so it can't be argued into a pass. (agents/verifier.md)
• Rubric — a small markdown file in .loop/rubrics/ that declares, for a class of work, the pass/fail criteria and how each one is verified (a command to run, a file to inspect). It's the contract the verifier grades against. Example: a code rubric might require "tests pass", "no secrets committed", "public functions documented".
• Gate — a real command from your project (npm test, a typecheck, ./tests/run.sh) that must exit 0 before work is committed. Rubrics judge quality; gates enforce that it actually runs.
• Vault — .loop/memory/, the plain-markdown store that travels with the repo: INDEX.md (map + stats), STATE.md (session handoff), LEDGER.md (failure log), and notes/ (distilled rules).
• Distill — the 5-stage protocol (Fail → Investigate → Verify → Distill → Consult) that turns a failure into a verified, reusable note in the vault, instead of a lesson you learn twice.
• Loop-Verified: n/m — a commit trailer stamped by loop-task: n of m rubric criteria met, judged by the independent verifier. Your audit trail.
• Backlog source — where loop-run reads its work queue: a document section (file, the default) or an external system (github / jira / command) you wire up at loop-init.
• Adapter — a small script (e.g. .loop/adapters/github.sh) implementing the list/report contract for one provider. The core stays vendor-neutral; the adapter is the only place gh/jira is ever called. Copy it as a template for a new provider.
• Write-back — what loop-run does with a result on the source: none, a verdict comment, or a draft-pr that links Closes #<id> so your merge auto-closes the item.

What you get

Component	What it does
SessionStart hook	Injects your project's memory (INDEX.md + STATE.md) into every new session, plus a reminder for unresolved failures in the ledger. Claude starts already knowing what past sessions learned.
Stop gate hook	Write before walking away: if code changed but STATE.md wasn't updated, ending the session is blocked once with a reminder. Also blocks ending mid-verification when a loop task marker is present. Max one block per session — never a lock-in.
PreCompact hook	Right before context compaction, reminds the model to persist progress into STATE.md so nothing is lost to summarization.
/loopcraft:distill skill	A 5-stage failure-to-knowledge protocol: Fail → Investigate → Verify → Distill → Consult. Failures become verified, general rules in your vault — merged into existing notes first, never duplicated.
Obsidian-compatible vault	.loop/memory/ is plain markdown with YAML frontmatter and [[wikilinks]]. Open it as an Obsidian vault and watch the knowledge graph grow. No app dependency — the loop only needs files.
verifier subagent	An independent grader that scores your work against a rubric — seeing only the output and criteria, not your reasoning. Prevents maker bias from clouding judgment.
/loopcraft:loop-task skill	Maker → verifier → retry → gate → commit cycle: submit a task description, get a verdict summary, then automatically stamp Loop-Verified: n/m in the commit trailer for audited work. Pass a leading #123 / issue key and it also comments the verdict on that item (when a write-back source is configured).
/loopcraft:loop-init skill	Scans your repo and interviews you to scaffold .loop/ with configured gates and a rubric starter. One-command project onboarding.
/loopcraft:loop-run skill	Autonomously traverses your backlog unattended — selects items, runs loop-task cycles, gates them, and commits. Commits stay on a branch by default; only in draft-pr mode does it push a review-only feature branch and open a draft PR (opt-in). Merging to the default branch always remains your call.

Zero runtime dependencies: bash + git + grep/sed/awk. Escape hatch: set LOOP_DISABLE=1 to disable all hooks.

See it in action

An illustrative loop-task cycle. The rubric is the one loopcraft actually ships, and the verdict follows the verifier's real output format — but the run below is a representative example, not a captured log.

Say you're adding a new branch to a hook script. Instead of committing it directly, you route it through the loop:

/loopcraft:loop-task Add a LOOP_DISABLE short-circuit to the SessionStart hook

loop-task matches the changed file (hooks/scripts/*.sh) to the code rubric — five criteria, each with a declared way to check it:

1. Gate passes        — ./tests/run.sh exits 0, no `not ok` lines
2. Safety options     — changed scripts declare `set -euo pipefail` (or at least `set -u`)
3. Variables quoted   — path / user-input vars expanded as "$VAR"
4. Tests accompany    — every new branch gets a matching assert_* in tests/run.sh
5. Executable bit kept — files under hooks/scripts/ stay 755+

The maker does the work, then hands the diff — and only the diff and the rubric, never its own reasoning — to the independent verifier. First pass:

## Verdict

| # | Criterion           | Verdict | Evidence |
|---|---------------------|---------|----------|
| 1 | Gate passes         | pass    | ./tests/run.sh → exit 0, 0 `not ok` |
| 2 | Safety options      | pass    | line 2: `set -euo pipefail` |
| 3 | Variables quoted    | pass    | diff adds only `"$LOOP_DISABLE"` |
| 4 | Tests accompany     | fail    | new early-return branch, no matching assert_* in the tests/run.sh diff |
| 5 | Executable bit kept | pass    | mode 755 unchanged |

**Unscorable criteria**: none
**Result**: FAIL (4/5)
**FAIL summary**: #4 — the new disable branch ships without a regression test.

Because the verifier never saw the maker's reasoning, "it obviously works" carries no weight — only the missing test does. The maker gets just that FAIL summary, adds the assert_* case, and re-submits. Second pass:

**Result**: PASS (5/5)

Now the real gate runs, comes back green, and the work lands with its verdict stamped into the commit:

$ git log -1 --format='%s%n%n%b'
Add LOOP_DISABLE short-circuit to SessionStart hook

Loop-Verified: 5/5