Agent_Quality_Kit

# AQK — Agent Quality Kit

> A CLI that answers one question: can the checks this repository declares actually fail? A check
> that cannot fail looks exactly like a check that passes — `|| true`, `continue-on-error`, a
> linter aimed at an empty directory, a test with no assertion, a hook nobody installed. AQK plants
> a known defect into a COPY of the project and reports which declared guard noticed and which
> stayed silent. It distinguishes three outcomes and never collapses them into two: clean ·
> finding · COULD NOT CHECK. The third means the check itself failed; treating it as either of the
> others is how a repository ends up protected by checks that cannot go red. Every rule the project
> promises becomes a command with an exit code, so a machine holds the promise instead of somebody's
> attention. Levels AQK-0..3 measure equipment, not quality, and are computed by a run — never by a
> questionnaire and never by a model's opinion.

Vendor-neutral: works with any coding agent (Claude Code, Codex, Cursor, Gemini CLI, GitHub
Copilot, Windsurf, Aider, OpenCode) and with no AI at all. It calls no vendor API and needs no
key. Stack-neutral: portable checks are plain `sh`; where the project already has a native tool
(ruff, eslint, knip, jscpd) the check uses it instead and says so when it falls back.

Zero runtime dependencies. Node 18+ and an `sh` shell. MIT.

## Use it

- Check an existing repository: `npx agent-quality-kit doctor` (read-only: writes nothing, sends
  nothing)
- Start a new one: `npx agent-quality-kit start`
- Install one guard from the catalogue: `npx agent-quality-kit add <name>`
- Check the minimum a project needs before agents can be handed the work:
  `npx agent-quality-kit doctor --baseline` (14 of 50 points confirmed by a run, ecosystem-neutral;
  the other 36 are named as a number, not hidden)
- Fail a pipeline below a level or on a failed gate: `npx agent-quality-kit doctor --run --min 1`
- Show only what a diff introduced, so a legacy repo is usable from day one: `doctor --run --since main`
- Prove the gates actually catch defects: `npx agent-quality-kit prove` — every *provable* gate is
  run against its own red and green sample and must go red on the first and stay quiet on the
  second. A gate with no samples, with samples written for another recipe, whose command takes
  no directory, or whose `requires:` program is not installed is reported as unprovable and
  named — never as broken; the verdict is "nothing proven is broken, and
  at least one gate is proven". Level AQK-2 and the badge depend on this, not on the presence of
  files
- See what proves a diff, file by file: `npx agent-quality-kit report --since main` — each changed
  code file is named by a check, walked past in silence, or touched by nothing at all, plus a
  fingerprint over the base, the commands and the file contents
- Put the repository state into the agent's context instead of hoping it reads the files:
  `npx agent-quality-kit context` — level, what is red right now, how many rules no machine
  enforces, what the ratchets hold. Where it does not know, it says so: a run that never happened
  is reported as unknown, never as clean. `context --install` writes a `SessionStart` hook into
  `.claude/settings.json` (Claude Code only; the rest of the kit stays vendor-neutral). Measured:
  the block is ~500 tokens, and carries what a file cannot — what changed today, the next three
  steps with ready commands, and when to run which command (before a commit, after changing a
  check, when a check is in the way). `context --full`
  adds the command map and the rulebook verbatim (~7000 tokens): a deliberate trade, chosen by
  the owner after the objection about long inputs, on the grounds that an agent reads files
  poorly and the tokens are the price of it not guessing
- Hand the agent one task instead of retelling the diagnosis: `npx agent-quality-kit prompt` —
  ground rules on top, at most five items by weight (red gates, defects the probe planted and no
  check caught, the project's own checks to declare, rules Claude Code cannot see, catalog
  entries to propose), and for every item the command that proves it done. Nothing is run
- Send the author one answer — the only payment the kit asks: `npx agent-quality-kit feedback`
  prints a short report built from the last run and the probe (version, level, stack, what went
  red, what it COULD NOT CHECK, which defect classes nothing here catches) with **no paths, no
  code and no repository name**, plus a prefilled link. `feedback --send "your words"` posts it in
  one command using the human's own `gh` account, as a comment in an open discussion. **Without
  the flag nothing ever leaves the machine**, and a machine holds that claim, not this sentence.
  An agent must show the text and ask before adding the flag
