loop-ops

Files (29)

• SKILL.md
• STATE.template.md · assets/
• STATE.md · assets/examples/pr-watch/
• github-actions.yml · assets/examples/pr-watch/
• loop-run.sh · assets/examples/pr-watch/
• loop.config.yaml · assets/examples/pr-watch/
• run-log.md · assets/examples/pr-watch/
• run.md · assets/examples/pr-watch/
• loop.config.template.yaml · assets/
• model-pricing.json · assets/
• run.sh.template · assets/
• run.template.md · assets/
• claude-code-loops.md · references/
• composition-map.md · references/
• failure-modes.md · references/
• native-primitives-at-a-glance.md · references/
• native-scheduling.md · references/
• pattern-catalog.md · references/
• reference-index.md · references/
• risk-tiers.md · references/
• state-spine.md · references/
• tools.md · references/
• check-native-facts.py · scripts/
• check-pricing-sync.py · scripts/
• loop-check.sh · scripts/
• loop-doctor.sh · scripts/
• loop-estimate.py · scripts/
• loop-scaffold.sh · scripts/
• run.sh · tests/

SKILL.md (first lines)

# Loop Ops — outer-loop design discipline

**A loop is not a prompt.** Turn-by-turn prompting puts you in the loop forever. *Loop
engineering* inverts it: you design a **recurring process with memory, verification, and
boundaries** that discovers work, hands it to agents, verifies the result, and decides —
on a schedule or until a goal is met — whether to **land it or escalate to a human**.

This is the **outer loop** above a single agent run, the twin of [`iterate`](../iterate/SKILL.md) (the inner loop); it composes what this repo already ships rather than reimplementing it: [references/composition-map.md](references/composition-map.md).

## Native primitives schedule; loop-ops governs

Claude Code now ships the *cadence* half natively. **Do not hand-roll a scheduler** — pick
a native host, declare it as `host:` in the config, and spend the discipline where the
primitives leave a hole. Verified surface, parameters and limits (2026-08-30):
[references/native-scheduling.md](references/native-scheduling.md).

`/loop` (session-scoped, 7-day expiry, L1 only) · Desktop scheduled tasks (durable local, worktree toggle off by default) · cloud routines (machine-off, 1 h floor, no permission mode, every connector attached) · `/goal` (a completion gate, not a cadence). Gives vs lacks: [references/native-primitives-at-a-glance.md](references/native-primitives-at-a-glance.md).

What **none** of them provide — and what this skill is for: a **state spine** that survives
ticks, a **token budget**, a **verify gate** you can trust, an **escalation rule**, and the
**risk-tier ladder** that decides whether the loop has earned the autonomy you're about to
grant it. The plumbing moved into the harness; the judgement did not.

### When the native primitive is enough — stop here

Don't scaffold a loop for work the harness already does. **Use the primitive raw** when
*all* of these hold:

- it **writes nothing** you'd have to undo (watch a deploy, poll a build, remind you), or
  the only writes are ones you'll review anyway;
- it is **supervised or short-lived** — you're watching, or it stops in a session;
- **nothing needs to be remembered between ticks** beyond what's in the repo;
- and you'd **shrug if a tick silently didn't fire**.

`/loop 5m check if the deploy finished` is a complete, correct answer. Wrapping it in a
`loop.config.yaml` adds ceremony and no safety.

Reach for loop-ops the moment **any one** of those flips: the loop starts *changing*
things, runs *unattended*, needs to know what it did *last time*, or its silence would
cost you. That is the whole trigger — everything below is what to do once it fires.

---

## The six primitives → what owns each here

Every durable loop rests on six primitives. The discipline is wiring them; the parts
already exist:

| Primitive | What it is | Owned in claude-mods by |
|---|---|---|
| **Schedule** | fire the loop on a cadence *or an event* | native-first, declared as `host:` — `session-cron` (`/loop`+`CronCreate`, L1 only), `desktop-task` (`scheduled-tasks` MCP: local + durable), `cloud-routine` (`/schedule`: machine-off, plus API/GitHub event triggers), `/goal` for completion. `external` (cron/Task Scheduler + `loop-run.sh`) only for non-Claude-Code control |
| **Worktree** | isolated, discardable execution context | `git-ops` worktrees, `fleet-worker` (per-task worktree) |
| **Skills** | persistent project knowledge the run loads | this repo's skill layer + your `CLAUDE.md` |
| **Sub-agents** | maker/checker separation | `Agent`/`Task`; dispatching skills (`review`, `testgen`) |
| **Connectors** | reach tickets / CI / chat | MCP tools, `gh`, `github-ops` |
| **+ State** | a durable spine *outside* the conversation | `STATE.md` + run-log + budget (this skill) |

