# Agents with Receipts

> Agents with Receipts answers two questions about a repository. Can an agent **understand** it — AGENTS.md, conditional rules, hooks, skills, permissions? And can an agent **verify** its own work in it — one command that runs every check, determinism, failure evidence, hard constraints? Four zero-dependency Node CLIs report on both, and every claim in the handbook links to official vendor documentation.

The problem it addresses: most "best practices for Claude Code / Codex / Cursor" collections are unsourced assertions — *keep CLAUDE.md short*, *plan before you code* — with nothing to click. This repository's rule is that every claim must answer "where's the source?" with a link to official vendor documentation, and stale entries get deleted rather than accumulated. It ships four parts covering two axes: `rosetta/`, a cross-tool comparison table where all 40 cells are official-doc links re-verified 2026-09-11; `practices/`, thirteen chapters structured as scenario → approach → evidence → boundaries, of which 09–11 cover the second axis (and 12 covers the first axis: building a mental model of unfamiliar code with `/how`, `/why`, `/teach`, `/recall`) (a single verification command, determinism, failure artefacts, module boundaries, escape-hatch ratchets, flaky quarantine, visual evidence for UI work); and `tools/`, four CLIs (`agentsmd-lint`, `agents-doctor`, `agents-init`, `verify-doctor`) that turn the practices into executable checks — the first three ask whether an agent can understand the repo, the fourth asks whether an agent can verify its own work; and `templates/`, two `AGENTS.md` / `RULES.md` skeletons built to pass the linter. Requires Node ≥ 20 and has zero runtime dependencies; install by cloning: `git clone https://github.com/alloevil/agents-with-receipts.git`.

## Agent interface

All four CLIs accept `--help` (always exit 0) and `--json`. Under `--json`, stdout carries exactly one JSON object with no human output and no ANSI, and exit codes are identical to human mode — only an `error`-level result exits 1.

```json
{
  "tool": "verify-doctor",
  "target": "/abs/path/to/repo",
  "summary": { "ok": 2, "warn": 5, "error": 0, "info": 2 },
  "results": [
    { "id": "verify-command", "level": "warn", "message": "...", "advice": "...", "stage": 0 }
  ]
}
```

- `level` is one of `ok`, `warn`, `error`, `info` — there is no fifth value.
- `advice` is optional; a missing field is omitted rather than emitted as `null`.
- `stage` (integer 0–5) appears only on `verify-doctor` results. `line` appears on file-level findings — `agentsmd-lint`, and `agents-init`'s self-lint of what it just wrote — and is omitted when a finding has no line number.
- `agentsmd-lint` reports on files, so its `target` is always an array of absolute paths and every result carries its own `file` key; one JSON object covers a multi-file run.
- Branch on `summary` and on the stable `results[].id`; treat `message` and `advice` as prose whose wording can change.
- Per-tool field tables and id lists live in each `tools/<name>/README.md` under 「机器可读输出」.

