Agentic Loop Project Template

A starter kit for projects where an AI agent iterates autonomously toward a goal, based on the principle that a real loop needs three things:

1. Verify — an automatic gate that can reject bad work. Without it, the agent just agrees with itself on repeat.
2. State — persistent memory of what was tried and what failed, so iterations don't repeat mistakes.
3. Stop condition — success criteria AND a hard iteration cap, so the loop can't run (and spend) forever.

Before you start: the four-box test

Only build a loop if all four are true. If even one is false, stay with manual prompting — it will be cheaper and better.

• The task repeats at least weekly (setup cost must amortize)
• Bad output can be rejected automatically (tests, lint, build, rules)
• The agent can complete the work end-to-end without human handoffs
• Success is objectively measurable, not a matter of taste

How to use this template

1. Copy this folder to start a new project (or clone and rename).
2. Run /setup-loop in Claude Code — it interviews you, runs the four-box test, and fills in LOOP.md, scripts/verify.sh and CLAUDE.md for you. (Or fill them in by hand: LOOP.md is the contract; verify.sh must exit 0 on success, non-zero on failure.)
3. Follow the build order below — do not skip steps.

Build order (sequence matters more than tools)

1. Manual first — run the workflow by hand once, prove it works.
2. Solidify as a skill — encode the working steps in .claude/commands/iterate.md.
3. Add loop structure — verify gate + stop condition (already scaffolded here).
4. Only then schedule — cron, /loop, GitHub Actions, hooks. Automating an unproven workflow means it fails silently overnight.

Running the loop

With Claude Code, from this directory:

/iterate          # one supervised iteration (start here)
/loop 30m /iterate   # scheduled, only after the workflow is proven

Each iteration: read STATE.md → pick the highest-impact problem → make the minimal fix → run scripts/verify.sh → log the result in STATE.md → stop if the gate passes or the iteration cap is hit.

Cost guardrails

• Context re-sends every iteration and grows each pass — iteration 8 costs more than iteration 1. Keep STATE.md a compact log, not a transcript.
• Track your accept rate: if fewer than 50% of loop outputs get used, the loop costs more than it saves. Kill it.
• Watch for the agent declaring victory prematurely while the loop keeps running — that's why verify.sh must be the judge, never the agent's own claim of success.
• Use a maker/checker split (separate reviewer agent) only for high-stakes work: it roughly doubles the bill.

Files

File	Purpose
LOOP.md	The loop contract: goal, verify gate, stop condition
STATE.md	Persistent memory across iterations
scripts/verify.sh	The automatic gate (exit 0 = pass)
.claude/commands/setup-loop.md	/setup-loop — interactive first-time setup
.claude/commands/iterate.md	The reusable skill one iteration follows
CLAUDE.md	Project instructions loaded by Claude Code every session
.env / .env.example	Secrets (API keys) — .env is gitignored, fill it locally