The inner improvement loop is `iterate`; cheap parallel makers are `fleet-worker`; the
test-gated merge queue is `fleet-ops`; inter-loop signalling is `pigeon`. `loop-ops` is
the doctrine that connects them.

## Loop anatomy

```
   ┌──────────────────────────────────────────────────────────────┐
   │  SCHEDULE (cadence)                                           │
   │     └─▶ TRIAGE      read STATE.md → pick the next unit of work │
   │           └─▶ WORKTREE   isolate (git worktree)               │
   │                 └─▶ MAKER     implementer run (or fleet-worker)│
   │                       └─▶ CHECKER  verify gate + guard (tests) │
   │                             └─▶ GATE  safe & allowlisted?      │
   │                                   ├─ yes → LAND  (commit/PR)   │
   │                                   └─ no  → ESCALATE (+context) │
   │     └─▶ write STATE.md, append run-log, decrement budget ──────┘
```

The **gate** is the load-bearing decision. Everything before it is mechanical; the gate
is where a loop earns the right to run unattended — or doesn't.

## The risk-tier ladder (the heart of the discipline)

Never start a loop unattended. Graduate it. Each tier maps to a concrete Claude Code
**permission mode** — full mapping, the headless-profile table, and the *enumerate vs
isolate* fork in [references/risk-tiers.md](references/risk-tiers.md).

| Tier | Posture | Permission mode | May do | Lands by |
|---|---|---|---|---|
| **L1 Report** | read-only discovery + triage | `plan` / `dontAsk`+read allowlist | scan, summarize, propose — **writes nothing** | a human reads the report |
| **L2 Assisted** | suggest changes, human gates the merge | `dontAsk`+narrow allowlist, or `auto` | edit in a **worktree**, run tests, open a PR | a human approves the PR (or `fleet-ops`) |
| **L3 Unattended** | autonomous land within a denylist | `bypassPermissions` **in an isolated container only** | commit/merge allowlisted classes | the loop itself, inside its boundary |

**The host is part of the tier.** `session-cron` (`/loop` + `CronCreate`) cannot host L2+
at all: it needs an open idle session and every recurring job expires after 7 days.
`cloud-routine` has *no permission mode*, so its tier is expressed as repos + environment
network policy + connectors instead — which means a routine is effectively autonomous the
moment it is created, and the L1 posture has to come from the prompt being read-only.
`loop-doctor` enforces both. Details: [references/native-scheduling.md](references/native-scheduling.md).

The cardinal rule, straight from Claude Code's own gate model: **an unattended loop is a
*scheduler/script that invokes `claude -p`*, not a Claude session that spawns ungated
children.** A session in `auto` mode that tries to launch a `--permission-mode
bypassPermissions` child is blocked as *Create Unsafe Agents* — by design. See
[references/risk-tiers.md](references/risk-tiers.md) and the repo's
[auto-mode-classifier reference](../../docs/AUTO-MODE-CLASSIFIER.md).

## The escalation gate

What a loop may **land** vs what it must **escalate** is not a vibe — it mirrors Claude
Code's classifier tiers. Bake these into the config's `escalation:` field:

- **Always escalate (never auto-land):** force-push, push to `main`, production deploys
  or migrations, mass deletion, granting IAM/repo permissions, anything destroying
  pre-session files, editing `.claude/`/settings (self-modification), `curl | bash`.
- **Safe to auto-land at L2/L3 (when allowlisted):** a green PR on a feature branch,
  a lockfile patch bump that passes the guard, a generated changelog draft, a label/
  triage classification, a comment.
- **The test:** *would a careful human let this happen unattended in this repo?* If the
  action's blast radius exceeds the loop's stated purpose, it escalates. A general goal
  ("keep CI green") is **not** authorization for a specific high-blast action it implies.

From 0xDarkMatter/claude-mods, MIT.

More from 0xDarkMatter/claude-mods