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:
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:
- Daily Triage — read-only morning scan; zero risk; establishes observability habits
- PR Babysitter — monitors existing PRs; limited write scope (labels, comments only at L1)
- 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.)