Skip to content

Loop Patterns Catalog

Named, composable production loop patterns with defined cadence, risk level, and operational requirements. Each is a reusable blueprint that can be instantiated into any repo using the standard six primitives.

(Cobus Greyling, cobusgreyling/loop-engineering, Jun 2026.)

Note on readiness vs. developer maturity: Loop readiness levels (L1/L2/L3) classify each individual loop's operational trust. They are distinct from the 14-step developer maturity progression in Loop Maturity Model, which classifies the engineer's capability. A step-14 loop engineer still starts every new loop at L1.

Loop Readiness Levels

Before deploying any pattern, assign it a readiness level:

Level Mode What the loop does Gate to advance
L1 Report-only Discovers work, notifies humans — no autonomous action ≥1 week of zero false positives
L2 Assisted Proposes fixes; human approves before merge Full observability + loop-budget.md in place
L3 Autonomous Auto-merges; fires without human approval L2 gate + loop-run-log.md + LOOP.md BUDGET section

Default rule: start every new loop at L1. The first week is observation-only regardless of confidence. Advancing to L3 requires documented evidence of reliability, not just absence of visible failures. L3 should be explicitly gated in the loop's own LOOP.md before any auto-merge is allowed.

Loop Command Modes

Every pattern below runs on top of the /loop primitive, which as of v2.1.248 offers two modes with no platform restriction. Changelog, verbatim: "Changed /loop: self-paced dynamic mode and the no-prompt autonomous default are now always available, including on Bedrock/Vertex/Foundry." (v2.1.248 release notes.) Before that release, self-paced mode (Claude sets its own wake-up cadence instead of a human choosing a fixed interval) and the no-prompt autonomous default were gated off Bedrock, Vertex, and Foundry — a loop engineer deploying on those platforms had to fall back to a fixed interval with per-wake-up confirmation. v2.1.248 removes that platform check entirely.

/loop is also quieter about doing nothing, as of v2.1.243: "consecutive wake-ups where Claude has nothing to do now fold into a single line in the terminal instead of printing each one." (v2.1.243 release notes.) That is a terminal-output change, not a change to the Early Exit rule itself (see Token Cost Reference below) — a no-op wake-up still exits at the same token cost, it just no longer floods the transcript with one line per wake-up.

Pattern Catalog

Daily Triage

Cadence: Morning once daily · Default level: L1

Scans open issues, failing CI, stale PRs, and dependency alerts. Outputs a structured report to a channel or file. Never takes autonomous action — discovery and notification only.

Property Value
Risk Low
State file STATE.md (watchlist)
Human gate Read report; prioritise manually
Token cost/run ~50,000–80,000

Thin Loop

Cadence: Event-driven (issue/PR opened) + weekday cron · Default level: L1

A report-only loop that runs in GitHub Actions with almost no extra files: the issue tracker and the Actions job summary are the state. It lists open PRs and issues with gh and writes the snapshot to the job summary. On a run triggered by an issue or PR it also posts one short comment, and a <!-- thin-loop --> marker stops a second comment on the same thread. It makes no code edits, applies no labels, closes nothing and never auto-merges.

Property Value
Risk Low — its only write is one marked comment per triggering thread (needs issues: write / pull-requests: write)
State file None — GitHub issues/PRs carry the backlog; an optional loop-run-log.md line is the only persisted trace
Human gate Reads the job summary or the comment; the loop does not close issues, apply labels or push commits
Token cost/run Very low — at L1 the workflow uses gh only, with no agent invoked

It matches how most loops already look, on purpose. The pattern's own write-up paraphrases Lulla et al.'s study (autonomous loops confirmed "in 217 of the 256 repositories our heuristics matched", out of 36,710 mined), putting the finding as "they commit triggers (cron / pull_request workflows), and almost never commit STATE.md" — Cobus Greyling's wording, not a quotation from the paper itself (Lulla et al., "Loop Engineering: Building Blocks, Adoption, and Impact," arXiv 2608.21884, Aug 2026, the underlying study). The same paper is cited in Loop Maturity Model. With no implementer there is no verifier; the check is mechanical: "gh succeeded and the summary is non-empty." Add STATE.md once findings must survive across runs (backlogs, attempt counts, budgets). The source is explicit: "Do not start here if you need attempt caps, a maker/checker split, or a token kill switch". Use Daily Triage or PR Babysitter instead.

