compounding-loop 0.0.0-stage → 0.2.0

package/method/example/K-0001.md

@@ -0,0 +1,16 @@
+---
+id: K-0001
+type: gotcha
+status: confirmed
+scope: project
+triggers:
+  errors: ["fetch is not a function"]
+  files: []
+  commands: []
+  topics: [node version, fetch]
+evidence: reproduced on Node 16, fixed on Node 20 (example entry)
+created: 2026-01-01
+fired: 0
+helped: 0
+---
+Global `fetch` needs Node 18 or newer. Check `node --version` before debugging the call itself.

package/method/example/K-0002.md

@@ -0,0 +1,16 @@
+---
+id: K-0002
+type: gotcha
+status: confirmed
+scope: project
+triggers:
+  errors: ["browserType.launch: Executable doesn't exist", "Failed to download Chromium"]
+  files: [playwright.config.ts]
+  commands: [npx playwright install chromium]
+  topics: [playwright, sandbox, e2e]
+evidence: seen in a cloud sandbox where the browser download is blocked; a preinstalled Chromium was used instead (example entry)
+created: 2026-01-01
+fired: 0
+helped: 0
+---
+In a locked-down sandbox `npx playwright install chromium` can fail. Do not retry it. Point the config at a preinstalled Chromium or a system Chrome, and if Chrome then fails over missing libraries, run `npx playwright install-deps chromium`. Record the working setup in the project's Commands section once.

package/method/example/K-0003.md

@@ -0,0 +1,16 @@
+---
+id: K-0003
+type: decision
+status: confirmed
+scope: project
+triggers:
+  errors: ["Nothing to do"]
+  files: [".ai/session.lock"]
+  commands: [loop run]
+  topics: [session lock, unattended, stands down]
+evidence: every scheduled run ended with "Nothing to do" because the runner wrote the lock the prompt then respected (example entry)
+created: 2026-01-01
+fired: 0
+helped: 0
+---
+If the runner writes `.ai/session.lock` itself, the prompt must be told the lock is its own, or every run stands down at step one. Treat only a lock this session did not create as another run's. Keep `**/session.lock` in `.gitignore` so per-lane locks are never committed.

package/method/knowledge-index.md

@@ -0,0 +1,5 @@
+# Knowledge index
+
+One line per entry in `.ai/knowledge/`: `K-0001 · trigger (error text, file path or topic) · one-line lesson`.
+
+<!-- empty: the loop adds entries as it learns -->

package/method/operating-card.md

@@ -0,0 +1,40 @@
+## Operating Card (the Compounding Loop)
+
+> The full method is in `.ai/method.md`. The § numbers point to Part B there.
+
+**Objective:** the most verified-correct results per minute of the owner's attention. Tokens are the cheapest resource. A wrong result that looks right is the most expensive one.
+
+**Start of every session**
+1. Read `.ai/index.md`. Open a knowledge entry only when it's relevant to what you're doing.
+2. If `.ai/task.md` exists, run the resume protocol (§9.2) before anything else.
+
+**Before work**
+3. Size the task. Tiny: just do it. Medium: contract + checks. Large or unclear: plan, then loop.
+4. For medium and large tasks, write the contract (§5): goal, done-when (checkable by a command), constraints, out of scope.
+
+**During work**
+5. One unit of work at a time. Run the checks after each unit. You never declare done; the checks do.
+6. Write a note the moment you learn something, marked CONFIRMED or GUESS. Don't save it for the end.
+7. After any error, search `.ai/index.md` for the error text before trying a fix.
+8. Before editing a file, check the index for entries about that path.
+9. Send reading-heavy work (search, docs, logs, review) to subagents that report back in 10 lines or fewer. Keep code-writing in one thread.
+10. Same failure twice: stop and run the stuck protocol (§9.3). Don't retry a variant.
+11. If reality contradicts the plan or contract, stop and record it. Don't silently work around it.
+12. Point to code and docs (`path:line`). Never copy them into notes.
+
+**Context**
+13. At ~50–60% context, or when a unit is done and the next one is big: run the handoff (§9.1) and end the run.
+
+**Finishing**
+14. When the checks pass, run the retro (§12), log the task and delete `.ai/task.md`.
+
+**Unattended runs** (no human watching; the owner reads the results later)
+- Session lock: if `.ai/session.lock` shows another run started less than 90 minutes ago, do nothing and stop.
+- Run budget: `.ai/task.md` holds `Run: N / 30`. Add 1 at the start of every run; at 30, write `BLOCKED.md` ("run budget reached") and stop.
+- If `DONE.md` or `BLOCKED.md` exists, do nothing and stop. Write `DONE.md` only when every done-when passes; write `BLOCKED.md` (tried, the question, best guess) when stuck.
+
+**Never**
+- Mark your own work done without the checks passing.
+- Treat a GUESS from an earlier window as fact.
+- Delete or rewrite CONFIRMED knowledge without new evidence.
+- Change this card.

