AGENTS.md

This is the canonical instruction file for AI coding agents working in this repository. Tools that understand AGENTS.md (Cursor, Codex, Windsurf, Claude Code, Cline, Continue, Aider, ...) read this file directly. Per-tool files like CLAUDE.md or .cursorrules are stubs that point here so the guidance lives in one place.

Decision logging — logmind log is REQUIRED for substantive commits

logmind log replaces git add + git commit + git push for any change that carries a decision — do not run those git commands directly.

DO NOT run raw git add / git commit / git push for substantive code changes. The commit-msg hook installed by logmind init warns when raw git is used on a substantive commit; the intent is to prevent the warning, not bypass it via --no-verify. Typo / whitespace / dep-bump-only commits MAY use raw git.

logmind log "summary" -r "why" -a "alternative" -i "implication"

This project uses logmind. What counts as a decision, branch routing, --stage scoped for unrelated WIP, logmind doctor, and the required-reading list (docs/timeline.md, docs/decisions.md, docs/file-structure.md, docs/decisions-branches/<branch>.md) all live in the logmind agent skill at https://github.com/thrillmade/agent-skills/tree/main/skills/logmind.

Project Overview

Development Commands

python3 .github/scripts/validate_skills.py   # the skill gate — run it before you push
pytest tests/ -q                             # the gates' own regression guard
logmind log "…" -r "…" -a "…" -i "…"         # the commit primitive (see above)

The validator runs in about a second. The suite takes minutes: most of its wall clock is the two mutation files (test_prose_retention_mutations.py, test_skill_directory_mutations.py), which each run the real suites in a subprocess once per mutation — that is what makes "this guard can fail" a fact rather than a claim, and it is worth the wait. Run the fast subset while iterating — pytest tests/ -q --ignore=tests/test_prose_retention_mutations.py --ignore=tests/test_skill_directory_mutations.py — and the whole thing before you push. Neither command is optional before opening a PR — CI runs the same two, unconditionally. (No test count or duration is quoted here on purpose: a hand-kept number with no gate reads as true until one quietly isn't. Run it and read the output.)

The dev branch

Work lands on dev first and reaches main in batches. dev is somewhere work passes through, not somewhere work lives. These are the organisation's rules, not this repo's; changing them is not a local decision.

Branch from dev, and open the pull request into dev. The default base is main, so set it by hand. Never push straight to dev — no workflow runs on a push there, so the commit is checked by nothing.

Into dev: an independent adversarial review. A change may merge once a reviewer that did not write it has reviewed it and its findings are addressed — a refute-first panel, or clud-bug in local mode. Independence means a different agent. A fresh context window on the same agent is not a different agent, and neither is the same agent asked to look again. The review is a panel, not a GitHub approval; a PR into dev reports no review decision at all. This is the only rule applied per change rather than per batch, so it carries the weight.

Into main: a person. An agent does not open or merge the dev → main promotion; it reports the batch ready and hands off.

A red check is fixed, not merged past. Read the failing step first.

Every failing step is real — including one where the check's own step never ran because a setup step died. A skipped verdict is not a passing verdict. Re-run it or fix it; do not reason your way past it.

(check-links and check-derived-docs used to check out the head branch by name, so a run still in flight when the PR merged died at the checkout step with A branch or tag with the name '…' could not be found — a red that was an artifact, not a verdict. Fixed in #223 by checking out the SHA instead; if you see that exact message again, it's a regression, not a known quirk.)

Batching dilutes exactly one check. check-decisions asks only whether some decision file is in the diff, so one entry clears a whole batch. Every change still logs its own regardless.

Nothing in the forge enforces any of the above. No rule protects dev; main's approving-review rule is bypassed in practice; nothing there tells an agent from a person. That a rule is not enforced is a property of the forge, not a permission.

clud-bug — Claude PR review

This repo uses clud-bug for automatic PR reviews. Full collaboration rules — fix-push flow, skill structure, comment format, strict-mode mechanics, workflow-edit constraint — live in the bundled clud-bug-collaboration skill. Read that skill before pushing fixes addressing prior review threads.

Strict mode is on in this repo (workflow check fails on critical findings). Toggle via .claude/skills/.clud-bug.json (read from PR base ref, so PRs can't disable strict-mode on themselves).

For agent invocations of the clud-bug CLI, prefer CLUD_BUG_QUIET=1 (or pass --quiet) — suppresses progress chatter and emits a single ok <key-value> summary line per command.

Installed at clud-bug v0.7.0-rc.20.

clud-bug review coverage here is intermittent — measure it, don't assume it

The block above describes the mechanism and is regenerated by clud-bug update weekly, so nothing measured belongs inside it. What is measured belongs here. The clud-bug-review check on this repo has had four eras (measured 2026-11-03; probe control-tested against the known hits below):

• Before #188, mixed — not a clean era: #187 carries a workflow-produced success (from the then-extant clud-bug-review.yml on its own branch) and an App-posted neutral; #150 is an App failure; #120 has no run at all.
• neutral "clud-bug review unavailable" from #188 through at least #269 — the outage era.
• success "clud-bug review — clean (notarized)" from the App on #274 and #277 (October) — the App did produce real reviews after the outage.
• Absent entirely on #293–#296 (November): no check-run at all. The review workflow was removed in #117 (the App migration), so a check-run exists only when the App posts one — and today it posts nothing here. Strict mode cannot fail on a review that never runs.

While the check is absent, the per-change review gate above is carried entirely by local panels. Re-check before relying on it, and control-test an empty result against #274's head SHA (the cleanest known hit) before reading absence as fact:

gh api repos/thrillmade/agent-skills/commits/<sha>/check-runs \
  --jq '.check_runs[] | select(.name=="clud-bug-review") | "\(.conclusion) \(.output.title)"'