(Cobus Greyling, cobusgreyling/loop-engineering — patterns/thin-loop.md at commit 3f7ac78, Aug 2026.)


PR Babysitter

Cadence: Every 10–15 min · Default level: L2

Shepherds open PRs through CI and review. Responds to failing checks, updates descriptions, pings reviewers on idle PRs, and merges when all conditions are met.

Property Value
Risk Medium — can comment and ping team
State file STATE.md (acting_on: pr-id — collision prevention)
Human gate Merge approval at L2; explicit conditions required at L3
Token cost/run ~200,000–250,000

CI Sweeper

Cadence: Every 15 min · Default level: L2

Reacts to failing CI. Reads the failure, determines root cause, applies a fix, pushes to branch, monitors the next CI run. Hard limit: 3 fix attempts per failure; escalates to human after that.

Property Value
Risk Medium-high — writes code autonomously
Attempt cap 3 per failure (required — prevents infinite fix loop)
Early exit If CI is green, exit immediately at <5k tokens
Token cost at 15 min without early exit ~5M tokens/day

The early exit rule is mandatory. Without it, a CI Sweeper running at 15-minute cadence against a passing repo burns ~5M tokens/day on no-ops. The loop must check for work before doing any triage; if the watchlist is empty, exit immediately.


Dependency Sweeper

Cadence: Every 6 hours · Default level: L2

Patches CVEs and outdated packages. Patch-level changes only — no minor or major bumps without explicit approval. Opens PRs, runs tests, merges if CI passes.

Property Value
Risk Low-medium (patch-only)
Safe Security patches, patch version bumps in test files
Escalate Minor/major bumps, lockfile changes, dependency removals

This pattern is harder than it looks. DEPBENCH — 203 real dependency-upgrade tasks across 5 package ecosystems, each with hidden code-level breakage (signature/API/runtime- semantic changes the upstream changelog never mentions) — found the best-performing agent-harness-ecosystem combination solves only 51.2% of tasks. Read as a caution against the "merges if CI passes" framing above: CI passing on a patch bump is necessary but the benchmark's whole point is that upstream breakage is often silent and un-changelogged, so a sweeper needs its own regression suite, not just the upstream project's stated compatibility promise, to catch what green CI on a stale test suite would miss. (arXiv 2608.30300, "Update from Hell", Aug 2026.)


Post-Merge Cleanup

Cadence: Off-peak (nightly) · Default level: L2

After each merge, scans for TODO comments, dead code, and debt markers. Files cleanup PRs at low-traffic times. Never runs during active working hours.

Property Value
Risk Low — additive cleanup
Constraint Off-peak only; does not interrupt active work
Token cost/run ~50,000–80,000

Changelog Drafter

Cadence: Pre-release · Default level: L1

Reads commit history since last release and drafts a human-readable changelog. Draft only — human reviews and approves before publish. Never auto-publishes.

Property Value
Risk Minimal
Output CHANGELOG_DRAFT.md (human approves before merge)

Issue Triage

Cadence: Companion to Daily Triage · Default level: L1–L2

Labels, prioritises, and categorises incoming issues. At L1: labels and comment summaries. At L2: may close obvious duplicates or out-of-scope issues with an explanation comment.

Property Value
Risk Low (L1) · Medium (L2)
Human gate Review labels before any auto-close actions

Token Cost Reference

Benchmarks from operating experience:

Run type Token cost
Noop pass (empty watchlist, early exit) ~3,000–5,000
Report-only triage ~50,000–80,000
Action run (implementer + verifier) ~200,000–250,000
CI Sweeper at 15 min cadence, no early exit ~5M/day