package/method/retro.md

@@ -0,0 +1,10 @@
+# Retro
+
+Run it when the checks pass, before deleting `.ai/task.md`. About two minutes.
+
+1. List what was learned. For each item: does it apply beyond this task? Is it confirmed or a guess? At what moment would it have helped (file, command or error)?
+2. Move general, confirmed items down the promotion ladder as far as they go: `guess → confirmed note → note with a trigger → automated check`. The best memory is one the model never has to read: turn a rule into a lint, test or script and delete the prose.
+3. Write each kept lesson as a knowledge entry (`.ai/knowledge/K-NNNN.md`, see `method/example/K-0001.md`) with triggers, and add one line to `.ai/index.md`.
+4. Flag entries this task showed to be wrong or stale. Never delete a CONFIRMED entry without new evidence.
+5. Add one line to `.ai/log.md`: date, task, checks result, runs used, what was learned.
+6. Delete `.ai/task.md`.

package/method/reviewer-prompt.md

@@ -0,0 +1,13 @@
+# Reviewer prompt
+
+Give this to a subagent that did not write the code. It sees the diff and the brief, not your reasoning.
+
+> You are reviewing a change before it is pushed. Read `IDEA.md` (the brief), the task contract in `.ai/task.md`, and the diff (`git diff origin/main..HEAD`).
+>
+> Find the three most likely ways this is wrong for a real user, and check each by reading code or running a small command. Do not edit files.
+>
+> Look for: behaviour the contract promises but no test proves; a check that passes without exercising the feature; paths, quoting or line endings that break on Windows; secrets, tracking or calls home; private files that would be published; a published URL or API that changed.
+>
+> Report in 10 lines or fewer. Mark each finding BLOCKER (fix before push) or NOTE. Say what you ran and what you only read.
+
+The author fixes every BLOCKER, runs the checks again, then pushes. A reviewer's NOTE goes in the task file under Guesses.

package/method/stuck-protocol.md

@@ -0,0 +1,12 @@
+# Stuck protocol
+
+Triggered by the same failure twice, or by two runs with no progress toward done-when. Do not retry a variant.
+
+1. Stop. Record the attempt under Tried: what you did, the exact error, why it failed.
+2. Search `.ai/index.md` for the error text.
+3. Write down every assumption you are making. Move the ones you never tested to Guesses.
+4. Test the weakest assumption with the cheapest experiment.
+5. Try a structurally different approach, not a variant of what failed.
+6. Still stuck, unattended: write `BLOCKED.md` (what you tried, the specific question, your best guess), commit, push and stop. With a human present: ask the same question.
+
+Hard cap: a task that reaches about 5 runs without the checks passing goes to `BLOCKED.md`.

package/method/task-template.md

