inluck-net/ilk-skills

**A staged execution loop for AI coding agents.**
Decompose work into a verifiable plan, then let the loop drive it to done —
across timeouts, API hiccups, and overnight runs.
> *ilk* — "of that kind". A kind of plan-loop: you decompose work into a
> sequenced **plan**, the loop drives a fresh AI session per step, and a
> watchdog keeps it going without human babysitting.
---
Why this exists
A single agent session is a poor unit of work for anything real. It forgets, it
times out, it stops at the first ambiguity, and it will happily tell you it
finished something it never verified.
ilk-skills makes the **plan** the unit of work instead of the session:
- **Every step is recoverable from disk** — plans live as Markdown with
frontmatter, so a run survives a killed session, a rebooted laptop, or a
switch between Cursor, Claude Code, and Codex.
- **Every step has to prove itself** — each sub-plan step carries executable
local_checks. "Done" means a command exited 0, not that a model said so.
- **Nothing runs unsupervised without a supervisor** — a watchdog classifies
why a loop stopped and either resumes it or stops loudly with a reason.
How it works
Plans, runtime state, and logs live under ~/.ilk-data/projects/ /,
keyed off the project's .git root — **your repository never grows a single
skill artifact.**
The local loop performance preview
adds measured dispatch/recovery improvements and an opt-in Mac profile where
the driver owns gates, commits and plan state. Its rollout and limitations are
recorded in the manual tracker.
Quick start
> [!WARNING]
> **Installing changes your agent behavior globally — not just in this repo.**
>
> conventions/config.yml ships with auto_use_ilk_plan: true, and the normal
> --apply path always reconciles the auto-plan managed block. So --apply
> edits your **user-global agent instructions**, which apply to *every* project
> on the machine:
>
> | File | Effect |
> |---|---|
> | ~/.claude/CLAUDE.md | Claude Code routes implementation work to /ilk-plan by default |
> | ~/.codex/AGENTS.md | same routing for Codex |
> | ~/.cursor/rules/ilk-auto-plan.mdc | same routing for Cursor |
>
> **--dry-run does not show this step** — it exits before the reconcile — so
> the dry-run output understates what --apply touches.
>
> **To install the skills without changing global agent behavior**, set
> auto_use_ilk_plan: false in conventions/config.yml before applying. The
> block is delimited by /
> markers, so it is fully removable — see Auto-plan routing.
The installer creates symlinks (junctions on Windows) into ~/.cursor/skills/,
~/.claude/skills/, and ~/.codex/skills/, plus the matching commands/
directories. Use --only-codex / -OnlyCodex to install for one host only.
The first install seeds skills/ilk-launcher/projects.json from
projects.example.json (the real file is gitignored, per-operator). Point it at
your projects, then from any git repo:
Codex users invoke the same skills through natural language — the installer
places identical files under ~/.codex/skills/.
Commands
| Command | What it does |
|---|---|
| /ilk-plan | Turn a free-text task into a MASTER plan + sub-plans with machine-checkable acceptance criteria |
| /ilk | Pick the active master and run the next pending step |
| /ilk-run | Start the loop *with* its watchdog, detached, for unattended runs |
| /ilk-status | Read-only progress. --watch gives a self-refreshing all-projects cockpit |
| /ilk-schedule | Launch the one cross-project scheduler that drains **every** project's queue |
| /ilk-stop | Stop a running loop and its watchdog |
| /ilk-feedback | Postmortem: classify why a run stopped, recommend next-launch params |
| /ilk-upgrade | Pull the latest toolkit and make it effective on this machine |