Loop kit
The front door of a four-skill maintenance-loop suite. One tick does a slice of
maintenance work and stops; a scheduler starts the next tick. This skill owns
the shared runtime the other three call: the config, the state directory, the
Reply Desk, the templates, the AGENTS.md block, doctor and the tick lock.
Nothing in the suite reaches the network without a card approved on the Reply Desk by a human.
<kit-dir> below is the directory containing this file — the loop-kit skill
directory. It is wherever the suite was installed, for example
<repo>/.claude/skills/loop-kit in a Claude Code project, so every invocation
is written against <kit-dir> rather than a path that only works in the skills
repository.
When to use it
- The user asks to set up, install or configure the maintenance loops.
- A tick skill stopped because
.loop/config.jsonis missing. - The user asks whether the loops are ready: run
doctor. - A tick reports a lock it cannot take.
Setup
Confirm the working tree is the target repository and the user wants the suite installed there.
git rev-parse --show-toplevelgives the root.Run init:
python3 <kit-dir>/scripts/loopkit.py --repo-root <repo> initInit reads
git remote get-url originforrepo, defaultsprojectto the repository name, and accepts--repo,--project,--state-dir,--lessons,--rules,--agents,--default-branchand--forcewhen the user wants something other than the default.Read the doctor rows init printed and resolve every
FAILbefore the user arms a scheduler.Show the user the three scheduler lines init printed and the command that installs the sibling skills that are missing. Arming a scheduler is the user's call.
Init is idempotent. Re-running it rewrites .loop/config.json from the file
already there, so keys the user added by hand survive, and it leaves an existing
LESSONS.md and rules file untouched.
Configuration
Everything project-specific lives in .loop/config.json in the target
repository. The file is committed; the state directory is never inside the
repository. references/desk.md documents the desk, loopkit.py config prints
the resolved file.
| Key | Meaning |
|---|---|
project |
Names the state directory, the worktree prefix and the lock. |
repo |
owner/name, resolved from the git remote when not given. |
defaultBranch |
Branch a tick branches from and merges into. |
stateDir |
State, desk cards and locks. ~ is expanded; never in the repo. |
lessonsPath |
LESSONS.md, written by the nightly review. |
rulesPath |
Acceptance rules the review promotes lessons into. |
agentsPath |
File whose marked block tells every agent the loops exist. |
verifyDoc |
Pointer to how this project verifies a change, or null. |
worktreeCmd |
Template over {project}, {branch}, {slug}, or null. |
checks |
Commands a tick must run before it drafts a PR. Empty means ask. |
trustedLogins |
Bot logins a tick may treat as trusted reviewers. |
windowDays |
The shared lookback knob, in days, for both tick loops that look back. |
desk |
{"kind": "files"} for the portable desk. |
loops |
Per-loop interval and enabled, plus loop-specific keys. |
windowDays is one number read by two skills, so they cannot drift:
loop-triage-githubuses it as the recent-issue window: only threads created within the lastwindowDaysdays are the loop's to triage.loop-nightly-reviewuses it as the seed range when it backfills a freshLESSONS.md(one still carrying<!-- reviewed-through: 0000000 (never reviewed) -->), and as the cap on how far back a backfill may reach.
Both meanings are the same intent: how far back this project considers a thread
or a commit to be current. A tick with no cursor yet falls back to windowDays
rather than to "everything".
One tick
Every tick skill carries the same sections in the same order, and the same invariants. The canonical wording is in references/send-protocol.md:
- Preconditions, then the trust boundary.
- Send what was approved on the desk, re-reading each thread first.
- Advance state, collect, decide, act.
- Draft every outbound action as a card, then report and stop.
A tick never posts without an approved card, never posts a draft whose thread
moved, and never retries a card left in sending by a tick that died.
The Reply Desk
Every outbound action exists first as a JSON card in the state directory, and a
static index.html renders the ones waiting. The maintainer opens the page,
reads each draft, and approves, edits or drops it.
python3 <kit-dir>/scripts/desk.py list --status pending
python3 <kit-dir>/scripts/desk.py approve pr-123 --note "shorten it"
python3 <kit-dir>/scripts/desk.py claim pr-123
python3 <kit-dir>/scripts/desk.py sent pr-123 --url <comment url>
python3 <kit-dir>/scripts/desk.py render
put refuses to overwrite a card that is approved, sending or sent, so a
loop cannot erase a decision the maintainer already made. claim is atomic and
refuses a card that is not approved. Both exit 3 when the state refuses the
operation; 2 is a usage or config error. The full surface is in
references/desk.md.
Templates the kit installs
- templates/LESSONS.md is the lessons file the nightly
review maintains: one rule per lesson, then the evidence, with a
Seen Nxcount of distinct days. - templates/acceptance.md is the acceptance-rules file, including the table lessons are promoted into after three days.
- templates/agents-block.md is the block init keeps
in place between
<!-- loop-kit:begin -->and<!-- loop-kit:end -->.
Scheduling a tick
references/harnesses.md gives the scheduler lines for Claude Code, this harness, cron, systemd and Windows Task Scheduler, plus the five-minute send check and how to re-arm the event watcher.
Scripts
scripts/loopkit.py takes init, doctor, status, config and lock, all
with --repo-root and --json where it makes sense:
python3 <kit-dir>/scripts/loopkit.py doctor
python3 <kit-dir>/scripts/loopkit.py status --json
python3 <kit-dir>/scripts/loopkit.py lock acquire --name triage-github
doctor prints one PASS/WARN/FAIL/SKIP row per check and exits non-zero
on any FAIL. It looks for the sibling tick skills next to <kit-dir> — the
directory <kit-dir> lives in, which is <repo>/.claude/skills in an installed
project and the repository root in the skills library — never in the target
repository. Pass --suite-root DIR to check a different install location.
lock acquire exits 3 while another tick holds the lock, and takes over a lock
older than --stale-seconds after saying so.
Both scripts are Python 3 standard library only and run on Windows and POSIX.
Porting notes
references/porting-readest.md records what the suite took from the original maintenance-loop pull request and what it changed on purpose, including why the Reply Desk is files rather than a hosted page.