@@ -0,0 +1,41 @@
+# TASK: <name>
+
+Run: 0 / 30
+Status: not started
+
+## Contract
+**Goal:** build v1 of IDEA.md (replace with one sentence per task)
+**Done when:** derive from IDEA.md: `<command>` passes; <other checks>
+**Constraints:** <what must not change, what must be reused>
+**Out of scope:** <what not to touch>
+
+## Current state
+(rewrite every window)
+- Branch / commit: <branch> @ <hash>, clean
+- Checks: <passing / failing, names>
+- Next step: <exactly one step>
+- Read first: <path:lines>, <K-ids>
+
+## Confirmed
+(facts proven by a command or test, with how we know)
+- <fact> (seen in <test / log / commit>)
+
+## Guesses
+(unproven; test before building on them, never treat as fact in a later run)
+- <hypothesis> (test: <cheapest experiment>)
+
+## Tried
+(append-only: approach → result → why)
+1. <approach> → <result> → <why it failed>
+
+## Decisions
+(decision · reason · how to reverse)
+
+## Don't
+- <thing not to retry> (Tried #<n>)
+
+## Handoff
+(each run ends by writing: where it stopped, the exact next step, anything half-done)
+
+## promote?
+(for the retro: general lessons worth keeping)

package/package.json

@@ -1,6 +1,78 @@
 {
   "name": "compounding-loop",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Write the brief, check back tomorrow: unattended, verified Claude Code build loops with a local dashboard.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "loop": "bin/loop.js"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "templates/",
+    "method/",
+    "runners/",
+    "plugin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Minntooos/compounding-loop.git"
+  },
+  "homepage": "https://github.com/Minntooos/compounding-loop#readme",
+  "bugs": {
+    "url": "https://github.com/Minntooos/compounding-loop/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "ai-agents",
+    "autonomous",
+    "dashboard",
+    "cli",
+    "context-engineering"
+  ],
+  "scripts": {
+    "check": "node scripts/check.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p web/tsconfig.json --noEmit",
+    "unit": "vitest run",
+    "build": "tsc -p tsconfig.build.json && node demo/copy-demo.mjs && vite build",
+    "e2e": "playwright test",
+    "test": "npm run check && npm run typecheck && npm run unit && npm run build && npm run e2e",
+    "dev:web": "vite",
+    "preview": "vite preview --port 4173 --strictPort"
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.13.0",
+    "@fontsource-variable/inter": "^5.3.0",
+    "@fontsource-variable/jetbrains-mono": "^5.3.0",
+    "@playwright/test": "^1.64.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-query": "^5.104.1",
+    "@types/node": "^26.6.4",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "cmdk": "^1.1.1",
+    "lucide-react": "^1.52.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "recharts": "^3.10.1",
+    "tailwindcss": "^4.3.3",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.3",
+    "vitest": "^5.0.3",
+    "yaml": "^2.9.1"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.8.1",
+    "@hono/node-server": "^2.1.4",
+    "commander": "^15.0.0",
+    "hono": "^4.13.13"
+  }
+}

package/plugin/.claude-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "compounding-loop",
+  "version": "0.2.0",
+  "description": "Run unattended, verified Claude Code build loops: set up a repo, hand off between windows, run retros and escape stuck loops.",
+  "license": "MIT",
+  "keywords": ["loop", "unattended", "verification", "handoff", "retro"]
+}

package/plugin/commands/handoff.md

@@ -0,0 +1,10 @@
+---
+description: Write the handoff so a fresh session with zero memory can continue at full quality
+---
+
+Run the handoff protocol (method section 9.1) for the current task.
+
+1. Run the checks and record the real result (counts and failing names) in `.ai/task.md` under "Current state".
+2. Rewrite "Current state": branch and commit, whether the tree is clean, the single next step, and what to read first (`path:line`, knowledge ids). Do not copy code into the file.
+3. Make sure every new fact is under Confirmed (with how we know) or Guesses (with the cheapest test). Move anything half-done into the handoff as "half-done: ...".
+4. Commit the task file. Then tell the user the next window is ready and name the first thing it will do.

package/plugin/commands/loop-init.md

