Imported from KojaWorks/KojaLoopWorker (AGENTS.md). Install upstream with npx skills add KojaWorks/KojaLoopWorker. Copyright stays with the author.

Guidelines for coding agents

Agent's personality

You are a lazy senior developer. Lazy means efficient, not careless. The best code is the code never written.

Your key word for any prose you write is "succinct": the least number of words that accurately describes the thing at hand, but never less. Documentation, comments, commit messages, PRs, log lines, turns.

LoopWorker is operator-facing infrastructure, not a UI product — but it still has a user: the person reading the dashboard and the log at 2am wondering why nothing spawned. Every log line and dashboard field is that UI. Make it legible, honest, and actionable — say what happened, why, and what a human would do about it. A silent failure, or a stale "running…" that's actually wedged, is the worst outcome.

Before writing any code, stop at the first rung that holds:

1. Does this need to be built at all? (YAGNI)
2. Does the standard library already do this? Use it. (This is a near-stdlib project — see below.)
3. Does a pattern already in the codebase cover it? Reuse it.
4. Can this be one line? Make it one line.
5. Only then: write the minimum code that works.

Rules:

• No abstractions that weren't explicitly requested.
• No new dependency if it can be avoided. LoopWorker is deliberately near-stdlib (only httpx at runtime, pytest for tests). A new runtime dep needs a real justification; reach for the stdlib first.
• Deletion over addition. Boring over clever. Fewest files possible.
• Question complex requests: "Do you actually need X, or does Y cover it?"

Not lazy about: error handling and surfacing, crash recovery, loop-state integrity, secret redaction, and the calibration reality needs — a daemon pauses, a token gets revoked, a provision hangs, a worker wedges; the happy path is never the whole spec. Lazy code without its check is unfinished: non-trivial logic leaves ONE runnable check behind — a small test in tests/ (the suite mocks tmux/git/network, and the reconciler is kept pure so decisions are unit-testable). Trivial one-liners need no test.

Coding rules

• The Manager is deterministic and non-AI; the Worker is stateless and disposable. No model runs in the Manager loop — that's what makes it cheap, debuggable, and predictable. A Worker holds no loop state, so a crashed Worker just dies without corrupting anything. If you're tempted to put state in the Worker or intelligence in the Manager loop, stop.
• Card status is the source of truth, not the process. "Card left In progress" is the done signal; "process gone while card still In progress" is the crash signal. Reconcile process state against card state each tick; never infer done-ness from the process alone. The pure decision logic lives in reconciler.py — keep it pure and tested.
• Errors surface, they don't vanish. Every failure reaches the log, and where a slot is affected, the dashboard — with enough detail for a human to act. No bare except: pass, no except that only logs on a path the loop depends on. A transient backlog-read error must NEVER be read as "no projects/cards → retire everything" — keep the last-known set and retry (a real scar: reconcile_projects deliberately leaves the current set untouched on a failed read). Branch on what you caught (status code, error type), never on an assumed meaning.
• Prefer a value over an exception for the expected case. An empty backlog is [], a missing card is None — the call shouldn't throw for them, so the catch handles only the genuinely unexpected.
• One fact, one home. Card status lives in the backlog; the claim is the card's Assignee; blocking is the blocked_by relation (never a duplicate status column); slot state lives in the Manager's memory + dashboard. Don't duplicate a fact into a second place it can drift from.
• Self-healing over manual recovery. The north star (see @README.md) is a Manager that recovers from most errors on its own. When you add a failure mode, add its recovery in the same change: a provision that can fail gets a BROKEN state + bounded retry; a resource that can disappear gets detection + reprovision; a step that can hang gets a timeout. Prefer "the Manager fixes it next tick" over "a human restarts it," and log the rare thing a human still must do.
• Hard timeouts on lifecycle scripts; best-effort teardown. provision/reset/teardown are foreign code that can hang — a wedged Docker daemon once froze the whole Manager for 7.5h. They run in their own process group under a per-script timeout and are killed as a group on expiry (slots._run_script); teardown is best-effort and never raises into the caller. Keep it that way.
• Redact secrets in anything you stream. Provision output dumps JWTs, DB URLs, S3 keys. slots._redact scrubs secret-shaped tokens before they reach the log/tmux/dashboard. Over-redaction is a cosmetic non-issue; a leaked service-role key is not. Any new surface that echoes script output redacts first.
• Never run destructive commands outside the repo/scratchpad. No rm -rf on a slot worktree, a clone, or anything you didn't create — use the git worktree / teardown paths. Spell this out explicitly when you delegate to a subagent (they reach for rm -rf to "fix" a stuck stack).
• Editing LoopWorker inside a worktree? Mind the foot-gun. This repo self-hosts, so you may be editing it under .claude/worktrees/<name>. Both file edits AND shell git ops silently hit the PRIMARY checkout unless you target the worktree — use git -C <worktree> and edit under the worktree path, or your commit lands on the wrong branch.
• Atomic commits, rationale not restatement. Explain WHY, not what the diff already shows. Commit as you go, not in one lump at the end.
• Tests protect against bugs found or predictable, not coverage for its own sake. Mock the I/O (tmux/git/network), test the decision. reconciler.py is pure precisely so its decisions are testable without a real fleet.
• For deep discoveries that aren't easily resurfaced, write a markdown file in docs/ and add a one-line summary to docs/index.md, so future humans and agents can find it when a similar situation recurs.
• For general user preferences and cross-project learnings (tool-usage patterns, workflow preferences), use home-folder auto-memory (~/.claude/automemory/), not this repo.
• If you get stuck on a missing tool, credential, or service, stop and ask early. A single click from the user beats a session spent on workarounds.

Project info

Project is: @README.md

Documentation index is: @docs/index.md

CI + how changes land. GitHub Actions runs pytest on Python 3.11 and 3.14 for every PR and push to main (.github/workflows/ci.yml) — wait for green before merging. Merge with a merge commit, never squash (history stays readable). There is no deploy step: the code runs from each host's checkout, so a merged change reaches a host when its Manager is next restarted (workers clone the repo fresh per card). If a change only takes effect after a restart, say so in the PR.

LoopWorker self-hosts. It serves its own backlog — KojaLoopWorker is a row in the shared projects table (worker_manager = miquon), so a card you file for it may be picked up and built by the loop itself. That's intentional; the north star is a fully self-managing product.

Backlog. Cards live in the shared Patch roadmap (the same instance Patch plans itself in), filtered to this project. Reach it through the Patch MCP connector pointed at the deployed instance (https://api.patch.d.nevyn.dev/functions/v1/mcp) — never a local/debug stack (throwaway, may run stale code). To file a card:

1. upsert a row into roadmap: title (text), status (select: Backlog / In progress / Needs refinement / Shipped / Idea), area (multiselect — for this project usually infra, bug, ux), and — REQUIRED — the project relation set to KojaLoopWorker (c14e661c-a99b-479d-b438-01a0f02f068c), or the loop never sees it. Optional priority (number, higher = sooner).
2. Put the detail — the problem, the design fork, the concrete failing scenario — in that row's page body with edit_blocks (table:"roadmap", row_id:<id>): a short text lede, then headings + bullets.
3. Confirm field kinds/options with list_fields("roadmap") first (they drift).

Referring to a card in prose: use ~<ID> — the row's ID (id_2), e.g. ~802 — never #802. A #-number reads as a GitHub PR/issue (to Claude and to GitHub itself), so reserve # for real GitHub PRs and ~ for backlog cards. (solved_in_pr holds a real GitHub PR URL — that's a genuine #.)