# Loop Engineering

> 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.

- Skill: `geeksfino/loop-engineering` (Agent Skill, multi-file: 18 files)
- Install (CLI): `npx skillmds@latest add geeksfino/loop-engineering`
- Raw SKILL.md: https://api.skillmd.com/api/skills/geeksfino/loop-engineering/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: geeksfino (https://skillmd.com/u/geeksfino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/geeksfino/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):

| 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.