These are third-party operating benchmarks, not a measurement of any specific loop. As of v2.1.243, /usage reports the real per-loop figure instead — see Cost Per Loop, Now First-Party in Cost & Turn Control.

See Cost & Turn Control for budget caps and --max-budget-usd usage.

Multi-Loop Coordination

When multiple loops coexist in the same repo, uncoordinated writes cause conflicts.

Priority ordering

When two loops both find work, higher-priority loops act first: 1. CI Sweeper (live failures — highest urgency) 2. PR Babysitter (in-progress reviews) 3. Dependency Sweeper (proactive patches) 4. Post-Merge Cleanup (low urgency) 5. Daily Triage (report-only — always last)

Collision detection

Each action loop writes acting_on: <branch-or-pr-id> to its STATE.md before spawning a fix. All other loops read all STATE.md files before starting work and skip any item that is already claimed. Rule: one owner per branch per hour.

(cobusgreyling/loop-engineering, Jun 2026.)

When a conflict cannot be resolved automatically, the loop writes to a human inbox section in STATE.md and notifies rather than acting.

Concrete Multi-Loop STATE.md Example

Two loops coexisting on the same repo — PR Babysitter and CI Sweeper — with non-overlapping claimed work, each in its own state file (the convention this KB's cited source actually uses — see cobusgreyling/loop-engineering's multi-loop.md):

# ci-sweeper-state.md
acting_on: fix/auth-token-race
locked_at: 2026-06-26T09:12Z
attempt: 1 of 3

# pr-babysitter-state.md
acting_on: pr-1048
locked_at: 2026-06-26T09:14Z
status: awaiting-ci

Each loop reads every other loop's state file before claiming work. If acting_on in any file matches the branch/PR a loop was about to claim, that loop skips the item and moves to the next candidate.

Per-Agent Heartbeat Alternative (Harnery Pattern)

An alternative to per-loop markdown state files — harnery gives each agent instance a continuously-updated heartbeat file at .harnery/active/<instance_id>.json (fields include session_id, last_heartbeat, and a files_touched array of claimed paths):

{
  "instance_id": "claude-worktree-a1b2",
  "session_id": "sess_9f2c",
  "last_heartbeat": "2026-06-26T09:12:00Z",
  "files_touched": ["src/auth/token.ts"]
}

Coordination rules: 1. Claim — a claim check (evaluateClaim) adds the path to files_touched when no fresh peer already holds it 2. Release — the path is removed from files_touched on completion (releaseClaim); a crashed group's claims can be swept via groupUnclaim 3. Liveness, not per-claim TTL — last_heartbeat is refreshed on every heartbeat write; a background stale-sweep prunes the whole heartbeat file once it is older than a single repo-wide freshness threshold (default 600s, HARNERY_AGENT_COORD_FRESHNESS), not a per-claim ttl_seconds

Benefits over a markdown state file: no merge conflict risk (one file per agent instance, atomic rename writes), and orphaned claims are swept automatically after a crash.

(ryanjkelly/harnery, Jun 2026.)

See Fan-Out for scope-verified parallelism at the hook layer.

Safety Defaults

Auto-merge allowlist (L3 only — nothing else auto-merges): - Typo fixes in documentation - Lint auto-fixes in test files - Import ordering changes

Never auto-merge at any level: - Dependency bumps or lockfile changes - Behaviour-affecting code changes - Database migrations - Infrastructure configuration

Path denylist — never touch these files autonomously:

