argot AGENTS.md

Working with argot

argot is a guardrail that flags code foreign to a repo's own patterns — learned from its git history. Five learned detectors: a foreign dependency/API/idiom, a function the repo already has, code filed in the wrong place, an internal import that reverses the repo's layering, and a test weakened, disabled, or deleted alongside the production change it covers — plus repo-local custom rules the team scripts itself (see below). It answers "is this how we write things here?", not "is this valid?". This file tells a coding agent how to use it well. (Developing argot itself? See CLAUDE.md.)

The contract: surface, don't enforce

argot is a probabilistic linter. It has false positives, and its confidence depends on the repo. A hit is a prompt to think, never a reason to refuse.

• Never block a commit, fail a task, or refuse to proceed because argot fired.
• Never auto-"fix" a hit by rewriting code the human didn't ask you to change.
• The human always has the last word. Your job is to surface divergences and record decisions, not to enforce.

Two moments

1. Setup (once per repo). Fit the voice model and decide what shouldn't shape it. → argot init (also builds the semantic index — the embedding model ships inside the binary, so this needs no network). Review and commit argot.toml and the generated .argot/ fit snapshot; CI consumes that snapshot and never fits. Then use the argot-setup skill for anything with generated/vendored/data directories. See Setup.
2. Check (per change). Before committing code you generated or edited, score it. → argot check, or the argot-check skill.

Snapshot maintenance is adaptive, not scheduled: argot status compares the accepted tree with the fitted source/function/layout profile. Commit count and age are context only unless the team explicitly configures [fit] refresh-after as a backstop. watch is informational; only recommended or strongly_recommended should prompt maintenance. Use the argot-refresh skill: refresh.next_action says whether to fit directly or review scope first; the skill also reviews mutes before the local fit, review, and commit. No command or CI workflow refits automatically.