Loop Engineering

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):

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

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:

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.

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.

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.