| 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:
- All five loop moves are covered (see
references/five-moves.md)
- Generated loop-triage matches bundled template except CUSTOMIZE substitutions
loop-reviewer.md is byte-identical to templates/evaluator-agent/loop-reviewer.md (minus TEMPLATE header)dev-loop/triage.md, dev-loop/followups.jsonl, dev-loop/inbox/, and verify scripts exist before first run- Budget ceiling from Q7 is reflected in workflow
--max-tokens or documented for local runs
dev-loop/checklist.md is in place — walk through it together if this is the first loop./scripts/dev/test-loop-verify.sh passes (or python3 scripts/dev/record_dev_loop_verdict.py self-test)python3 scripts/dev/record_followup.py self-test passes- 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, schedulingreferences/failure-modes.md — The five anti-patterns and how to diagnose themreferences/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.
