AGENTS.md · Archive228/loopkit

Sections

1. The three-step loop
2. Single-feature rule
3. Clean-state contract (end of every session)
4. Skills vs rules
5. Slash-command entry points
6. Never
7. Verify before you commit
8. When user instructions and this file disagree
9. Escalation
10. Model routing
11. Presets

First lines (shown under the repo's MIT license)

# AGENTS.md — loopkit loop contract

This repo runs long-lived agent sessions. Every session shares one contract:
**Plan → Act → Verify**, single-feature per session, clean state at the end.

This file is the cross-agent voice (Claude Code, Cursor, Codex CLI, Gemini CLI, Amp).
Claude-specific extras live in `.claude/CLAUDE.md`, which imports this file via `@../AGENTS.md`.

## The three-step loop

Every session, in order:

1. **Plan.** Read `PROMPT.md` (goal), `IMPLEMENTATION_PLAN.md` (state), and `git log --oneline -20` (history). If the last session claimed a feature done, smoke-test it before picking new work.
2. **Act.** Implement exactly one feature. Not two. Not "one and a small one".
3. **Verify.** Run `/verify` (adversarial pass against the diff) BEFORE claiming done or committing. Non-zero from `/verify` blocks the commit.

If `IMPLEMENTATION_PLAN.md` and the git log disagree, trust the git log. Git is append-only; the plan is rewritten each turn.

## Single-feature rule

One feature per session. Sessions that pack multiple features ship them all half-done — we have measured this. The next session takes the next feature. There is no reward for finishing more in one session; there is a real cost to leaving things half-done.

## Clean-state contract (end of every session)

- All code committed to git. Prefer `scripts/committer "<msg>" <files>` — it refuses `.` and empty messages.
- No uncommitted changes in the working tree.
- `IMPLEMENTATION_PLAN.md` updated: what was done, what is next, known open issues.
- Dev server killed (`./stop.sh` if the project has one).
- A feature is only "done" after end-to-end verification (`/verify`), not after unit tests alone.

## Skills vs rules

- **Skills** (`skills/*/SKILL.md`) — invoked on demand by trigger phrases in their `description`. Read the skill's SKILL.md before acting on a matching task.
- **Rules** (`.claude/rules/*.md`) — auto-loaded when a file path matches. Silent guardrails, not opt-in.

Full skill routing table: `skills/using-loopkit/SKILL.md` (repo layout) or `.claude/skills/using-loopkit/SKILL.md` (installed layout).

## Slash-command entry points

- `/spec` — write `PROMPT.md` before implementing. Refuses to run if `PROMPT.md` exists without `--force`.
- `/verify` — adversarial pass against the current diff. Non-zero exit blocks completion claims.
- `/loop` — describe or run the Plan → Act → Verify cycle.

## Never

- Weaken or delete a test to make red go green. If a test is wrong, fix the test in its own commit with justification.
- Mark work done without running `/verify`.
- Edit a merged migration. Migrations are additive-only.
- Add a dependency without justifying it in the commit body.
- Run `npm update`, `pip install -U`, or equivalents unless the feature is literally "upgrade dependencies".
- Push to `main` from an agent session. Humans push.

## Verify before you commit

The maker's-head reviewer always agrees with itself. `/verify` is a separate, hostile pass. Every code change goes through it. See `skills/adversarial-verify/SKILL.md` for the 11 shortcuts that fake "done".

## When user instructions and this file disagree

User instructions win. This file is the default when the user has not said otherwise.

## Escalation

When stuck, the agent runs `hitl-escalate`. If no channel is configured, it writes `BLOCKED.md` and the loop exits with code 2. Human unblocks, deletes `BLOCKED.md`, restarts `run.sh`.

## Model routing

`run.sh` reads `CLAUDE_EXECUTOR_MODEL` (per-turn workhorse call) and `CLAUDE_JUDGE_MODEL` (per-turn `/verify` call) as first-class knobs, plus `CLAUDE_PLANNER_MODEL` reserved for `/spec`. Unset = CLI default. See `skills/model-routing/SKILL.md` for the cheap-executor + frontier-judge shape.

## Presets

The `presets/` directory holds opinionated stacks — arrangements of the base skills for specific shipping cadences. Base loopkit stays a 49-skill floor that any preset can build on; the presets themselves are one arrangement of that floor, not replacements for it. `presets/finn-loop/` is the first one to ship: async, human-gated (`/spec` → ACK → `/build` → `/review` → rocket-emoji merge signal), with Linear-MCP and Slack-webhook hooks that are OFF by default. Future presets on the roadmap: `three-agent` (planner + generator + evaluator, per Prithvi's harness-design work) and `executor-judge` (do → judge → do → judge).