loop-engineering

name

loop-engineering

description

Use this skill whenever a developer wants to set up, design, audit, or debug an automated agent loop for their project. Triggers include: "help me set up a loop", "I want agents to run while I sleep", "automate my CI triage", "set up a goal loop", "review my loop setup", "design an agentic workflow", "loop engineering", "build a self-running agent", or any request to make Claude Code or Codex run autonomously on a schedule or goal. Also trigger when a developer describes wanting agents to find work, fix bugs, open PRs, or run verification without manual prompting, or capture deferred follow-up work for later. This skill copies canonical templates from templates/ (bundled with this skill), customizes them from a project interview, and writes the files to the correct paths in the developer's project. Do not paraphrase or shorten template content — copy first, then customize only CUSTOMIZE markers and interview-driven fields.

Loop Engineering Skill

Loop engineering replaces manual prompting with designed systems that prompt agents automatically. This skill scaffolds those systems for a specific project.

Canonical templates: All loop artifacts live in templates/ next to this SKILL.md. Path A (this skill) and Path B (README direct copy) use the same files. BUILD mode copies from templates/, applies interview answers at CUSTOMIZE points, and writes to the project. Never invent structure from memory — read the template files first.

Two modes:

• BUILD — developer wants to create a loop from scratch → Interview, then copy templates
• AUDIT — developer has an existing loop and wants it reviewed → Audit Checklist

Determine which mode applies from context, or ask if unclear.

---

Mode 1: BUILD — Scaffolding a First Loop