.env, **/secrets/**, auth/**, payments/**, **/migrations/**,
k8s/production/**, **/credentials/**

Add project-specific sensitive paths to this list in CLAUDE.md before deploying any L2+ loop.

Three-Loop Onboarding Sequence

When introducing loops to a new codebase or team, start with exactly three patterns and do not add a fourth until the first three are stable:

  1. Daily Triage — read-only morning scan; zero risk; establishes observability habits
  2. PR Babysitter — monitors existing PRs; limited write scope (labels, comments only at L1)
  3. Post-Merge Cleanup — runs after merge; bounded scope (a closed PR cannot regress)

Add CI Sweeper only after PR Babysitter's attempt limits and verifier have been proven for two weeks in the first three loops. CI Sweeper is more aggressive (writes code, opens PRs) and requires the collision-detection infrastructure (the acting_on field in each loop's state file) to already be working and trusted.

Starting with CI Sweeper before the triage + babysitter + cleanup loops are stable is a common failure mode: the team gains no observability before the first high-risk loop runs.

(cobusgreyling/loop-engineering, Jun 2026.)

Debt Audit Loop

Property Value
Trigger Weekly cron (Monday 09:00)
Scope Entire codebase — discovery pass; scoped to read-only behavior by the prompt, not by permission mode (the template runs under acceptEdits)
Action Identify tech debt items (dead code, deprecated deps, TODO comments, coverage gaps); append to .loopflow/reports/debt-audit.md — never modifies code
Cadence Weekly discovery; human reviews report and creates tickets manually
Token cost ~80,000–120,000 (report-only run across large codebase)
Readiness L1 only — report mode; never auto-creates issues or PRs
Stop condition Report written; no open PRs to check

The report file persists across runs. The loop appends new findings and marks previously-reported items as "still open" or "resolved", giving the team a living tech-debt register rather than a static weekly snapshot.

(faisalishfaq2005/loopflow, Jun 2026.)

Docs Sync Loop

Property Value
Trigger Scheduled (weekly cron or CI — LoopFlow ships no daemon; e.g. the maintainer's examples/github-action-docs-sync.yml runs it every Monday)
Scope docs/ only; runs in isolated git worktree
Action Detects drift between code and documentation (API signatures, config fields, deprecated flags); proposes doc edits as a PR
Token cost ~50,000–100,000 depending on diff size
Readiness L2 — proposes PRs but does not auto-merge; human reviews before merge
Stop condition VERDICT: PASS — all doc references match current code, or PR opened for any that don't

(faisalishfaq2005/loopflow, Jun 2026.)

Knowledge-Base Tracker Loop (two-stage: search → integrate)

The loop that maintains this knowledge base is itself a pattern worth cataloguing: a self-writing KB whose run is decomposed into two single-responsibility stages behind an artifact handoff, run under worktree isolation — on demand by default since v3.7.0 (20260912), with the daily-cron schedule kept available but disabled (scripts/SCHEDULING.md).

Property Value
Trigger On demand (scripts/run-loop-news-now.sh) since v3.7.0 (20260912); the launchd 05:00-local schedule remains available but disabled — see scripts/SCHEDULING.md
Scope The KB (docs/, index, digest, sources, changelog); runs in a throwaway git worktree branched off origin/main
Action Stage A (fetch-loop-news) searches tracked sources + the general web, scores candidates, writes .loop-news/findings.json, and stops. Stage B (integrate-loop-news) consumes that artifact, writes the digest, integrates each finding into the docs, runs the structural reviews (Phase 4b/4c), cuts a release, and push origin HEAD:main
Cadence One run per deliberate invocation (one per day only under the pre-v3.7.0 schedule); the two stages run as two separate claude -p sessions sharing the worktree
Readiness L3 — commits and publishes to main autonomously; bounded by per-stage budgets and a publish-safety retry guard
Stop condition Digest section written for the date and pushed — including on a zero-finding day, which commits an empty section rather than discarding it, so "swept, found nothing" and "did not run" leave different traces in the committed record

Why two stages. Search (retrieval, external I/O, noisy, parallel) and integration (KB reasoning, sequential, writes) fail for unrelated reasons and need disjoint context. Splitting at the artifact boundary gives each a single responsibility, keeps the search stage's bulky retrieval context out of the reasoning stage, and enables granular retry — a failure in Stage B re-runs only B against the saved findings, never repeating the search. Worktree isolation makes each attempt's filesystem disposable and decouples the run from the primary checkout's state; because the final push is durable, the retry guard keys off whether origin/main advanced rather than the local tree (see Headless Mode).

(This repo, .claude/skills/ + scripts/run-loop-news.sh, Jul 2026.)