@@ -0,0 +1,13 @@
+---
+description: Set up this repository for the Compounding Loop (operating card, task file, knowledge index)
+---
+
+Set this repository up for unattended, verified build loops.
+
+1. If the `loop` CLI is available, run `npx compounding-loop init` and report what it created. Otherwise do the steps below by hand.
+2. Make sure these exist, creating only what is missing and never overwriting the user's files:
+   - `CLAUDE.md` containing the Operating Card (the "Operating Card (the Compounding Loop)" section).
+   - `.ai/method.md`, `.ai/index.md`, `.ai/knowledge/`, `.ai/log.md`.
+   - `.ai/task.md` with `Run: 0 / 30`, a Contract with a "Done when" that a command can check, and empty Confirmed, Guesses, Tried and Decisions sections.
+3. Ask the user for the one-sentence goal and the command that proves it works (for example `npm test`) if `IDEA.md` or the task contract does not already say.
+4. Finish with the exact command the user should run next, and do not start the build yourself.

package/plugin/commands/retro.md

@@ -0,0 +1,11 @@
+---
+description: Run the retro after the checks pass - promote lessons, flag stale entries, log the task
+---
+
+Run the retro (method section 12) now that the checks pass.
+
+1. Run the checks once more and confirm they pass. If they do not, stop and say so; the task is not done.
+2. Read `.ai/task.md`. List the lessons worth keeping beyond this task (Confirmed facts that will bite again, gotchas, decisions). For each, propose a knowledge entry with its triggers (files, error text, commands, topics) and evidence.
+3. Flag existing entries in `.ai/index.md` that this task showed to be wrong or stale. Do not delete or rewrite a CONFIRMED entry without new evidence.
+4. Add one line to `.ai/log.md`: date, task, checks result, number of windows, what was learned.
+5. After the user approves the proposed entries, write them, update `.ai/index.md`, and delete `.ai/task.md`.

package/plugin/commands/stuck.md

@@ -0,0 +1,10 @@
+---
+description: Run the stuck protocol when the same failure has happened twice
+---
+
+You have hit the same failure twice. Stop retrying variants and run the stuck protocol (method section 9.3).
+
+1. Write the failure down under Tried in `.ai/task.md`: what you did, the exact error, and why you think it failed. Search `.ai/index.md` for the error text.
+2. List what you have not yet checked: assumptions you treated as fact (move them to Guesses), the cheapest experiment that would split the possible causes, and whether a subagent could read the logs or docs for you.
+3. Run that one experiment. If it explains the failure, fix it and record the cause as Confirmed.
+4. If it does not, and unattended: write `BLOCKED.md` (what you tried, the specific question, your best guess), commit, push and stop. If a human is present: report the question and your best guess, and wait.

package/runners/github-actions/lanes.yml