Step 1: Interview the Project (ask these, don't skip)

Before producing any files, collect the following. Ask all at once to save turns.

1. What triggers the work? (CI failures / open issues / commits / manual Slack trigger / all of the above)
2. What does "done" look like for a task? (tests pass / lint clean / PR approved / custom condition)
3. Which toolchain? (Cursor / Claude Code / Codex / other)
4. Where should the loop run? (local machine / GitHub Actions / both)
5. Should agents open PRs automatically, or land everything in an inbox for human review?
6. Do you already have a CLAUDE.md, AGENTS.md, or .cursor/rules? (affects harness + skill paths)
7. What's the budget ceiling per run? (dollar amount or token count — required before shipping)
8. Should deferred follow-ups be `off`, `suggest` (default), or `auto`?
9. Which GitHub repository receives follow-ups? (do not assume it is the checkout repository; for multi-repo ledgers, record `--target-repo` per finding)
10. Which labels and categories require human confirmation? (security, cross-repository, public, or low-confidence are recommended)

If the developer can't answer #2 (the stop condition), stop and resolve it before proceeding. A loop without a verifiable stop condition is the Nodding Loop anti-pattern.

Step 2: Resolve destination paths

From interview answer #3, set these paths in the target project (not this skill dir):

Toolchain	loop-triage skill	loop-engineering (already installed)	evaluator agent
Cursor	.cursor/skills/loop-triage/SKILL.md	.cursor/skills/loop-engineering/	.cursor/agents/loop-reviewer.md
Claude Code	.claude/skills/loop-triage/SKILL.md	.claude/skills/loop-engineering/	.claude/agents/loop-reviewer.md
Codex	.codex/skills/loop-triage/SKILL.md	.codex/skills/loop-engineering/	.codex/agents/loop-reviewer.md

Shared paths (all toolchains) — dev-loop/ namespace (avoids generic state/ / inbox/ at repo root):

Artifact	Destination
Dev-loop README	dev-loop/README.md
State ledger	dev-loop/triage.md
Human hold queue	dev-loop/inbox/.gitkeep
Pre-flight checklist	dev-loop/checklist.md
Verify commands	dev-loop/verify-commands.md
Follow-up ledger	dev-loop/followups.jsonl
Verdict log	dev-loop/verdicts.jsonl (created on first record)
Verify scripts	scripts/dev/loop-verify.sh, record_dev_loop_verdict.py, test-loop-verify.sh
Follow-up scripts	scripts/dev/record_followup.py, flush_followups.sh
Schedule	.github/workflows/loop-triage.yml (if answer #4 includes GitHub Actions)

Tell the developer the resolved paths before writing files.

Step 3: Copy templates and customize

Read each file from templates/ (relative to this skill). Copy content to the destination paths above. Do not paraphrase, summarize, or omit sections outside CUSTOMIZE markers. If a bundled template is missing, fetch the matching file from https://raw.githubusercontent.com/Geeksfino/ai-dev-playbook/main/templates/.

Apply interview answers only where indicated:

Template	Source file	Customize using
Discovery skill	templates/loop-triage/loop-triage.md	Q1 (triggers → Read), Q2 (stop condition → Hand off examples), Q5 (inbox vs PR → Stop), Q8–10 (follow-up mode, destination, confirmations), project rules at <!-- CUSTOMIZE -->
Dev-loop README	templates/dev-loop/README.md	Usually none
State file	templates/dev-loop/triage.md	Usually none — commit as-is
Checklist	templates/dev-loop/checklist.md	Copy as-is; developer checks boxes manually
Verify commands	templates/dev-loop/verify-commands.md	Project test/lint commands
Follow-up ledger	templates/dev-loop/followups.jsonl	Start empty; append records through record_followup.py
Evaluator	templates/evaluator-agent/loop-reviewer.md	No edits — copy verbatim
Verify scripts	templates/scripts/dev/*	chmod +x on .sh files after copy; run both helper self-tests
Schedule	templates/github-actions/loop-triage.yml	Q4 (cron if Actions), Q7 (--max-tokens), Phase 1-only note
Inbox	templates/dev-loop/inbox/.gitkeep	Copy as-is

Strip TEMPLATE header comments (lines starting with # TEMPLATE) from files written into the target project — those headers are for humans copying from the playbook repo, not for deployed loop files.

Three-phase loop (verification): loop-triage Phase 2 implements in a worktree; Phase 3 must launch a separate readonly Task subagent using loop-reviewer + loop-verify.sh. Never let the generator self-approve.

Scheduling (#4): If GitHub Actions only → workflow runs Phase 1 (triage) on cron; document full Phases 1–3 /loop from references/toolchain-map.md for Cursor. If local only → skip workflow. If both → workflow for discovery + on-demand /loop for implement/review.

Evaluator: Never weaken loop-reviewer.md. A separate skeptical evaluator prevents the Nodding Loop anti-pattern.

Step 4: Verify before finishing

Confirm for the developer:

1. All five loop moves are covered (see references/five-moves.md)
2. Generated loop-triage matches bundled template except CUSTOMIZE substitutions
3. loop-reviewer.md is byte-identical to templates/evaluator-agent/loop-reviewer.md (minus TEMPLATE header)
4. dev-loop/triage.md, dev-loop/followups.jsonl, dev-loop/inbox/, and verify scripts exist before first run
5. Budget ceiling from Q7 is reflected in workflow --max-tokens or documented for local runs
6. dev-loop/checklist.md is in place — walk through it together if this is the first loop
7. ./scripts/dev/test-loop-verify.sh passes (or python3 scripts/dev/record_dev_loop_verdict.py self-test)
8. python3 scripts/dev/record_followup.py self-test passes
9. Follow-up mode is suggest unless Q8 explicitly selected auto, and Q9 names the destination repository

---

Mode 2: AUDIT — Reviewing an Existing Loop

When a developer has a loop already running (or partially built), audit it against the five failure modes from the IEEE paper. Read references/failure-modes.md for the full diagnostic criteria.

Run through each anti-pattern and report: present / absent / partial.

Anti-pattern	Symptom to check for
Nodding Loop	Has the loop ever produced a REJECT from its evaluator? If no REJECTs in >50 turns, the evaluator is broken. Check dev-loop/verdicts.jsonl.
Amnesiac Loop	Does each run start from the same place? Check if dev-loop/triage.md exists and is committed.
Manual Loop	When was the last automated run? If the answer is "the day we built it", scheduling is broken.
Blind Loop	Is a human still deciding what the loop works on each morning? Discovery is missing.
Tangled Loop	Do parallel agents use separate worktrees? Check for shared working directory collisions.

For each absent or partial item, copy the relevant file from templates/, customize from what you know about the project, and write to the correct destination (same rules as BUILD Step 3).

Legacy layout: If the project still uses repo-root state/triage.md and inbox/, recommend migrating to dev-loop/ and updating skill paths (see FinClaw adoption).

---

Token Budget Guidance

Set these before the first unattended run. Hard caps prevent a spinning bug from consuming an entire night's quota.

Loop type	Suggested per-run cap	Suggested daily cap
Triage only (Phase 1)	30k tokens	100k tokens
Full loop (Phases 1–3, worktrees)	100k tokens	500k tokens
Enterprise / parallel fleet	Set by cost ceiling, not token count

A loop without a budget cap has delegated its spending authority to its own bugs.

---

Reference Files

• templates/ — Canonical loop artifacts (same as playbook templates/ at repo root)
• references/five-moves.md — Theory: discovery, handoff, verification, persistence, scheduling
• references/failure-modes.md — The five anti-patterns and how to diagnose them
• references/toolchain-map.md — Claude Code vs Codex vs Cursor command equivalents

Read reference files only when you need underlying reasoning. Always read templates/ when producing or repairing artifacts.