# Agentic Loops: Playbook Proactive loops that scan the codebase and our external systems (GitHub, Vercel), then **propose** fixes and file well-formed tickets. This file is the shared contract every loop obeys. Skills under `.claude/skills/loop-*` implement the loops; local `/loop` invocations and session-local crons run them on a schedule. **Cloud routines are retired (2026-07-20): all loops are LOCAL.** > These are **proactive loops**: triggered by a schedule, no human in real time, each item exits when > its goal is met. Quality comes from the *system around the loop* (verification skills, clean > conventions, second-agent review), not from a clever prompt. > **This file lives at `.claude/loops.md` (committed).** `dev_docs/*` is gitignored ("internal > reference, not published"), so the playbook cannot live there: the cloud routines clone `main` and > need this file present. --- ## Autonomy policy: "Propose, don't merge" This is a Swedish accounting/compliance codebase. Loops never touch `main` or production. | Loop may… | Loop may **NOT**… | |---|---| | Fix trivial/low-risk issues on a `loop/*` branch | Merge any PR (`gh pr merge` is forbidden) | | Open PRs for review, comment on PRs | Push to `main` or any human's active branch | | File / label / dedupe / close GitHub issues | Force-push over another author's commits | | Push to a PR branch it created, or a dependabot branch | Edit posted journal entries / violate an [Accounting Guard Rail](../CLAUDE.md#accounting-guard-rails) | | Escalate to a human via `loop:needs-human` | Act on PRs from `contributor:flagged` / `pr:flagged` authors | Every code change a loop makes **must pass the [`loop-verify`](skills/loop-verify/SKILL.md) gate before the PR is opened.** No exceptions. --- ## Ticketing & dedupe conventions (all loops share these) **Destination:** GitHub Issues + PRs in `erp-mafia/accounted` (via `gh`). Not Linear. **Labels:** `loop:auto` (always, on anything a loop creates), `loop:vercel`, `loop:triage`, `loop:design`, `loop:needs-human` (a loop tried and could not safely proceed). **Idempotency / anti-spam: MANDATORY.** Before filing anything: 1. Compute a stable **fingerprint** (error signature, file:line, rule id, never a timestamp). 2. `gh issue list --search " in:body state:all"` (include closed). Match → comment instead of filing a duplicate; closed + recurring → reopen with a note. 3. Embed `` in the body so future runs find it. **Branch naming:** `loop/-`, e.g. `loop/ci-pr848`, `loop/issue-843`, `loop/vercel-`. **Anti-thrash:** if the same fix (same fingerprint) already failed, **stop**, label `loop:needs-human`, comment what was tried. Never retry the same failing action in a cycle. **Per-run caps (cost):** each run bounds how much it acts and `log()`s what it skipped. Defaults below. --- ## The loops | # | Loop | Skill | Where | Cadence (default) | Per-run cap | |---|---|---|---|---|---| | 1 | PR + CI triage | `loop-pr-ci-triage` | **Local** (session cron / `/loop`) | ~3x/day while a session is open | ≤5 PRs | | 2 | Vercel errors → tickets | `loop-vercel-errors` | **Local** (Vercel MCP) | daily / on-demand | ≤8 issues, ≤2 PRs | | 3 | Issue triage + easy-fix | `loop-issue-triage` | **Local** (session cron / `/loop`) | ~2x/day while a session is open | triage all; ≤2 PRs | | 4 | UI/UX + design scan | `loop-design-scan` | **Local** (`/loop`) | on-demand | ≤1 area, ≤6 findings | **All loops are local.** Cloud routines were retired 2026-07-20: the three claude.ai triggers (`trig_01J2nG7eB9gsdAb9YSGBVwa8`, `trig_014CmE3gTJ7ErnvL2trPYymu`, `trig_017hB94ieGVwreJqHpGRDVoM`) ran for 19 days as silent no-ops (no `GH_TOKEN` in the cloud env, issue #993) and the founder chose to disable them rather than provision. Do not re-enable or re-create them. Loop 2 additionally needs the Vercel MCP (local-only; Sentry is not used). Loop 4 needs `npm run dev` + Chrome. The `loop-ignite` skill audits and (re)schedules the local cadence each session. --- ## The verification gate (`loop-verify`) Before any loop opens a PR: `check:lint` → targeted `vitest` → `test:pg` **iff** a trigger/RPC/RLS/migration was touched → `check:guards` → the "no core imports from `@/extensions/`" grep → build if config/types changed. Plus: never violate an [Accounting Guard Rail](../CLAUDE.md#accounting-guard-rails); keep `sv`/`en` in sync ([i18n](rules/i18n.md)). --- ## Why not cloud (historical, kept so nobody re-litigates it) Cloud routines were tried 2026-07-01 and retired 2026-07-20. The blockers, should anyone revisit: the anthropic_cloud env needs a `GH_TOKEN` fine-grained PAT for private-repo access (OAuth-only integration does not work, anthropics/claude-code#64130), cannot reach interactively-authenticated MCPs (Vercel/Supabase plugins), and Sentry is **not** used in this codebase (the `SENTRY_*` names in `.env.local` are leftovers). Reviving cloud means: set `GH_TOKEN` in the routine editor's cloud env, re-enable the triggers, and verify the first fire leaves a real GitHub trace. Until someone does all of that deliberately, treat cloud as retired: see issue #993 for the full history. --- ## Operating the loops - **Audit / (re)ignite each session:** `/loop-ignite` (audits evidence, schedules session-local crons). - **Run on-demand:** `/loop-pr-ci-triage`, `/loop-issue-triage`, `/loop-vercel-errors`, `/loop-design-scan `. Wrap in `/loop ` to repeat locally; `/goal` for a hard exit. - **Cost:** route mechanical steps to cheaper models; reserve judgment for the strong model. `/usage`. Don't run more often than the watched thing changes. ## Extending When a loop produces a bad result, encode the lesson back into the skill / a CLAUDE.md rule / a verifier so every future run improves: don't just fix the one output.