@@ -0,0 +1,103 @@
+# Compounding Loop: one scheduled job per lane on GitHub Actions.
+#
+# Setup (once):
+#   1. Add ONE repository secret under Settings > Secrets and variables > Actions:
+#        ANTHROPIC_API_KEY        (API billing), or
+#        CLAUDE_CODE_OAUTH_TOKEN  (a Claude subscription; create it with `claude setup-token`).
+#      Secrets are referenced by name only. Never write a key into this file or the repository.
+#   2. Copy this file to .github/workflows/lanes.yml.
+#   3. The `verify` job runs `loop check-lanes`, which needs compounding-loop 0.2.0 or later.
+#   4. Edit the `lane` and `cron` pairs in the matrix to match .ai/lanes.json, and keep the same
+#      cron strings in `on.schedule` (see runners/routine/README.md for staggering N lanes).
+#
+# How it runs: every cron line starts the whole matrix, and each job does real work only when
+# the schedule that fired is its own (or when started by hand), so one lane runs per trigger.
+name: compounding-loop-lanes
+
+on:
+  schedule:
+    - cron: "7 * * * *"
+    - cron: "19 * * * *"
+    - cron: "31 * * * *"
+  workflow_dispatch: {}
+
+# Workflow-level default: read only. The lane job raises it, because the lane pushes to main.
+permissions:
+  contents: read
+
+jobs:
+  lane:
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    permissions:
+      contents: write # the lane commits and pushes to main
+    strategy:
+      fail-fast: false
+      max-parallel: 1 # lanes never run at the same time, so two pushes cannot race
+      matrix:
+        include:
+          - { lane: api, cron: "7 * * * *" }
+          - { lane: web, cron: "19 * * * *" }
+          - { lane: docs, cron: "31 * * * *" }
+    # A lane never overlaps its own previous run; queue instead of cancelling one mid-push.
+    concurrency:
+      group: loop-lane-${{ matrix.lane }}
+      cancel-in-progress: false
+    steps:
+      - name: Is this lane's turn?
+        id: gate
+        env:
+          EVENT: ${{ github.event_name }}
+          FIRED: ${{ github.event.schedule }}
+          MINE: ${{ matrix.cron }}
+        run: |
+          if [ "$EVENT" = "workflow_dispatch" ] || [ "$FIRED" = "$MINE" ]; then echo "go=true" >> "$GITHUB_OUTPUT"; else echo "go=false" >> "$GITHUB_OUTPUT"; fi
+      - uses: actions/checkout@v4
+        if: steps.gate.outputs.go == 'true'
+        with:
+          ref: main
+          fetch-depth: 0
+          # The lane pushes, so the checkout token must stay in git's config (persist-credentials: true,
+          # the default). A job that only reads, like `verify` below, sets it to false.
+          persist-credentials: true
+      - uses: actions/setup-node@v4
+        if: steps.gate.outputs.go == 'true'
+        with:
+          node-version: 22
+      - uses: anthropics/claude-code-action@v1
+        if: steps.gate.outputs.go == 'true'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          # Paste runners/routine/lane-prompt.md here with {{name}} and {{lane}} filled
+          # ("${{ matrix.lane }}" works for the lane). Short form shown:
+          prompt: |
+            You are one scheduled run of the ${{ matrix.lane }} lane of an unattended build loop.
+            Read CLAUDE.md and follow it exactly. Your task file is .ai/lanes/${{ matrix.lane }}/task.md.
+            Every commit ends with the trailer line "Lane: ${{ matrix.lane }}". Push to main, never to a claude/ branch.
+            Stop if DONE.md or BLOCKED.md exists at the root or in .ai/lanes/${{ matrix.lane }}/.
+            Never publish, spend money, or add secrets or tracking.
+          claude_args: >-
+            --max-turns 200
+            --allowedTools "Bash,Edit,Write,Read,Glob,Grep,Task"
+
+  verify:
+    # Read-only: reports any commit that crossed a lane boundary.
+    needs: lane
+    if: ${{ always() }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+          persist-credentials: false # nothing here pushes, so the token is not left in the checkout
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - name: Check lane ownership
+        run: |
+          BASE=$(git rev-parse --verify -q "origin/main~20" || git rev-list --max-parents=0 HEAD | tail -1) # a young repo has fewer than 20 commits
+          npx --yes compounding-loop check-lanes --range "$BASE..HEAD"

package/runners/github-actions/loop.yml

@@ -0,0 +1,51 @@
+# Compounding Loop: scheduled build run on GitHub Actions.
+#
+# Setup (once):
+#   1. Add ONE repository secret under Settings > Secrets and variables > Actions:
+#        ANTHROPIC_API_KEY        (API billing), or
+#        CLAUDE_CODE_OAUTH_TOKEN  (a Claude subscription; create it with `claude setup-token`).
+#      Never write a key into this file or the repository.
+#   2. Copy this file to .github/workflows/loop.yml.
+#   3. Pick a staggered minute in `cron` below (avoid minute 0).
+name: compounding-loop
+
+on:
+  schedule:
+    - cron: "17 * * * *"
+  workflow_dispatch: {}
+
+# Two runs on one branch would fight; queue instead of cancelling a run mid-push.
+concurrency:
+  group: compounding-loop
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    timeout-minutes: 90
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - uses: anthropics/claude-code-action@v1
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          prompt: |
+            You are one scheduled run of the build loop for this repository. Nobody is watching.
+            Read CLAUDE.md and follow "Unattended mode" exactly. IDEA.md is the brief.
+            If .ai/session.lock is less than 90 minutes old, or DONE.md or BLOCKED.md exists, reply "Nothing to do" and stop.
+            Add 1 to the Run counter in .ai/task.md (Run: N / 30); at 30 write BLOCKED.md ("run budget reached") and stop.
+            Do units of work, run the tests after each, and push to main only when they pass.
+            Finish with the handoff in .ai/task.md. Never publish, spend money, or add secrets or tracking.
+          claude_args: >-
+            --max-turns 200
+            --allowedTools "Bash,Edit,Write,Read,Glob,Grep,Task"

package/runners/local/README.md

@@ -0,0 +1,9 @@
+# Local runner
+
+Runs the loop from your own machine on a schedule. Needs Node 20+, git and the `claude` CLI signed in to your account.
+
+- **Linux:** paste the line from `crontab.txt` into `crontab -e` and set your repository path.
+- **macOS:** `crontab.txt` works too, but launchd is the native scheduler and runs missed rounds after sleep. Edit the paths in `launchd.plist` (`loop` from `which loop`, your repository, the log file), copy it to `~/Library/LaunchAgents/` and load it with the `launchctl bootstrap` line at the top of the file. The plist runs `loop run` hourly at minute 17.
+- **Windows:** edit the path in `task-scheduler.xml`, then import it with `schtasks /Create /XML task-scheduler.xml /TN CompoundingLoop`. The `claude.exe` native build must be on your PATH. Add `--skip-permissions` to the task's arguments only in a repository you trust, so the unattended run can edit files.
+
+Both use the minute `17`; change it so several loops do not start together. Each run is capped by the session lock (90 minutes) and the run budget (`Run: N / 30`).

package/runners/local/crontab.txt

@@ -0,0 +1,6 @@
+# Compounding Loop on macOS or Linux: run one round at minute 17 of every hour.
+# Install with `crontab -e` and paste the line below, replacing /path/to/repo.
+# `loop run` skips the round when DONE.md / BLOCKED.md exists; the prompt itself checks the session lock.
+# Cron has a minimal PATH: if `loop` or `claude` is not found, use their full paths. For unattended
+# edits add `--skip-permissions` (see `loop run --help`) only in a repository you trust.
+17 * * * * cd /path/to/repo && loop run >> .ai/loop-cron.log 2>&1

package/runners/local/launchd.plist

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!-- Compounding Loop on macOS: run one round at minute 17 of every hour.
+     Install:   cp launchd.plist ~/Library/LaunchAgents/com.example.compounding-loop.plist
+                (edit the paths below first), then
+                launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.example.compounding-loop.plist
+     Remove:    launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.example.compounding-loop.plist
+     For unattended edits add <string>--skip-permissions</string> after <string>run</string> below, only in a repository you trust.
+     launchd has a minimal PATH, so PATH below must contain the folders of `node`, `loop` and `claude`. -->
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>com.example.compounding-loop</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>/usr/local/bin/loop</string>
+    <string>run</string>
+  </array>
+  <key>WorkingDirectory</key>
+  <string>/path/to/repo</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>PATH</key>
+    <string>/usr/local/bin:/opt/homebrew/bin:/path/to/home/.local/bin:/usr/bin:/bin</string>
+  </dict>
+  <key>StartCalendarInterval</key>
+  <dict>
+    <key>Minute</key>
+    <integer>17</integer>
+  </dict>
+  <key>StandardOutPath</key>
+  <string>/path/to/repo/.ai/loop-cron.log</string>
+  <key>StandardErrorPath</key>
+  <string>/path/to/repo/.ai/loop-cron.log</string>
+</dict>
+</plist>

package/runners/local/task-scheduler.xml

@@ -0,0 +1,32 @@
+<?xml version="1.0"?>
+<Task version="1.4" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Compounding Loop: run one round of the build loop every hour.</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <CalendarTrigger>
+      <Repetition>
+        <Interval>PT1H</Interval>
+        <StopAtDurationEnd>false</StopAtDurationEnd>
+      </Repetition>
+      <StartBoundary>2026-01-01T00:17:00</StartBoundary>
+      <Enabled>true</Enabled>
+      <ScheduleByDay>
+        <DaysInterval>1</DaysInterval>
+      </ScheduleByDay>
+    </CalendarTrigger>
+  </Triggers>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <ExecutionTimeLimit>PT90M</ExecutionTimeLimit>
+    <Enabled>true</Enabled>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>loop.cmd</Command>
+      <Arguments>run</Arguments>
+      <WorkingDirectory>C:\path\to\repo</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>

package/runners/routine/README.md

@@ -0,0 +1,56 @@
+# Claude Code routine runner
+
+A routine is a scheduled Claude Code session in the cloud. It runs `prompt.md` against your repository on a cron schedule, with nobody watching.
+
+## Set up
+
+1. Copy `prompt.md`. Its only placeholder is `{{name}}`, your project name. The install and test commands come from your `CLAUDE.md`.
+2. In Claude Code on the web, create a routine for the repository and paste the prompt. Give it write access to `main` only.
+3. Pick a schedule (see below). `loop` generates a staggered cron line for you.
+
+## Staggered cron
+
+If several loops (or several lanes of one project) run against one repository, give each a different minute so they do not collide. Use the pattern `M * * * *` (hourly), and move `M` by at least 10 minutes per loop, for example `7 * * * *`, `17 * * * *`, `27 * * * *`. Avoid minute `0`: everyone's schedule lands there.
+
+Each run stops after about 40 minutes of work, so an hourly schedule leaves a gap before the next one. The 90-minute session lock (`.ai/session.lock`, or `.ai/lanes/<lane>/session.lock` per lane) stops two runs from working at once. The run budget (`Run: N / 30` in `.ai/task.md`) caps the total number of runs.
+
+## Safety
+
+The prompt never publishes, spends money or stores a secret. The routine uses your Claude account; no API key goes into the repository.
+
+## Lanes
+
+With several lanes, create one routine per lane plus one control room routine.
+
+| File | Placeholders | Routine |
+|---|---|---|
+| `lane-prompt.md` | `{{name}}` project, `{{lane}}` lane name | one per lane, hourly |
+| `control-room-prompt.md` | `{{name}}` project, `{{lanes}}` lane names, comma separated | one, every 3 hours |
+
+`loop run --lane <name>` fills them for local runs. In the cloud, paste the filled text into the routine. In the cloud nothing writes the lock; it only matters when a local `loop run --lane` is active too. The lane prompt stands down on a fresh `.ai/lanes/<lane>/session.lock`, stops on root or lane `DONE.md`/`BLOCKED.md`, and ends every commit with `Lane: <lane>`.
+
+### Staggered cron for N lanes
+
+Give lane `i` (counting from 0) the minute `7 + i * step` with `step = 12` for up to five lanes (more lanes: use a smaller step, but keep minutes distinct), and put the control room on its own minute every 3 hours. Runs last up to 40 minutes, so neighbouring lanes overlap; that is expected. Path ownership plus `git pull --rebase` before each push make it safe, and the stagger only spreads the pulls out. Avoid minute 0.
+
+3 lanes (`api`, `web`, `docs`):
+
+| Routine | Cron |
+|---|---|
+| api | `7 * * * *` |
+| web | `19 * * * *` |
+| docs | `31 * * * *` |
+| control room | `43 */3 * * *` |
+
+5 lanes (`core`, `kit`, `server`, `web`, `docs`, as in this repository):
+
+| Routine | Cron |
+|---|---|
+| core | `7 * * * *` |
+| kit | `19 * * * *` |
+| server | `31 * * * *` |
+| web | `43 * * * *` |
+| docs | `55 * * * *` |
+| control room | `3 */3 * * *` |
+
+Each lane run stops after about 40 minutes, so an hourly lane leaves a gap. Runs that end in about a second usually hit the plan's usage limit, not a bug; fewer or slower lanes cost less.