- Install it into Claude Code as a plugin, from the kit's own marketplace, with nobody's approval
  to wait for: `/plugin marketplace add arsen-ask-lx/Agent_Quality_Kit` then
  `/plugin install aqk@agent-quality-kit`. The session-start hook puts the repository state into
  the agent's context before its first action; two skills cover "can these checks fail" and "what
  to fix first". A thin wrapper over the same CLI — no logic of its own
- Check that the kit's own wiring is actually connected: `npx agent-quality-kit vitals` — are the
  tools the declared gates need installed, is the hook present in `.git/hooks` (a line in the
  config is an intention, not a guard), does the agent receive the state, is the version current.
  Four states, not two: connected · BROKEN · not connected and that is a choice · could not look.
  Only BROKEN affects the exit code
- See what your declared checks CANNOT see: `npx agent-quality-kit probe` — takes the files your
  own fix history calls hot, plants a proven red sample from the catalogue into a copy of each,
  and runs YOUR declared gates against it. Coverage is not declared, it is proven by planting.
  Three states that never merge: caught · nothing catches it · nothing to check with. Measured on
  the kit itself: a real file, a swallowed error and a debug print planted, 21 declared gates,
  none went red. The working tree is untouched and the exit code is always 0 — a look, not a
  threshold
- See what you told the agent and never wrote down: `npx agent-quality-kit learn` — reads Claude Code
  transcripts for this project on this machine and prints rule candidates missing from the entry
  point. Current project only, terminal only, writes nothing, always exits 0
- Exit codes: 0 pass, 1 below the level or a gate failed
- As a pre-commit hook: `repo: https://github.com/arsen-ask-lx/Agent_Quality_Kit` with
  `id: aqk` (blocking), `aqk-doctor` (read-only) or `aqk-baseline`. pre-commit installs the
  package itself; there are no dependencies to pull in.
- Without Node at all (a Python, Go or Rust project where nobody installed it):
  `docker run --rm -u "$(id -u):$(id -g)" -v "$PWD:/work" ghcr.io/arsen-ask-lx/aqk doctor`.
  Pushed to the registry by the same run, from the same tag, that publishes the package.
  Keep the `--user` flag: without it the container runs as root and
  the files `init` writes are owned by root, so you cannot edit your own manifest. Debian-based
  on purpose: the gates are `sh`, `grep`, `awk`, `find` — under alpine's busybox they behave
  differently, and an image where the gates behave differently is worse than no image
- As a GitHub Action: `uses: arsen-ask-lx/Agent_Quality_Kit@v0.19.0` with `min: 1`
  (https://github.com/marketplace/actions/agent-quality-kit-aqk)

## What makes it different

- The level is computed by running what the repository declares — not from a self-assessment
  questionnaire, not from the presence of a config file, not from a language model's judgement.
- Every guard must ship a red and a green sample, and a machine checks that the guard goes red on
  the red one and stays quiet on the green one. A check that cannot fail is indistinguishable
  from a check that works; this is the only place that requirement is enforced.
- An entry enters the catalogue only when it names a real failure it caught, recorded in the
  bruise journal.

## Files it reads and writes

- `AGENTS.md` — what the agent reads first (the entry point; `CLAUDE.md` and others work too)
- `.aqk.yml` — the manifest: entry, rules, docs, lang, gates as commands, covers (what a
  declared gate already holds, so it is not reported as debt), samples, ratchets, lessons
- `.aqkignore` — paths the scanning checks must not read (brought-in code, vendored, generated)
- `.aqk/last-run.md` — the short report of the last run, with three marks and not two: `✔` clean,
  `✘` a finding, `?` COULD NOT CHECK. Readers (the context block, the task list, the feedback
  report) must never collapse the third into either of the others

## Documentation

- [README](README.md): what it is, how to install, the catalogue, the badge, CI
- [SPEC.md](SPEC.md): the standard itself — levels, manifest, how an entry is accepted
- [Project baseline](kit/docs/ai/project-baseline.md): what a project needs before agents can be
  handed the work, in plain words, independent of language and tooling
- [The gate catalogue](kit/gates/README.md): what a gate is and the bar an entry must clear
- [The bruise journal](incidents/README.md): every defect found, and what was made of it
- [CONTRIBUTING.md](CONTRIBUTING.md): how to bring a gate
- [SECURITY.md](SECURITY.md): reporting a vulnerability, and the trust model of the manifest