## Docs
- [Site (receipt-stub navigation, renders the repository Markdown)](https://alloevil.github.io/agents-with-receipts/): the reading UI; content is fetched from the repo Markdown at runtime
- [00 — Get a repo agent-ready (follow-along)](https://alloevil.github.io/agents-with-receipts/practices/00-agent-ready-walkthrough.html): AGENTS.md → conditional rules → hook → lint in CI, every step verifiable
- [01 — Memory files](https://alloevil.github.io/agents-with-receipts/practices/01-memory-files.html): how to write and maintain AGENTS.md / CLAUDE.md plus Claude's auto-memory store, and what to leave out
- [02 — Mechanism selection](https://alloevil.github.io/agents-with-receipts/practices/02-mechanism-selection.html): memory vs rules vs skills vs hooks vs sub-agents, positioned on two axes
- [03 — Task framing and planning](https://alloevil.github.io/agents-with-receipts/practices/03-task-framing.html): Goal / Context / Constraints / Done-When; explore before editing
- [04 — Verification loops](https://alloevil.github.io/agents-with-receipts/practices/04-verification.html): agent-TDD, independent review, diff reconciliation
- [05 — Permissions and sandboxing](https://alloevil.github.io/agents-with-receipts/practices/05-permissions-sandbox.html): progressive privilege, the four vendors' tiers, prerequisites for unattended CI
- [06 — Context management](https://alloevil.github.io/agents-with-receipts/practices/06-context-management.html): /clear discipline, isolating exploration, writing plans to disk, budget awareness
- [07 — Parallelism and orchestration](https://alloevil.github.io/agents-with-receipts/practices/07-parallel-orchestration.html): deciding independence, file ownership, git worktree
- [08 — Security and team governance](https://alloevil.github.io/agents-with-receipts/practices/08-security-governance.html): untrusted input, secret interception, checking config into the repo
- [09 — Verifiable repositories](https://alloevil.github.io/agents-with-receipts/practices/09-verifiable-repo.html): one command that runs every check, determinism, failure artefacts an agent can read, evidence-based review, prerequisites for auto-merge
- [10 — Pushing rules down into hard constraints](https://alloevil.github.io/agents-with-receipts/practices/10-hard-constraints.html): structure over types over mechanical CI checks over prose, and how to clear the backlog before flipping a rule to error
- [11 — Verification skills](https://alloevil.github.io/agents-with-receipts/practices/11-verification-skills.html): screenshots, video and traces as failure evidence; driving the real app for receipts; visual evidence in the PR flow
- [12 — Codebase mental model](https://alloevil.github.io/agents-with-receipts/practices/12-codebase-mental-model.html): `/how` asks the runtime, `/why` digs the git history for motivation, `/teach` demands trade-offs, `/recall` brings context back — shipped as a commit-able skill
- [AGENTS.md of this repository](https://alloevil.github.io/agents-with-receipts/AGENTS.html): the repo dogfoods its own linter; this file was generated by `agents-init` and then refined by hand
- [中文版 README](https://alloevil.github.io/agents-with-receipts/README.zh-CN.html): the same overview in Simplified Chinese
- [English README](https://alloevil.github.io/agents-with-receipts/english.html): the rendered English overview, for readers who land on the site rather than the repository

## Evidence
- [claims.json](https://alloevil.github.io/agents-with-receipts/claims.json): every number below, with the exact command that reproduces it
- [Cross-tool comparison table](https://github.com/alloevil/agents-with-receipts/blob/main/rosetta/README.md): 10 concepts × 4 tools = 40 cells, and 40 official-documentation links — every cell's text *is* the link, so each is independently checkable. Re-verified 2026-09-11 (first pass 2026-08).
- [agentsmd-lint rules](https://github.com/alloevil/agents-with-receipts/blob/main/tools/agentsmd-lint/README.md): 5 rules (`max-lines`, `placeholder`, `vague`, `dead-script`, `empty-section`), each with the reasoning that justifies it
- [agents-doctor checks](https://github.com/alloevil/agents-with-receipts/blob/main/tools/agents-doctor/README.md): 8 checks (`agents-md`, `claude-md`, `rules`, `hooks`, `skills`, `adr`, `secrets`, `ci-gate`), path list kept consistent with the rosetta table
- [verify-doctor checks](https://github.com/alloevil/agents-with-receipts/blob/main/tools/verify-doctor/README.md): 10 checks (`verify-command`, `determinism`, `failure-artifacts`, `ui-evidence`, `module-boundary`, `type-strict`, `lint-hardness`, `escape-ratchet`, `flaky-quarantine`, `evidence-template`), reported by stage 0–5; stage gaps are warnings unless `--strict` is passed
- [package.json](https://github.com/alloevil/agents-with-receipts/blob/main/package.json): no `dependencies` and no `devDependencies` keys — zero install footprint; 4 `bin` entries
- [CI workflow](https://github.com/alloevil/agents-with-receipts/blob/main/.github/workflows/ci.yml): the repo runs its own lint gate, doctor checkup and verify-doctor pass on every push and pull request

## Source
- [GitHub repository](https://github.com/alloevil/agents-with-receipts)
- [Templates](https://github.com/alloevil/agents-with-receipts/tree/main/templates): `AGENTS.md` / `RULES.md` skeletons, designed to pass the linter
- [Contribution rules](https://github.com/alloevil/agents-with-receipts/blob/main/CONTRIBUTING.md): new entries must carry an official source